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>

16 files changed, 180 insertions, 31 deletions

diff --git a/doc/qtcreator/src/qtcreator-toc.qdoc b/doc/qtcreator/src/qtcreator-toc.qdoc
index 269d6c7a12..8b3f1efa24 100644
--- a/doc/qtcreator/src/qtcreator-toc.qdoc
+++ b/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}
diff --git a/doc/qtdesignstudio/images/studio-qtquick-3d-custom-effect-navigator.png b/doc/qtdesignstudio/images/studio-qtquick-3d-custom-effect-navigator.png
new file mode 100644
index 0000000000..be1814c66e
--- /dev/null
+++ b/doc/qtdesignstudio/images/studio-qtquick-3d-custom-effect-navigator.png
diff --git a/doc/qtdesignstudio/images/studio-qtquick-3d-custom-effect.png b/doc/qtdesignstudio/images/studio-qtquick-3d-custom-effect.png
new file mode 100644
index 0000000000..c430657dae
--- /dev/null
+++ b/doc/qtdesignstudio/images/studio-qtquick-3d-custom-effect.png
diff --git a/doc/qtdesignstudio/images/studio-qtquick-3d-custom-material-navigator.png b/doc/qtdesignstudio/images/studio-qtquick-3d-custom-material-navigator.png
new file mode 100644
index 0000000000..43131421af
--- /dev/null
+++ b/doc/qtdesignstudio/images/studio-qtquick-3d-custom-material-navigator.png
diff --git a/doc/qtdesignstudio/images/studio-qtquick-3d-custom-material.png b/doc/qtdesignstudio/images/studio-qtquick-3d-custom-material.png
new file mode 100644
index 0000000000..a6499d990d
--- /dev/null
+++ b/doc/qtdesignstudio/images/studio-qtquick-3d-custom-material.png
diff --git a/doc/qtdesignstudio/images/studio-qtquick-3d-pass.png b/doc/qtdesignstudio/images/studio-qtquick-3d-pass.png
new file mode 100644
index 0000000000..572ff78a08
--- /dev/null
+++ b/doc/qtdesignstudio/images/studio-qtquick-3d-pass.png
diff --git a/doc/qtdesignstudio/images/studio-qtquick-3d-shader-info.png b/doc/qtdesignstudio/images/studio-qtquick-3d-shader-info.png
new file mode 100644
index 0000000000..7e1667f16d
--- /dev/null
+++ b/doc/qtdesignstudio/images/studio-qtquick-3d-shader-info.png
diff --git a/doc/qtdesignstudio/images/studio-qtquick-3d-shader-properties.png b/doc/qtdesignstudio/images/studio-qtquick-3d-shader-properties.png
new file mode 100644
index 0000000000..94e85a8529
--- /dev/null
+++ b/doc/qtdesignstudio/images/studio-qtquick-3d-shader-properties.png
diff --git a/doc/qtdesignstudio/images/studio-qtquick-3d-shader-utilities.png b/doc/qtdesignstudio/images/studio-qtquick-3d-shader-utilities.png
new file mode 100644
index 0000000000..56da683c00
--- /dev/null
+++ b/doc/qtdesignstudio/images/studio-qtquick-3d-shader-utilities.png
diff --git a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc
index 1bf80045c7..4a0edda2ef 100644
--- a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc
+++ b/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}
diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-components.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-components.qdoc
index b9b463c52e..157d0934c0 100644
--- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-components.qdoc
+++ b/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.
diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-custom-effects-materials.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-custom-effects-materials.qdoc
new file mode 100644
index 0000000000..b5d03d9fb9
--- /dev/null
+++ b/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
+*/
diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-custom-shaders.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-custom-shaders.qdoc
index 27c6c5fc1c..2232020c60 100644
--- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-custom-shaders.qdoc
+++ b/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
 
diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-effects.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-effects.qdoc
index 6ff97946a5..a1839cca56 100644
--- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-effects.qdoc
+++ b/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
diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-lights.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-lights.qdoc
index 8a1737c0c3..555bf9d91b 100644
--- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-lights.qdoc
+++ b/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
diff --git a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-materials-shaders.qdoc b/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-materials-shaders.qdoc
index 54873e84d5..f198f2d93f 100644
--- a/doc/qtdesignstudio/src/qtquick3d-editor/qtdesignstudio-3d-materials-shaders.qdoc
+++ b/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
-    to implement your own materials.
+    component enables you to construct 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: