Doc: add a section about common rendering issues

Change-Id: I8c4d03df80d022db2f7d32330d41d7f24bae40d2
Reviewed-by: Sean Harmer <sean.harmer@kdab.com>

2 files changed, 136 insertions, 0 deletions

diff --git a/src/doc/src/qt3d-overview.qdoc b/src/doc/src/qt3d-overview.qdoc
index 9bbd7f988..e22e2ba4e 100644
--- a/src/doc/src/qt3d-overview.qdoc
+++ b/src/doc/src/qt3d-overview.qdoc
@@ -72,6 +72,7 @@
         \li Multitexturing
         \li \l {Instanced Rendering}{Instanced rendering}
         \li \l {Uniform Buffer Objects}
+        \li \l {Pro Tips}
     \endlist
 
     \section2 Materials
@@ -181,6 +182,11 @@
     large amounts of data readily available. Typical use cases for UBOs are for
     sets of material or lighting parameters.
 
+    \section2 Pro Tips
+
+    Because Murphy's law proves to often be true when it comes to 3D rendering,
+    \l {Qt 3D Render Pro Tips}{here} are a few points that might help you.
+
     \section1 Configurable Renderer
 
     To combine support for both C++ and QML APIs with having a fully
diff --git a/src/doc/src/qt3drender-protips.qdoc b/src/doc/src/qt3drender-protips.qdoc
new file mode 100644
index 000000000..c78f3d598
--- /dev/null
+++ b/src/doc/src/qt3drender-protips.qdoc
@@ -0,0 +1,130 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 Klaralvdalens Datakonsult AB (KDAB).
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt3D module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or (at your option) the GNU General
+** Public license version 3 or any later version approved by the KDE Free
+** Qt Foundation. The licenses are as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-2.0.html and
+** https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page qt3drender-protips.html
+    \title Qt 3D Render Pro Tips
+
+    \brief This sections tries to make you aware of various pitfalls inherent
+    to 3D rendering and ways to prevent them.
+
+    To render even the simplest shapes, Qt 3D needs to perform various
+    operations through several stages. If anything goes wrong at any of these
+    stages you may end up, in the best cases with something different than what
+    you expected, in the worst cases with a black screen.
+
+    \list
+        \li \l {Technique Selection}
+        \li \l {Order Matters}
+        \li \l {Blending}
+        \li \l {Useful Tools}
+    \endlist
+
+    \section2 Technique Selection
+
+     Qt 3D provides a technique selection mechanism allowing you to provide
+     shaders for various rendering APIs and versions of these APIs.
+
+     In order to avoid unnecessary waste of your time, you should make sure
+     that your technique's API filter data is correct for the platform you are
+     targeting.
+
+     \section2 Order Matters
+
+     The order of the draw calls performed by the renderer is not necessarily
+     the same as the order of the entities in the scene.
+
+     The renderer tries to optimize calls that are sent to the graphics API.
+     It orders draw calls based on the material/shader being used, the render
+     states that are defined for a given material, their depth, the parameters
+     shared in common between two materials, etc.
+
+     If your rendering depends on a specific draw order you should then have
+     a few options:
+
+    \list
+
+     \li Filtering with a Qt3DRender::QLayer component and
+     Qt3DRender::QLayerFilter in the FrameGraph
+
+     \li RenderPass or Technique filtering using Qt3DRender::QRenderPassFilter
+     or Qt3DRender::QTechniqueFilter in the FrameGraph
+
+     \endlist
+
+     \section2 Blending
+
+     Mastering blending with proper arguments and functions is an art in
+     itself. Therefore obtaining the proper visual result is often hit and
+     miss.
+
+     \l {http://www.andersriggelsen.dk/glblendfunc.php}{Anders Riggelsen's
+     online visualizer} may help you find out which arguments and functions
+     work for you.
+
+     \section3 Blending with Scene3D
+
+     When rendering a Qt 3D scene through a Qt Quick scene with the Scene3D
+     element you should be aware that you might have to adjust the blending
+     arguments of your render state to obtain a sensible rendering. This is
+     because of the way Qt 3D first renders a scene into an offscreen texture
+     which is then blended in with the rest of the Qt Quick scene.
+
+     Sensible values are often Qt3DRender::QBlendEquationArguments::Zero for
+     the source alpha and Qt3DRender::QBlendEquationArguments::One for the
+     destination alpha.
+
+     \section2 Useful Tools
+
+     Given the rather limited of troubleshooting given by Qt 3D in its first
+     versions it sometimes helps to have tools to capture OpenGL draw calls and
+     get more clues about what's happening
+
+     \list
+     \li \l {https://github.com/apitrace/apitrace}{apitrace}
+     \li \l {https://github.com/ValveSoftware/vogl}{vogl}
+     \endlist
+
+     These tools allow you to gather traces of all the OpenGL calls being made
+     by a Qt 3D application. Having a look at a generated trace file may help
+     you verify that draw calls are being made, textures correctly uploaded,
+     uniforms set with proper values, ...
+
+     There are plans for Qt 3D tooling in later releases.
+ */