QSGMaterialShader Class

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.

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 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.

#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;
}

#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);
}

See Also▲

enum QSGMaterialShader::Flag▲

QSGMaterialShader::QSGMaterialShader()▲

[since 6.4] int QSGMaterialShader::combinedImageSamplerCount(int binding) const▲

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

QSGMaterialShader::Flags QSGMaterialShader::flags() const▲

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

void QSGMaterialShader::setFlags(QSGMaterialShader::Flags flags)▲

[protected] void QSGMaterialShader::setShader(QSGMaterialShader::Stage stage, const QShader &shader)▲

[protected] void QSGMaterialShader::setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename)▲

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

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

[virtual] bool QSGMaterialShader::updateUniformData(QSGMaterialShader::RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)▲