Revision control
++ // Copyright (C) 2020 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example quickitems
++ \ingroup quick3d-examples
++ \title Qt Quick 3D - Quick Items Example
++ \examplecategory {3D}
++ \brief Demonstrates the use of Qt Quick Items in Quick 3D scene.
++ \image quickitems-example.png
++ {3D sphere with layered 2D items including Qt logo and text}
++
++ This example demonstrates using \l{Qt Quick 3D Scenes with 2D Content}{Qt Quick 2D items in the Quick 3D scene}.
++
++ \section1 Quick Items in a Quick 3D Scene
++
++ Qt Quick 2D \l{Item}s, together with all their child items, can be added into Quick 3D
++ scenes. When using Qt Quick types in the 3D scene, there are a few things to note:
++
++ \list
++
++ \li When an \l Item is inside a \l Node, its top-left corner is placed to the Node's
++ origin. This means that the item will often want to specify \c{anchors.centerIn:
++ parent} to ensure the \l{Node}'s origin serves the center point of the \l Item.
++
++ \li 3D transforms are inherited from the parent \l Node. If more than one \c Item
++ should be affected by the same transform, then these items can be grouped together
++ under a common parent \l Item under the \l Node.
++
++ \li In Qt 6.0, items do not receive touch/mouse events e.g. with \c MouseArea, so they
++ should be non-interactive.
++
++ \li Quick items are not affected by lights and shadows.
++
++ \li \l{Item::clip}{Clipping} should be avoided and not relied on.
++
++ \endlist
++
++ Unlike earlier Qt versions, and other 2D-in-3D embedding approaches, parenting a Qt
++ Quick item to a Qt Quick 3D node does not imply creating a texture, rendering the 2D
++ content to it, and then drawing a textured quad. Rather, Qt 6.0 supports rendering the
++ 2D content within the same render pass as the 3D scene. This can present potentially
++ huge performance improvements in practice. This does not apply when the Item were to
++ render using an additional render target by design, for example because it has
++ \l{Item Layers}{layer.enabled} set to true, or because it is a \l ShaderEffectSource.
++
++ \section1 The test scene
++
++ The important parts of this example are the scene content of the \c View3D element.
++
++ We start by adding the layer furthest away from the camera. This layer contains \c
++ Rectangle, \c Text and \c Image elements. To ensure that the elements in the layer are
++ positioned correctly they are grouped together under a common parent \c Item. Note
++ that all content is clipped inside this root item so it needs to be sized
++ appropriately.
++
++ \snippet quickitems/main.qml background item
++
++ Next \c Node and its items are positioned a bit closer to the camera. It contains
++ three \c Rectangle items which animate both the x position and the rotation. Note that
++ the animations are done on the parent \c Node while the content of the Quick \c Item
++ remains static. From a performance perspective this is a good approach with more
++ complex items.
++
++ \snippet quickitems/main.qml circles item
++
++ The third item layer of this example contains a single \c Text item with an opacity
++ animation. The Text item is automatically centered into the parent \c Node.
++
++ \snippet quickitems/main.qml text item
++
++ To visualize z-ordering of the above Quick Item layers, we will also setup a model for
++ the 3D wrecking ball. It animates rotation around the top \c Node, which makes the
++ sphere move through the other layers.
++
++ \snippet quickitems/main.qml wrecking ball model
++
++ \sa {Qt Quick 3D Scenes with 2D Content}
++ */