diff options
Diffstat (limited to 'src/doc')
-rw-r--r-- | src/doc/src/qt3d-overview.qdoc | 6 | ||||
-rw-r--r-- | src/doc/src/qt3drender-protips.qdoc | 130 |
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. + */ |