aboutsummaryrefslogtreecommitdiffstats
path: root/doc/reference/modules/qt-shadertools-module.qdoc
blob: dc8cf6d6fa1a8871be026ddf20178a625563063e (plain)
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
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
/****************************************************************************
**
** Copyright (C) 2025 Ivan Komissarov (abbapoh@gmail.com).
** Contact: https://www.qt.io/licensing/
**
** This file is part of Qbs.
**
** $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$
**
****************************************************************************/

/*!
    \qmltype Qt.shadertools
    \inqmlmodule QbsModules
    \brief Provides Qt Shader Tools support.

    The Qt.shadertools module provides functionality for compiling and processing shaders
    in \QBS projects. It supports various shader languages including GLSL, HLSL, and MSL.

    \section2 Relevant File Tags
    \target filetags-qtshadertools

    \table
    \header
        \li Tag
        \li Auto-tagged File Names
        \li Since
        \li Description
    \row
        \li \c{qt.shader}
        \li \c{*.vert, *.tesc, *.tese, *.frag, *.comp}
        \li \c{3.0}
        \li Source files with these extensions are considered shaders and are processed by
            the qsb tool.
    \row
        \li \c{qt.shader.vertex}
        \li \c{*.vert}
        \li \c{3.0}
        \li Source files with this extension are considered vertex shaders.
    \row
        \li \c{qt.shader.fragment}
        \li \c{*.frag}
        \li \c{3.0}
        \li Source files with this extension are considered fragment shaders.
    \row
        \li \c{qt.shader.compute}
        \li \c{*.comp}
        \li \c{3.0}
        \li Source files with this extension are considered compute shaders.
    \row
        \li \c{qt.shader.tessellation}
        \li \c{*.tesc}
        \li \c{3.0}
        \li Source files with this extension are considered tessellation shaders. These shaders
            are automatically processed by using tessellation properties.
    \row
        \li \c{qt.compiled_shader}
        \li n/a
        \li \c{3.0}
        \li This tag is attached to the output artifacts of the rule that runs the qsb tool.
    \endtable

    \section2 Example

    \code
    QtApplication {
        name: "shader-app"
        type: "application"

        Depends { name: "Qt.shadertools" }

        files: ["shader.frag", "shader.vert"]
        Qt.shadertools.glslVersions: ["300 es", "330"]
        Qt.shadertools.hlslVersions: ["50"]
        Qt.shadertools.mslVersions: ["12"]
    }
    \endcode

    For more details on the \c{qsb} tool, see
    \l{https://doc.qt.io/qt-6/qtshadertools-qsb.html}{its documentation}

*/

/*!
    \qmlproperty string Qt.shadertools::generatedShadersDir

    The directory where compiled shaders will be placed.

    \defaultvalue \c{"shaders"}
*/

/*!
    \qmlproperty string Qt.shadertools::qsbName

    The name of the Qt Shader Tools compiler executable.

    \defaultvalue \c{"qsb"}
*/

/*!
    \qmlproperty stringList Qt.shadertools::glslVersions

    List of GLSL versions to generate. Each version should be specified as a string,
    for example \c{"100 es"} for GLSL ES 1.00.

    If this property is set to \c{[]}, GLSL generation is disabled.

    \defaultvalue \c{[]}
*/

/*!
    \qmlproperty stringList Qt.shadertools::hlslVersions

    List of HLSL (shader model) versions to generate. The versions follow GLSL-style
    version numbers, where 50 corresponds to Shader Model 5.0.

    If this property is set to \c{[]}, HLSL generation is disabled.

    \defaultvalue \c{[]}
*/

/*!
    \qmlproperty stringList Qt.shadertools::mslVersions

    List of Metal Shading Language versions to generate. 12 corresponds to version 1.2.

    If this property is set to \c{[]}, MSL generation is disabled.

    \defaultvalue \c{[]}
*/

