Doc: Add some docs for the shadow map example

Change-Id: Iea29c9f654fc57518bf3d428b30fa5955aa1230d
Reviewed-by: Sean Harmer <sean.harmer@kdab.com>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@theqtcompany.com>

3 files changed, 239 insertions, 1 deletions

diff --git a/examples/qt3d/shadow-map-qml/doc/images/shadowmapping-depth.png b/examples/qt3d/shadow-map-qml/doc/images/shadowmapping-depth.png
new file mode 100644
index 000000000..d2b501412
--- /dev/null
+++ b/examples/qt3d/shadow-map-qml/doc/images/shadowmapping-depth.png
diff --git a/examples/qt3d/shadow-map-qml/doc/images/shadowmapping-qt3d.png b/examples/qt3d/shadow-map-qml/doc/images/shadowmapping-qt3d.png
new file mode 100644
index 000000000..bac6ac75c
--- /dev/null
+++ b/examples/qt3d/shadow-map-qml/doc/images/shadowmapping-qt3d.png
diff --git a/examples/qt3d/shadow-map-qml/doc/src/shadow-map-qml.qdoc b/examples/qt3d/shadow-map-qml/doc/src/shadow-map-qml.qdoc
index 4e55da3b1..fd3377a8b 100644
--- a/examples/qt3d/shadow-map-qml/doc/src/shadow-map-qml.qdoc
+++ b/examples/qt3d/shadow-map-qml/doc/src/shadow-map-qml.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2015 The Qt Company Ltd.
+** Copyright (C) 2015 Klaralvdalens Datakonsult AB (KDAB).
 ** Contact: http://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -29,4 +29,242 @@
     \example shadow-map-qml
     \title Qt3D: Shadow Map QML Example
     \ingroup qt3d-examples-qml
