QNoDraw: improve documentation

Change-Id: Id621005f420928b08f24f867d84a26c75c5df796
Reviewed-by: Sean Harmer <sean.harmer@kdab.com>

1 files changed, 69 insertions, 14 deletions

diff --git a/src/render/framegraph/qnodraw.cpp b/src/render/framegraph/qnodraw.cpp
index 21634d1cb..46756557e 100644
--- a/src/render/framegraph/qnodraw.cpp
+++ b/src/render/framegraph/qnodraw.cpp
@@ -44,19 +44,42 @@ QT_BEGIN_NAMESPACE
 namespace Qt3DRender {
 
 /*!
- * \class Qt3DRender::QNoDraw
- * \inmodule Qt3DRender
- *
- * \brief When a QNoDraw node is present in a FrameGraph branch, this
- * prevents the renderer from rendering any primitive.
- *
- * QNoDraw should be used when the FrameGraph needs to set up some render
- * states or clear some buffers without requiring any mesh to be drawn. It has
- * the same effect as having a Qt3DRender::QRenderPassFilter that matches none of
- * available Qt3DRender::QRenderPass instances of the scene without the overhead cost
- * of actually performing the filtering.
- *
- * \since 5.5
+    \class Qt3DRender::QNoDraw
+    \inmodule Qt3DRender
+
+    \brief When a Qt3DRender::QNoDraw node is present in a FrameGraph branch, this
+    prevents the renderer from rendering any primitive.
+
+    Qt3DRender::QNoDraw should be used when the FrameGraph needs to set up some render
+    states or clear some buffers without requiring any mesh to be drawn. It has
+    the same effect as having a Qt3DRender::QRenderPassFilter that matches none of
+    available Qt3DRender::QRenderPass instances of the scene without the overhead cost
+    of actually performing the filtering.
+
+    When disabled, a Qt3DRender::QNoDraw node won't prevent the scene from
+    being rendered. Toggling the enabled property is therefore a way to make a
+    Qt3DRender::QNoDraw active or inactive.
+
+    Qt3DRender::QNoDraw is usually used as a child of a
+    Qt3DRendeR::QClearBuffers node to prevent from drawing the scene when there
+    are multiple render passes.
+
+    \code
+    Qt3DRender::QViewport *viewport = new Qt3DRender::QViewport();
+    Qt3DRender::QCameraSelector *cameraSelector = new Qt3DRender::QCameraSelector(viewport);
+
+    Qt3DRender::QClearBuffers *clearBuffers = new Qt3DRender::QClearBuffers(cameraSelector);
+    clearBuffers->setBuffers(Qt3DRender::QClearBuffers::ColorDepthBuffer);
+
+    Qt3DRender::QNoDraw *noDraw = new Qt3DRender::QNoDraw(clearBuffers);
+
+    Qt3DRender::QRenderPassFilter *mainPass = new Qt3DRender::QRenderPassFilter(cameraSelector);
+    ....
+    Qt3DRender::QRenderPassFilter *previewPass = new Qt3DRender::QRenderPassFilter(cameraSelector);
+    ....
+    \endcode
+
+    \since 5.5
  */
 
 /*!
@@ -66,7 +89,39 @@ namespace Qt3DRender {
     \inqmlmodule Qt3D.Render
     \since 5.5
     \brief When a NoDraw node is present in a FrameGraph branch, this
- * prevents the renderer from rendering any primitive.
+     prevents the renderer from rendering any primitive.
+
+    NoDraw should be used when the FrameGraph needs to set up some render
+    states or clear some buffers without requiring any mesh to be drawn. It has
+    the same effect as having a Qt3DRender::QRenderPassFilter that matches none
+    of available Qt3DRender::QRenderPass instances of the scene without the
+    overhead cost of actually performing the filtering.
+
+    When disabled, a NoDraw node won't prevent the scene from being rendered.
+    Toggling the enabled property is therefore a way to make a NoDraw active or
+    inactive.
+
+    NoDraw is usually used as a child of a ClearBuffers node to prevent from
+    drawing the scene when there are multiple render passes.
+
+    \code
+
+    Viewport {
+        CameraSelector {
+            ClearBuffers {
+                buffers: ClearBuffers.ColorDepthBuffer
+                NoDraw { } // Prevents from drawing anything
+            }
+            RenderPassFilter {
+                ...
+            }
+            RenderPassFilter {
+                ...
+            }
+        }
+    }
+
+    \endcode
 */
 
 /*!