<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- scene2d.qdoc -->
<title>Qt 3D: Scene2D QML Example | Qt 3D 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.9</td><td ><a href="qt3d-index.html">Qt 3D</a></td><td >Qt 3D: Scene2D QML Example</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</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="#setting-up-the-3d-scene">Setting up the 3D Scene</a></li>
<li class="level1"><a href="#rendering-qt-quick-into-a-texture">Rendering Qt Quick into a Texture</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt 3D: Scene2D QML Example</h1>
<span class="subtitle"></span>
<!-- $$$scene2d-description -->
<div class="descr"> <a name="details"></a>
<p class="centerAlign"><img src="images/scene2d.png" alt="" /></p><p><i><a href="qt3dscene2d-module.html#scene2d">Scene2D</a></i> demonstrates rendering a Qt Quick 2 scene into a texture and utilising the texture within a Qt 3D application including handling mouse events. The 3D scene contains a single active camera and renders a 3D Qt logo along with some controls declared with Qt Quick Controls.</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="setting-up-the-3d-scene"></a>
<h2 id="setting-up-the-3d-scene">Setting up the 3D Scene</h2>
<p>We set up the 3D scene in an Entity that acts as the root of the object tree. The virtual camera is specified in <i>main.qml</i>:</p>
<pre class="qml">
<span class="type"><a href="qml-qt3d-render-camera.html">Camera</a></span> {
<span class="name">id</span>: <span class="name">camera</span>
<span class="name">projectionType</span>: <span class="name">CameraLens</span>.<span class="name">PerspectiveProjection</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">20</span> )
}
</pre>
<p>The <a href="qml-qt3d-render-rendersettings.html">RenderSettings</a> specify the rendering algorithm used and also enable triangle based picking which is needed to properly handle mouse events when projecting a Qt Quick scene onto 3D geometry:</p>
<pre class="qml">
<span class="type"><a href="qml-qt3d-render-rendersettings.html">RenderSettings</a></span> {
<span class="name">activeFrameGraph</span>: <span class="name">ForwardRenderer</span> {
<span class="name">camera</span>: <span class="name">camera</span>
<span class="name">clearColor</span>: <span class="string">"white"</span>
}
<span class="name">pickingSettings</span>.pickMethod: <span class="name">PickingSettings</span>.<span class="name">TrianglePicking</span>
},
</pre>
<p>The 3D Qt logo that will be controlled by the controls in the Qt Quick scene is declared with:</p>
<pre class="qml">
<span class="type"><a href="qml-qt3d-core-entity.html">Entity</a></span> {
<span class="name">id</span>: <span class="name">logoEntity</span>
<span class="type"><a href="qml-qt3d-core-transform.html">Transform</a></span> {
<span class="name">id</span>: <span class="name">logoTransform</span>
<span class="name">scale</span>: <span class="number">1</span>
<span class="name">translation</span>: <span class="name">Qt</span>.<span class="name">vector3d</span>( <span class="number">0</span>, <span class="number">0</span>, <span class="name">logoControls</span>.<span class="name">logoCentreZ</span> )
<span class="name">rotation</span>: <span class="name">fromEulerAngles</span>( <span class="name">logoControls</span>.<span class="name">rotationX</span>,
<span class="name">logoControls</span>.<span class="name">rotationY</span>,
<span class="name">logoControls</span>.<span class="name">rotationZ</span> )
}
<span class="type"><a href="qml-qt3d-render-mesh.html">Mesh</a></span> {
<span class="name">id</span>: <span class="name">logoMesh</span>
<span class="name">source</span>: <span class="string">"Qt_logo.obj"</span>
}
<span class="type"><a href="qml-qt3d-extras-phongmaterial.html">PhongMaterial</a></span> {
<span class="name">id</span>: <span class="name">logoMaterial</span>
<span class="name">ambient</span>: <span class="name">Qt</span>.<span class="name">rgba</span>( <span class="name">logoControls</span>.<span class="name">colorR</span><span class="operator">/</span><span class="number">255</span>,
<span class="name">logoControls</span>.<span class="name">colorG</span><span class="operator">/</span><span class="number">255</span>,
<span class="name">logoControls</span>.<span class="name">colorB</span><span class="operator">/</span><span class="number">255</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.1</span>, <span class="number">0.1</span>, <span class="number">0.1</span>, <span class="number">0.5</span> )
<span class="name">shininess</span>: <span class="name">logoControls</span>.<span class="name">shininess</span>
}
<span class="name">components</span>: [ <span class="name">logoTransform</span>, <span class="name">logoMesh</span>, <span class="name">logoMaterial</span> ]
}
</pre>
<p>It simply consists of a Mesh component to load the geometry; a <a href="qml-qt3d-extras-phongmaterial.html">PhongMaterial</a> component to give it a surface appearance, and a Transform component to specify its postion, orientation, and scale. The properties of these components are bound to properties on the logoControls element which we will discuss next.</p>
<a name="rendering-qt-quick-into-a-texture"></a>
<h2 id="rendering-qt-quick-into-a-texture">Rendering Qt Quick into a Texture</h2>
<p>We begin by declaring the Entity that will become our control panel. It consists of a <a href="qml-qt3d-extras-cuboidmesh.html">CuboidMesh</a> onto which we will place the texture containing a rendering of the Qt Quick scene. In this case we are using a simple cube for the geometry, but we could use any valid 3D geometry as long as it has texture coordinates. The texture coordinates are used for projecting the texture onto the 3D surface, and also for calculating the coordinates of mouse events to be passed to the originating Qt Quick scene.</p>
<pre class="qml">
<span class="type"><a href="qml-qt3d-core-entity.html">Entity</a></span> {
<span class="name">id</span>: <span class="name">cube</span>
<span class="name">components</span>: [<span class="name">cubeTransform</span>, <span class="name">cubeMaterial</span>, <span class="name">cubeMesh</span>, <span class="name">cubePicker</span>]
property <span class="type">real</span> <span class="name">rotationAngle</span>: <span class="number">0</span>
<span class="type"><a href="qml-qt3d-core-transform.html">Transform</a></span> {
<span class="name">id</span>: <span class="name">cubeTransform</span>
<span class="name">translation</span>: <span class="name">Qt</span>.<span class="name">vector3d</span>(<span class="number">2</span>, <span class="number">0</span>, <span class="number">10</span>)
<span class="name">scale3D</span>: <span class="name">Qt</span>.<span class="name">vector3d</span>(<span class="number">1</span>, <span class="number">4</span>, <span class="number">1</span>)
<span class="name">rotation</span>: <span class="name">fromAxisAndAngle</span>(<span class="name">Qt</span>.<span class="name">vector3d</span>(<span class="number">0</span>,<span class="number">1</span>,<span class="number">0</span>), <span class="name">cube</span>.<span class="name">rotationAngle</span>)
}
<span class="type"><a href="qml-qt3d-extras-cuboidmesh.html">CuboidMesh</a></span> {
<span class="name">id</span>: <span class="name">cubeMesh</span>
}
</pre>
<p>We also include an <a href="qml-qt3d-render-objectpicker.html">ObjectPicker</a> component so that we can interact with the controls using the mouse:</p>
<pre class="qml">
<span class="type"><a href="qml-qt3d-render-objectpicker.html">ObjectPicker</a></span> {
<span class="name">id</span>: <span class="name">cubePicker</span>
<span class="name">hoverEnabled</span>: <span class="number">true</span>
<span class="name">dragEnabled</span>: <span class="number">true</span>
<span class="comment">// Explicitly require a middle click to have the Scene2D grab the mouse</span>
<span class="comment">// events from the picker</span>
<span class="name">onPressed</span>: {
<span class="keyword">if</span> (<span class="name">pick</span>.<span class="name">button</span> <span class="operator">===</span> <span class="name">PickEvent</span>.<span class="name">MiddleButton</span>) {
<span class="name">qmlTexture</span>.<span class="name">mouseEnabled</span> <span class="operator">=</span> !<span class="name">qmlTexture</span>.<span class="name">mouseEnabled</span>
<span class="name">logoControls</span>.<span class="name">enabled</span> <span class="operator">=</span> !<span class="name">logoControls</span>.<span class="name">enabled</span>
}
}
}
</pre>
<p>For this example we have chosen to use an interaction mechanism whereby you must explicitly middle-click the controls to enable them.</p>
<p>To apply the texture to the mesh, we make use of the built in TextureMaterial:</p>
<pre class="qml">
<span class="type">TextureMaterial</span> {
<span class="name">id</span>: <span class="name">cubeMaterial</span>
<span class="name">texture</span>: <span class="name">offscreenTexture</span>
}
</pre>
<p>The final remaining piece is how to render the above texture from a Qt Quick scene. This is done with the <a href="qt3dscene2d-module.html#scene2d">Scene2D</a> element:</p>
<pre class="qml">
<span class="type"><a href="qml-qt3d-scene2d-scene2d.html">Scene2D</a></span> {
<span class="name">id</span>: <span class="name">qmlTexture</span>
<span class="name">output</span>: <span class="name">RenderTargetOutput</span> {
<span class="name">attachmentPoint</span>: <span class="name">RenderTargetOutput</span>.<span class="name">Color0</span>
<span class="name">texture</span>: <span class="name">Texture2D</span> {
<span class="name">id</span>: <span class="name">offscreenTexture</span>
<span class="name">width</span>: <span class="number">256</span>
<span class="name">height</span>: <span class="number">1024</span>
<span class="name">format</span>: <span class="name">Texture</span>.<span class="name">RGBA8_UNorm</span>
<span class="name">generateMipMaps</span>: <span class="number">true</span>
<span class="name">magnificationFilter</span>: <span class="name">Texture</span>.<span class="name">Linear</span>
<span class="name">minificationFilter</span>: <span class="name">Texture</span>.<span class="name">LinearMipMapLinear</span>
<span class="type">wrapMode</span> {
<span class="name">x</span>: <span class="name">WrapMode</span>.<span class="name">ClampToEdge</span>
<span class="name">y</span>: <span class="name">WrapMode</span>.<span class="name">ClampToEdge</span>
</pre>
<p>where we have made use of the Texture2D and <a href="qml-rendertargetoutput.html">RenderTargetOutput</a> types to create a destination texture and attach it as the output of the <a href="qt3dscene2d-module.html#scene2d">Scene2D</a> renderer.</p>
<p>Next, we tell the <a href="qt3dscene2d-module.html#scene2d">Scene2D</a> object which entities may feed it input events and we initially disable the handling of mouse events:</p>
<pre class="qml">
}
}
}
<span class="name">entities</span>: [ <span class="name">cube</span> ]
</pre>
<p>Finally, we can specify the Qt Quick scene to render by adding a custom QML component as a child to the <a href="qt3dscene2d-module.html#scene2d">Scene2D</a> element:</p>
<pre class="qml">
<span class="type">LogoControls</span> {
<span class="name">id</span>: <span class="name">logoControls</span>
<span class="name">width</span>: <span class="name">offscreenTexture</span>.<span class="name">width</span>
<span class="name">height</span>: <span class="name">offscreenTexture</span>.<span class="name">height</span>
}
}
</pre>
<p>When the mouseEnabled property is set to true by the <a href="qml-qt3d-render-objectpicker.html">ObjectPicker</a>, then the <a href="qt3dscene2d-module.html#scene2d">Scene2D</a> object will process mouse events from any ObjectPickers attached to the listed entities. In this way, you have the freedom to use the texture generated by the <a href="qt3dscene2d-module.html#scene2d">Scene2D</a> object in any way you wish, even on more than one Entity.</p>
<p>The <i>LogoControls.qml</i> file is just a regular Qt Quick 2 scene which in this case also makes use of the Qt Quick Controls components.</p>
<p>Files:</p>
<ul>
<li><a href="qt3d-scene2d-logocontrols-qml.html">scene2d/LogoControls.qml</a></li>
<li><a href="qt3d-scene2d-main-qml.html">scene2d/main.qml</a></li>
<li><a href="qt3d-scene2d-main-cpp.html">scene2d/main.cpp</a></li>
<li><a href="qt3d-scene2d-scene2d-pro.html">scene2d/scene2d.pro</a></li>
<li><a href="qt3d-scene2d-scene2d-qrc.html">scene2d/scene2d.qrc</a></li>
</ul>
</div>
<!-- @@@scene2d -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 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>
