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>

2 files changed, 160 insertions, 2 deletions

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