Doc: Describe creating custom effects and materials

...using Qt Quick 3D custom shader utilities and commands

Fixes: QDS-2613
Change-Id: I5807c1617d2b54b3fba183c1278ec1266f899c70
Reviewed-by: Tomi Korpipää <tomi.korpipaa@qt.io>
Reviewed-by: Johanna Vanhatapio <johanna.vanhatapio@qt.io>
Reviewed-by: Mahmoud Badri <mahmoud.badri@qt.io>

doc/qtcreator/src/qtcreator-toc.qdoc

@@ -139,6 +139,7 @@
                                 \li \l{Using 3D Materials}
                                 \li \l{Applying 3D Effects}
                                 \li \l{Using Custom Shaders}
+                                \li \l{Creating Custom Effects and Materials}
                                 \li \l{Using Lights}
                                 \li \l{Using Scene Camera}
                                 \li \l{Setting Scene Environment}

doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc

@@ -109,6 +109,7 @@
                        \li \l{Attaching Textures to Materials}
                        \li \l{Applying 3D Effects}
                        \li \l{Using Custom Shaders}
+                       \li \l{Creating Custom Effects and Materials}
                        \li \l{Using Lights}
                        \li \l{Using Scene Camera}
                        \li \l{Setting Scene Environment}

doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-components.qdoc

@@ -72,7 +72,13 @@
             You can use 3D shader utilities to construct your own effects and
             materials.
 
-        \li \l {Using Lights}
+        \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
             scene and set their properties.

doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-custom-effects-materials.qdoc

@@ -0,0 +1,163 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qt Design Studio.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \page studio-3d-custom-effects-materials.html
+    \previouspage studio-3d-custom-shaders.html
+    \nextpage studio-3d-lights.html
+
+    \title Creating Custom Effects and Materials
+
+    You can use the QML types in the \uicontrol {Qt Quick 3D Custom Shader Utils}
+    tab of \uicontrol Library to create custom effects and materials. To make
+    the \uicontrol Effect and \uicontrol {Custom Material} types appear in the
+    tab, you must select \uicontrol {Add Import} in the \uicontrol {QML Imports}
+    tab, and then select \uicontrol QtQuick3D.Effects and
+    \uicontrol QtQuick3D.Materials to import the QML types in the
+    \l{Qt Quick 3D Effects QML Types}{Qt Quick 3D Effects} and
+    \l{Qt Quick 3D Materials QML Types}{Qt Quick 3D Materials} modules to your
+    project. These modules contain a set of ready-made effects and materials
+    that you can apply to 3D models.
+
+    For more information about the shader utilities and commands and their
+    properties, see \l {Using Custom Shaders}.
+
+    \image studio-qtquick-3d-shader-utilities.png "Qt Quick 3D Custom Shader Utils tab in Library"
+
+    \note You must create the actual shader source files with some other tool
+    and copy them to your project folder. You can then specify the source file
+    names in the custom effect or material properties.
+
+    \section1 Creating Custom Effects
+
+    By default, a custom effect component contains a Pass type and a Shader
+    type in the fragment stage. You can add passes, shaders, and other shader
+    utilities to the effect.
+
+    \image studio-qtquick-3d-custom-effect-navigator.png "Custom effect in Navigator"
+
+    The fragment shader component is created with a placeholder for the path
+    to the shader file. Specify the path to the shader file to use in the
+    shader properties.
+
+    To create a custom effect:
+
+    \list 1
+        \li Drag and drop an \uicontrol {Effect} type from the
+            \uicontrol {Qt Quick 3D Custom Shader Utils} tab of
+            \uicontrol Library to a Model component in \uicontrol Navigator.
+        \li Select the custom effect component in \uicontrol Navigator to edit
+            the values of its properties in the \uicontrol Properties view.
+            \image studio-qtquick-3d-custom-effect.png "Custom effect properties"
+        \li In the \uicontrol Passes field, select the pass components for
+            the effect.
+        \li Select the pass component in \uicontrol Navigator to specify values
+            for its properties in \uicontrol Properties.
+            \image studio-qtquick-3d-pass.png "Pass properties"
+        \li To execute commands during the pass, drag and drop the following
+            command types from \uicontrol Library to the custom material in
+            \uicontrol Navigator: \uicontrol Blending, \uicontrol {Buffer Blit},
+            \uicontrol {Buffer Input}, \uicontrol {Cull Mode},
+            \uicontrol {Depth Input}, \uicontrol {Render State}, and
+            \uicontrol {Set Uniform Value}. Then select the commands in the
+            \uicontrol Commands field.
+        \li To allocate a buffer for the pass, drag and drop a \uicontrol Buffer
+            type to the custom material. Then select the buffer in the
+            \uicontrol Buffer field.
+        \li Select the shader component in \uicontrol Navigator to set the path
+            to the shader files in the \uicontrol Source field in
+            \uicontrol Properties.
+            \image studio-qtquick-3d-shader-properties.png "Shader properties"
+    \endlist
+
+    \section1 Creating Custom Materials
+
+    By default, a Custom Material component contains two Shader types, a Shader
+    Info type, and a Pass type. You can add shaders, passes, and other shader
+    utilities to the material.
+
+    \image studio-qtquick-3d-custom-material-navigator.png "Custom material in Navigator"
+
+    By default, fragment and vertex shaders are created with placeholders for
+    the paths to the shader files. Specify the paths to the shader files to use
+    in the shader properties.
+
+    The Shader Info type specifies the shader type and version, as well
+    as the options used by the shader based on the selected shader key values,
+    such as diffuse or specular lighting, refraction, transparency, displacement,
+    transmissiveness, glossiness, and alpha cutout.
+
+    The shaders are used with the Pass type to create the resulting material.
+    A pass can contain multiple rendering passes and other commands. You can
+    use a Buffer type to allocate a buffer for storing intermediate rendering
+    results.
+
+    To create a custom material:
+
+    \list 1
+        \li Drag and drop a \uicontrol {Custom Material} type from the
+            \uicontrol {Qt Quick 3D Custom Shader Utils} tab of
+            \uicontrol Library to a Model component in \uicontrol Navigator.
+        \li Select the custom material component in \uicontrol Navigator to
+            edit the values of its properties in the \uicontrol Properties view.
+            \image studio-qtquick-3d-custom-material.png "Custom material properties"
+        \li Select the \uicontrol Transparency check box to make the material
+            transparent.
+        \li Select the \uicontrol Refraction check box to specify that the
+            material is \l{Using Highlights and Reflections}{reflective}.
+        \li Select the \uicontrol {Always dirty} check box to determine that
+            the material needs to be refreshed every time it is used.
+        \li In the \uicontrol {Shader Info} field, select the shader info
+            type to use.
+        \li In the \uicontrol Passes field, select the pass components for
+            the effect.
+        \li In the \uicontrol Material group, select the
+            \l{Using Highlights and Reflections}{light probe},
+            \l{Simulating Geometry Displacement}{displacement map and amount},
+            and \l{Culling Faces}{culling mode} to use.
+        \li Select the shader info component in \uicontrol Navigator to specify
+            values for its properties in \uicontrol Properties.
+            \image studio-qtquick-3d-shader-info.png "Shader Info properties"
+        \li Select the pass component in \uicontrol Navigator to specify values
+            for its properties in \uicontrol Properties.
+            \image studio-qtquick-3d-pass.png "Pass properties"
+        \li To execute commands during the pass, drag and drop the following
+            command types from \uicontrol Library to the custom material in
+            \uicontrol Navigator: \uicontrol Blending, \uicontrol {Buffer Blit},
+            \uicontrol {Buffer Input}, \uicontrol {Cull Mode},
+            \uicontrol {Depth Input}, \uicontrol {Render State}, and
+            \uicontrol {Set Uniform Value}. Then select the commands in the
+            \uicontrol Commands field.
+        \li To allocate a buffer for the pass, drag and drop a \uicontrol Buffer
+            type to the custom material. Then select the buffer in the
+            \uicontrol Buffer field.
+        \li Select the shader components in \uicontrol Navigator to set the
+            paths to the shader files in the \uicontrol Source field in
+            \uicontrol Properties.
+            \image studio-qtquick-3d-shader-properties.png "Shader properties"
+    \endlist
+*/

doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-custom-shaders.qdoc

@@ -28,7 +28,7 @@
 /*!
     \page studio-3d-custom-shaders.html
     \previouspage studio-3d-effects.html
-    \nextpage studio-3d-lights.html
+    \nextpage studio-3d-custom-effects-materials.html
 
     \title Using Custom Shaders
 

doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-effects.qdoc

@@ -44,6 +44,9 @@
 
     See the following table for available effects and example images.
 
+    For more information about creating your own effects, see
+    \l {Creating Custom Effects and Materials}.
+
     \section1 Available Effects
     \table
     \header

doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-lights.qdoc

@@ -27,7 +27,7 @@
 
 /*!
     \page studio-3d-lights.html
-    \previouspage studio-3d-custom-shaders.html
+    \previouspage studio-3d-custom-effects-materials.html
     \nextpage studio-3d-camera.html
 
     \title Using Lights

doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-materials-shaders.qdoc

@@ -3,7 +3,7 @@
 ** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
-** This file is part of Qt Desing Studio.
+** This file is part of Qt Design Studio.
 **
 ** $QT_BEGIN_LICENSE:FDL$
 ** Commercial License Usage
@@ -48,7 +48,7 @@
     \list
         \li Default material
         \li Principled material
-        \li Custom material
+        \li \l{Creating Custom Effects and Materials}{Custom material}
         \li Texture
     \endlist
 
@@ -56,8 +56,7 @@
     material to define how the mesh is shaded. The DefaultMaterial component
     is the easiest way to define such a material. The PrincipledMaterial
     component specifies the minimum amount of properties. The CustomMaterial
-    component enables you to access the Qt Quick 3D material library and
+    component enables you to construct your own materials.
-    to implement your own materials.
 
     You can use the \l Texture component to apply textures to materials. It
     defines an image and how the image is mapped to meshes in a 3D scene. For
@@ -219,30 +218,6 @@
     is not rendered. Culling makes rendering objects quicker and more efficient
     by reducing the number of polygons to draw.
 
-    \section1 Creating Custom Materials
-
-    The material uses a Shader component to specify shader source and shader
-    stage. These are used with the \uicontrol passes property to create the
-    resulting material. The passes can contain multiple rendering passes and
-    also other commands.
-
-    Normally, only the fragment shader needs to be specified as a value for
-    the \uicontrol passes property. The material library generates the vertex
-    shader for the material. The material can also create buffers to store
-    intermediate rendering results.
-
-    The \uicontrol shaderInfo property specifies settings for the shader.
-
-    To specify that the material state is always dirty, which indicates that
-    the material needs to be refreshed every time it is used, select the
-    \uicontrol alwaysDirty check box.
-
-    To specify that the material has refraction, select the
-    \uicontrol hasRefraction check box.
-
-    To specify that the material has transparency, select the
-    \uicontrol hasTransparency check box.
-
     \section1 Applying Materials to Models
 
     To apply materials to models: