1 files changed, 163 insertions, 0 deletions
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 00000000000..b5d03d9fb90
--- /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
+*/