From f80b87e4fa3eec8d784b2423f6578e4006600e02 Mon Sep 17 00:00:00 2001
From: Nicolas Pope <nwpope@utu.fi>
Date: Tue, 27 Oct 2020 16:49:43 +0200
Subject: [PATCH] Some renderer documentation
---
.../cpp/include/ftl/render/renderer.hpp | 23 +++++++++++++++----
1 file changed, 19 insertions(+), 4 deletions(-)
diff --git a/components/renderers/cpp/include/ftl/render/renderer.hpp b/components/renderers/cpp/include/ftl/render/renderer.hpp
index 598e2a6ee..7ab50a8f9 100644
--- a/components/renderers/cpp/include/ftl/render/renderer.hpp
+++ b/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;
};
--
GitLab