/*!
    \qmlproperty bool Qt.shadertools::useQt6Versions

    Use default version used by Qt6.

    This is equivalent to passing \c{--qt6} switch to the \c{qsb} tool.

    \defaultvalue \c{false}
*/

/*!
    \qmlproperty bool Qt.shadertools::tessellation

    Whether the shaders are used in a pipeline that uses tessellation.

    By default, \QBS adds flags contolled by \l{tessellationMode} and \l{tessellationVertexCount}
    properties for all files with the \c{"qt.shader.tessellation"} file tag. Set this property to
    \c{false} to disable tessellation options for such files.

    \defaultvalue \c{true}
*/

/*!
    \qmlproperty string Qt.shadertools::tessellationMode

    The tessellation mode. Can be either \c{"triangles"} or \c{"quads"}.

    This property must be specified when a tessellation control shader is used.

    \defaultvalue \c{"triangles"}
*/

/*!
    \qmlproperty int Qt.shadertools::tessellationVertexCount

    The output vertex count from the tessellation control stage.

    \defaultvalue \c{3}
*/

/*!
    \qmlproperty int Qt.shadertools::viewCount

    The number of views a vertex shader is used with. Relevant for multiview
    functionality (GL_OVR_multiview2, VK_KHR_multiview, D3D12 view instancing).

    \defaultvalue \c{undefined}
*/

/*!
    \qmlproperty bool Qt.shadertools::batchable

    Whether vertex shaders should be made batchable for use with Qt Quick.

    \defaultvalue \c{false}
*/

/*!
    \qmlproperty int Qt.shadertools::zOrderLocation

    When \l{Qt.shadertools::batchable}{batchable} is true, this specifies the location for the
    additional vertex input that is injected with location 7 by default.

    Use this property to change the location of the injected vertex input to another value.

    This becomes relevant if the vertex shader has many inputs and 7 is in use and would clash.

    \defaultvalue \c{undefined}
*/

/*!
    \qmlproperty bool Qt.shadertools::optimized

    Whether to perform SPIR-V optimizations using spirv-opt.

    \defaultvalue \c{false}
*/

/*!
    \qmlproperty stringList Qt.shadertools::defines

    List of preprocessor defines to be active during shader compilation.

    Defines should be added as \c{"<name>=<value>"} pairs.

    \defaultvalue \c{[]}
*/

/*!
    \qmlproperty bool Qt.shadertools::debugInformation

    Whether to generate full debug information for SPIR-V.

    \defaultvalue \c{false}
*/

/*!
    \qmlproperty bool Qt.shadertools::addResourceData

    Whether to automatically add the compiled shaders to the Qt resource data.

    \defaultvalue \c{true}
*/

/*!
    \qmlproperty bool Qt.shadertools::enableLinking

    Set this property to \c{true} to enable linking to the QtShaderTools library.

    For example:
    \code
    QtApplication {
        name: "shader-app"
        Depends { name: "Qt.shadertools" }
        Qt.shadertools.enableLinking: true
    }
    \endcode

    The Qt.shadertools module can be used in two ways:
    \list
        \li Using the \c{qsb} tool to compile shaders.
        \li Linking directly to the \l{https://doc.qt.io/qt-6/qtshadertools-index.html}{QtShaderTools}
            library and using the \l{https://doc.qt.io/qt-6/qshaderbaker.html}{QShaderBaker} class.
    \endlist

    This property and \l{useCompiler} property controls which mode is used. You can also enable
    both modes by setting both properties to \c{true}.

    \defaultvalue \c{false}
*/

/*!
    \qmlproperty bool Qt.shadertools::useCompiler

    Whether to use the Qt Shader Tools compiler.

    Set this property to \c{false} to disable the qsb tool. This is set to \c{false} by default
    if \l{Qt.shadertools::enableLinking}{enableLinking} is \c{true}.

    \defaultvalue \c{true}
*/