Pipeline documentation

SDK/C++/private/pipeline_impl.cpp

@@ -49,6 +49,8 @@ bool PipelineImpl::waitCompletion(int timeout)
 
 voltu::OperatorPtr PipelineImpl::appendOperator(voltu::OperatorId id)
 {
+	if (static_cast<int>(id) <= 0) throw voltu::exceptions::BadParameterValue();
+	
 	switch (id)
 	{
 	case voltu::OperatorId::kFusion			: return std::make_shared<voltu::internal::OperatorImpl>(graph_->append<ftl::operators::Fusion>("fusion"));

SDK/C++/public/include/voltu/operator.hpp

@@ -12,23 +12,38 @@
 namespace voltu
 {
 
+
+/**
+ * @brief Operation type identifier.
+ */
 enum class OperatorId
 {
 	kInvalid		= 0,
-	kDepth			= 1,
-	kGTEvaluator	= 2,
-	kFusion			= 3,
-	kClipping		= 4,
-	kAruco			= 5,
-	kPixelAnalysis	= 6
+	kDepth			= 1,	///< Calculate depth map from stereo images
+	kGTEvaluator	= 2,	///< Ground truth quality evaluation
+	kFusion			= 3,	///< Fuse multiple depth maps together
+	kClipping		= 4,	///< Use a clip box to remove unwanted data
+	kAruco			= 5,	///< Aruco tag detector
+	kPixelAnalysis	= 6		// TODO: Change this
 };
 
+/**
+ * @brief Manage operator settings.
+ */
 class Operator
 {
 public:
 	virtual ~Operator() = default;
 	
+	/**
+	 * @brief Get a named operator property.
+	 * 
+	 * @throw voltu::exceptions::BadPropertyName If name not valid.
+	 * @return Property accessor object.
+	 */
 	PY_API virtual voltu::PropertyPtr property(const std::string &name) = 0;
+
+	// TODO: Get list of properties supported
 };
 
 typedef std::shared_ptr<Operator> OperatorPtr;

SDK/C++/public/include/voltu/pipeline.hpp

@@ -14,15 +14,73 @@
 namespace voltu
 {
 
+/**
+ * @brief Manage a pipeline of frame procesing operations.
+ * 
+ * A frame processing pipeline can be constructed from a range of different
+ * operators. One example is the fusion operator that merges all input data
+ * together with a model. The pipeline of operators runs asynchonously but in
+ * sequential order and modifies the frames internal data.
+ * 
+ * @see voltu::Frame
+ * @see voltu::Operator
+ */
 class Pipeline
 {
 public:
 	virtual ~Pipeline() = default;
 	
+	/**
+	 * @brief Send a frame for processing.
+	 * 
+	 * This method is non-blocking and will therefore return before operator
+	 * processing has been completed. The data inside the frame object is
+	 * modified during this process, so the data should not be accessed until
+	 * the pipeline is completed.
+	 * 
+	 * @note
+	 * You must not submit multiple frames to the same pipeline without
+	 * ensuring completion. You must also not access frame data during
+	 * processing. The room object associated with the frame must remain valid
+	 * for the duration of processing.
+	 * 
+	 * @param frame A room data frame.
+	 * 
+	 * @throw voltu::exceptions::InvalidFrameObject If the frame is invalid
+	 * @throw voltu::exceptions::IncompatibleOperation If the pipeline given
+	 *     cannot be applied to the frame for some reason.
+	 */
 	PY_API virtual void submit(const voltu::FramePtr &frame) = 0;
 
+	/**
+	 * @brief Block until all processing is completed.
+	 * 
+	 * If a frame has been submitted, this can be used to block until all
+	 * processing has finished. If no frame has been submitted then this
+	 * method will currently block until timeout.
+	 * 
+	 * @todo Allow timeout of -1 and exception on no frame.
+	 * 
+	 * @param timeout Millisecond timeout, or 0 for non-blocking check.
+	 * @return True if completed
+	 */
 	PY_API virtual bool waitCompletion(int timeout) = 0;
 
+	/**
+	 * @brief Add an operator to this pipeline.
+	 * 
+	 * Each operator is appended to the pipeline in the order added, and
+	 * therefore will be processed sequentially in that same order. One type
+	 * of operator can be appended multiple times, useful if different settings
+	 * are to be used each time. Settings can be accessed from the returned
+	 * operator management instance.
+	 * 
+	 * @see voltu::Operator
+	 * 
+	 * @throw voltu::exceptions::BadParameterValue For invalid operators
+	 * @throw voltu::exceptions::NotImplemented If operator not implemented for SDK
+	 * @return Operator management instance for settings.
+	 */
 	PY_API virtual voltu::OperatorPtr appendOperator(voltu::OperatorId id) = 0;
 };
 

SDK/C++/public/include/voltu/room.hpp

@@ -60,6 +60,7 @@ public:
 	 * 2) If `timeout` < 0 then it blocks without timeout.
 	 * 3) If `timeout` > 0 then it blocks for maximum `timeout` milliseconds.
 	 * 
+	 * @note
 	 * Note that for composite rooms with multiple physical rooms, a new
 	 * frame occurs whenever any of the physical rooms provides a new frame,
 	 * even if other rooms do not.
@@ -88,6 +89,7 @@ public:
 	 * marks the data as seen, and therefore causes a subsequent call to
 	 * `waitNextFrame` to block until more data arrives.
 	 * 
+	 * @note
 	 * Each call to `getFrame` can return a different smart pointer for the same
 	 * frame data, this is valid. The room object must remain in existence for
 	 * as long as any frame objects are held.