diff --git a/doc/qtcreator/src/qtcreator-toc.qdoc b/doc/qtcreator/src/qtcreator-toc.qdoc index 43396743138..8f331922ff4 100644 --- a/doc/qtcreator/src/qtcreator-toc.qdoc +++ b/doc/qtcreator/src/qtcreator-toc.qdoc @@ -132,6 +132,7 @@ \li \l{Animations} \li \l{3D Views} \li \l{Group} + \li \l{Instanced Rendering} \li \l{Skeletal Animation} \li \l{3D Models} \li \l{Materials and Shaders} diff --git a/doc/qtcreator/src/qtquick/library/qtquick-preset-components.qdoc b/doc/qtcreator/src/qtquick/library/qtquick-preset-components.qdoc index 68c1875c068..2ab482358b2 100644 --- a/doc/qtcreator/src/qtquick/library/qtquick-preset-components.qdoc +++ b/doc/qtcreator/src/qtquick/library/qtquick-preset-components.qdoc @@ -70,6 +70,7 @@ \list \li \l {3D Views} \li \l {Group} + \li \l {Instanced Rendering} \li \l {Skeletal Animation} \li \l {3D Models} \li \l {Materials and Shaders} diff --git a/doc/qtcreator/src/qtquick/qtquick-library.qdoc b/doc/qtcreator/src/qtquick/qtquick-library.qdoc index ae206f3e4fd..dad5e9b9282 100644 --- a/doc/qtcreator/src/qtquick/qtquick-library.qdoc +++ b/doc/qtcreator/src/qtquick/qtquick-library.qdoc @@ -71,6 +71,7 @@ \li \l Animations \li \l{3D Views} \li \l{Group} + \li \l{Instanced Rendering} \li \l{Skeletal Animation} \li \l{3D Models} \li \l{Materials and Shaders} diff --git a/doc/qtdesignstudio/images/studio-3d-instancing-instance-list-entry-properties.png b/doc/qtdesignstudio/images/studio-3d-instancing-instance-list-entry-properties.png new file mode 100644 index 00000000000..72d465e5628 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-3d-instancing-instance-list-entry-properties.png differ diff --git a/doc/qtdesignstudio/images/studio-3d-instancing-instance-list.png b/doc/qtdesignstudio/images/studio-3d-instancing-instance-list.png new file mode 100644 index 00000000000..f7bb9f8f1f3 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-3d-instancing-instance-list.png differ diff --git a/doc/qtdesignstudio/images/studio-3d-instancing-model.png b/doc/qtdesignstudio/images/studio-3d-instancing-model.png new file mode 100644 index 00000000000..b93b9079450 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-3d-instancing-model.png differ diff --git a/doc/qtdesignstudio/images/studio-3d-instancing-properties.png b/doc/qtdesignstudio/images/studio-3d-instancing-properties.png new file mode 100644 index 00000000000..269df799066 Binary files /dev/null and b/doc/qtdesignstudio/images/studio-3d-instancing-properties.png differ diff --git a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc index ceb5d458611..8427aa74938 100644 --- a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc +++ b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc @@ -89,6 +89,7 @@ \li \l Animations \li \l{3D Views} \li \l{Group} + \li \l{Instanced Rendering} \li \l{Skeletal Animation} \li \l{3D Models} \li \l{Materials and Shaders} diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-instancing.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-instancing.qdoc new file mode 100644 index 00000000000..cde225b547c --- /dev/null +++ b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-instancing.qdoc @@ -0,0 +1,153 @@ +/**************************************************************************** +** +** Copyright (C) 2021 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt Design Studio documentation. +** +** 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. +** +****************************************************************************/ + +/*! + \page studio-3d-instancing.html + \previouspage studio-3d-node.html + \nextpage studio-skeletal-components.html + + \title Instanced Rendering + + Instancing allows duplicating a model with variations. In contrast to using + the \uicontrol Repeater3D component, the model and its graphics resources are + only allocated once. The rendering of the duplicated instances is done at a + low level by the GPU. Depending on the complexity of the model, this can + give a performance improvement of several orders of magnitude. + + In practice, instancing is done by defining a table that specifies how each + instance is modified relative to the base model. + + You can add instancing to your scenes by using the instancing components + available in \uicontrol Library > \uicontrol Components > + \uicontrol {Qt Quick 3D} > \uicontrol {Qt Quick 3D}: + \list + \li \uicontrol {Instancing} + \li \uicontrol {Instance List} + \li \uicontrol {Instance List Entry}. + \endlist + + \section1 Reading Instance Tables from Files + + The \uicontrol Instancing component makes it possible to read instance tables + from files in XML or binary format. The binary file format uses the same + layout as the table that is uploaded to the GPU, so it can be directly mapped + to memory. + + In order to be valid, the XML file must have a top-level instance table + element. Each instance is represented by an Instance element inside the + InstanceTable. Unknown elements are silently ignored. + + An Instance element can have a number of attributes. Color attributes are + specified by using SVG color names, such as "red", "green", or + "lightsteelblue", or by using a hexadecimal notation. \c Vector3d and + \c vector4d attributes are specified by a string of space-separated numbers, + where missing trailing numbers indicate zeroes. The following attributes are + supported: position, scale, eulerRotation, quaternion, custom, and color. + For more information about instance tables, see the documentation for the + \l[Instancing]{FileInstancing} QML type. + + To use the \uicontrol Instancing component, drag-and-drop it from + \uicontrol Library to \uicontrol Scene in \uicontrol Navigator. + + \section2 Instancing Properties + + Define the location of an XML or a binary file containing the instance data + in \uicontrol Properties > \uicontrol {File Instancing} > \uicontrol Source. + + \image studio-3d-instancing-properties.png "File Instancing in the Properties View" + + If the file name has a \c .bin extension, it is assumed to refer to a binary + file. Otherwise it is assumed to refer to an XML file. If an XML file + \c foo.xml is specified, and the file \c foo.xml.bin exists, the binary file + \c foo.xml.bin will be loaded instead. + + After defining the \uicontrol Source property for the \uicontrol Instancing + component, select a model in \uicontrol Navigator, and in + \uicontrol Properties > \uicontrol Model > \uicontrol Instancing, select the + name of the \uicontrol Instancing component. + + \image studio-3d-instancing-model.png "The Instancing property" + + \section1 Using Instance Lists to Build Instance Tables + + Use the \uicontrol {Instance List} component to define an instance table in + \QDS. An instance table consists of instances defined as + \uicontrol {Instance List Entry} components, which can have property bindings + and animation. This gives great flexibility but also causes memory overhead. + Therefore, it is not recommended to use \uicontrol {Instance List} + for procedurally generated tables containing a large number of instances. + Also, any property change to an entry will cause the entire instance table + to be recalculated and uploaded to the GPU. + + \image studio-3d-instancing-instance-list.png "Instance List and Instance Entries in Navigator" + + To build an instance table: + \list 1 + \li Drag-and-drop an \uicontrol {Instance List} component from + \uicontrol Library > \uicontrol Components > \uicontrol {Qt Quick 3D} + > \uicontrol {Qt Quick 3D} to \uicontrol Scene in + \uicontrol Navigator. + \li Drag-and-drop \uicontrol {Instance List Entry} components to the + \uicontrol {Instance List} component to create list items. + \image studio-3d-instancing-instance-list.png "Instance List and Instance Entries in Navigator" + + \li Select the \uicontrol {Instance List} in \uicontrol Navigator, and in + \uicontrol Properties > \uicontrol {Instance List} > + \uicontrol Instances, select each \uicontrol {Instance List Entry} + you wish to include in the \uicontrol {Instance List} by using + the dropdown menu. You can add more fields for the property by + clicking the \inlineimage plus.png + icon. + \li To define an \uicontrol {Instance List Entry}, select it in + \uicontrol Navigator, and specify its properties in + \uicontrol Properties > \uicontrol {Instance List Entry}. + \li Select a model component in \uicontrol Navigator, and in + \uicontrol Properties > \uicontrol Instancing, select the name + of the \uicontrol {Instance List} component. + \endlist + + \section2 Defining Instance List Entries + + Use the \uicontrol {Instance List Entry} component to specify each instance + in an \uicontrol {Instance List}. + + Each of the \uicontrol {Instance List Entry} properties can have + \l {Adding Bindings Between Properties}{bindings} and animation. Select an + \uicontrol {Instance List Entry} in \uicontrol Navigator to specify the + properties in \uicontrol Properties > \uicontrol {Instance List Entry}. + + \image studio-3d-instancing-instance-list-entry-properties.png "Instance List Entry Properties" + + Use the \uicontrol Color property to \l{Picking Colors}{specify the color} + for the instance. + + Specify the position for the instance using the \uicontrol Position property, + and the scale by defining the scale factors of the \uicontrol Scale property + along the x, y, and z axes. + + Set the rotation for the instance using the \uicontrol Rotation + property, which specifies the rotation for the instance as an Euler vector + containing the rotation in degrees around the x, y, and z axes. +*/ diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-model.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-model.qdoc index 26d0685296d..33c5e23b9a0 100644 --- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-model.qdoc +++ b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-model.qdoc @@ -77,7 +77,10 @@ The \uicontrol Source field must be empty when custom geometry is used. Set the \uicontrol Instancing property to render a number of instances of - the model as defined by the instance table. + the model as defined by an instancing table. The instancing tables can be + defined by using one of the \l{Instanced Rendering}{instancing components} + available in \uicontrol Library > \uicontrol Components > + \uicontrol {Qt Quick 3D} > {Qt Quick 3D}. Set the \uicontrol {Instance root} property to define the origin of the instance's coordinate system. diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-node.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-node.qdoc index 9c50ec4232d..d524fd8da00 100644 --- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-node.qdoc +++ b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-node.qdoc @@ -26,7 +26,7 @@ /*! \page studio-3d-node.html \previouspage quick-animations.html - \nextpage studio-skeletal-components.html + \nextpage studio-3d-instancing.html \title Group diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/studio-skeletal-components.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/studio-skeletal-components.qdoc index c6edcc7197c..c73c561adf6 100644 --- a/doc/qtdesignstudio/src/qtquick3d-editor/studio-skeletal-components.qdoc +++ b/doc/qtdesignstudio/src/qtquick3d-editor/studio-skeletal-components.qdoc @@ -25,7 +25,7 @@ /*! \page studio-skeletal-components.html - \previouspage studio-3d-node.html + \previouspage studio-3d-instancing.html \nextpage studio-3d-model.html \title Skeletal Animation