1// Copyright (C) 2020 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
6\title Qt Quick 3D Scenes with 2D Content
7\brief Embedding Qt Quick items in a 3D scene
9\section1 2D Items in a 3D World
11Qt Quick 3D offers efficient creation and rendering of scenes that combine 3D and 2D
14What do we mean by a combined 3D-2D scene?
16By nature, a \l View3D object, representing a 3D viewport in the 2D scene, can be easily
17combined with Qt Quick items, such as, Rectangle, Image, Text, around, below, or above the
18View3D item, which itself is a Qt Quick \l Item.
20Consider the following example:
28 GradientStop { position: 0; color: "steelblue" }
29 GradientStop { position: 1; color: "black" }
32 text: "Hello 2D World"
35 anchors.top: parent.top
36 anchors.horizontalCenter: parent.horizontalCenter
39 width: 400; height: 400
40 anchors.centerIn: parent
43 environment: SceneEnvironment { backgroundMode: SceneEnvironment.Color; clearColor: "lightGray" }
44 PerspectiveCamera { z: 600 }
48 materials: PrincipledMaterial { baseColor: "green"; metalness: 0.0; roughness: 0.0 }
49 eulerRotation: Qt.vector3d(30, 45, 0)
56\image quick2d-3d-1.jpg
58Here the 3D scene is the area with gray background. The rest of the window consists of 2D
59Qt Quick items. These can overlap with the View3D but are not part of the 3D world, are
60not using the 3D coordinate system, and do not take part in the 3D scene's
63What if we want to have 2D items within the 3D world, in a way that they truly participate
64in all 3D transforms? For example, can we have \l Rectangle and \l Text items placed
65within the 3D world, in a way that they follow the cube's rotation and are always placed
68\image quick2d-3d-3.jpg
70In the following sections we will take a look at how this can be achieved. While the
71example uses \l Rectangle and \l Text, any Qt Quick content, including Qt Quick Controls,
72\l Shape, \l ShaderEffect, \l ParticleSystem, can be used this way.
74\note There are also other approaches available to integrate 2D content with the 3D
75objects. Adding 2D items to 3D nodes allows freely combining the 2D and 3D objects in the
763D world, but it does not allow rendering the 2D content on the surface of a 3D object. If
77the goal is to texture a 3D mesh with content generated by Qt Quick, use
78\l{Texture::sourceItem}{the sourceItem property} of \l Texture instead.
82\li Qt Quick content used as a texture map
83\li Qt Quick items in the 3D scene
85\li \image quick2d-3d-4.jpg
86\li \image quick2d-3d-5.jpg
89\section1 Adding 2D Items to 3D Nodes
91The key enabler is \l{Object3D}'s ability to accept \l Item child objects, and treat them
92in a special way. \l Object3D is the base class for the \l Node type. This means that any
93\l Node, and also types like \l Model, accept \l Item children.
95Starting with Qt 6.0, adding a 2D item to a 3D node no longer triggers rendering the 2D
96content into a OpenGL texture, Vulkan image, or similar. Rather, the default mode is to
97render the 2D items in-line with the rest of the 3D scene, in the same render pass. The 2D
98items have all 3D transformations applied. The transformations are inherited from the
107 GradientStop { position: 0; color: "steelblue" }
108 GradientStop { position: 1; color: "black" }
111 text: "Hello 2D World"
114 anchors.top: parent.top
115 anchors.horizontalCenter: parent.horizontalCenter
118 width: 400; height: 400
119 anchors.centerIn: parent
122 environment: SceneEnvironment { backgroundMode: SceneEnvironment.Color; clearColor: "lightGray" }
123 PerspectiveCamera { z: 600 }
129 anchors.horizontalCenter: parent.horizontalCenter
132 height: text3d.height
135 text: "Hello 3D World"
141 materials: PrincipledMaterial { baseColor: "green"; metalness: 0.0; roughness: 0.0 }
142 eulerRotation: Qt.vector3d(30, 45, 0)
149\image quick2d-3d-2.jpg
151Compared to the first snippet, the \l Model node now has a child node, with a transform
152that places it somewhat above the cube's position. \c 150 is relative to the cube's
153center, in the 3D coordinate space.
161Then there is the \l Rectangle item. When adding it under a \l Node, the boundaries of the
1623D and 2D world are crossed internally, but this remains transparent to the application
163designer. An invisible \c{content item} is generated automatically, allowing the Rectangle
164to refer to \c parent and perform anchoring. The 3D transform from the Node is applied to
165the entire 2D subtree. In the example this means that the rotation will match the cube's
172 anchors.horizontalCenter: parent.horizontalCenter
175\section2 Coordinate Spaces in 2D and 3D
177The 2D items continue to use Qt Quick's coordinate system: Y axis runs from top to bottom,
178and the units correspond to pixels. 3D nodes on the other hand use the 3D coordinate
179system: the Y axis points up, and the units correspond to centimeters, affected by the
180\l{Camera}'s perspective projection.
182The top item's top-left corner is placed at the Node's origin by default. This means that
183the top-level item in a 2D subtree will often want to specify an anchor, for example
184\c{anchors.centerIn: parent}, or, like in the example, anchoring the horizontal center to
185the parent' horizontal center, thus centering the 2D content horizontally over the 3D
188\section2 Further Considerations
192\li While the 2D items are rended in-line with 3D objects, they do not participate in
193lighting, and will not be casting shadows.
195\li \l{Item::clip}{Clipping} may not perform as expected and should be avoided. If
196clipping is essential to the design of 2D items, the application should make an explicit
197fall back to rendering to a texture. This can be achieved by adding \c{layer.enabled:
198true} to the top-level \c Item under the 3D node.
200\li As of Qt 6.2, input is passed to the 2D items as necessary. Input from pointing devices
201must occur within the \l{Item::childrenRect.x}{childrenRect} of the declared Items.
203\li While adding a 2D item tree into the 3D scene is fairly cheap, excess amounts
204(hundreds or more) of 2D subtrees within the 3D scene should be avoided, because in large
205amounts this may lead to increased memory and graphics resource usage. Note that this
206refers to the number of separate \l Item subtrees under 3D nodes, not the total number of
2072D items in those subtrees. For example, the QML snippet above contains only one 2D
212\sa {Qt Quick 3D - Quick Items Example}, QQuickItem::mapFromGlobal()