Doc: Describe Best Practices in QDS

Project files for the example scene will be added as a separate task. Task-number: QDS-1243 Change-Id: I0bc9bd861d2b6a3c58372cedb2395deb3c78f590 Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io> Reviewed-by: Mahmoud Badri <mahmoud.badri@qt.io>
2020-10-26 10:27:22 +02:00
parent bf8879ee5c
commit 77b91fd4a9
24 changed files with 421 additions and 23 deletions
@@ -57,11 +57,10 @@
            properties set in \QD can be changed dynamically within the code.
            Furthermore, features such as widget promotion and custom plugins
            allow you to use your own widgets with \QD.
-        \li \l{Optimizing Applications for Mobile Devices}

-            Mobile devices have been designed for use when mobile. Keep the
-            characteristics of mobile devices in mind when you create
-            applications for them.
+        \li \l{Best Practices}

+            Apply the best practices to ensure that the UIs you create work
+            efficiently on the intended platforms, such as mobile devices.
    \endlist
 */
@@ -30,9 +30,9 @@
 // **********************************************************************

 /*!
-    \previouspage adding-plugins.html
+    \previouspage creator-ui-best-practices.html
    \page creator-usability.html
-    \nextpage creator-coding.html
+    \nextpage studio-qtquick-best-practices.html

    \title Optimizing Applications for Mobile Devices

@@ -0,0 +1,47 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Creator 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.
+**
+****************************************************************************/
+
+/*!
+    \previouspage adding-plugins.html
+    \page creator-ui-best-practices.html
+    \nextpage creator-usability.html
+
+    \title Best Practices
+
+    Apply the best practices to ensure that the UIs you create work
+    efficiently on the intended platforms, such as mobile devices.
+
+    \list
+        \li \l {Optimizing Applications for Mobile Devices}
+
+            Guidelines to help you design and develop usable applications for
+            mobile devices with varying characteristics.
+
+        \li \l {Qt Quick Best Practices}
+
+            Guidelines describing the most efficient ways to use \QDS to
+            create UIs and scenes that run flawlessly on the intended platforms.
+    \endlist
+*/
@@ -157,7 +157,14 @@
            \list
                \li  \l{Adding Qt Designer Plugins}
            \endlist
-            \li \l{Optimizing Applications for Mobile Devices}
+            \li \l {Best Practices}
+            \list
+                \li \l{Optimizing Applications for Mobile Devices}
+                \li \l{Qt Quick Best Practices}
+                    \list
+                        \li \l{Creating Optimized 3D Scenes}
+                    \endlist
+            \endlist
        \endlist
        \li \l{Coding}
        \list
@@ -77,7 +77,7 @@
                \list
                    \li \l{Developing Qt Quick Applications}
                    \li \l{Developing Widget Based Applications}
-                    \li \l{Optimizing Applications for Mobile Devices}
+                    \li \l{Best Practices}
                \endlist
            \li \b {\l{Coding}}
                \list
