Update docs for render targets

Update docs for QRenderTarget, QRenderTargetSelector and
QRenderTargetOutput

Change-Id: Iceff6605e4a5093e9af29718600534b9267f8c3d
Reviewed-by: Tomi Korpipää <tomi.korpipaa@qt.io>
Reviewed-by: Sean Harmer <sean.harmer@kdab.com>

3 files changed, 215 insertions, 81 deletions

diff --git a/src/render/framegraph/qrendertargetselector.cpp b/src/render/framegraph/qrendertargetselector.cpp
index a413bbf56..f129d6e1e 100644
--- a/src/render/framegraph/qrendertargetselector.cpp
+++ b/src/render/framegraph/qrendertargetselector.cpp
@@ -49,23 +49,38 @@ using namespace Qt3DCore;
 
 namespace Qt3DRender {
 /*!
- * \class Qt3DRender::QRenderTargetSelector
- * \inmodule Qt3DRender
- * \brief Provides a way of specifying a render target
- * \since 5.7
- *
- * \inherits Qt3DRender::QFrameGraphNode
- *
+    \class Qt3DRender::QRenderTargetSelector
+    \inmodule Qt3DRender
+    \since 5.7
+    \brief Provides a way of specifying a render target
+
+    A Qt3DRender::QRenderTargetSelector is used to select active Qt3DRender::QRenderTarget
+    for the FrameGraph. When QRenderTargetSelector is present in the FrameGraph,
+    the rendering is directed into QTexture objects or draw buffers instead of the surface
+    specified in the Qt3DRender::QRenderSurfaceSelector. A render buffer is automatically
+    generated for an attachment point if drawBuffers contain attachment point that any
+    output in the QRenderTarget do not specify. If the drawBuffers is empty,
+    the renderer will default to using all the outputs in QRenderTarget.
  */
 
 /*!
- * \qmltype RenderTargetSelector
- * \inqmlmodule Qt3D.Render
- * \since 5.7
- * \ingroup
- * \instantiates Qt3DRender::QRenderTargetSelector
- * \brief RenderTargetSelector
- *
+    \qmltype RenderTargetSelector
+    \inqmlmodule Qt3D.Render
+    \since 5.7
+    \instantiates Qt3DRender::QRenderTargetSelector
+    \inherits FrameGraphNode
+    \brief Provides a way of specifying a render target
+
+    A RenderTargetSelector is used to select active RenderTarget
+    for the FrameGraph. When RenderTargetSelector is present in the FrameGraph,
+    the rendering is directed into Texture objects or draw buffers instead of the surface
+    specified in the RenderSurfaceSelector.
+ */
+/*!
+    \qmlproperty list<variant> RenderTargetSelector::drawBuffers
+    Holds the list of draw buffers enabled for the RenderTarget.
+
+    \sa Qt3DRender::QRenderTargetOutput::AttachmentPoint
  */
 
 QRenderTargetSelectorPrivate::QRenderTargetSelectorPrivate()
@@ -75,7 +90,7 @@ QRenderTargetSelectorPrivate::QRenderTargetSelectorPrivate()
 }
 
 /*!
- * Constructs QRenderTargetSelector with given \a parent.
+    Constructs QRenderTargetSelector with given \a parent.
  */
 QRenderTargetSelector::QRenderTargetSelector(QNode *parent)
     : QFrameGraphNode(*new QRenderTargetSelectorPrivate, parent)
@@ -88,13 +103,13 @@ QRenderTargetSelector::~QRenderTargetSelector()
 }
 
 /*!
- *  \property QRenderTargetSelector::target
- *  Specifies the target to be rendered
+    \property QRenderTargetSelector::target
+    Holds the current render target
  */
 
