/usr/share/qt5/doc/qt3drenderer/qt3drenderer-wireframe-example.html is in qt3d5-doc-html 5.5.1-4ubuntu3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- wireframe.qdoc -->
<title>Qt3D: Wireframe QML Example | Qt3D Module 5.5</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li>Qt 5.5</li>
<li>Qt3D Module</li>
<li>Qt3D: Wireframe QML Example</li>
<li id="buildversion">Qt 5.5.1 Reference Documentation</li>
</ul>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#running-the-example">Running the Example</a></li>
<li class="level1"><a href="#creating-entities">Creating Entities</a></li>
<li class="level1"><a href="#specifying-transformations">Specifying Transformations</a></li>
<li class="level1"><a href="#loading-dynamic-per-vertex-data">Loading Dynamic Per-Vertex Data</a></li>
<li class="level1"><a href="#aggregating-components">Aggregating Components</a></li>
<li class="level1"><a href="#rendering-from-cameras">Rendering from Cameras</a></li>
<li class="level1"><a href="#mapping-materials">Mapping Materials</a></li>
<li class="level1"><a href="#using-animation-elements">Using Animation Elements</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt3D: Wireframe QML Example</h1>
<span class="subtitle"></span>
<!-- $$$wireframe-description -->
<div class="descr"> <a name="details"></a>
<p class="centerAlign"><img src="images/qt3d-wireframe-rendering.png" alt="" /></p><p><i>Qt3D Wireframe Rendering</i> illustrates how to draw a single entity (a trefoil knot) using a custom set of shaders to implement a single-pass wireframe rendering method.</p>
<a name="running-the-example"></a>
<h2 id="running-the-example">Running the Example</h2>
<p>To run the example from Qt Creator, open the <b>Welcome</b> mode and select the example from <b>Examples</b>. For more information, visit Building and Running an Example.</p>
<a name="creating-entities"></a>
<h2 id="creating-entities">Creating Entities</h2>
<p>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 Mesh, Material, and <a href="../qtquick/qml-qtquick-transform.html">Transform</a>. We use these components to create a custom QML item in <i>TrefoilKnot.qml</i>.</p>
<p>We start off by importing the <code>Qt3D 2.0</code> module that provides the Entity type and value type helpers, such as Qt.vector3d(). We also import the <code>Qt3D.Renderer</code> module that provides the components and other types picked up by the renderer aspect:</p>
<pre class="qml">import Qt3D 2.0
import Qt3D.Renderer 2.0</pre>
<p>To use components from other aspects, we would need to import the corresponding QML module, too.</p>
<p>We then use an 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:</p>
<pre class="qml"><span class="type">Entity</span> {
<span class="name">id</span>: <span class="name">root</span>
property <span class="type">alias</span> <span class="name">x</span>: <span class="name">translation</span>.<span class="name">dx</span>
property <span class="type">alias</span> <span class="name">y</span>: <span class="name">translation</span>.<span class="name">dy</span>
property <span class="type">alias</span> <span class="name">z</span>: <span class="name">translation</span>.<span class="name">dz</span>
property <span class="type">alias</span> <span class="name">scale</span>: <span class="name">scaleTransform</span>.<span class="name">scale</span>
property <span class="type">alias</span> <span class="name">theta</span>: <span class="name">thetaRotation</span>.<span class="name">angle</span>
property <span class="type">alias</span> <span class="name">phi</span>: <span class="name">phiRotation</span>.<span class="name">angle</span>
property <span class="type">Material</span> <span class="name">material</span></pre>
<p>In addition to aggregating components, the Entity type can be used to group child objects together. This is analogous to how the <a href="../qtquick/qml-qtquick-item.html">Item</a> type is used in Qt Quick 2.</p>
<a name="specifying-transformations"></a>
<h2 id="specifying-transformations">Specifying Transformations</h2>
<p>We instantiate a <a href="../qtquick/qml-qtquick-transform.html">Transform</a> component and a Mesh component. The <a href="../qtquick/qml-qtquick-transform.html">Transform</a> 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 <a href="../qtquick/qml-qtquick-transform.html">Transform</a> component. This information will be automatically available to our shaders through standard named uniform variables:</p>
<pre class="qml"> <span class="type"><a href="../qtquick/qml-qtquick-transform.html">Transform</a></span> {
<span class="name">id</span>: <span class="name">transform</span>
<span class="type"><a href="../qtquick/qml-qtquick-translate.html">Translate</a></span> { <span class="name">id</span>: <span class="name">translation</span> }
<span class="type"><a href="../qtquick/qml-qtquick-scale.html">Scale</a></span> { <span class="name">id</span>: <span class="name">scaleTransform</span> }
<span class="type">Rotate</span>{ <span class="name">id</span>: <span class="name">thetaRotation</span>; <span class="name">axis</span>: <span class="name">Qt</span>.<span class="name">vector3d</span>( <span class="number">1.0</span>, <span class="number">0.0</span>, <span class="number">0.0</span> ) }
<span class="type">Rotate</span>{ <span class="name">id</span>: <span class="name">phiRotation</span>; <span class="name">axis</span>: <span class="name">Qt</span>.<span class="name">vector3d</span>( <span class="number">0.0</span>, <span class="number">1.0</span>, <span class="number">0.0</span> ) }
}</pre>
<a name="loading-dynamic-per-vertex-data"></a>
<h2 id="loading-dynamic-per-vertex-data">Loading Dynamic Per-Vertex Data</h2>
<p>The 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.</p>
<pre class="qml"> <span class="type">Mesh</span> {
<span class="name">id</span>: <span class="name">mesh</span>
<span class="name">source</span>: <span class="string">"assets/obj/trefoil.obj"</span>
}</pre>
<p>In addition to the Mesh element, Qt3D also enables dynamic generation of per-vertex attribute data through C++ hooks that are called by the task-based engine.</p>
<a name="aggregating-components"></a>
<h2 id="aggregating-components">Aggregating Components</h2>
<p>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:</p>
<pre class="qml"> <span class="name">components</span>: [ <span class="name">transform</span>, <span class="name">mesh</span>, <span class="name">root</span>.<span class="name">material</span> ]</pre>
<p>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 Material, is provided by a property of the TrefoilKnot custom type. We will later customize the appearance of the entity.</p>
<a name="rendering-from-cameras"></a>
<h2 id="rendering-from-cameras">Rendering from Cameras</h2>
<p>We use the TrefoilKnot custom type in <i>main.qml</i> to draw the trefoil knot on the screen.</p>
<p>We use the same import statements as in <i>TrefoilKnot.qml</i>, with the addition of a namespaced import for the Qt Quick module that we will need for animations:</p>
<pre class="qml">import Qt3D 2.0
import Qt3D.Renderer 2.0
import QtQuick 2.1 as QQ2</pre>
<p>We use an Entity type as the root type simply to act as a parent for its children. In this sense, the Entity type is much like the <a href="../qtquick/qml-qtquick-item.html">Item</a> type:</p>
<pre class="qml"><span class="type">Entity</span> {
<span class="name">id</span>: <span class="name">root</span></pre>
<p>The <a href="qml-qt3d-renderer-framegraph.html">FrameGraph</a> component uses the ForwardRenderer type to completely configure the renderer without touching any C++ code:</p>
<pre class="qml"> <span class="comment">// Render from the mainCamera</span>
<span class="name">components</span>: [
<span class="type"><a href="qml-qt3d-renderer-framegraph.html">FrameGraph</a></span> {
<span class="name">activeFrameGraph</span>: <span class="name">ForwardRenderer</span> {
<span class="name">id</span>: <span class="name">renderer</span>
<span class="name">camera</span>: <span class="name">mainCamera</span>
}
}
]</pre>
<p>The BasicCamera type is a trivial wrapper around the built-in 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:</p>
<pre class="qml"> <span class="type">BasicCamera</span> {
<span class="name">id</span>: <span class="name">mainCamera</span>
<span class="name">position</span>: <span class="name">Qt</span>.<span class="name">vector3d</span>( <span class="number">0.0</span>, <span class="number">0.0</span>, <span class="number">15.0</span> )
}</pre>
<p>The 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:</p>
<pre class="qml"> <span class="type">Configuration</span> {
<span class="name">controlledCamera</span>: <span class="name">mainCamera</span>
}</pre>
<p>It is trivial to use multiple cameras and choose between them using the framegraph for all or part of the scene rendering.</p>
<a name="mapping-materials"></a>
<h2 id="mapping-materials">Mapping Materials</h2>
<p>Qt3D has a robust and very flexible material system that allows multiple levels of customization. We use the WireframeMaterial custom type to wrap the Material type:</p>
<pre class="qml"> <span class="type">WireframeMaterial</span> {
<span class="name">id</span>: <span class="name">wireframeMaterial</span>
<span class="name">effect</span>: <span class="name">WireframeEffect</span> {}
<span class="name">ambient</span>: <span class="name">Qt</span>.<span class="name">rgba</span>( <span class="number">0.2</span>, <span class="number">0.0</span>, <span class="number">0.0</span>, <span class="number">1.0</span> )
<span class="name">diffuse</span>: <span class="name">Qt</span>.<span class="name">rgba</span>( <span class="number">0.8</span>, <span class="number">0.0</span>, <span class="number">0.0</span>, <span class="number">1.0</span> )</pre>
<p>We then instantiate the TrefoilKnot type and set the material on it:</p>
<pre class="qml"> <span class="type">TrefoilKnot</span> {
<span class="name">id</span>: <span class="name">trefoilKnot</span>
<span class="name">material</span>: <span class="name">wireframeMaterial</span>
}</pre>
<p>The Qt3D engine in conjunction with the renderer aspect now has enough information to finally render our mesh using the material we specified.</p>
<a name="using-animation-elements"></a>
<h2 id="using-animation-elements">Using Animation Elements</h2>
<p>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:</p>
<pre class="qml"> <span class="type">QQ2</span>.SequentialAnimation {
<span class="name">loops</span>: <span class="name">QQ2</span>.<span class="name">Animation</span>.<span class="name">Infinite</span>
<span class="name">running</span>: <span class="number">true</span>
<span class="type">QQ2</span>.NumberAnimation {
<span class="name">target</span>: <span class="name">wireframeMaterial</span>;
<span class="name">property</span>: <span class="string">"lineWidth"</span>;
<span class="name">duration</span>: <span class="number">1000</span>;
<span class="name">from</span>: <span class="number">0.8</span>
<span class="name">to</span>: <span class="number">1.8</span>
}
<span class="type">QQ2</span>.NumberAnimation {
<span class="name">target</span>: <span class="name">wireframeMaterial</span>;
<span class="name">property</span>: <span class="string">"lineWidth"</span>;
<span class="name">duration</span>: <span class="number">1000</span>;
<span class="name">from</span>: <span class="number">1.8</span>
<span class="name">to</span>: <span class="number">0.8</span>
}
<span class="type">QQ2</span>.PauseAnimation { <span class="name">duration</span>: <span class="number">1500</span> }
}</pre>
<p>The property updates are noticed by the 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.</p>
<p>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.</p>
<p>It is also possible to animate on the GPU via a custom shader program and material.</p>
<p>Files:</p>
<ul>
<li><a href="qt3drenderer-wireframe-basiccamera-qml.html">wireframe/BasicCamera.qml</a></li>
<li><a href="qt3drenderer-wireframe-trefoilknot-qml.html">wireframe/TrefoilKnot.qml</a></li>
<li><a href="qt3drenderer-wireframe-wireframeeffect-qml.html">wireframe/WireframeEffect.qml</a></li>
<li><a href="qt3drenderer-wireframe-wireframematerial-qml.html">wireframe/WireframeMaterial.qml</a></li>
<li><a href="qt3drenderer-wireframe-main-qml.html">wireframe/main.qml</a></li>
<li><a href="qt3drenderer-wireframe-shaders-robustwireframe-geom.html">wireframe/shaders/robustwireframe.geom</a></li>
<li><a href="qt3drenderer-wireframe-shaders-robustwireframe-vert.html">wireframe/shaders/robustwireframe.vert</a></li>
<li><a href="qt3drenderer-wireframe-main-cpp.html">wireframe/main.cpp</a></li>
<li><a href="qt3drenderer-wireframe-wireframe-pro.html">wireframe/wireframe.pro</a></li>
<li><a href="qt3drenderer-wireframe-wireframe-qrc.html">wireframe/wireframe.qrc</a></li>
</ul>
</div>
<!-- @@@wireframe -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|