1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
|
/****************************************************************************
**
** 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
The \l{Applying 3D Effects}{Qt Quick 3D Effects} and \l{Using 3D Materials}
{Qt Quick 3D Materials} modules contain a set of ready-made effects and
materials that you can apply to 3D models. If the ready-made effects and
materials don't meet your needs, you can create custom effects and
materials. Each effect or material must have a fragment shader that
implements all the functions needed to calculate the shaded color. The
material system also offers ready-made functions to help you implement
the material.
The material system supports dielectric, metallic, and transparent
materials, point lights, area lights, ambient occlusion, shadowing,
two-sided polygons, index-of-refraction, and fragment cutoff (masking).
For more information, see \l {Qt Quick 3D Custom Material Reference}.
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 those modules to
your project.
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. To use custom \e uniforms
in the shader files, you must specify them as QML properties for the custom
effect or material component. \QDS automatically generates the uniforms for
the shaders based on the property values.
\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 pass component 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}. The command components are created
at the same level as the pass component and automatically added to
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 To add a shader to the pass, drag and drop the \uicontrol Shader
type from the \uicontrol Library to the pass component in \uicontrol
Navigator. The shader components are created at the same
level as the pass component and automatically added to the
\uicontrol Shaders 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
\section1 Creating Shader Files
The requirements set for shaders that you can use in custom effects and
materials are described in \l {Qt Quick 3D Custom Material Reference}.
If you use custom uniforms in the shader files, you must specify them
as QML properties for the custom effect or material component. \QDS
automatically generates the uniforms based on the property values.
For example, the following code snippet shows fragment shader code that
uses two uniforms: \c uTextureInUse and \c uInputTexture.
\code
out vec4 fragColor;
in vec3 pos;
in vec3 texCoord0;
void main() {
vec4 textCol;
if (uTextureInUse)
textCol = texture( uInputTexture, texCoord0.xy );
fragColor = vec4(pos.x * 0.02 * textCol.x, pos.y * 0.02 * textCol.y, pos.z * 0.02, 1.0);
}
\endcode
To use the above fragment shader in a custom effect or material component,
you must remove the uniforms from the shader code and define them as
properties for the component in \uicontrol {Connection View} >
\uicontrol Properties.
\image studio-custom-material-uniform-properties.png "Uniforms as properties in Connection View Properties tab"
For more information about adding properties, see
\l{Specifying Dynamic Properties}.
*/
|