-/*! \qmlproperty QWindow Qt3D.Render::RenderTargetSelector::target
- *
- * the target to be rendered
+/*! \qmlproperty RenderTarget Qt3D.Render::RenderTargetSelector::target
+
+    Holds the current render target
  */
 void QRenderTargetSelector::setTarget(QRenderTarget *target)
 {
@@ -124,15 +139,13 @@ QRenderTarget *QRenderTargetSelector::target() const
 }
 
 /*!
- * \internal
- * Sets the draw buffers \a buffers to be used. The draw buffers should be
- * matching the Qt3DRender::QRenderTargetOutput::RenderAttachmentType
- * defined in the attachments of the Qt3DRender::QRenderTarget associated to the
- * Qt3DRender::QRenderTargetSelector instance.
- *
- * \note At render time, if no draw buffer has been specified, the renderer will
- * default to using all the attachments' draw buffers.
- *
+    Sets the draw \a buffers to be used. The draw buffers should be
+    matching the Qt3DRender::QRenderTargetOutput::AttachmentPoint
+    defined in the attachments of the Qt3DRender::QRenderTarget associated to the
+    Qt3DRender::QRenderTargetSelector instance.
+
+    \note At render time, if no draw buffer has been specified, the renderer will
+    default to using all the attachments' draw buffers.
  */
 void QRenderTargetSelector::setOutputs(const QVector<QRenderTargetOutput::AttachmentPoint> &buffers)
 {
@@ -150,7 +163,7 @@ void QRenderTargetSelector::setOutputs(const QVector<QRenderTargetOutput::Attach
 }
 
 /*!
- * Returns the list of draw buffers for the current Qt3DRender::QRenderTargetSelector instance.
+    \return the list of draw buffers for the current Qt3DRender::QRenderTargetSelector instance.
  */
 QVector<QRenderTargetOutput::AttachmentPoint> QRenderTargetSelector::outputs() const
 {
diff --git a/src/render/frontend/qrendertarget.cpp b/src/render/frontend/qrendertarget.cpp
index 44414e904..bdf8b5fa1 100644
--- a/src/render/frontend/qrendertarget.cpp
+++ b/src/render/frontend/qrendertarget.cpp
@@ -51,13 +51,40 @@ using namespace Qt3DCore;
 namespace Qt3DRender {
 
 /*!
- * \class Qt3DRender::QRenderTarget
- * \brief The QRenderTarget class encapsulates a target (usually a frame buffer
- * object) which the renderer can render into.
- * \since 5.7
- * \inmodule Qt3DRender
+    \class Qt3DRender::QRenderTarget
+    \brief The QRenderTarget class encapsulates a target (usually a frame buffer
+    object) which the renderer can render into.
+    \since 5.7
+    \inmodule Qt3DRender
+
+    A Qt3DRender::QRenderTarget comprises of Qt3DRender::QRenderTargetOutput objects,
+    which specify the the buffers the render target is rendering to. The user can
+    specify MRT(Multiple Render Targets) by attaching multiple textures to different
+    attachment points. The results are undefined if the user tries to attach multiple
+    textures to the same attachment point. At render time, only the draw buffers specified
+    in the Qt3DRender::QRenderTargetSelector are used.
+
+ */
+/*!
+    \qmltype RenderTarget
+    \brief The RenderTarget class encapsulates a target (usually a frame buffer
+    object) which the renderer can render into.
+    \since 5.7
+    \inmodule Qt3D.Render
+    \instantiates Qt3DRender::QRenderTarget
+
+    A RenderTarget comprises of RenderTargetOutput objects, which specify the the buffers
+    the render target is rendering to. The user can specify MRT(Multiple Render Targets)
+    by attaching multiple textures to different attachment points. The results are undefined
+    if the user tries to attach multiple textures to the same attachment point. At render
+    time, only the draw buffers specified in the RenderTargetSelector are used.
  */
 
+/*!
+    \qmlproperty list<RenderTargetOutput> RenderTarget::attachments
+    Holds the attachments for the RenderTarget.
+*/
+
 /*! \internal */
 QRenderTargetPrivate::QRenderTargetPrivate()
     : QComponentPrivate()
@@ -65,8 +92,8 @@ QRenderTargetPrivate::QRenderTargetPrivate()
 }
 
 /*!
- * The constructor creates a new QRenderTarget::QRenderTarget instance with
- * the specified \a parent.
+    The constructor creates a new QRenderTarget::QRenderTarget instance with
+    the specified \a parent.
  */
 QRenderTarget::QRenderTarget(QNode *parent)
     : QComponent(*new QRenderTargetPrivate, parent)
@@ -85,8 +112,7 @@ QRenderTarget::QRenderTarget(QRenderTargetPrivate &dd, QNode *parent)
 }
 
 /*!
- * Adds a chosen output via \a output.
- * \param output
+    Adds a chosen output via \a output.
  */
 void QRenderTarget::addOutput(QRenderTargetOutput *output)
 {
@@ -109,8 +135,7 @@ void QRenderTarget::addOutput(QRenderTargetOutput *output)
 }
 
 /*!
- * Removes a chosen output via \a output.
- * \param output
+    Removes a chosen output via \a output.
  */
 void QRenderTarget::removeOutput(QRenderTargetOutput *output)
 {
@@ -127,7 +152,7 @@ void QRenderTarget::removeOutput(QRenderTargetOutput *output)
 }
 
 /*!
- * \return the chosen outputs.
+    \return the chosen outputs.
  */
 QVector<QRenderTargetOutput *> QRenderTarget::outputs() const
 {
diff --git a/src/render/frontend/qrendertargetoutput.cpp b/src/render/frontend/qrendertargetoutput.cpp
index 55b788a23..6d65ec08e 100644
--- a/src/render/frontend/qrendertargetoutput.cpp
+++ b/src/render/frontend/qrendertargetoutput.cpp
@@ -47,13 +47,141 @@ QT_BEGIN_NAMESPACE
 namespace Qt3DRender {
 
 /*!
- * \class Qt3DRender::QRenderTargetOutput
- * \brief The QRenderTargetOutput class allows the specification of an attachment
- * of a render target (whether it is a color texture, a depth texture, etc... ).
- * \since 5.7
- * \inmodule Qt3DRender
+    \class Qt3DRender::QRenderTargetOutput
+    \brief The QRenderTargetOutput class allows the specification of an attachment
+    of a render target (whether it is a color texture, a depth texture, etc... ).
+    \since 5.7
+    \inmodule Qt3DRender
+
+    A QRenderTargetOutput specifies the attachment point and parameters for texture
+    that is attached to render target. In addition to the attachment point, texture
+    miplevel, layer and cubemap face can be specified. The texture attached to the
+    QRenderTargetOutput must be compatible with the given parameters.
+ */
+
+/*!
+    \qmltype RenderTargetOutput
+    \brief The RenderTargetOutput type allows the specification of an attachment
+    of a render target (whether it is a color texture, a depth texture, etc... ).
+    \since 5.7
+    \inmodule Qt3D.Render
+    \inherits Node
+    \instantiates Qt3DRender::QRenderTargetOutput
+
+    A RenderTargetOutput specifies the attachment point and parameters for texture
+    that is attached to render target. In addition to the attachment point, texture
+    miplevel, layer and cubemap face can be specified. The texture attached to the
+    RenderTargetOutput must be compatible with the given parameters.
  */
 
+/*!
+    \enum QRenderTargetOutput::AttachmentPoint
+
+    This enumeration specifies the values for the attachment point.
+
+    \value Color0 Color attachment point at index 0
+    \value Color1 Color attachment point at index 1
+    \value Color2 Color attachment point at index 2
+    \value Color3 Color attachment point at index 3
+    \value Color4 Color attachment point at index 4
+    \value Color5 Color attachment point at index 5
+    \value Color6 Color attachment point at index 6
+    \value Color7 Color attachment point at index 7
+    \value Color8 Color attachment point at index 8
+    \value Color9 Color attachment point at index 9
+    \value Color10 Color attachment point at index 10
+    \value Color11 Color attachment point at index 11
+    \value Color12 Color attachment point at index 12
+    \value Color13 Color attachment point at index 13
+    \value Color14 Color attachment point at index 14
+    \value Color15 Color attachment point at index 15
+    \value Depth Depth attachment point
+    \value Stencil Stencil attachment point
+    \value DepthStencil DepthStencil attachment point
+*/
+
+/*!
+    \qmlproperty enumeration RenderTargetOutput::attachmentPoint
+    Holds the attachment point of the RenderTargetOutput.
+    \list
+    \li RenderTargetOutput.Color0
+    \li RenderTargetOutput.Color1
+    \li RenderTargetOutput.Color2
+    \li RenderTargetOutput.Color3
+    \li RenderTargetOutput.Color4
+    \li RenderTargetOutput.Color5
+    \li RenderTargetOutput.Color6
+    \li RenderTargetOutput.Color7
+    \li RenderTargetOutput.Color8
+    \li RenderTargetOutput.Color9
+    \li RenderTargetOutput.Color10
+    \li RenderTargetOutput.Color11
+    \li RenderTargetOutput.Color12
+    \li RenderTargetOutput.Color13
+    \li RenderTargetOutput.Color14
+    \li RenderTargetOutput.Color15
+    \li RenderTargetOutput.Depth
+    \li RenderTargetOutput.Stencil
+    \li RenderTargetOutput.DepthStencil
+    \endlist
+
+    \sa Qt3DRender::QRenderTargetOutput::AttachmentPoint
+*/
+
+/*!
+    \qmlproperty Texture RenderTargetOutput::texture
+    Holds the texture attached to the attachment point.
+*/
+
+/*!
+    \qmlproperty int RenderTargetOutput::mipLevel
+    Holds the miplevel of the attached texture the rendering is directed to.
+*/
+
+/*!
+    \qmlproperty int RenderTargetOutput::layer
+    Holds the layer of the attached texture the rendering is directed to.
+*/
+
+/*!
+    \qmlproperty enumeration RenderTargetOutput::face
+    Holds the face of the attached cubemap texture the rendering is directed to.
+    \list
+    \li Texture.CubeMapPositiveX
+    \li Texture.CubeMapNegativeX
+    \li Texture.CubeMapPositiveY
+    \li Texture.CubeMapNegativeY
+    \li Texture.CubeMapPositiveZ
+    \li Texture.CubeMapNegativeZ
+    \endlist
+    \sa Qt3DRender::QAbstractTexture::CubeMapFace
+*/
+
+/*!
+    \property QRenderTargetOutput::attachmentPoint
+    Holds the attachment point of the QRenderTargetOutput.
+*/
+
+/*!
+    \property QRenderTargetOutput::texture
+    Holds the texture attached to the attachment point.
+*/
+
+/*!
+    \property QRenderTargetOutput::mipLevel
+    Holds the miplevel of the attached texture the rendering is directed to.
+*/
+
+/*!
+    \property QRenderTargetOutput::layer
+    Holds the layer of the attached texture the rendering is directed to.
+*/
+
+/*!
+    \property QRenderTargetOutput::face
+    Holds the face of the attached cubemap texture the rendering is directed to.
+*/
+
 /*! \internal */
 QRenderTargetOutputPrivate::QRenderTargetOutputPrivate()
     : QNodePrivate()
@@ -66,9 +194,8 @@ QRenderTargetOutputPrivate::QRenderTargetOutputPrivate()
 }
 
 /*!
- * The constructor creates a new QRenderTargetOutput::QRenderTargetOutput instance
- * with the specified \a parent.
- * \param parent
+    The constructor creates a new QRenderTargetOutput::QRenderTargetOutput instance
+    with the specified \a parent.
  */
 QRenderTargetOutput::QRenderTargetOutput(QNode *parent)
     : QNode(*new QRenderTargetOutputPrivate, parent)
@@ -86,10 +213,6 @@ QRenderTargetOutput::QRenderTargetOutput(QRenderTargetOutputPrivate &dd, QNode *
 {
 }
 
-/*!
- * Sets the attachment point to \a attachmentPoint.
- * \param attachmentPoint
- */
 void QRenderTargetOutput::setAttachmentPoint(QRenderTargetOutput::AttachmentPoint attachmentPoint)
 {
     Q_D(QRenderTargetOutput);
@@ -99,9 +222,6 @@ void QRenderTargetOutput::setAttachmentPoint(QRenderTargetOutput::AttachmentPoin
     }
 }
 
-/*!
- * \return the current attachment point.
- */
 QRenderTargetOutput::AttachmentPoint QRenderTargetOutput::attachmentPoint() const
 {
     Q_D(const QRenderTargetOutput);
@@ -130,19 +250,12 @@ void QRenderTargetOutput::setTexture(QAbstractTexture *texture)
     }
 }
 
-/*!
- * \return the current texture.
- */
 QAbstractTexture *QRenderTargetOutput::texture() const
 {
     Q_D(const QRenderTargetOutput);
     return d->m_texture;
 }
 
-/*!
- * Sets the required mip level to \a level.
- * \param level
- */
 void QRenderTargetOutput::setMipLevel(int level)
 {
     Q_D(QRenderTargetOutput);
@@ -152,19 +265,12 @@ void QRenderTargetOutput::setMipLevel(int level)
     }
 }
 
-/*!
- * \return the current mip level.
- */
 int QRenderTargetOutput::mipLevel() const
 {
     Q_D(const QRenderTargetOutput);
     return d->m_mipLevel;
 }
 
-/*!
- * Sets the required layer to \a layer.
- * \param layer
- */
 void QRenderTargetOutput::setLayer(int layer)
 {
     Q_D(QRenderTargetOutput);
@@ -174,19 +280,12 @@ void QRenderTargetOutput::setLayer(int layer)
     }
 }
 
-/*!
- * \return the current layer.
- */
 int QRenderTargetOutput::layer() const
 {
     Q_D(const QRenderTargetOutput);
     return d->m_layer;
 }
 
-/*!
- * Sets the required cubemap face to \a face.
- * \param face
- */
 void QRenderTargetOutput::setFace(QAbstractTexture::CubeMapFace face)
 {
     Q_D(QRenderTargetOutput);
@@ -196,9 +295,6 @@ void QRenderTargetOutput::setFace(QAbstractTexture::CubeMapFace face)
     }
 }
 
-/*!
- * \return the current cubemap face.
- */
 QAbstractTexture::CubeMapFace QRenderTargetOutput::face() const
 {
     Q_D(const QRenderTargetOutput);