Doc: Add and improve examples in render states and material system

Also switch \code to \qml.

Change-Id: I3f216a3abd55fdf51295ed14715f6f1ffc5e2ea4
Reviewed-by: Paul Lemire <paul.lemire@kdab.com>
Reviewed-by: Nico Vertriest <nico.vertriest@qt.io>

5 files changed, 255 insertions, 21 deletions

diff --git a/src/render/framegraph/qrenderstateset.cpp b/src/render/framegraph/qrenderstateset.cpp
index 4e3e4ab0b..f44e9d50f 100644
--- a/src/render/framegraph/qrenderstateset.cpp
+++ b/src/render/framegraph/qrenderstateset.cpp
@@ -71,6 +71,31 @@ QRenderStateSetPrivate::QRenderStateSetPrivate()
     executed. Adding a QRenderState state explicitly enables that render
     state at runtime.
 
+    The RenderStateSet is enabled when added to the active frame graph:
+
+    \code
+    // using namespace Qt3DRender;
+
+    Qt3DCore::QEntity *rootEntity = new Qt3DCore::QEntity();
+
+    QRenderSettings *renderSettings = new QRenderSettings();
+
+    QViewport *viewport = new QViewport();
+    QCameraSelector *cameraSelector = new QCameraSelector(viewport);
+
+    QClearBuffers *clearBuffers = new QClearBuffers(cameraSelector);
+    clearBuffers->setBuffers(QClearBuffers::ColorDepthBuffer);
+
+    QRenderStateSet *renderStateSet = new QRenderStateSet(cameraSelector);
+    QCullFace *cullFace = new QCullFace(renderStateSet);
+    cullFace->setMode(QCullFace::Front);
+    renderStateSet->addRenderState(cullFace);
+
+    renderSettings->setActiveFrameGraph(viewport);
+
+    rootEntity->addComponent(renderSettings);
+    \endcode
+
     \sa QRenderState, QRenderPass
  */
 
@@ -90,6 +115,47 @@ QRenderStateSetPrivate::QRenderStateSetPrivate()
     executed. Adding a RenderState state explicitly enables that render
     state at runtime.
 
+    The RenderStateSet is enabled when added to the active frame graph:
+
+    \qml
+    import Qt3D.Core 2.0
+    import Qt3D.Render 2.0
+    import Qt3D.Extras 2.0
+
+    Entity {
+        id: rootNode
+        components: [
+            RenderSettings {
+                activeFrameGraph: RenderSurfaceSelector {
+                    ClearBuffers {
+                        buffers : ClearBuffers.ColorDepthBuffer
+
+                        CameraSelector {
+                            camera: Camera {
+                                position: Qt.vector3d(10, 0, 0)
+                                viewCenter: Qt.vector3d(0, 0, 0)
+                            }
+                            RenderStateSet {
+                                renderStates: [
+                                    CullFace { mode: CullFace.Back }
+                                ]
+                            }
+                        }
+                    }
+                }
+            }
+        ]
+
+        Entity {
+            id: sphereEntity
+            components: [
+                SphereMesh {},
+                PhongMaterial {}
+            ]
+        }
+    }
+    \endqml
+
     \sa RenderState, RenderPass
  */
 
diff --git a/src/render/materialsystem/qrenderpass.cpp b/src/render/materialsystem/qrenderpass.cpp
index 61f844be3..111bb7b5f 100644
--- a/src/render/materialsystem/qrenderpass.cpp
+++ b/src/render/materialsystem/qrenderpass.cpp
@@ -87,23 +87,33 @@ QRenderPassPrivate::QRenderPassPrivate()
     FrameGraph branch. Each RenderPass can overload this base render state by
     specifying its own RenderState nodes.
 
