diff options
Diffstat (limited to 'tests/manual/shadow-map-qml/doc/src/shadow-map-qml.qdoc')
| -rw-r--r-- | tests/manual/shadow-map-qml/doc/src/shadow-map-qml.qdoc | 252 |
1 files changed, 252 insertions, 0 deletions
diff --git a/tests/manual/shadow-map-qml/doc/src/shadow-map-qml.qdoc b/tests/manual/shadow-map-qml/doc/src/shadow-map-qml.qdoc new file mode 100644 index 000000000..29cb4d391 --- /dev/null +++ b/tests/manual/shadow-map-qml/doc/src/shadow-map-qml.qdoc @@ -0,0 +1,252 @@ +// Copyright (C) 2015 Klaralvdalens Datakonsult AB (KDAB). +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \example shadow-map-qml + \title Qt 3D: Shadow Map QML Example + \ingroup qt3d-examples-qml + + \brief A Qt 3D QML application that illustrates how to render a scene in Qt 3D + with shadows. + + \image shadowmapping-qt3d.png + + \e {Qt 3D 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.Core + \printuntil Render 2.0 + + 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 frame graph, 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 ShadowMapLight.qml. + + Again, we import the necessary modules: + + \quotefromfile shadow-map-qml/ShadowMapLight.qml + \skipto import Qt3D + \printuntil Qt3D.Render + + 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 Qt 3D, the frame graph is the data-driven configuration for the rendering. + We implement the frame graph in the \e ShadowMapFrameGraph.qml file. + + In addition to the Qt 3D and Qt 3D Render modules, we also import the + Qt Quick module: + + \quotefromfile shadow-map-qml/ShadowMapFrameGraph.qml + \skipto import QtQuick + \printuntil Render 2.0 + + The code defines a \l RenderSettings node that has a tree of nodes as the + active frame graph: + + \badcode + RenderSettings { + activeFrameGraph: Viewport {...} + } + \endcode + + Any path from the leaves of this tree to the root is a viable frame graph + configuration. Filter entities can enable or disable such paths, and + selector entities can alter the configuration. + + In our case, the tree looks like this: + + \badcode + Viewport + RenderSurfaceSelector + RenderPassFilter + RenderTargetSelector + ClearBuffers + CameraSelector + RenderPassFilter + ClearBuffers + CameraSelector + \endcode + + So we have two paths from the topmost \l Viewport entity. Each path + corresponds to a pass, or phase, of the shadow map technique. The paths are + enabled and disabled using a RenderPassFilter, a node that can filter + depending on arbitrary values defined in a given render pass. In this + example, it is a string: + + \skipto RenderPassFilter + \printuntil ] + + The actual passes are not defined within the frame graph. Instead the + available passes are declared in the Materials used in the scene graph. The + frame graph is only used to select which passes are used when rendering. + + \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 Qt 3D, 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: + + \skipto RenderPassFilter + \printuntil } + \printuntil } + \printuntil } + \printuntil } + + \section1 Using Effects + + The bulk of the magic happens in the \e AdsEffect.qml file, where our main + \l Effect is defined. It implements the Ambient, Diffuse and Specular + (ADS) Lighting Model using Phong shading with the addition of shadow mapping. + + 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 shader program uniform variables, so that in the + shaders we can access their values. 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 frame graph: + + \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 {Technique}{Techniques} and a + \l RenderPass within a \l Technique. This allows a \l Material instance to + override defaults in an \l Effect, \l Technique or \l RenderPass. + + 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 a \l FilterKey object, matching the ones + we specified in the frame graph 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 } +*/ |