QSGMaterialShader Class Reference

The QSGMaterialShader class represents a graphics API independent shader program. More...

#include <qsgmaterialshader.h>

Inheritance diagram for QSGMaterialShader:

Collaboration diagram for QSGMaterialShader:

Classes
class	GraphicsPipelineState
	Describes state changes that the material wants to apply to the currently active graphics pipeline state. More...
class	RenderState
	Encapsulates the current rendering state during a call to QSGMaterialShader::updateUniformData() and the other update type of functions. More...

Public Types
enum	Flag { UpdatesGraphicsPipelineState = 0x0001 }
	Flag values to indicate special material properties. More...
enum	Stage { VertexStage , FragmentStage }

Public Member Functions
	QSGMaterialShader ()
	Constructs a new QSGMaterialShader.
virtual	~QSGMaterialShader ()
virtual bool	updateUniformData (RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
	This function is called by the scene graph to get the contents of the shader program's uniform buffer updated.
virtual void	updateSampledImage (RenderState &state, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
	This function is called by the scene graph to prepare use of sampled images in the shader, typically in the form of combined image samplers.
virtual bool	updateGraphicsPipelineState (RenderState &state, GraphicsPipelineState *ps, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
	This function is called by the scene graph to enable the material to provide a custom set of graphics state.
Flags	flags () const
void	setFlag (Flags flags, bool on=true)
	Sets the flags on this material shader if on is true; otherwise clears the specified flags.
void	setFlags (Flags flags)
	Sets the flags for this material shader.
int	combinedImageSamplerCount (int binding) const
	Returns the number of elements in the combined image sampler variable at binding.

Protected Member Functions
	QSGMaterialShader (QSGMaterialShaderPrivate &dd)
void	setShaderFileName (Stage stage, const QString &filename)
	Sets the filename for the shader for the specified stage.
void	setShaderFileName (Stage stage, const QString &filename, int viewCount)
	Sets the filename for the shader for the specified stage.
void	setShader (Stage stage, const QShader &shader)
	Sets the shader for the specified stage.

Detailed Description

The QSGMaterialShader class represents a graphics API independent shader program.

\inmodule QtQuick

Since

5.14

QSGMaterialShader represents a combination of vertex and fragment shaders, data that define the graphics pipeline state changes, and logic that updates graphics resources, such as uniform buffers and textures.

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.

The QSGMaterial and QSGMaterialShader form a tight relationship. For one scene graph (including nested graphs), there is one unique QSGMaterialShader instance that encapsulates the shaders and other data the scene graph uses to render an object with that material. Each QSGGeometryNode can have a unique QSGMaterial that defines how the graphics pipeline must be configured while drawing the node. An instance of QSGMaterialShader is never created explicitly by the user, it will be created on demand by the scene graph through QSGMaterial::createShader(). The scene graph creates an instance of QSGMaterialShader by calling the QSGMaterial::createShader() method, ensuring that there is only one instance of each shader implementation.

In Qt 5, QSGMaterialShader was tied to OpenGL. It was built directly on QOpenGLShaderProgram and had functions like updateState() that could issue arbitrary OpenGL commands. This is no longer the case in Qt 6. QSGMaterialShader is not strictly data-oriented, meaning it provides data (shaders and the desired pipeline state changes) together with logic that updates data in a uniform buffer. Graphics API access is not provided. This means that a QSGMaterialShader cannot make OpenGL, Vulkan, Metal, or Direct 3D calls on its own. Together with the unified shader management, this allows a QSGMaterialShader to be written once, and be functional with any of the supported graphics APIs at run time.

The shaders set by calling the protected setShaderFileName() function control what material does with the vertex data from the geometry, and how the fragments are shaded. A QSGMaterialShader will typically set a vertex and a fragment shader during construction. Changing the shaders afterwards may not lead to the desired effect and must be avoided.

In Qt 6, the default approach is to ship {.qsb} files with the application, typically embedded via the resource system, and referenced when calling setShaderFileName(). The {.qsb} files are generated offline, or at latest at application build time, from Vulkan-style GLSL source code using the qsb tool from the Qt Shader Tools module.

There are three virtuals that can be overridden. These provide the data, or the logic to generate the data, for uniform buffers, textures, and pipeline state changes.

updateUniformData() is the function that is most commonly reimplemented in subclasses. This function is expected to update the contents of a QByteArray that will then be exposed to the shaders as a uniform buffer. Any QSGMaterialShader that has a uniform block in its vertex or fragment shader must reimplement updateUniformData().

updateSampledImage() is relevant when the shader code samples textures. The function will be invoked for each sampler (or combined image sampler, in APIs where relevant), giving it the option to specify which QSGTexture should be exposed to the shader.

The shader pipeline state changes are less often used. One use case is materials that wish to use a specific blend mode. The relevant function is updateGraphicsPipelineState(). This function is not called unless the QSGMaterialShader has opted in by setting the flag UpdatesGraphicsPipelineState. The task of the function is to update the GraphicsPipelineState struct instance that is passed to it with the desired changes. Currently only blending and culling-related features are available, other states cannot be controlled by materials.

A minimal example, that also includes texture support, could be the following. Here we assume that Material is the QSGMaterial that creates an instance of Shader in its \l{QSGMaterial::createShader()}{createShader()}, and that it holds a QSGTexture we want to sample in the fragment shader. The vertex shader relies only on the modelview-projection matrix.

class Shader : public QSGMaterialShader
{
public:
    Shader()
    {
        setShaderFileName(VertexStage, QLatin1String(":/materialshader.vert.qsb"));
        setShaderFileName(FragmentStage, QLatin1String(":/materialshader.frag.qsb"));
    }
 
    bool updateUniformData(RenderState &state, QSGMaterial *, QSGMaterial *)
    {
        bool changed = false;
        QByteArray *buf = state.uniformData();
        if (state.isMatrixDirty()) {
            const QMatrix4x4 m = state.combinedMatrix();
            memcpy(buf->data(), m.constData(), 64);
            changed = true;
        }
        return changed;
    }
 
    void updateSampledImage(RenderState &, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *)
    {
        Material *mat = static_cast<Material *>(newMaterial);
        if (binding == 1)
            *texture = mat->texture();
    }
};

The Vulkan-style GLSL source code for the shaders could look like the following. These are expected to be preprocessed offline using the qsb tool, which generates the {.qsb} files referenced in the Shader() constructor.

\badcode #version 440 layout(location = 0) in vec4 aVertex; layout(location = 1) in vec2 aTexCoord; layout(location = 0) out vec2 vTexCoord; layout(std140, binding = 0) uniform buf { mat4 qt_Matrix; } ubuf; out gl_PerVertex { vec4 gl_Position; }; void main() { gl_Position = ubuf.qt_Matrix * aVertex; vTexCoord = aTexCoord; }

\badcode #version 440 layout(location = 0) in vec2 vTexCoord; layout(location = 0) out vec4 fragColor; layout(binding = 1) uniform sampler2D srcTex; void main() { vec4 c = texture(srcTex, vTexCoord); fragColor = vec4(c.rgb * 0.5, 1.0); }

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.

See also

QSGMaterial, {Scene Graph - Custom Material}, {Scene Graph - Two Texture Providers}, {Scene Graph - Graph}

Definition at line 22 of file qsgmaterialshader.h.

Member Enumeration Documentation

Flag

enum QSGMaterialShader::Flag

Flag values to indicate special material properties.

\value UpdatesGraphicsPipelineState Setting this flag enables calling updateGraphicsPipelineState().

Enumerator
UpdatesGraphicsPipelineState

Definition at line 119 of file qsgmaterialshader.h.

Stage

enum QSGMaterialShader::Stage

Enumerator
VertexStage
FragmentStage

Definition at line 124 of file qsgmaterialshader.h.

Constructor & Destructor Documentation

QSGMaterialShader() [1/2]

QSGMaterialShader::QSGMaterialShader

(

)

Constructs a new QSGMaterialShader.

Definition at line 309 of file qsgmaterialshader.cpp.

~QSGMaterialShader()

QSGMaterialShader::~QSGMaterialShader ( )

virtual

Definition at line 325 of file qsgmaterialshader.cpp.

QSGMaterialShader() [2/2]

QSGMaterialShader::QSGMaterialShader ( QSGMaterialShaderPrivate & dd )

protected

Definition at line 317 of file qsgmaterialshader.cpp.

Member Function Documentation

combinedImageSamplerCount()

int QSGMaterialShader::combinedImageSamplerCount

(

int

binding

)

const

Returns the number of elements in the combined image sampler variable at binding.

This value is introspected from the shader code. The variable may be an array, and may have more than one dimension.

The count reflects the total number of combined image sampler items in the variable. In the following example, the count for {srcA} is 1, {srcB} is 4, and {srcC} is 6.

\badcode layout (binding = 0) uniform sampler2D srcA; layout (binding = 1) uniform sampler2D srcB[4]; layout (binding = 2) uniform sampler2D srcC[2][3];

This count is the number of QSGTexture pointers in the texture parameter of \l{QSGMaterialShader::updateSampledImage}.

See also

QSGMaterialShader::updateSampledImage

Since

6.4

Definition at line 442 of file qsgmaterialshader.cpp.

References d.

flags()

QSGMaterialShader::Flags QSGMaterialShader::flags

(

)

const

Returns

the currently set flags for this material shader.

Definition at line 393 of file qsgmaterialshader.cpp.

References d.

Referenced by setFlag(), and setFlags().

Here is the caller graph for this function:

setFlag()

void QSGMaterialShader::setFlag	(	Flags	flags,
		bool	on = true )

Sets the flags on this material shader if on is true; otherwise clears the specified flags.

Definition at line 403 of file qsgmaterialshader.cpp.

References d, and flags().

Referenced by QSG24BitTextMaskRhiShader::QSG24BitTextMaskRhiShader(), QSGHiQSubPixelDistanceFieldTextMaterialRhiShader::QSGHiQSubPixelDistanceFieldTextMaterialRhiShader(), and QSGRhiShaderEffectMaterialShader::QSGRhiShaderEffectMaterialShader().

Here is the call graph for this function:

Here is the caller graph for this function:

setFlags()

void QSGMaterialShader::setFlags

(

Flags

flags

)

Sets the flags for this material shader.

Definition at line 415 of file qsgmaterialshader.cpp.

References d, and flags().

Here is the call graph for this function:

setShader()

void QSGMaterialShader::setShader ( Stage stage, const QShader & shader )

protected

Sets the shader for the specified stage.

Definition at line 346 of file qsgmaterialshader.cpp.

References d, and toShaderStage().

Referenced by QSGRhiShaderEffectMaterialShader::QSGRhiShaderEffectMaterialShader().

Here is the call graph for this function:

Here is the caller graph for this function:

setShaderFileName() [1/2]

void QSGMaterialShader::setShaderFileName ( Stage stage, const QString & filename )

protected

Sets the filename for the shader for the specified stage.

The file is expected to contain a serialized QShader.

Definition at line 357 of file qsgmaterialshader.cpp.

References d, and toShaderStage().

Referenced by ColoredMaterialRhiShader::ColoredMaterialRhiShader(), ColoredPointMaterialRhiShader::ColoredPointMaterialRhiShader(), DeformableMaterialRhiShader::DeformableMaterialRhiShader(), DistanceFieldAnisotropicOutlineTextMaterialRhiShader::DistanceFieldAnisotropicOutlineTextMaterialRhiShader(), DistanceFieldAnisotropicShiftedTextMaterialRhiShader::DistanceFieldAnisotropicShiftedTextMaterialRhiShader(), DistanceFieldAnisotropicTextMaterialRhiShader::DistanceFieldAnisotropicTextMaterialRhiShader(), DistanceFieldOutlineTextMaterialRhiShader::DistanceFieldOutlineTextMaterialRhiShader(), DistanceFieldShiftedStyleTextMaterialRhiShader::DistanceFieldShiftedStyleTextMaterialRhiShader(), FlatColorMaterialRhiShader::FlatColorMaterialRhiShader(), ParticleSpriteMaterialRhiShader::ParticleSpriteMaterialRhiShader(), QQuickShapeConicalGradientRhiShader::QQuickShapeConicalGradientRhiShader(), QQuickShapeLinearGradientRhiShader::QQuickShapeLinearGradientRhiShader(), QQuickShapeRadialGradientRhiShader::QQuickShapeRadialGradientRhiShader(), QSG24BitTextMaskRhiShader::QSG24BitTextMaskRhiShader(), QSG32BitColorTextRhiShader::QSG32BitColorTextRhiShader(), QSG8BitTextMaskRhiShader::QSG8BitTextMaskRhiShader(), QSGDistanceFieldTextMaterialRhiShader::QSGDistanceFieldTextMaterialRhiShader(), QSGHiQSubPixelDistanceFieldTextMaterialRhiShader::QSGHiQSubPixelDistanceFieldTextMaterialRhiShader(), QSGLoQSubPixelDistanceFieldTextMaterialRhiShader::QSGLoQSubPixelDistanceFieldTextMaterialRhiShader(), QSGOpaqueTextureMaterialRhiShader::QSGOpaqueTextureMaterialRhiShader(), QSGOutlinedTextRhiShader::QSGOutlinedTextRhiShader(), QSGStyledTextRhiShader::QSGStyledTextRhiShader(), QSGTextMaskRhiShader::QSGTextMaskRhiShader(), QSGTextureMaterialRhiShader::QSGTextureMaterialRhiShader(), QSGVertexColorMaterialRhiShader::QSGVertexColorMaterialRhiShader(), QSGVideoMaterialRhiShader::QSGVideoMaterialRhiShader(), QSGVivanteVideoMaterialShader::QSGVivanteVideoMaterialShader(), SimplePointMaterialRhiShader::SimplePointMaterialRhiShader(), SmoothColorMaterialRhiShader::SmoothColorMaterialRhiShader(), SmoothTextureMaterialRhiShader::SmoothTextureMaterialRhiShader(), SpriteMaterialRhiShader::SpriteMaterialRhiShader(), and TabledMaterialRhiShader::TabledMaterialRhiShader().

Here is the call graph for this function:

Here is the caller graph for this function:

setShaderFileName() [2/2]

void QSGMaterialShader::setShaderFileName ( Stage stage, const QString & filename, int viewCount )

protected

Sets the filename for the shader for the specified stage.

The file is expected to contain a serialized QShader.

This overload is used when enabling \l{QSGMaterial::viewCount()}{multiview} rendering, in particular when the \l{Qt Shader Tools Build System Integration}{build system's MULTIVIEW convenience option} is used.

viewCount should be 2, 3, or 4. The filename is adjusted automatically based on this.

Since

6.8

Definition at line 377 of file qsgmaterialshader.cpp.

References d, QStringLiteral, and toShaderStage().

Here is the call graph for this function:

updateGraphicsPipelineState()

bool QSGMaterialShader::updateGraphicsPipelineState ( RenderState & state, GraphicsPipelineState * ps, QSGMaterial * newMaterial, QSGMaterial * oldMaterial )

virtual

This function is called by the scene graph to enable the material to provide a custom set of graphics state.

The set of states that are customizable by material is limited to blending and related settings.

Note

This function is only called when the UpdatesGraphicsPipelineState flag was enabled via setFlags(). By default it is not set, and so this function is never called.

The return value must be true whenever a change was made to any of the members in ps.

Note

The contents of ps is not persistent between invocations of this function.

The current rendering state is passed from the scene graph.

The subclass specific state can be extracted from newMaterial. When oldMaterial is null, this shader was just activated.

Reimplemented in QSG24BitTextMaskRhiShader, QSGHiQSubPixelDistanceFieldTextMaterialRhiShader, and QSGRhiShaderEffectMaterialShader.

Definition at line 550 of file qsgmaterialshader.cpp.

References Q_UNUSED, and state.

updateSampledImage()

void QSGMaterialShader::updateSampledImage ( RenderState & state, int binding, QSGTexture ** texture, QSGMaterial * newMaterial, QSGMaterial * oldMaterial )

virtual

This function is called by the scene graph to prepare use of sampled images in the shader, typically in the form of combined image samplers.

binding is the binding number of the sampler. The function is called for each combined image sampler variable in the shader code associated with the QSGMaterialShader.

{texture} is an array of QSGTexture pointers. The number of elements in the array matches the number of elements in the image sampler variable specified in the shader code. This variable may be an array, and may have more than one dimension. The number of elements in the array may be found via \l{QSGMaterialShader::combinedImageSamplerCount}

When an element in {texture} is null, it must be set to a valid QSGTexture pointer before returning. When non-null, it is up to the material to decide if a new {QSGTexture *} is stored to it, or if it updates some parameters on the already known QSGTexture. The ownership of the QSGTexture is not transferred.

The current rendering state is passed from the scene graph. Where relevant, it is up to the material to trigger enqueuing texture data uploads via QSGTexture::commitTextureOperations().

The subclass specific state can be extracted from newMaterial.

oldMaterial can be used to minimize changes. When oldMaterial is null, this shader was just activated.

See also

QSGMaterialShader::combinedImageSamplerCount

Reimplemented in TabledMaterialRhiShader, DeformableMaterialRhiShader, ParticleSpriteMaterialRhiShader, ColoredPointMaterialRhiShader, SimplePointMaterialRhiShader, QT_BEGIN_NAMESPACE::QSGCurveFillMaterialShader, QSGTextMaskRhiShader, SpriteMaterialRhiShader, QSGDistanceFieldTextMaterialRhiShader, QSGRhiShaderEffectMaterialShader, QSGOpaqueTextureMaterialRhiShader, QQuickShapeLinearGradientRhiShader, QQuickShapeRadialGradientRhiShader, QQuickShapeConicalGradientRhiShader, QSGVideoMaterialRhiShader, and QSGVivanteVideoMaterialShader.

Definition at line 517 of file qsgmaterialshader.cpp.

References Q_UNUSED, and state.

updateUniformData()

bool QSGMaterialShader::updateUniformData ( RenderState & state, QSGMaterial * newMaterial, QSGMaterial * oldMaterial )

virtual

This function is called by the scene graph to get the contents of the shader program's uniform buffer updated.

The implementation is not expected to perform any real graphics operations, it is merely responsible for copying data to the QByteArray returned from RenderState::uniformData(). The scene graph takes care of making that buffer visible in the shaders.

The current rendering state is passed from the scene graph. If the state indicates that any relevant state is dirty, the implementation must update the appropriate region in the buffer data that is accessible via RenderState::uniformData(). When a state, such as, matrix or opacity, is not dirty, there is no need to touch the corresponding region since the data is persistent.

The return value must be true whenever any change was made to the uniform data.

The subclass specific state, such as the color of a flat color material, should be extracted from newMaterial to update the relevant regions in the buffer accordingly.

oldMaterial can be used to minimize buffer changes (which are typically memcpy calls) when updating material states. When oldMaterial is null, this shader was just activated.

Reimplemented in TabledMaterialRhiShader, DeformableMaterialRhiShader, ParticleSpriteMaterialRhiShader, ColoredPointMaterialRhiShader, SimplePointMaterialRhiShader, QT_BEGIN_NAMESPACE::QSGCurveFillMaterialShader, QSGCurveStrokeMaterialShader, QSGTextMaskRhiShader, QSG8BitTextMaskRhiShader, QSG24BitTextMaskRhiShader, QSG32BitColorTextRhiShader, QSGStyledTextRhiShader, SmoothTextureMaterialRhiShader, SmoothColorMaterialRhiShader, SpriteMaterialRhiShader, QSGDistanceFieldTextMaterialRhiShader, DistanceFieldStyledTextMaterialRhiShader, DistanceFieldOutlineTextMaterialRhiShader, DistanceFieldShiftedStyleTextMaterialRhiShader, QSGHiQSubPixelDistanceFieldTextMaterialRhiShader, QSGRhiShaderEffectMaterialShader, FlatColorMaterialRhiShader, QSGOpaqueTextureMaterialRhiShader, QSGTextureMaterialRhiShader, QSGVertexColorMaterialRhiShader, QQuickShapeLinearGradientRhiShader, QQuickShapeRadialGradientRhiShader, QQuickShapeConicalGradientRhiShader, QSGVideoMaterialRhiShader, and QSGVivanteVideoMaterialShader.

Definition at line 476 of file qsgmaterialshader.cpp.

References Q_UNUSED, and state.

---

The documentation for this class was generated from the following files:

• qtdeclarative/src/quick/scenegraph/coreapi/qsgmaterialshader.h (b5a05e4e7e97f8ef5c4cc65fee0cfcfd9e4c5cc4)
• qtdeclarative/src/quick/scenegraph/coreapi/qsgmaterialshader.cpp (7a222970f56e4396696e82c0113839f61cdd9a83)