-    \code
-    RenderPass {
-        id: pass
-        shaderProgram: ShaderProgram {
-            ...
-        }
-        parameters: [
-            Parameters { name: "color"; value: "red" }
-        ]
+    \qml
+    Technique {
         filterKeys: [
-            FilterKey { name: "name"; value: "zFillPass" }
+            FilterKey { name: "renderingStyle"; value: "forward" }
         ]
-        renderStates: [
-            DepthTest { }
+        graphicsApiFilter: {
+            api: GraphicsApiFilter.OpenGL
+            profile: GraphicsApiFilter.CoreProfile
+            majorVersion: 3
+            minorVersion: 1
+        }
+        renderPasses: [
+            RenderPass {
+                id: pass
+                shaderProgram: ShaderProgram {
+                    // ...
+                }
+                parameters: [
+                    Parameter { name: "color"; value: "red" }
+                ]
+                renderStates: [
+                    DepthTest {}
+                ]
+            }
         ]
     }
-    \endcode
+    \endqml
 
     \sa RenderPassFilter, FilterKey, Parameter, RenderState, Effect, Technique
  */
diff --git a/src/render/materialsystem/qtechnique.cpp b/src/render/materialsystem/qtechnique.cpp
index df142cdee..b668eb25f 100644
--- a/src/render/materialsystem/qtechnique.cpp
+++ b/src/render/materialsystem/qtechnique.cpp
@@ -90,16 +90,16 @@ QTechniquePrivate::~QTechniquePrivate()
     QSurfaceFormat::setDefaultFormat(). Setting the QSurfaceFormat on the view
     will likely have no effect on Qt3D related rendering.
 
-    \code
+    \qml
     Technique {
         id: gl3Technique
         parameters: [
             Parameter { name: "color"; value: "orange" }
         ]
         filterKeys: [
-            FilterKey { name: "name"; value: "zFillTechnique" }
+            FilterKey { name: "renderingStyle"; value: "forward" }
         ]
-        graphicsApiFilter {
+        graphicsApiFilter: {
             api: GraphicsApiFilter.OpenGL
             profile: GraphicsApiFilter.CoreProfile
             majorVersion: 3
@@ -109,18 +109,18 @@ QTechniquePrivate::~QTechniquePrivate()
             RenderPass {
                 id: firstPass
                 shaderProgram: ShaderProgram {
-                    ...
+                    // ...
                 }
             },
             RenderPass {
                 id: secondPass
                 shaderProgram: ShaderProgram {
-                    ...
+                    // ...
                 }
             }
         ]
     }
-    \endcode
+    \endqml
 
     \sa Effect, RenderPass, TechniqueFilter
  */
diff --git a/src/render/renderstates/qalphacoverage.cpp b/src/render/renderstates/qalphacoverage.cpp
index 428454040..6383f2469 100644
--- a/src/render/renderstates/qalphacoverage.cpp
+++ b/src/render/renderstates/qalphacoverage.cpp
@@ -59,6 +59,34 @@ namespace Qt3DRender {
     order independent blending is required, for example when rendering leaves,
     grass and other rich vegetation.
 
+    It can be added to a QRenderPass by calling QRenderPass::addRenderState():
+
+    \code
+    QRenderPass *renderPass = new QRenderPass();
+
+    // Create a alpha coverage render state
+    QAlphaCoverage *alphaCoverage = new QAlphaCoverage();
+    QMultiSampleAntiAliasing *multiSampleAntialiasing = new QMultiSampleAntiAliasing();
+
+    // Add the render states to the render pass
+    renderPass->addRenderState(alphaCoverage);
+    renderPass->addRenderState(multiSampleAntialiasing);
+    \endcode
+
+    Or to a QRenderStateSet by calling QRenderStateSet::addRenderState():
+
+    \code
+    QRenderStateSet *renderStateSet = new QRenderStateSet();
+
+    // Create a alpha coverage render state
+    QAlphaCoverage *alphaCoverage = new QAlphaCoverage();
+    QMultiSampleAntiAliasing *multiSampleAntialiasing = new QMultiSampleAntiAliasing();
+
+    // Add the render states to the render state set
+    renderStateSet->addRenderState(alphaCoverage);
+    renderStateSet->addRenderState(multiSampleAntialiasing);
+    \endcode
+
     \sa Qt3DRender::QMultiSampleAntiAliasing
  */
 
@@ -78,6 +106,31 @@ namespace Qt3DRender {
     order independent blending is required, for example when rendering leaves,
     grass and other rich vegetation.
 
+    It can be added to a RenderPass:
+
+    \qml
+    RenderPass {
+        shaderProgram: ShaderProgram {
+            // ...
+        }
+        renderStates: [
+            AlphaCoverage {},
+            MultiSampleAntiAliasing {}
+        ]
+    }
+    \endqml
+
+    Or to a RenderStateSet:
+
+    \qml
+    RenderStateSet {
+        renderStates: [
+            AlphaCoverage {},
+            MultiSampleAntiAliasing {}
+        ]
+    }
+    \endqml
+
     \sa MultiSampleAntiAliasing
  */
 
diff --git a/src/render/renderstates/qmultisampleantialiasing.cpp b/src/render/renderstates/qmultisampleantialiasing.cpp
index 923fc435e..156489008 100644
--- a/src/render/renderstates/qmultisampleantialiasing.cpp
+++ b/src/render/renderstates/qmultisampleantialiasing.cpp
@@ -54,7 +54,56 @@ namespace Qt3DRender {
     \inmodule Qt3DRender
 
     A Qt3DRender::QMultiSampleAntiAliasing class enables multisample antialiasing.
-    The render target must have been allocated with multisampling enabled.
+
+    It can be added to a QRenderPass by calling QRenderPass::addRenderState():
+
+    \code
+    QRenderPass *renderPass = new QRenderPass();
+
+    QMultiSampleAntiAliasing *msaa = new QMultiSampleAntiAliasing();
+    renderPass->addRenderState(msaa);
+    \endcode
+
+    Or a QRenderStateSet by calling QRenderStateSet::addRenderState():
+
+    \code
+    QRenderStateSet *renderStateSet = new QRenderStateSet();
+
+    QMultiSampleAntiAliasing *msaa = new QMultiSampleAntiAliasing();
+    renderStateSet->addRenderState(msaa);
+    \endcode
+
+    For multisampling to take effect, the render target must have been allocated
+    with multisampling enabled:
+
+    \code
+    QTexture2DMultisample *colorTex = new QTexture2DMultisample;
+    colorTex->setFormat(QAbstractTexture::RGBA8_UNorm);
+    colorTex->setWidth(1024);
+    colorTex->setHeight(1024);
+
+    QRenderTargetOutput *color = new QRenderTargetOutput;
+    color->setAttachmentPoint(QRenderTargetOutput::Color0);
+    color->setTexture(colorTex);
+
+    QTexture2DMultisample *depthStencilTex = new QTexture2DMultisample;
+    depthStencilTex->setFormat(QAbstractTexture::RGBA8_UNorm);
+    depthStencilTex->setWidth(1024);
+    depthStencilTex->setHeight(1024);
+
+    QRenderTargetOutput *depthStencil = new QRenderTargetOutput;
+    depthStencil->setAttachmentPoint(QRenderTargetOutput::DepthStencil);
+    depthStencil->setTexture(depthStencilTex);
+
+    Qt3DRender::QRenderTarget *renderTarget = new Qt3DRender::QRenderTarget;
+    renderTarget->addOutput(color);
+    renderTarget->addOutput(depthStencil);
+    \endcode
+
+    \include code/src_render_renderstates_qmultisampleantialiasing.qdocinc
+
+    \note When using OpenGL as the graphics API, glEnable(GL_MULTISAMPLE) will be called if
+    QMultiSampleAntiAliasing has been added to the render states.
  */
 
 /*!
@@ -67,7 +116,63 @@ namespace Qt3DRender {
     \instantiates Qt3DRender::QMultiSampleAntiAliasing
 
     A MultiSampleAntiAliasing type enables multisample antialiasing.
-    The render target must have been allocated with multisampling enabled.
+
+    It can be added to a RenderPass:
+
+    \qml
+    RenderPass {
+        shaderProgram: ShaderProgram {
+            // ...
+        }
+        renderStates: [
+            MultiSampleAntiAliasing {}
+        ]
+    }
+    \endqml
+
+    Or a RenderStateSet:
+
+    \qml
+    RenderStateSet {
+        renderStates: [
+            MultiSampleAntiAliasing {}
+        ]
+    }
+    \endqml
+
+    For multisampling to take effect, the render target must have been allocated
+    with multisampling enabled:
+
+    \qml
+    RenderTarget {
+        attachments: [
+            RenderTargetOutput {
+                attachmentPoint: RenderTargetOutput.Color0
+                texture: Texture2DMultisample {
+                    width: 1024
+                    height: 1024
+                    format: Texture.RGBA8_UNorm
+                }
+            },
+            RenderTargetOutput {
+                attachmentPoint: RenderTargetOutput.DepthStencil
+                texture: Texture2DMultisample{
+                    width: 1024
+                    height: 1024
+                    format: Texture.D24S8
+                }
+            }
+        ]
+    }
+    \endqml
+
+    Further, the shader code must use multisampling sampler types and texelFetch() instead
+    of texture().
+
+    \include code/src_render_renderstates_qmultisampleantialiasing.qdocinc
+
+    \note When using OpenGL as the graphics API, glEnable(GL_MULTISAMPLE) will be called if
+    MultiSampleAntiAliasing has been added to the render states.
  */
 
 class QMultiSampleAntiAliasingPrivate : public QRenderStatePrivate