1// Copyright (C) 2019 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qsgmaterial.h"
5#include "qsgrenderer_p.h"
6#include "qsgmaterialshader_p.h"
7#include <QtCore/QFile>
8
9QT_BEGIN_NAMESPACE
10
11/*!
12 \class QSGMaterialShader
13 \brief The QSGMaterialShader class represents a graphics API independent shader program.
14 \inmodule QtQuick
15 \ingroup qtquick-scenegraph-materials
16 \since 5.14
17
18 QSGMaterialShader represents a combination of vertex and fragment shaders,
19 data that define the graphics pipeline state changes, and logic that
20 updates graphics resources, such as uniform buffers and textures.
21
22 \note All classes with QSG prefix should be used solely on the scene graph's
23 rendering thread. See \l {Scene Graph and Rendering} for more information.
24
25 The QSGMaterial and QSGMaterialShader form a tight relationship. For one
26 scene graph (including nested graphs), there is one unique
27 QSGMaterialShader instance that encapsulates the shaders and other data
28 the scene graph uses to render an object with that material. Each
29 QSGGeometryNode can have a unique QSGMaterial that defines how the graphics
30 pipeline must be configured while drawing the node. An instance of
31 QSGMaterialShader is never created explicitly by the user, it will be
32 created on demand by the scene graph through QSGMaterial::createShader().
33 The scene graph creates an instance of QSGMaterialShader by calling the
34 QSGMaterial::createShader() method, ensuring that there is only one
35 instance of each shader implementation.
36
37 In Qt 5, QSGMaterialShader was tied to OpenGL. It was built directly on
38 QOpenGLShaderProgram and had functions like \c updateState() that could
39 issue arbitrary OpenGL commands. This is no longer the case in Qt 6.
40 QSGMaterialShader is not strictly data-oriented, meaning it provides data
41 (shaders and the desired pipeline state changes) together with logic that
42 updates data in a uniform buffer. Graphics API access is not provided. This
43 means that a QSGMaterialShader cannot make OpenGL, Vulkan, Metal, or Direct
44 3D calls on its own. Together with the unified shader management, this
45 allows a QSGMaterialShader to be written once, and be functional with any of
46 the supported graphics APIs at run time.
47
48 The shaders set by calling the protected setShaderFileName() function
49 control what material does with the vertex data from the geometry, and how
50 the fragments are shaded. A QSGMaterialShader will typically set a vertex
51 and a fragment shader during construction. Changing the shaders afterwards
52 may not lead to the desired effect and must be avoided.
53
54 In Qt 6, the default approach is to ship \c{.qsb} files with the application,
55 typically embedded via the resource system, and referenced when calling
56 setShaderFileName(). The \c{.qsb} files are generated offline, or at latest
57 at application build time, from Vulkan-style GLSL source code using the \c
58 qsb tool from the Qt Shader Tools module.
59
60 There are three virtuals that can be overridden. These provide the data, or
61 the logic to generate the data, for uniform buffers, textures, and pipeline
62 state changes.
63
64 updateUniformData() is the function that is most commonly reimplemented in
65 subclasses. This function is expected to update the contents of a
66 QByteArray that will then be exposed to the shaders as a uniform buffer.
67 Any QSGMaterialShader that has a uniform block in its vertex or fragment
68 shader must reimplement updateUniformData().
69
70 updateSampledImage() is relevant when the shader code samples textures. The
71 function will be invoked for each sampler (or combined image sampler, in
72 APIs where relevant), giving it the option to specify which QSGTexture
73 should be exposed to the shader.
74
75 The shader pipeline state changes are less often used. One use case is
76 materials that wish to use a specific blend mode. The relevant function is
77 updateGraphicsPipelineState(). This function is not called unless the
78 QSGMaterialShader has opted in by setting the flag
79 UpdatesGraphicsPipelineState. The task of the function is to update the
80 GraphicsPipelineState struct instance that is passed to it with the
81 desired changes. Currently only blending and culling-related features are
82 available, other states cannot be controlled by materials.
83
84 A minimal example, that also includes texture support, could be the
85 following. Here we assume that Material is the QSGMaterial that creates an
86 instance of Shader in its \l{QSGMaterial::createShader()}{createShader()},
87 and that it holds a QSGTexture we want to sample in the fragment shader. The
88 vertex shader relies only on the modelview-projection matrix.
89
90 \code
91 class Shader : public QSGMaterialShader
92 {
93 public:
94 Shader()
95 {
96 setShaderFileName(VertexStage, QLatin1String(":/materialshader.vert.qsb"));
97 setShaderFileName(FragmentStage, QLatin1String(":/materialshader.frag.qsb"));
98 }
99
100 bool updateUniformData(RenderState &state, QSGMaterial *, QSGMaterial *)
101 {
102 bool changed = false;
103 QByteArray *buf = state.uniformData();
104 if (state.isMatrixDirty()) {
105 const QMatrix4x4 m = state.combinedMatrix();
106 memcpy(buf->data(), m.constData(), 64);
107 changed = true;
108 }
109 return changed;
110 }
111
112 void updateSampledImage(RenderState &, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *)
113 {
114 Material *mat = static_cast<Material *>(newMaterial);
115 if (binding == 1)
116 *texture = mat->texture();
117 }
118 };
119 \endcode
120
121 The Vulkan-style GLSL source code for the shaders could look like the
122 following. These are expected to be preprocessed offline using the \c qsb
123 tool, which generates the \c{.qsb} files referenced in the Shader()
124 constructor.
125
126 \badcode
127 #version 440
128 layout(location = 0) in vec4 aVertex;
129 layout(location = 1) in vec2 aTexCoord;
130 layout(location = 0) out vec2 vTexCoord;
131 layout(std140, binding = 0) uniform buf {
132 mat4 qt_Matrix;
133 } ubuf;
134 out gl_PerVertex { vec4 gl_Position; };
135 void main() {
136 gl_Position = ubuf.qt_Matrix * aVertex;
137 vTexCoord = aTexCoord;
138 }
139 \endcode
140
141 \badcode
142 #version 440
143 layout(location = 0) in vec2 vTexCoord;
144 layout(location = 0) out vec4 fragColor;
145 layout(binding = 1) uniform sampler2D srcTex;
146 void main() {
147 vec4 c = texture(srcTex, vTexCoord);
148 fragColor = vec4(c.rgb * 0.5, 1.0);
149 }
150 \endcode
151
152 \note All classes with QSG prefix should be used solely on the scene graph's
153 rendering thread. See \l {Scene Graph and Rendering} for more information.
154
155 \sa QSGMaterial, {Scene Graph - Custom Material}, {Scene Graph - Two Texture Providers}, {Scene Graph - Graph}
156 */
157
158/*!
159 \enum QSGMaterialShader::Flag
160 Flag values to indicate special material properties.
161
162 \value UpdatesGraphicsPipelineState Setting this flag enables calling
163 updateGraphicsPipelineState().
164 */
165
166QShader QSGMaterialShaderPrivate::loadShader(const QString &filename)
167{
168 QFile f(filename);
169 if (!f.open(flags: QIODevice::ReadOnly)) {
170 qWarning() << "Failed to find shader" << filename;
171 return QShader();
172 }
173 return QShader::fromSerialized(data: f.readAll());
174}
175
176void QSGMaterialShaderPrivate::clearCachedRendererData()
177{
178 for (int i = 0; i < MAX_SHADER_RESOURCE_BINDINGS; ++i)
179 textureBindingTable[i].clear();
180 for (int i = 0; i < MAX_SHADER_RESOURCE_BINDINGS; ++i)
181 samplerBindingTable[i].clear();
182}
183
184static inline QRhiShaderResourceBinding::StageFlags toSrbStage(QShader::Stage stage)
185{
186 switch (stage) {
187 case QShader::VertexStage:
188 return QRhiShaderResourceBinding::VertexStage;
189 case QShader::FragmentStage:
190 return QRhiShaderResourceBinding::FragmentStage;
191 default:
192 Q_UNREACHABLE();
193 break;
194 }
195 return { };
196}
197
198void QSGMaterialShaderPrivate::prepare(QShader::Variant vertexShaderVariant)
199{
200 ubufBinding = -1;
201 ubufSize = 0;
202 ubufStages = { };
203 memset(s: static_cast<void *>(combinedImageSamplerBindings), c: 0, n: sizeof(combinedImageSamplerBindings));
204 memset(s: static_cast<void *>(combinedImageSamplerCount), c: 0, n: sizeof(combinedImageSamplerCount));
205 vertexShader = fragmentShader = nullptr;
206 masterUniformData.clear();
207
208 clearCachedRendererData();
209
210 for (QShader::Stage stage : { QShader::VertexStage, QShader::FragmentStage }) {
211 auto it = shaderFileNames.constFind(key: stage);
212 if (it != shaderFileNames.cend()) {
213 QString fn = *it;
214 const QShader s = loadShader(filename: *it);
215 if (!s.isValid())
216 continue;
217 shaders[stage] = ShaderStageData(s);
218 // load only once, subsequent prepare() calls will have it all in shaders already
219 shaderFileNames.erase(it);
220 }
221 }
222
223 auto vsIt = shaders.find(key: QShader::VertexStage);
224 if (vsIt != shaders.end()) {
225 vsIt->shaderVariant = vertexShaderVariant;
226 vsIt->vertexInputLocations.clear();
227 vsIt->qt_order_attrib_location = -1;
228
229 const QShaderDescription desc = vsIt->shader.description();
230 const QVector<QShaderDescription::InOutVariable> vertexInputs = desc.inputVariables();
231 for (const QShaderDescription::InOutVariable &v : vertexInputs) {
232 if (vertexShaderVariant == QShader::BatchableVertexShader
233 && v.name == QByteArrayLiteral("_qt_order")) {
234 vsIt->qt_order_attrib_location = v.location;
235 } else {
236 vsIt->vertexInputLocations.append(t: v.location);
237 }
238 }
239
240 if (vsIt->vertexInputLocations.contains(t: vsIt->qt_order_attrib_location)) {
241 qWarning(msg: "Vertex input clash in rewritten (batchable) vertex shader at input location %d. "
242 "Vertex shaders must avoid using this location.", vsIt->qt_order_attrib_location);
243 }
244 }
245
246 for (auto it = shaders.begin(); it != shaders.end(); ++it) {
247 const QShaderDescription desc = it->shader.description();
248
249 const QVector<QShaderDescription::UniformBlock> ubufs = desc.uniformBlocks();
250 const int ubufCount = ubufs.size();
251 if (ubufCount > 1) {
252 qWarning(msg: "Multiple uniform blocks found in shader. "
253 "This should be avoided as Qt Quick supports only one.");
254 }
255 for (int i = 0; i < ubufCount; ++i) {
256 const QShaderDescription::UniformBlock &ubuf(ubufs[i]);
257 if (ubufBinding == -1 && ubuf.binding >= 0) {
258 ubufBinding = ubuf.binding;
259 ubufSize = ubuf.size;
260 ubufStages |= toSrbStage(stage: it->shader.stage());
261 masterUniformData.fill(c: '\0', size: ubufSize);
262 } else if (ubufBinding == ubuf.binding && ubuf.binding >= 0) {
263 if (ubuf.size > ubufSize) {
264 ubufSize = ubuf.size;
265 masterUniformData.fill(c: '\0', size: ubufSize);
266 }
267 ubufStages |= toSrbStage(stage: it->shader.stage());
268 } else {
269 qWarning(msg: "Uniform block %s (binding %d) ignored", ubuf.blockName.constData(),
270 ubuf.binding);
271 }
272 }
273
274 const QVector<QShaderDescription::InOutVariable> imageSamplers = desc.combinedImageSamplers();
275 const int imageSamplersCount = imageSamplers.size();
276 for (int i = 0; i < imageSamplersCount; ++i) {
277 const QShaderDescription::InOutVariable &var(imageSamplers[i]);
278
279 if (var.binding < 0)
280 continue;
281
282 if (var.binding < MAX_SHADER_RESOURCE_BINDINGS) {
283 combinedImageSamplerBindings[var.binding] |= toSrbStage(stage: it->shader.stage());
284
285 int count = 1;
286 for (int dim : var.arrayDims)
287 count *= dim;
288
289 combinedImageSamplerCount[var.binding] = count;
290 } else {
291 qWarning(msg: "Encountered invalid combined image sampler (%s) binding %d",
292 var.name.constData(), var.binding);
293 }
294 }
295
296 if (it.key() == QShader::VertexStage)
297 vertexShader = &it.value();
298 else if (it.key() == QShader::FragmentStage)
299 fragmentShader = &it.value();
300 }
301
302 if (vertexShader && vertexShaderVariant == QShader::BatchableVertexShader && vertexShader->qt_order_attrib_location == -1)
303 qWarning(msg: "No rewriter-inserted attribute found, this should not happen.");
304}
305
306/*!
307 Constructs a new QSGMaterialShader.
308 */
309QSGMaterialShader::QSGMaterialShader()
310 : d_ptr(new QSGMaterialShaderPrivate(this))
311{
312}
313
314/*!
315 \internal
316 */
317QSGMaterialShader::QSGMaterialShader(QSGMaterialShaderPrivate &dd)
318 : d_ptr(&dd)
319{
320}
321
322/*!
323 \internal
324 */
325QSGMaterialShader::~QSGMaterialShader()
326{
327}
328
329// We have our own enum as QShader is not initially public. Internally
330// everything works with QShader::Stage however. So convert.
331static inline QShader::Stage toShaderStage(QSGMaterialShader::Stage stage)
332{
333 switch (stage) {
334 case QSGMaterialShader::VertexStage:
335 return QShader::VertexStage;
336 case QSGMaterialShader::FragmentStage:
337 return QShader::FragmentStage;
338 default:
339 Q_UNREACHABLE_RETURN(QShader::VertexStage);
340 }
341}
342
343/*!
344 Sets the \a shader for the specified \a stage.
345 */
346void QSGMaterialShader::setShader(Stage stage, const QShader &shader)
347{
348 Q_D(QSGMaterialShader);
349 d->shaders[toShaderStage(stage)] = QSGMaterialShaderPrivate::ShaderStageData(shader);
350}
351
352/*!
353 Sets the \a filename for the shader for the specified \a stage.
354
355 The file is expected to contain a serialized QShader.
356
357 \warning Shaders, including \c{.qsb} files, are assumed to be trusted
358 content. Application developers are advised to carefully consider the
359 potential implications before allowing the loading of user-provided content
360 that is not part of the application.
361 */
362void QSGMaterialShader::setShaderFileName(Stage stage, const QString &filename)
363{
364 Q_D(QSGMaterialShader);
365 d->shaderFileNames[toShaderStage(stage)] = filename;
366}
367
368/*!
369 Sets the \a filename for the shader for the specified \a stage.
370
371 The file is expected to contain a serialized QShader.
372
373 This overload is used when enabling \l{QSGMaterial::viewCount()}{multiview}
374 rendering, in particular when the \l{Qt Shader Tools Build System
375 Integration}{build system's MULTIVIEW convenience option} is used.
376
377 \a viewCount should be 2, 3, or 4. The \a filename is adjusted automatically
378 based on this.
379
380 \warning Shaders, including \c{.qsb} files, are assumed to be trusted
381 content. Application developers are advised to carefully consider the
382 potential implications before allowing the loading of user-provided content
383 that is not part of the application.
384
385 \since 6.8
386 */
387void QSGMaterialShader::setShaderFileName(Stage stage, const QString &filename, int viewCount)
388{
389 Q_D(QSGMaterialShader);
390 if (viewCount == 2)
391 d->shaderFileNames[toShaderStage(stage)] = filename + QStringLiteral(".mv2qsb");
392 else if (viewCount == 3)
393 d->shaderFileNames[toShaderStage(stage)] = filename + QStringLiteral(".mv3qsb");
394 else if (viewCount == 4)
395 d->shaderFileNames[toShaderStage(stage)] = filename + QStringLiteral(".mv4qsb");
396 else
397 d->shaderFileNames[toShaderStage(stage)] = filename;
398}
399
400/*!
401 \return the currently set flags for this material shader.
402 */
403QSGMaterialShader::Flags QSGMaterialShader::flags() const
404{
405 Q_D(const QSGMaterialShader);
406 return d->flags;
407}
408
409/*!
410 Sets the \a flags on this material shader if \a on is true;
411 otherwise clears the specified flags.
412*/
413void QSGMaterialShader::setFlag(Flags flags, bool on)
414{
415 Q_D(QSGMaterialShader);
416 if (on)
417 d->flags |= flags;
418 else
419 d->flags &= ~flags;
420}
421
422/*!
423 Sets the \a flags for this material shader.
424 */
425void QSGMaterialShader::setFlags(Flags flags)
426{
427 Q_D(QSGMaterialShader);
428 d->flags = flags;
429}
430
431/*!
432 Returns the number of elements in the combined image sampler variable at \a
433 binding. This value is introspected from the shader code. The variable may
434 be an array, and may have more than one dimension.
435
436 The count reflects the total number of combined image sampler items in the
437 variable. In the following example, the count for \c{srcA} is 1, \c{srcB}
438 is 4, and \c{srcC} is 6.
439
440 \badcode
441 layout (binding = 0) uniform sampler2D srcA;
442 layout (binding = 1) uniform sampler2D srcB[4];
443 layout (binding = 2) uniform sampler2D srcC[2][3];
444 \endcode
445
446 This count is the number of QSGTexture pointers in the texture parameter
447 of \l{QSGMaterialShader::updateSampledImage}.
448
449 \sa QSGMaterialShader::updateSampledImage
450 \since 6.4
451 */
452int QSGMaterialShader::combinedImageSamplerCount(int binding) const
453{
454 Q_D(const QSGMaterialShader);
455
456 if (binding >= 0 && binding < d->MAX_SHADER_RESOURCE_BINDINGS)
457 return d->combinedImageSamplerCount[binding];
458
459 return 0;
460}
461
462/*!
463 This function is called by the scene graph to get the contents of the
464 shader program's uniform buffer updated. The implementation is not expected
465 to perform any real graphics operations, it is merely responsible for
466 copying data to the QByteArray returned from RenderState::uniformData().
467 The scene graph takes care of making that buffer visible in the shaders.
468
469 The current rendering \a state is passed from the scene graph. If the state
470 indicates that any relevant state is dirty, the implementation must update
471 the appropriate region in the buffer data that is accessible via
472 RenderState::uniformData(). When a state, such as, matrix or opacity, is
473 not dirty, there is no need to touch the corresponding region since the
474 data is persistent.
475
476 The return value must be \c true whenever any change was made to the uniform data.
477
478 The subclass specific state, such as the color of a flat color material,
479 should be extracted from \a newMaterial to update the relevant regions in
480 the buffer accordingly.
481
482 \a oldMaterial can be used to minimize buffer changes (which are typically
483 memcpy calls) when updating material states. When \a oldMaterial is null,
484 this shader was just activated.
485 */
486bool QSGMaterialShader::updateUniformData(RenderState &state,
487 QSGMaterial *newMaterial,
488 QSGMaterial *oldMaterial)
489{
490 Q_UNUSED(state);
491 Q_UNUSED(newMaterial);
492 Q_UNUSED(oldMaterial);
493 return false;
494}
495
496/*!
497 This function is called by the scene graph to prepare use of sampled images
498 in the shader, typically in the form of combined image samplers.
499
500 \a binding is the binding number of the sampler. The function is called for
501 each combined image sampler variable in the shader code associated with the
502 QSGMaterialShader.
503
504 \a{texture} is an array of QSGTexture pointers. The number of elements in
505 the array matches the number of elements in the image sampler variable
506 specified in the shader code. This variable may be an array, and may have
507 more than one dimension. The number of elements in the array may be
508 found via \l{QSGMaterialShader::combinedImageSamplerCount}
509
510 When an element in \a{texture} is null, it must be set to a valid
511 QSGTexture pointer before returning. When non-null, it is up to the
512 material to decide if a new \c{QSGTexture *} is stored to it, or if it
513 updates some parameters on the already known QSGTexture. The ownership of
514 the QSGTexture is not transferred.
515
516 The current rendering \a state is passed from the scene graph. Where
517 relevant, it is up to the material to trigger enqueuing texture data
518 uploads via QSGTexture::commitTextureOperations().
519
520 The subclass specific state can be extracted from \a newMaterial.
521
522 \a oldMaterial can be used to minimize changes. When \a oldMaterial is null,
523 this shader was just activated.
524
525 \sa QSGMaterialShader::combinedImageSamplerCount
526 */
527void QSGMaterialShader::updateSampledImage(RenderState &state,
528 int binding,
529 QSGTexture **texture,
530 QSGMaterial *newMaterial,
531 QSGMaterial *oldMaterial)
532{
533 Q_UNUSED(state);
534 Q_UNUSED(binding);
535 Q_UNUSED(texture);
536 Q_UNUSED(newMaterial);
537 Q_UNUSED(oldMaterial);
538}
539
540/*!
541 This function is called by the scene graph to enable the material to
542 provide a custom set of graphics state. The set of states that are
543 customizable by material is limited to blending and related settings.
544
545 \note This function is only called when the UpdatesGraphicsPipelineState
546 flag was enabled via setFlags(). By default it is not set, and so this
547 function is never called.
548
549 The return value must be \c true whenever a change was made to any of the
550 members in \a ps.
551
552 \note The contents of \a ps is not persistent between invocations of this
553 function.
554
555 The current rendering \a state is passed from the scene graph.
556
557 The subclass specific state can be extracted from \a newMaterial. When \a
558 oldMaterial is null, this shader was just activated.
559 */
560bool QSGMaterialShader::updateGraphicsPipelineState(RenderState &state, GraphicsPipelineState *ps,
561 QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
562{
563 Q_UNUSED(state);
564 Q_UNUSED(ps);
565 Q_UNUSED(newMaterial);
566 Q_UNUSED(oldMaterial);
567 return false;
568}
569
570/*!
571 \class QSGMaterialShader::RenderState
572
573 \brief Encapsulates the current rendering state during a call to
574 QSGMaterialShader::updateUniformData() and the other \c update type of
575 functions.
576
577 \inmodule QtQuick
578 \since 5.14
579
580 The render state contains a number of accessors that the shader needs to
581 respect in order to conform to the current state of the scene graph.
582 */
583
584/*!
585 \enum QSGMaterialShader::RenderState::DirtyState
586
587 \value DirtyMatrix Used to indicate that the matrix has changed and must be
588 updated.
589
590 \value DirtyOpacity Used to indicate that the opacity has changed and must
591 be updated.
592
593 \value DirtyCachedMaterialData Used to indicate that the cached material
594 state has changed and must be updated.
595
596 \value DirtyAll Used to indicate that everything needs to be updated.
597 */
598
599/*!
600 \fn bool QSGMaterialShader::RenderState::isMatrixDirty() const
601
602 Returns \c true if the dirtyStates() contain the dirty matrix state,
603 otherwise returns \c false.
604 */
605
606/*!
607 \fn bool QSGMaterialShader::RenderState::isOpacityDirty() const
608
609 Returns \c true if the dirtyStates() contains the dirty opacity state,
610 otherwise returns \c false.
611 */
612
613/*!
614 \fn QSGMaterialShader::RenderState::DirtyStates QSGMaterialShader::RenderState::dirtyStates() const
615
616 Returns which rendering states that have changed and needs to be updated
617 for geometry rendered with this material to conform to the current
618 rendering state.
619 */
620
621/*!
622 \class QSGMaterialShader::GraphicsPipelineState
623
624 \brief Describes state changes that the material wants to apply to the
625 currently active graphics pipeline state.
626
627 \inmodule QtQuick
628 \since 5.14
629
630 Unlike QSGMaterialShader, directly issuing state change commands with the
631 underlying graphics API is not possible with QSGMaterialShader. This is
632 mainly because the concept of individually changeable states is considered
633 deprecated and not supported with modern graphics APIs.
634
635 Therefore, it is up to QSGMaterialShader to expose a data structure with
636 the set of supported states, which the material can change in its
637 updatePipelineState() implementation, if there is one. The scenegraph will
638 then internally apply these changes to the active graphics pipeline state,
639 then rolling them back as appropriate.
640
641 When updateGraphicsPipelineState() is called, the struct has all members
642 set to a valid value to reflect the renderer's current state. Not changing
643 any values (or not reimplementing the function) indicates that the material
644 is fine with the defaults (which are dynamic however, depending on
645 QSGMaterial flags, for example).
646 */
647
648/*!
649 \enum QSGMaterialShader::GraphicsPipelineState::BlendFactor
650 \since 5.14
651
652 \value Zero
653 \value One
654 \value SrcColor
655 \value OneMinusSrcColor
656 \value DstColor
657 \value OneMinusDstColor
658 \value SrcAlpha
659 \value OneMinusSrcAlpha
660 \value DstAlpha
661 \value OneMinusDstAlpha
662 \value ConstantColor
663 \value OneMinusConstantColor
664 \value ConstantAlpha
665 \value OneMinusConstantAlpha
666 \value SrcAlphaSaturate
667 \value Src1Color
668 \value OneMinusSrc1Color
669 \value Src1Alpha
670 \value OneMinusSrc1Alpha
671 */
672
673/*!
674 \enum QSGMaterialShader::GraphicsPipelineState::BlendOp
675 \since 6.8
676
677 \value Add
678 \value Subtract
679 \value ReverseSubtract
680 \value Min
681 \value Max
682 */
683
684/*!
685 \enum QSGMaterialShader::GraphicsPipelineState::ColorMaskComponent
686 \since 5.14
687
688 \value R
689 \value G
690 \value B
691 \value A
692 */
693
694/*!
695 \enum QSGMaterialShader::GraphicsPipelineState::CullMode
696 \since 5.14
697
698 \value CullNone
699 \value CullFront
700 \value CullBack
701 */
702
703/*!
704 \enum QSGMaterialShader::GraphicsPipelineState::PolygonMode
705 \since 6.4
706 \brief Specifies the polygon rasterization mode
707
708 Polygon Mode (Triangle Fill Mode in Metal, Fill Mode in D3D) specifies
709 the fill mode used when rasterizing polygons. Polygons may be drawn as
710 solids (Fill), or as a wire mesh (Line).
711
712 \warning OpenGL ES does not support the \c{Line} polygon mode. OpenGL ES
713 will rasterize all polygons as filled no matter what polygon mode is set.
714 Using \c{Line} will make your application non-portable.
715
716 \value Fill The interior of the polygon is filled (default)
717 \value Line Boundary edges of the polygon are drawn as line segments.
718 */
719
720/*!
721 \variable QSGMaterialShader::GraphicsPipelineState::blendEnable
722 \since 5.14
723 \brief Enables blending.
724
725 \note Changing this flag should be done with care, and is best avoided.
726 Rather, materials should always use the QSGMaterial::Blend flag to indicate
727 that they wish to use blending. Changing this value from false to true for
728 a material that did not declare QSGMaterial::Blend can lead to unexpected
729 visual results.
730 */
731
732/*!
733 \variable QSGMaterialShader::GraphicsPipelineState::srcColor
734 \since 5.14
735 \brief Source blending factor, either RGB or RGBA depending on separateBlendFactors.
736 */
737
738/*!
739 \variable QSGMaterialShader::GraphicsPipelineState::dstColor
740 \since 5.14
741 \brief Destination blending factor, either RGB or RGBA depending on separateBlendFactors.
742 */
743
744/*!
745 \variable QSGMaterialShader::GraphicsPipelineState::colorWrite
746 \since 5.14
747 \brief Color write mask.
748 */
749
750/*!
751 \variable QSGMaterialShader::GraphicsPipelineState::blendConstant
752 \since 5.14
753 \brief Blend constant applicable when a blending factor is set to use a constant value.
754 */
755
756/*!
757 \variable QSGMaterialShader::GraphicsPipelineState::cullMode
758 \since 5.14
759 \brief Cull mode.
760 */
761
762/*!
763 \variable QSGMaterialShader::GraphicsPipelineState::polygonMode
764 \since 6.4
765 \brief Polygon rasterization mode.
766 */
767
768/*!
769 \variable QSGMaterialShader::GraphicsPipelineState::separateBlendFactors
770 \since 6.5
771 \brief Indicates that alpha blending factors are specified separately.
772
773 False by default, meaning both RGB and alpha blending factors are defined
774 by srcColor and dstColor. When set to true, the alpha blending factors are
775 taken from srcAlpha and dstAlpha instead, and srcColor and dstColor applies
776 only to RGB.
777 */
778
779/*!
780 \variable QSGMaterialShader::GraphicsPipelineState::srcAlpha
781 \since 6.5
782 \brief Source alpha blending factor.
783
784 Applies only when separateBlendFactors is set to true.
785 */
786
787/*!
788 \variable QSGMaterialShader::GraphicsPipelineState::dstAlpha
789 \since 6.5
790 \brief Destination alpha blending factor.
791
792 Applies only when separateBlendFactors is set to true.
793 */
794
795/*!
796 \variable QSGMaterialShader::GraphicsPipelineState::opColor
797 \since 6.8
798 \brief RGB blending operation.
799 */
800
801/*!
802 \variable QSGMaterialShader::GraphicsPipelineState::opAlpha
803 \since 6.8
804 \brief Alpha blending operation.
805 */
806
807/*!
808 Returns the accumulated opacity to be used for rendering.
809 */
810float QSGMaterialShader::RenderState::opacity() const
811{
812 Q_ASSERT(m_data);
813 return float(static_cast<const QSGRenderer *>(m_data)->currentOpacity());
814}
815
816/*!
817 Returns the modelview determinant to be used for rendering.
818 */
819float QSGMaterialShader::RenderState::determinant() const
820{
821 Q_ASSERT(m_data);
822 return float(static_cast<const QSGRenderer *>(m_data)->determinant());
823}
824
825/*!
826 Returns the matrix combined of modelview matrix and project matrix.
827 */
828QMatrix4x4 QSGMaterialShader::RenderState::combinedMatrix() const
829{
830 Q_ASSERT(m_data);
831 return static_cast<const QSGRenderer *>(m_data)->currentCombinedMatrix(index: 0);
832}
833
834/*!
835 \internal
836 */
837QMatrix4x4 QSGMaterialShader::RenderState::combinedMatrix(qsizetype index) const
838{
839 Q_ASSERT(m_data);
840 return static_cast<const QSGRenderer *>(m_data)->currentCombinedMatrix(index);
841}
842
843/*!
844 Returns the ratio between physical pixels and device-independent pixels
845 to be used for rendering.
846*/
847float QSGMaterialShader::RenderState::devicePixelRatio() const
848{
849 Q_ASSERT(m_data);
850 return float(static_cast<const QSGRenderer *>(m_data)->devicePixelRatio());
851}
852
853/*!
854 Returns the model view matrix.
855
856 If the material has the RequiresFullMatrix flag set, this is guaranteed to
857 be the complete transform matrix calculated from the scenegraph.
858
859 However, if this flag is not set, the renderer may choose to alter this
860 matrix. For example, it may pre-transform vertices on the CPU and set this
861 matrix to identity.
862
863 In a situation such as the above, it is still possible to retrieve the
864 actual matrix determinant by setting the RequiresDeterminant flag in the
865 material and calling the determinant() accessor.
866 */
867QMatrix4x4 QSGMaterialShader::RenderState::modelViewMatrix() const
868{
869 Q_ASSERT(m_data);
870 return static_cast<const QSGRenderer *>(m_data)->currentModelViewMatrix();
871}
872
873/*!
874 Returns the projection matrix.
875 */
876QMatrix4x4 QSGMaterialShader::RenderState::projectionMatrix() const
877{
878 Q_ASSERT(m_data);
879 return static_cast<const QSGRenderer *>(m_data)->currentProjectionMatrix(index: 0);
880}
881
882/*!
883 \internal
884 */
885QMatrix4x4 QSGMaterialShader::RenderState::projectionMatrix(qsizetype index) const
886{
887 Q_ASSERT(m_data);
888 return static_cast<const QSGRenderer *>(m_data)->currentProjectionMatrix(index);
889}
890
891/*!
892 \internal
893 */
894qsizetype QSGMaterialShader::RenderState::projectionMatrixCount() const
895{
896 Q_ASSERT(m_data);
897 return static_cast<const QSGRenderer *>(m_data)->projectionMatrixCount();
898}
899
900/*!
901 Returns the viewport rect of the surface being rendered to.
902 */
903QRect QSGMaterialShader::RenderState::viewportRect() const
904{
905 Q_ASSERT(m_data);
906 return static_cast<const QSGRenderer *>(m_data)->viewportRect();
907}
908
909/*!
910 Returns the device rect of the surface being rendered to
911 */
912QRect QSGMaterialShader::RenderState::deviceRect() const
913{
914 Q_ASSERT(m_data);
915 return static_cast<const QSGRenderer *>(m_data)->deviceRect();
916}
917
918/*!
919 Returns a pointer to the data for the uniform (constant) buffer in the
920 shader. Uniform data must only be updated from
921 QSGMaterialShader::updateUniformData(). The return value is null in the
922 other reimplementable functions, such as,
923 QSGMaterialShader::updateSampledImage().
924
925 \note It is strongly recommended to declare the uniform block with \c
926 std140 in the shader, and to carefully study the standard uniform block
927 layout as described in section 7.6.2.2 of the OpenGL specification. It is
928 up to the QSGMaterialShader implementation to ensure data gets placed
929 at the right location in this QByteArray, taking alignment requirements
930 into account. Shader code translated to other shading languages is expected
931 to use the same offsets for block members, even when the target language
932 uses different packing rules by default.
933
934 \note Avoid copying from C++ POD types, such as, structs, in order to
935 update multiple members at once, unless it has been verified that the
936 layouts of the C++ struct and the GLSL uniform block match.
937 */
938QByteArray *QSGMaterialShader::RenderState::uniformData()
939{
940 Q_ASSERT(m_data);
941 return static_cast<const QSGRenderer *>(m_data)->currentUniformData();
942}
943
944/*!
945 Returns a resource update batch to which upload and copy operatoins can be
946 queued. This is typically used by
947 QSGMaterialShader::updateSampledImage() to enqueue texture image
948 content updates.
949 */
950QRhiResourceUpdateBatch *QSGMaterialShader::RenderState::resourceUpdateBatch()
951{
952 Q_ASSERT(m_data);
953 return static_cast<const QSGRenderer *>(m_data)->currentResourceUpdateBatch();
954}
955
956/*!
957 Returns the current QRhi.
958 */
959QRhi *QSGMaterialShader::RenderState::rhi()
960{
961 Q_ASSERT(m_data);
962 return static_cast<const QSGRenderer *>(m_data)->currentRhi();
963}
964
965QT_END_NAMESPACE
966

source code of qtdeclarative/src/quick/scenegraph/coreapi/qsgmaterialshader.cpp