@@ -0,0 +1,101 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 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-qtquick-best-practices.html
+    \if defined(qtdesignstudio)
+    \previouspage {Tutorials}
+    \nextpage studio-optimized-3d-scenes.html
+    \else
+    \previouspage creator-usability.html
+    \nextpage studio-optimized-3d-scenes.html
+    \endif
+
+    \title Qt Quick Best Practices
+
+    The following guidelines describe the most efficient ways to use \QC to
+    create UIs and scenes that run flawlessly on the intended platforms.
+
+    For best practices in creating 3D scenes with optimized graphics
+    performance, see \l {Creating Optimized 3D Scenes}.
+
+    \if defined(qtdesignstudio)
+    For guidelines on how to achieve best results when importing assets, see
+    \l {Exporting Artwork from Design Tools}.
+    \endif
+
+    \section1 Naming Conventions
+
+    Establish naming conventions to keep the items in your UI organized.
+    Name your items accurately and give them suitable QML IDs. You should
+    manually specify the names of the items you export from design tools to
+    create reliable and self-explanatory names that follow the naming
+    conventions you have established.
+
+    For example, a button symbol might have the ID \e myButton_symbol and the
+    different layers might have it as a prefix with the states appended, thus
+    producing IDs such as \e myButton_symbol_default. To prepare for additional
+    mouse areas later in the project, you could use similar IDs for them, such
+    as \e myButton_symbol_hotspot. When you use the button as instances in a
+    screen, you would give each of these instances a unique ID that relates to
+    that screen. For example, \e myButton_myMenu_home, \e myButton_myMenu_profile,
+    and \e myButton_myMenu_settings
+
+    \section1 Planning the UI
+
+    Plan your UI properly. Know what elements, such as screens, components,
+    and states, you need. Creating a descriptive wireframe and acquiring a
+    detailed UI specification before you start will make the process of creating
+    the UI more efficient.
+
+    \section1 Using Components Economically
+
+    It is important to understand the performance costs associated with using
+    components.
+
+    To use components efficiently and economically:
+
+    \list
+        \li Componentize your design by packaging your resources into reusable
+            components that can be conveniently recombined to suit the needs of
+            your UI.
+        \li Use as few components as necessary. To minimize the number of
+            components, use alias properties and states to create the
+            differences in your instances. We recommend reusing components
+            instead of duplicating them, so the components do not need to be
+            processed as completely new types. This reduces loading and
+            compilation time as well as the size of the binary.
+        \li Any content that is data-driven should be
+            \l {Using Qt Quick UI Forms}{exported as a public property} of the
+            relevant component. For example, a speedometer should have an \c int
+            or \c real property for speed to which the UI is bound.
+        \li Separate UI from the application logic. Designers should work with
+            the UI forms (.ui.qml files), while developers should work on the
+            corresponding QML files (.qml) to define their programmatic
+            behaviors or JavaScript. This enables iteration from both the design
+            and development side of the process without the the risk of
+            overwriting each other's work.
+    \endlist
+*/
@@ -0,0 +1,200 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 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-optimized-3d-scenes.html
+    \previouspage studio-qtquick-best-practices.html
+    \if defined(qtdesignstudio)
+    \nextpage studio-projects-managing.html
+    \else
+    \nextpage creator-coding.html
+    \endif
+
+    \title Creating Optimized 3D Scenes
+
+    In \QC, you can use various means to create a 3D scene. Your choice of
+    strategy should always depend on the target platform of your scene.
+    The way the content of your scene is authored can have dramatic effects on
+    the runtime performance of your UI. The Optimal 3D Scene described
+    below illustrates four different ways to create a scene. Also see guidelines
+    for \l{Optimizing your 3D Scene}{optimizing the graphics performance of your 3D scene}
+    and \l{Best Practices for 3D Scenes Based on Use Cases}.
+
+    \section1 The Optimal 3D Scene Example
+
+    The Optimal 3D Scene example features four versions of the same kitchen
+    scene that have been created using different strategies: High, Low, Combined,
+    and Vertex Color. The High Scene includes a significantly higher number of
+    objects compared to the other versions of the scene. The Low, Combined and
+    Vertex scenes include less objects since they have been optimized by, for
+    example, combining geometry and baking materials into textures. The
+    following image displays the components in each scene in \uicontrol
+    Navigator to illustrate the structural differences between the scenes.
+
+    \image studio-kitchen-navigators.png "Navigators for the four scenes in the Optimal 3D Scene."
+
+    \section2 The High Scene
+
+    \image studio-kitchen-high.png "The High Scene in the Optimal 3D Scene"
+
+    The High scene (1) includes a total of 27 objects. The scene is otherwise
+    similar to the Low scene, but has more details and animated components, such
+    as cabinet doors that can be opened and a latch for the oven.
+
+    \section2 The Low Scene
+
+    \image studio-kitchen-low.png "The Low Scene in the Optimal 3D Scene"
+
+    The Low scene (2) includes a total of 12 objects. Each model, for example
+    cabinets, lamps, plates, and the sink, are separate meshes.
+
+    \section2 The Combined Scene
+
+    \image studio-kitchen-combined.png "The Combined Scene in the Optimal 3D Scene"
+
+    The Combined scene (3) has all the meshes combined into a single object. All
+    materials are baked into one single texture.
+
+    \section2 The Vertex Color Scene
+
+    \image studio-kitchen-vertex.png "The Vertex Color Scene in the Optimal 3D Scene"
+
+    The Vertex Color scene (4) has all the meshes combined into a single object,
+    and colors for the mesh are provided from .mesh file's vertex data, which
+    includes one material and no textures.
+
+    \section1 Optimizing Your 3D Scene
+
+    To optimize the graphics performance of your 3D scene, you should first
+    consider whether you need to animate the 3D objects, lights, camera, or
+    other components in your scene. If not, simplify the scene structure by, for
+    example, combining geometries and baking materials into textures. Ideally,
+    pre-render your 3D image into a 2D image. You should not waste resources
+    by rendering static 3D objects. You should also check if your scene has
+    multiple instances of the same mesh. If so, import only one instance of the
+    mesh, duplicate it in the scene, and use the same material for each
+    duplicate.
+
+    See also the following guidelines related to scene graph, asset complexity,
+    CPU specific optimization, and model geometry.
+
+    \section2 Scene Graph
+
+    The scene graph is the hierarchy of nodes that describe the scene to be
+    rendered.
+
+    In \QC, the scene graph is represented by the tree-like view in
+    \uicontrol Navigator. You can also view the hierarchy of nodes in the
+    \uicontrol {Text Editor} view. By minimizing the size of the scene graph,
+    you can minimize the effort needed when running the scene. In terms of
+    optimization, you should avoid unnecessary groups and complex hierarchy when
+    possible. Deep hierarchies with complex parenting increase the performance
+    cost.
+
+    \section2 Asset Complexity
+
+    The performance of your UI or scene may sometimes be bottlenecked at render
+    time. Avoid this by simplifying your assets.
+
+    For 3D models, you should try to use the minimum number of triangles or
+    vertices to achieve the desired result. Also note that smaller images
+    require less memory and render faster.
+
+    \section2 Optimizing CPU Performance
+
+    Rendering objects requires plenty of processing work from the CPU.
+    Processing each component consumes resources, so reducing the visible object
+    count reduces the amount of work required from the CPU.
+
+    To reduce the visible object count:
+    \list
+        \li Combine objects that are positioned closely and share a texture.
+        \note Combining objects that do not share a texture does not increase
+        the CPU performance while running the scene.
+        \li Use fewer materials by combining separate textures into a single
+            texture atlas (like in the Merged scene in the
+            Kitchen Scene Example).
+        \li Minimize the number of factors that cause objects to be rendered
+            multiple times, for example reflections and shadows.
+    \endlist
+
+    \section2 Optimizing Model Geometry
+
+    To optimize the geometry of a model:
+
+    \list
+        \li Minimize the number of triangles used in the model.
+        \li Minimize the number of UV mapping seams and hard edges created with
+        doubled-up vertices.
+    \endlist
+
+    \section1 Best Practices for 3D Scenes Based on Use Cases
+
+    The following table summarizes best practices related to optimizing 3D
+    scenes in the form of use cases.
+
+    \table
+    \header
+        \li How to...
+        \li Solution
+    \row
+        \li Get best performance from the 3D scene.
+        \li If no animation is required, pre-render your 3D scene into a 2D
+            image.
+
+    \row
+        \li Include animation for some of the objects in the scene
+            (for example, to open doors).
+        \li Merge all objects that are static, and export only one of
+            each animated component (for example, each door type).
+
+    \row
+        \li Get best performance with animated camera.
+        \li While using a 2D image is not an option in this case, you should
+            combine all geometry and bake lighting and materials into a single
+            material.
+
+    \row
+        \li Get best performance with animated light.
+        \li While using a 2D image is not an option in this case, you should
+            combine all geometry and bake all materials into a single
+            material.
+
+    \row
+        \li Get best performance in a 3D scene where all meshes are
+            separated.
+        \li Use the same material for each instance of the same mesh.
+
+    \row
+        \li Disable rendering for one of the meshes during runtime.
+        \li Keep that particular mesh separate but merge the rest of the
+            components.
+
+    \row
+        \li Use baked textures with low memory.
+        \li Bake mesh colors into vertex colors (see the Vertex Color Scene
+            in the example project).
+    \endtable
+*/
@@ -181,7 +181,8 @@
    \endtable

    In addition, you can use arithmetic operators to compare numbers before
