Some renderer documentation

components/renderers/cpp/include/ftl/render/renderer.hpp

@@ -32,7 +32,8 @@ class Renderer : public ftl::Configurable {
 	 * frame given as parameter is where the output channels are rendered to.
 	 * The channel parameter is the render output channel which can either be
 	 * Left (Colour) or Right (Colour 2). Using "Right" will also adjust the
-	 * pose to the right eye position and use the right camera intrinsics.
+	 * pose to the right eye position and use the right camera intrinsics. The
+	 * pose and intrinsics also come from the given `Frame` object.
 	 */
 	virtual void begin(ftl::rgbd::Frame &, ftl::codecs::Channel)=0;
 
@@ -43,10 +44,18 @@ class Renderer : public ftl::Configurable {
 	 */
 	virtual void end()=0;
 
+	/**
+	 * Perform any final render pass that combines all results. This should be
+	 * called after all data has been submitted.
+	 */
 	virtual void render()=0;
 
 	virtual void blend(ftl::codecs::Channel)=0;
 
+	/**
+	 * If the render fails part way with an exception, it is necessary to call
+	 * this method to reset the renderer before trying the next frame.
+	 */
 	virtual void cancel()=0;
 
 	protected:
@@ -54,7 +63,11 @@ class Renderer : public ftl::Configurable {
 };
 
 /**
- * A renderer specifically for RGB-D framesets.
+ * A renderer specifically for RGB-D framesets. To use an instance, call
+ * `begin`, `submit` (multiple), `render` and `end` methods in that order. Note
+ * that usually the `submit` and `render` calls initiate asynchronous jobs on
+ * the GPU and so don't block. Only `end` will block until finished. The GPU
+ * stream used, if any, is the output frame's CUDA stream.
  */
 class FSRenderer : public ftl::render::Renderer {
 	public:
@@ -63,14 +76,16 @@ class FSRenderer : public ftl::render::Renderer {
 
 	/**
      * Render all frames of a frameset into the output frame. This can be called
-	 * multiple times between `begin` and `end` to combine multiple framesets.
+	 * multiple times between `begin` and `render` to combine multiple framesets.
 	 * Note that the frameset pointer must remain valid until `end` is called,
 	 * and ideally should not be swapped between.
 	 *
 	 * The channels parameter gives all of the source channels that will be
 	 * rendered into the single colour output. These will be blended
 	 * together by some undefined method. Non colour channels will be converted
-	 * to RGB colour appropriately.
+	 * to RGB colour appropriately. Config options may be able to control this
+	 * process. The final matrix is an addition transform to apply to this
+	 * frameset before rendering, it can be identity.
      */
     virtual bool submit(ftl::data::FrameSet *, ftl::codecs::Channels<0>, const Eigen::Matrix4d &)=0;
 };