+
+    \brief A Qt3D QML application that illustrates how to render a scene in Qt3D
+    with shadows.
+
+    \image shadowmapping-qt3d.png
+
+    \e {Qt3D Shadow Map} illustrates how to configure the renderer in order to
+    accommodate custom rendering techniques. The example application displays a
+    self-shadowed plane and trefoil knot.
+
+    We implement \l{Shadow Mapping}{shadow mapping} using a two pass rendering.
+    In the first pass, we generate the shadow information. In the second pass,
+    we generate the scene using the forward rendering technique with Phong
+    shading, while at the same time using the information gathered in the first
+    pass to draw the shadows.
+
+    The entire rendering is configured using QML, but it is possible to use C++
+    to achieve the very same result.
+
+    \include examples-run.qdocinc
+
+    \section1 Setting Up the Scene
+
+    We set up the entire scene in the \e main.qml file.
+
+    To be able to use the types in the Q3D and Q3D Renderer modules, we must
+    import the modules:
+
+    \quotefromfile shadow-map-qml/main.qml
+    \skipto import Qt3D
+    \printuntil Renderer
+
+    The first entities we create are a \l Camera, which represents the camera
+    used for the final rendering, and a \l Configuration, which allows us to
+    control this camera using the keyboard or the mouse:
+
+    \printuntil }
+    \printuntil }
+
+    We then create a Light custom entity, which represents our light. It is a
+    directional spotlight, placed somewhere above the plane and looking down at
+    the scene’s origin:
+
+    \printuntil }
+
+    This light entity is used by our custom framegraph, ShadowMapFrameGraph,
+    and our rendering effect, AdsEffect, whose instances are created just after
+    the light:
+
+    \printuntil ]
+    \printuntil }
+
+    Last, we create three entities for the meshes in the scene: a trefoil knot,
+    a toy plane, and a ground plane. They aggregate a mesh, a transformation,
+    and a material that uses the AdsEffect. The toy plane and the trefoil knot
+    transformations are animated:
+
+    \printuntil /^\}/
+
+    \section1 Specifying the Light
+
+    We specify the Light custom entity in \e Light.qml.
+
+    Again, we import the necessary modules:
+
+    \quotefromfile shadow-map-qml/Light.qml
+    \skipto import Qt3D
+    \printuntil Qt3D.Renderer
+
+    We then use an \l Entity type as the root element of the custom QML type.
+    The light is a directional spotlight that exposes as properties a position,
+    intensity, and a 4×4 transformation matrix:
+
+    \printuntil matrix4x4
+
+    In the first rendering pass, we use the light as a camera, and therefore we
+    use a \l Camera entity within the light and expose it as a property:
+
+    \printuntil /^\}/
+
+    \section1 Configuring the Framegraph
+
+    In Qt3D, the framegraph is the data-driven configuration for the rendering.
+    We implement the framegraph in the \e ShadowMapFrameGraph.qml file.
+
+    In addition to the Qt3D and Qt3D Renderer modules, we also import the
+    Qt Quick module:
+
+    \quotefromfile shadow-map-qml/ShadowMapFrameGraph.qml
+    \skipto import Qt3D
+    \printuntil QtQuick
+
+    The code defines a \l FrameGraph entity that has a tree of entities as the
+    active framegraph:
+
+    \printuntil clearColor
+
+    Any path from the leaves of this tree to the root is a viable framegraph
+    configuration. Filter entities can enable or disable such paths, and
+    selector entities can alter the configuration.
+
+    In our case, the tree looks like this:
+
+    \code
+    Viewport
+        RenderPassFilter
+            RenderTargetSelector
+                ClearBuffer
+                    CameraSelector
+        RenderPassFilter
+            ClearBuffer
+                CameraSelector
+    \endcode
+
+    So we have two paths from the topmost \l Viewport entity. Each path
+    corresponds to a pass of the shadow map technique. The paths are enabled and
+    disabled using a RenderPassFilter, an entity that can filter depending on
+    arbitrary values defined in a given render pass. In this example, it is a
+    string:
+
+    \printuntil ]
+
+    The actual passes are not defined here. The framegraph simply modifies its
+    configuration when a given pass is rendered.
+
+    \section1 Generating the Shadow Map
+
+    In the shadow map generation pass, we must render to an offscreen surface
+    (Framebuffer Object) which has a depth texture attachment. In Qt3D, it is
+    represented by the RenderTarget entity, which has a number of attachments.
+
+    In this example, we need only a depth attachment. We define it as a
+    RenderAttachment entity using the RenderAttachment.DepthAttachment \c type
+    that stores the depth and a Texture2D entity that actually configures the
+    exture storage used to store the depth information:
+
+    \printuntil ]
+    \printuntil }
+
+    Moreover, in this first pass, we must render using the light’s camera.
+    Therefore, we have a CameraSelector entity that sets the camera to the one
+    exported by the Light:
+
+    \skipto CameraSelector
+    \printuntil }
+
+    The second pass is more straightforward, because we simply render to the
+    screen using the main camera.
+
+    \section1 Using Effects
+
+    The bulk of the magic happens in the \e AdsEffect.qml file, where our main
+    \l Effect entity is defined. It implements the Ambient, Diffuse and Specular
+    (ADS) Lightning Model Phong shading with the addition of shadow mapped
+    generated shadows.
+
+    An effect contains the implementation of a particular rendering strategy. In
+    this example, shadow mapping using two passes:
+
+    \quotefromfile shadow-map-qml/AdsEffect.qml
+    \skipto Effect
+    \printuntil Light
+
+    The \c parameters list defines some default values for the effect. The
+    values will get mapped to OpenGL shader program uniforms, so that in the
+    shaders we can access them. In this example, we expose some information from
+    the Light entity (position, intensity, view or projection matrix defined by
+    the internal camera) and the shadow map texture exposed by the framegraph:
+
+    \skipto parameters:
+    \printuntil ]
+
+    It is possible to put such parameters all the way down, from a \l Material,
+    to its \l Effect, to one of the effect’s \l Techniques. This allows a
+    \l Material instance to override defaults in an \l Effect or \l Technique.
+    The bindings array provides the same thing, except that it also allows us to
+    rename some parameters. In this example, it renames the \c ambient,
+    \c diffuse, and \c specular values defined in the material to the actual
+    uniform names used by the shader programs:
+
+    \skipto bindings:
+    \printuntil ]
+
+    To adapt the implementation to different hardware or OpenGL versions, we
+    could use one or more \l Technique elements. In this example, only one
+    technique is provided, targeting OpenGL 3.2 Core, or later:
+
+    \quotefromfile shadow-map-qml/AdsEffect.qml
+    \skipto techniques:
+    \printuntil }
+
+    Inside the technique, we finally have the definition of our two rendering
+    passes. We \e tag each pass with an \l Annotation entity, matching the ones
+    we specified in the framegraph configuration, so that each pass will have
+    different rendering settings:
+
+    \printuntil ]
+
+    The first pass is the shadow map generation. We load a suitable set of GLSL
+    shaders, which are actually extremely simple. They do only MVP (Model, View,
+    Projection) to bring meshes from their model space into clip space (and,
+    remember, in this first pass, the light is the camera). The fragment shader
+    is totally empty, because there is no color to be generated, and the depth
+    will be automatically captured for us by OpenGL:
+
+    \printuntil }
+
+    In this first pass, we also set some custom OpenGL state in the form of a
+    polygon offset and depth testing mode:
+
+    \printuntil ]
+
+    \section1 Rendering Using Phong Shading
+
+    The second pass is a normal forward rendering using Phong shading. The code
+    in the effect entity is extremely simple. We simply configure some
+    parameters and load a pair of shaders which will be used when drawing.
+
+    The first part of the shadow mapping happens in the vertex shader defined in
+    \e ads.vert file, where we output towards the fragment shader the
+    coordinates of each vertex in light space:
+
+    \quotefromfile shadow-map-qml/shaders/ads.vert
+    \skipto mat4(
+    \skipto positionInLightSpace
+    \printuntil ;
+
+    Actually, the coordinates get adjusted a little to allow us to easily sample
+    the shadow map texture.
+
+    The second part happens in the fragment shader defined in the \e ads.frag
+    file, where we sample the shadow map. If the currently processed fragment is
+    behind the one closest to the light, then the current fragment is in shadow
+    (and only gets ambient contribution). Otherwise, it gets full Phong shading:
+
+    \quotefromfile shadow-map-qml/shaders/ads.frag
+    \skipto main
+    \printuntil }
 */