blob: 4f8566ed03f8127b05b25e4866a4f7989104b121 [file] [log] [blame]
/****************************************************************************
**
** Copyright (C) 2015 Klaralvdalens Datakonsult AB (KDAB).
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** 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 Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example wireframe
\title Qt 3D: Wireframe QML Example
\ingroup qt3d-examples-qml
\brief A Qt 3D QML application that implements a single-pass wireframe
rendering method.
\image qt3d-wireframe-rendering.png
\e {Qt 3D 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 Render
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 }
\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, Qt 3D 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 QtQuick
\printuntil Render 2.0
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 RendererSettings component uses the ForwardRenderer type to completely
configure the renderer without touching any C++ code:
\printuntil ]
The 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
Qt 3D has a robust and very flexible \l {Qt 3D 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 Qt 3D 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{Qt3DCore::}{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.
*/