-    checks.
+    checks. However, we recommend that you create separate properties for this
+    purpose whenever possible.

    \section2 Examples of when Conditions

@@ -46,6 +46,15 @@
    you can associate with an item to define how its properties will animate
    when they change due to a state change.

+    Each component in a scene or a project can have its own timeline and its own
+    set of states. We recommend that you place your timelines inside the
+    components and precompose them. Each component's timeline runs independently
+    of the rest of the scene, allowing for time-independent animations.
+    Additionally, separate states allow common functionality to be factored out
+    and reused across the scene. Do note, however, that adding states and
+    timelines to your components will increase the file size and runtime memory
+    requirements of your UI.
+
    You can find a video tutorial about creating timelines and adding keyframes
    \l{https://resources.qt.io/development-topic-ui-design/qtdesignstudio-clustertutorial-parttwo}
    {here}.
@@ -32,7 +32,7 @@
 /*!
    \previouspage creator-using-qt-designer.html
    \page adding-plugins.html
-    \nextpage creator-usability.html
+    \nextpage creator-ui-best-practices.html

    \title Adding Qt Designer Plugins

@@ -75,5 +75,9 @@
            Describes how to use \QDS to create a simple animated UI with some
            basic UI components, such as pages, buttons, and fields. Some of
            the buttons can be used for moving between the pages.
+        \li \l {Qt Quick Best Practices}
+
+            Describes how to create UIs that work efficiently on the intended
+            platforms.
     \endlist
 */
@@ -92,6 +92,10 @@
    layer in \uicontrol Navigator to reflect the QML code model. You
    can view the QML code in \uicontrol {Text Editor}.

+    After importing the metadata files, wait a few moments to allow all
+    imported assets to appear in your project files before selecting your
+    metadata filename from \uicontrol {QML Imports} > \uicontrol {Add Imports}.
+
    If asset importer conflicts, warnings, and errors are displayed in the
    \uicontrol {Asset Import} dialog while importing, fix the issues in
    design tool and export the assets again.
@@ -24,7 +24,7 @@
 ****************************************************************************/

 /*!
-    \previouspage {Tutorials}
+    \previouspage studio-optimized-3d-scenes.html
    \page studio-projects-managing.html
    \nextpage studio-projects.html

@@ -109,14 +109,18 @@
        \li qtquickcontrols2.conf file specifies the preferred style and some
            style-specific arguments.
        \li \e imports folder contains a \e {Constants.qml} file that specifies
-            a font loader for the Arial font and a \e qmldir module definition
-            file that declares the Constant QML type. For more information, see
-            \l {Module Definition qmldir Files}. In addition, the \e QtQuick
-            subfolder contains the Studio components and effects QML types.
+            a font loader for the Arial font and the screen resolution. The
+            size of the default Screen.ui.qml Rectangle should be set as
+            \c {width: Constants.width & height: Constants.height}, so it
+            inherits the global resolution saved here.
+        \li \e qmldir module definition file declares the Constant QML type.
+            For more information, see \l {Module Definition qmldir Files}.
+        \li In addition, the \e QtQuick subfolder contains the Studio components
+            and effects QML types.
    \endlist

-    To use JavaScript and image files in the UI, copy them to the
-    project folder.
+    To use JavaScript and image files in the UI, select \uicontrol Library >
+    Assets > Add New Assets.

    \section1 Adding Files to Projects

@@ -58,6 +58,10 @@
                        \li \l{Managing Sessions}
                     \endlist
                \li \l{Tutorials}
+                \li \l{Qt Quick Best Practices}
+                    \list
+                         \li \l{Creating Optimized 3D Scenes}
+                    \endlist
            \endlist
        \li \l{Managing Projects}
            \list
@@ -26,7 +26,7 @@
 /*!
    \group gstutorials
    \previouspage creator-project-managing-sessions.html
-    \nextpage studio-projects-managing.html
+    \nextpage studio-qtquick-best-practices.html

    \title Tutorials

@@ -47,6 +47,7 @@
                \li \l{User Interface}
                \li \l{Editing QML Files in Design Mode}
                \li \l{Tutorials}
+                \li \l{Qt Quick Best Practices}
            \endlist
            \li \b {\l{Managing Projects}}
                \list
@@ -45,6 +45,18 @@
    Depending on the 3D graphics tool, you might need to install export plugins
    to be able to export files to a particular format.

+    For complex 3D models, we recommend leaving the files exported from 3D
+    graphics tools unmerged, so if there are performance issues, you can easily
+    delete individual meshes within \QDS.
+
+    Consider how much detail is necessary for your 3D model prior to exporting
+    from 3D graphics tools. If the models will be far from camera view, optimize
+    the models to the least amount of polygons necessary without compromising
+    the model. For high-detailed models in close distance to the camera, use
+    image maps a much as possible for detail. If the model is only viewed from
+    certain angles, consider further optimization of parts not in direct camera
+    view for optimal performance.
+
    To get the best results when exporting 3D assets and importing them to
    \QDS, follow the general guidelines in the following sections. For more
    information about using the export plugins for a particular tool, see
@@ -133,6 +145,10 @@
    You need to bake actions to export animations that are using custom curves
    or object constraints to control the animation.

+    We recommend using the export panel in 3D graphics tools to bake animations
+    to the 3D graphics you are about to export. This will only bake your set
+    keyframes, rather than each individual keyframe along the timeline.
+
    \e Actions are data-blocks containing animation data. If you are exporting
    animations, you need to bake actions.

@@ -32,9 +32,13 @@

    To add 3D components to the scene, drag and drop a them from
    \uicontrol Library > \uicontrol {QML Types} > \uicontrol {Qt Quick 3D} to
-    the scene or to a 3D view in the \uicontrol Navigator.
+    the scene or to a 3D view in \uicontrol Navigator.

-    To edit 3D components, select the component in the 3D editor or in the
+    \note Using 3D components will affect the performance of your UI. You should
+    not use 3D components if the same results can be achieved using 2D
+    components.
+
+    To edit 3D components, select the component in \uicontrol {3D Editor} or in
    \uicontrol Navigator and set its properties in the \uicontrol Properties
    view.

@@ -66,18 +70,15 @@

            You can use 3D effect components to generate post-processing
            effects.
-
        \li \l {Using Custom Shaders}

            You can use 3D shader utilities to construct your own effects and
            materials.
-
        \li \l{Creating Custom Effects and Materials}

            If the ready-made 3D effects and materials don't meet your needs,
            you can use 3D shader utilities to construct your own effects and
            materials.
-
        \li \l{Using Lights}

            You can use several light types as the source of lighting in a