diff options
| -rw-r--r-- | examples/qt3d/wireframe/doc/images/qt3d-wireframe-rendering.png | bin | 0 -> 214431 bytes | |||
| -rw-r--r-- | examples/qt3d/wireframe/doc/src/wireframe.qdoc | 166 | ||||
| -rw-r--r-- | src/core/doc/src/qt3d-overview.qdoc | 31 | ||||
| -rw-r--r-- | src/render/doc/qt3drenderer.qdocconf | 3 |
4 files changed, 197 insertions, 3 deletions
diff --git a/examples/qt3d/wireframe/doc/images/qt3d-wireframe-rendering.png b/examples/qt3d/wireframe/doc/images/qt3d-wireframe-rendering.png Binary files differnew file mode 100644 index 000000000..c05f9b492 --- /dev/null +++ b/examples/qt3d/wireframe/doc/images/qt3d-wireframe-rendering.png diff --git a/examples/qt3d/wireframe/doc/src/wireframe.qdoc b/examples/qt3d/wireframe/doc/src/wireframe.qdoc index 453be115d..2b0cdda62 100644 --- a/examples/qt3d/wireframe/doc/src/wireframe.qdoc +++ b/examples/qt3d/wireframe/doc/src/wireframe.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,168 @@ \example wireframe \title Qt3D: Wireframe QML Example \ingroup qt3d-examples-qml + + \brief A Qt3D QML application that implements a single-pass wireframe + rendering method. + + \image qt3d-wireframe-rendering.png + + \e {Qt3D Wireframe Rendering} illustrates how to draw a single entity + (a trefoil knot) using a custom set of shaders to implement a single-pass + wireframe rendering method. + + \include examples-run.qdocinc + + \section1 Creating Entities + + The renderer aspect looks for entities that have some geometry, a material, + and optionally a transformation. These are all specified in the form of + subclasses of QComponent that have been exported to the QML engine in the + form of \l Mesh, \l Material, and \l Transform. We use these components to + create a custom QML item in \e TrefoilKnot.qml. + + We start off by importing the \c {Qt3D 2.0} module that provides the + \l Entity type and value type helpers, such as Qt.vector3d(). We also import + the \c {Qt3D.Renderer} module that provides the components and other types + picked up by the renderer aspect: + + \quotefromfile wireframe/TrefoilKnot.qml + \skipto import Qt3D + \printuntil Renderer + + To use components from other aspects, we would need to import the + corresponding QML module, too. + + We then use an \l Entity type as the root element of the custom QML type + exposing some custom properties just as you would with any other type in + QML: + + \printuntil Material + + In addition to aggregating components, the \l Entity type can be used to + group child objects together. This is analogous to how the \l Item type is + used in Qt Quick 2. + + \section1 Specifying Transformations + + We instantiate a \l Transform component and a \l Mesh component. The + \l Transform component specifies how the renderer should transform the + geometry when it is drawn with the OpenGL pipeline. We combine an ordered + set of transformations into a single \l Transform component. This + information will be automatically available to our shaders through standard + named uniform variables: + + \skipto Transform + \printuntil phiRotation + \printuntil } + + \section1 Loading Dynamic Per-Vertex Data + + The \l Mesh component is very simple. We use its source property to load in + a static set of geometry (such as vertex positions, normal vectors, and + texture coordinates) from a file in the Wavefront Obj format. This data was + exported from the Blender application. + + \printuntil } + + In addition to the \l Mesh element, Qt3D also enables dynamic generation of + per-vertex attribute data through C++ hooks that are called by the + task-based engine. + + \section1 Aggregating Components + + Simply instantiating components is not enough, however. In order for them to + imbue special behavior on an entity, the entity must aggregate the + components by means of its components property: + + \quotefromfile wireframe/TrefoilKnot.qml + \skipto components + \printuntil ] + + This allows components to be shared between multiple entities very easily. + In this example, we have components for the transform and mesh that are + contained within the TrefoilKnot custom type. The final component, of type + \l Material, is provided by a property of the TrefoilKnot custom type. We + will later customize the appearance of the entity. + + \section1 Rendering from Cameras + + We use the TrefoilKnot custom type in \e main.qml to draw the trefoil knot + on the screen. + + We use the same import statements as in \e TrefoilKnot.qml, with the + addition of a namespaced import for the Qt Quick module that we will + need for animations: + + \quotefromfile wireframe/main.qml + \skipto import Qt3D + \printuntil QtQuick + + We use an \l Entity type as the root type simply to act as a parent for + its children. In this sense, the \l Entity type is much like the \l Item + type: + + \printuntil id + + The FrameGraph component uses the ForwardRenderer type to completely + configure the renderer without touching any C++ code: + + \printuntil ] + + The \l BasicCamera type is a trivial wrapper around the built-in \l Camera + type that represents a virtual camera. It has properties for such things as + the near and far planes, field of view, aspect ratio, projection type, + position, and orientation: + + \printuntil } + + The \l Configuration type provides a temporary workaround for having mouse + control of the camera while the proper implementation that uses aspects and + components is being completed: + + \printuntil } + + It is trivial to use multiple cameras and choose between them using the + framegraph for all or part of the scene rendering. + + \section1 Mapping Materials + + Qt3D has a robust and very flexible \l {Qt3D Overview#Materials}{material + system} that allows multiple levels of customization. We use the + WireframeMaterial custom type to wrap the \l Material type: + + \printuntil diffuse + + We then instantiate the TrefoilKnot type and set the material on it: + + \skipto TrefoilKnot + \printuntil } + + The Qt3D engine in conjunction with the renderer aspect now has enough + information to finally render our mesh using the material we specified. + + \section1 Using Animation Elements + + We use the animation elements provided by Qt Quick 2 to animate the + properties of the TrefoilKnot and WireframeMaterial types. The properties of + the components of a type are updated by using the QML property binding + mechanism: + + \quotefromfile wireframe/main.qml + \skipto SequentialAnimation + \printuntil PauseAnimation + \printuntil } + + The property updates are noticed by the \l{Qt3D::}{QNode} base class + and automatically sent through to the corresponding objects in the renderer + aspect. The renderer then takes care of translating the property updates + to new values for uniform variables in the GLSL shader programs. + + Run the example to view the trefoil knot with the width of the wireframe + lines pulsing. All the heavy lifting is being done by the GPU. The CPU only + has to run the property animations and to translate the scenegraph and + framegraph into raw OpenGL calls. + + It is also possible to animate on the GPU via a custom shader program and + material. */ diff --git a/src/core/doc/src/qt3d-overview.qdoc b/src/core/doc/src/qt3d-overview.qdoc index a02f32d83..74a4c2949 100644 --- a/src/core/doc/src/qt3d-overview.qdoc +++ b/src/core/doc/src/qt3d-overview.qdoc @@ -60,9 +60,9 @@ \list \li 2D and 3D rendering for C++ and Qt Quick applications \li Meshes - \li Materials + \li \l {Materials} \li Shadows - \li Shaders + \li \l {Shaders} \li Ambient occlusion \li High dynamic range \li Deferred rendering @@ -71,6 +71,33 @@ \li Uniform Buffer Objects \endlist + \section2 Materials + + Qt3D has a robust and very flexible material system that allows multiple + levels of customization. It caters for different rendering approaches on + different platforms or OpenGL versions, enables multiple rendering passes + with different state sets, provides mechanisms for overriding of parameters + at different levels, and allows easy switching of shaders. All this from C++ + or using QML property bindings. + + The properties of a \l Material type can easily be mapped through to uniform + variables in a GLSL shader program that is itself specified in the + referenced effect property. + + For examples of using materials, see the \l {Qt3D: Materials C++ Example} + and \l {Qt3D: Materials QML Example}. + + \section2 Shaders + + Qt3D supports all of the OpenGL programmable rendering pipeline stages: + vertex, tessellation control, tessellation evaluation, geometry, and + fragment shaders. Compute shaders are planned for a future release. + + For examples of using shaders, see the Simple Shaders QML Example, + \l {Qt3D: Tessellation Modes QML Example}, + \l {Qt3D: Shadow Map QML Example}, \l{Qt3D: Wireframe QML Example}, and + \l {Qt3D: Wave QML Example}. + \section1 Configurable Renderer To combine support for both C++ and QML APIs with having a fully diff --git a/src/render/doc/qt3drenderer.qdocconf b/src/render/doc/qt3drenderer.qdocconf index e56b6f992..add1cc90c 100644 --- a/src/render/doc/qt3drenderer.qdocconf +++ b/src/render/doc/qt3drenderer.qdocconf @@ -45,6 +45,9 @@ exampledirs += ../../../examples/qt3d \ imagedirs += images +examples.fileextensions += "*.fraq *.geom *.vert" +examples.imageextensions += "*.png" + Cpp.ignoretokens += QT3DRENDERERSHARED_EXPORT \ QT3DRENDERERSHARED_PRIVATE_EXPORT |
