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
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
|
// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
#include "qsgmaterial.h"
#include "qsgrenderer_p.h"
QT_BEGIN_NAMESPACE
Q_DECLARE_LOGGING_CATEGORY(lcQsgLeak)
#ifndef QT_NO_DEBUG
bool qsg_material_failure = false;
bool qsg_test_and_clear_material_failure()
{
bool fail = qsg_material_failure;
qsg_material_failure = false;
return fail;
}
void qsg_set_material_failure()
{
qsg_material_failure = true;
}
#endif
/*!
\group qtquick-scenegraph-materials
\title Qt Quick Scene Graph Material Classes
\brief classes used to define materials in the Qt Quick Scene Graph.
This page lists the material classes in \l {Qt Quick}'s
\l {scene graph}{Qt Quick Scene Graph}.
*/
#ifndef QT_NO_DEBUG
static int qt_material_count = 0;
static void qt_print_material_count()
{
qCDebug(lcQsgLeak, "Number of leaked materials: %i", qt_material_count);
qt_material_count = -1;
}
#endif
/*!
\class QSGMaterialType
\brief The QSGMaterialType class is used as a unique type token in combination with QSGMaterial.
\inmodule QtQuick
\ingroup qtquick-scenegraph-materials
It serves no purpose outside the QSGMaterial::type() function.
\note All classes with QSG prefix should be used solely on the scene graph's
rendering thread. See \l {Scene Graph and Rendering} for more information.
*/
/*!
\class QSGMaterial
\brief The QSGMaterial class encapsulates rendering state for a shader program.
\inmodule QtQuick
\ingroup qtquick-scenegraph-materials
QSGMaterial and QSGMaterialShader subclasses form a tight relationship. For
one scene graph (including nested graphs), there is one unique
QSGMaterialShader instance which encapsulates the shaders the scene graph
uses to render that material, such as a shader to flat coloring of
geometry. Each QSGGeometryNode can have a unique QSGMaterial containing the
how the shader should be configured when drawing that node, such as the
actual color to used to render the geometry.
QSGMaterial has two virtual functions that both need to be implemented. The
function type() should return a unique instance for all instances of a
specific subclass. The createShader() function should return a new instance
of QSGMaterialShader, specific to that subclass of QSGMaterial.
A minimal QSGMaterial implementation could look like this:
\code
class Material : public QSGMaterial
{
public:
QSGMaterialType *type() const override { static QSGMaterialType type; return &type; }
QSGMaterialShader *createShader(QSGRendererInterface::RenderMode) const override { return new Shader; }
};
\endcode
See the \l{Scene Graph - Custom Material}{Custom Material example} for an introduction
on implementing a QQuickItem subclass backed by a QSGGeometryNode and a custom
material.
\note createShader() is called only once per QSGMaterialType, to reduce
redundant work with shader preparation. If a QSGMaterial is backed by
multiple sets of vertex and fragment shader combinations, the implementation
of type() must return a different, unique QSGMaterialType pointer for each
combination of shaders.
\note All classes with QSG prefix should be used solely on the scene graph's
rendering thread. See \l {Scene Graph and Rendering} for more information.
\sa QSGMaterialShader, {Scene Graph - Custom Material}, {Scene Graph - Two Texture Providers}, {Scene Graph - Graph}
*/
/*!
\internal
*/
QSGMaterial::QSGMaterial()
{
Q_UNUSED(m_reserved);
#ifndef QT_NO_DEBUG
if (lcQsgLeak().isDebugEnabled()) {
++qt_material_count;
static bool atexit_registered = false;
if (!atexit_registered) {
atexit(qt_print_material_count);
atexit_registered = true;
}
}
#endif
}
/*!
\internal
*/
QSGMaterial::~QSGMaterial()
{
#ifndef QT_NO_DEBUG
if (lcQsgLeak().isDebugEnabled()) {
--qt_material_count;
if (qt_material_count < 0)
qCDebug(lcQsgLeak, "Material destroyed after qt_print_material_count() was called.");
}
#endif
}
/*!
\enum QSGMaterial::Flag
\value Blending Set this flag to true if the material requires blending to be
enabled during rendering.
\value RequiresDeterminant Set this flag to true if the material relies on
the determinant of the matrix of the geometry nodes for rendering.
\value RequiresFullMatrixExceptTranslate Set this flag to true if the material
relies on the full matrix of the geometry nodes for rendering, except the translation part.
\value RequiresFullMatrix Set this flag to true if the material relies on
the full matrix of the geometry nodes for rendering.
\value NoBatching Set this flag to true if the material uses shaders that are
incompatible with the \l{Qt Quick Scene Graph Default Renderer}{scene graph's batching
mechanism}. This is relevant in certain advanced usages, such as, directly
manipulating \c{gl_Position.z} in the vertex shader. Such solutions are often tied to
a specific scene structure, and are likely not safe to use with arbitrary contents in
a scene. Thus this flag should only be set after appropriate investigation, and will
never be needed for the vast majority of materials. Setting this flag can lead to
reduced performance due to having to issue more draw calls. This flag was introduced
in Qt 6.3.
\value CustomCompileStep In Qt 6 this flag is identical to NoBatching. Prefer using
NoBatching instead.
\omitvalue MultiView2
\omitvalue MultiView3
\omitvalue MultiView4
*/
/*!
\fn QSGMaterial::Flags QSGMaterial::flags() const
Returns the material's flags.
*/
/*!
Sets the flags \a flags on this material if \a on is true;
otherwise clears the attribute.
*/
void QSGMaterial::setFlag(Flags flags, bool on)
{
if (on)
m_flags |= flags;
else
m_flags &= ~flags;
}
/*!
Compares this material to \a other and returns 0 if they are equal; -1 if
this material should sort before \a other and 1 if \a other should sort
before.
The scene graph can reorder geometry nodes to minimize state changes.
The compare function is called during the sorting process so that
the materials can be sorted to minimize state changes in each
call to QSGMaterialShader::updateState().
The this pointer and \a other is guaranteed to have the same type().
*/
int QSGMaterial::compare(const QSGMaterial *other) const
{
Q_ASSERT(other && type() == other->type());
const qintptr diff = qintptr(this) - qintptr(other);
return diff < 0 ? -1 : (diff > 0 ? 1 : 0);
}
/*!
\fn QSGMaterialType *QSGMaterial::type() const
This function is called by the scene graph to query an identifier that is
unique to the QSGMaterialShader instantiated by createShader().
For many materials, the typical approach will be to return a pointer to a
static, and so globally available, QSGMaterialType instance. The
QSGMaterialType is an opaque object. Its purpose is only to serve as a
type-safe, simple way to generate unique material identifiers.
\code
QSGMaterialType *type() const override
{
static QSGMaterialType type;
return &type;
}
\endcode
*/
/*!
\fn QSGMaterialShader *QSGMaterial::createShader(QSGRendererInterface::RenderMode renderMode) const
This function returns a new instance of a the QSGMaterialShader
implementation used to render geometry for a specific implementation
of QSGMaterial.
The function will be called only once for each combination of material type and \a renderMode
and will be cached internally.
For most materials, the \a renderMode can be ignored. A few materials may need
custom handling for specific render modes. For instance if the material implements
antialiasing in a way that needs to account for perspective transformations when
RenderMode3D is in use.
*/
/*!
\return The number of views in case of the material is used in multiview
rendering.
\note The return value is valid only when called from createShader(), and
afterwards. The value is not necessarily up-to-date before createShader()
is invokved by the scene graph.
Normally the return value is \c 1. A view count greater than 2 implies a
\e{multiview render pass}. Materials that support multiview are expected to
query viewCount() in createShader(), or in their QSGMaterialShader
constructor, and ensure the appropriate shaders are picked. The vertex
shader is then expected to use
\c{gl_ViewIndex} to index the modelview-projection matrix array as there
are multiple matrices in multiview mode. (one for each view)
As an example, take the following simple vertex shader:
\badcode
#version 440
layout(location = 0) in vec4 vertexCoord;
layout(location = 1) in vec4 vertexColor;
layout(location = 0) out vec4 color;
layout(std140, binding = 0) uniform buf {
mat4 matrix[2];
float opacity;
};
void main()
{
gl_Position = matrix[gl_ViewIndex] * vertexCoord;
color = vertexColor * opacity;
}
\endcode
This shader is prepared to handle 2 views, and 2 views only. It is not
compatible with other view counts. When conditioning the shader, the \c qsb
tool has to be invoked with \c{--view-count 2} or, if using the CMake
integration,
\c{VIEW_COUNT 2} must be specified in the \c{qt_add_shaders()} command.
\note A line with \c{#extension GL_EXT_multiview : require} is injected
automatically by \c qsb whenever a view count of 2 or greater is set.
Developers are encouraged to use the automatically injected preprocessor
variable \c{QSHADER_VIEW_COUNT} to simplify the handling of the different
number of views. For example, if there is a need to support both
non-multiview and multiview with a view count of 2 in the same source file,
the following could be done:
\badcode
#version 440
layout(location = 0) in vec4 vertexCoord;
layout(location = 1) in vec4 vertexColor;
layout(location = 0) out vec4 color;
layout(std140, binding = 0) uniform buf {
#if QSHADER_VIEW_COUNT >= 2
mat4 matrix[QSHADER_VIEW_COUNT];
#else
mat4 matrix;
#endif
float opacity;
};
void main()
{
#if QSHADER_VIEW_COUNT >= 2
gl_Position = matrix[gl_ViewIndex] * vertexCoord;
#else
gl_Position = matrix * vertexCoord;
#endif
color = vertexColor * opacity;
}
\endcode
The same source file can now be run through \c qsb or \c{qt_add_shaders()}
twice, once without specify the view count, and once with the view count
set to 2. The material can then pick the appropriate .qsb file based on
viewCount() at run time.
With CMake, this could looks similar to the following. With this example
the corresponding QSGMaterialShader is expected to choose between
\c{:/shaders/example.vert.qsb} and \c{:/shaders/multiview/example.vert.qsb}
based on the value of viewCount(). (same goes for the fragment shader)
\badcode
qt_add_shaders(application "application_shaders"
PREFIX
/
FILES
shaders/example.vert
shaders/example.frag
)
qt_add_shaders(application "application_multiview_shaders"
GLSL
330,300es
HLSL
61
MSL
12
VIEW_COUNT
2
PREFIX
/
FILES
shaders/example.vert
shaders/example.frag
OUTPUTS
shaders/multiview/example.vert
shaders/multiview/example.frag
)
\endcode
\note The fragment shader should be treated the same way the vertex shader
is, even though the fragment shader code cannot have any dependency on the
view count (\c{gl_ViewIndex}), for maximum portability. There are two
reasons for including fragment shaders too in the multiview set. One is that
mixing different shader versions within the same graphics pipeline can be
problematic, depending on the underlying graphics API: with D3D12 for
example, mixing HLSL shaders for shader model 5.0 and 6.1 would generate an
error. The other is that having \c QSHADER_VIEW_COUNT defined in fragment
shaders can be very useful, for example when sharing a uniform buffer layout
between the vertex and fragment stages.
\note For OpenGL the minimum GLSL version for vertex shaders relying on
\c{gl_ViewIndex} is \c 330. Lower versions may be accepted at build time,
but may lead to an error at run time, depending on the OpenGL implementation.
As a convenience, there is also a \c MULTIVIEW option for qt_add_shaders().
This first runs the \c qsb tool normally, then overrides \c VIEW_COUNT to
\c 2, sets \c GLSL, \c HLSL, \c MSL to some suitable defaults, and runs \c
qsb again, this time outputting .qsb files with a suffix added. The material
implementation can then use the \l QSGMaterialShader::setShaderFileName()
overload taking a \c viewCount argument, that automatically picks the
correct .qsb file.
The following is therefore mostly equivalent to the example call shown
above, except that no manually managed output files need to be specified.
Note that there can be cases when the automatically chosen shading language
versions are not sufficient, in which case applications should continue
specify everything explicitly.
\badcode
qt_add_shaders(application "application_multiview_shaders"
MULTIVIEW
PREFIX
/
FILES
shaders/example.vert
shaders/example.frag
)
\endcode
See \l QRhi::MultiView, \l QRhiColorAttachment::setMultiViewCount(), and
\l QRhiGraphicsPipeline::setMultiViewCount() for further, lower-level details
on multiview support in Qt. The Qt Quick scene graph renderer is prepared to
recognize multiview render targets, when specified via
\l QQuickRenderTarget::fromRhiRenderTarget() or the \c MultiView
functions such as \l{QQuickRenderTarget::}{fromVulkanImageMultiView()}, and
propagate the view count to graphics pipelines and the materials.
\since 6.8
*/
int QSGMaterial::viewCount() const
{
if (m_flags.testFlag(MultiView4))
return 4;
if (m_flags.testFlag(MultiView3))
return 3;
if (m_flags.testFlag(MultiView2))
return 2;
return 1;
}
QT_END_NAMESPACE
|