PySide6.QtQuick.QSGMaterialShader

class QSGMaterialShader

The QSGMaterialShader class represents a graphics API independent shader program. More_…

Synopsis

Methods

Virtual methods

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description

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 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 createShader() . The scene graph creates an instance of QSGMaterialShader by calling the 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);
}

Note

All classes with QSG prefix should be used solely on the scene graph’s rendering thread. See Scene Graph and Rendering for more information.

See also

QSGMaterial Scene Graph - Custom Material Scene Graph - Two Texture Providers Scene Graph - Graph

class Flag

(inherits enum.Flag) Flag values to indicate special material properties.

Constant

Description

QSGMaterialShader.UpdatesGraphicsPipelineState

Setting this flag enables calling updateGraphicsPipelineState() .
class Stage
__init__()

Constructs a new QSGMaterialShader .

combinedImageSamplerCount(binding)
Parameters:

binding – int

Return type:

int

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.

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

See also

updateSampledImage

flags()
Return type:

Combination of Flag

Returns the currently set flags for this material shader.

See also

setFlags()

setFlag(flags[, on=true])
Parameters:

  • flags – Combination of Flag

  • on – bool

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

setFlags(flags)
Parameters:

flags – Combination of Flag

Sets the flags for this material shader.

See also

flags()

setShaderFileName(stage, filename)
Parameters:

  • stage – Stage

  • filename – str

Sets the filename for the shader for the specified stage.

The file is expected to contain a serialized QShader.

setShaderFileName(stage, filename, viewCount)
Parameters:

  • stage – Stage

  • filename – str

  • viewCount – int

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 multiview rendering, in particular when the build system’s MULTIVIEW convenience option is used.

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

updateGraphicsPipelineState(state, ps, newMaterial, oldMaterial)
Parameters:
Return type:

bool

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.

updateUniformData(state, newMaterial, oldMaterial)
Parameters:
Return type:

bool

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

class RenderState

Encapsulates the current rendering state during a call to updateUniformData() and the other update type of functions. More_…

Synopsis

Methods

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description

The render state contains a number of accessors that the shader needs to respect in order to conform to the current state of the scene graph.

class DirtyState

Constant

Description

QSGMaterialShader.RenderState.DirtyMatrix

(inherits enum.Flag) Used to indicate that the matrix has changed and must be updated.

QSGMaterialShader.RenderState.DirtyOpacity

Used to indicate that the opacity has changed and must be updated.

QSGMaterialShader.RenderState.DirtyCachedMaterialData

Used to indicate that the cached material state has changed and must be updated.

QSGMaterialShader.RenderState.DirtyAll

Used to indicate that everything needs to be updated.
combinedMatrix()
Return type:

QMatrix4x4

Returns the matrix combined of modelview matrix and project matrix.

combinedMatrix(index)
Parameters:

index – int

Return type:

QMatrix4x4

determinant()
Return type:

float

Returns the modelview determinant to be used for rendering.

devicePixelRatio()
Return type:

float

Returns the ratio between physical pixels and device-independent pixels to be used for rendering.

deviceRect()
Return type:

QRect

Returns the device rect of the surface being rendered to

dirtyStates()
Return type:

Combination of DirtyState

Returns which rendering states that have changed and needs to be updated for geometry rendered with this material to conform to the current rendering state.

isMatrixDirty()
Return type:

bool

Returns true if the dirtyStates() contain the dirty matrix state, otherwise returns false.

isOpacityDirty()
Return type:

bool

Returns true if the dirtyStates() contains the dirty opacity state, otherwise returns false.

modelViewMatrix()
Return type:

QMatrix4x4

Returns the model view matrix.

If the material has the RequiresFullMatrix flag set, this is guaranteed to be the complete transform matrix calculated from the scenegraph.

However, if this flag is not set, the renderer may choose to alter this matrix. For example, it may pre-transform vertices on the CPU and set this matrix to identity.

In a situation such as the above, it is still possible to retrieve the actual matrix determinant by setting the RequiresDeterminant flag in the material and calling the determinant() accessor.

opacity()
Return type:

float

Returns the accumulated opacity to be used for rendering.

projectionMatrix()
Return type:

QMatrix4x4

Returns the projection matrix.

projectionMatrix(index)
Parameters:

index – int

Return type:

QMatrix4x4

projectionMatrixCount()
Return type:

int

resourceUpdateBatch()
Return type:

QRhiResourceUpdateBatch

Returns a resource update batch to which upload and copy operatoins can be queued. This is typically used by updateSampledImage() to enqueue texture image content updates.

rhi()
Return type:

QRhi

Returns the current QRhi.

uniformData()
Return type:

QByteArray

Returns a pointer to the data for the uniform (constant) buffer in the shader. Uniform data must only be updated from updateUniformData() . The return value is null in the other reimplementable functions, such as, updateSampledImage() .

Note

It is strongly recommended to declare the uniform block with std140 in the shader, and to carefully study the standard uniform block layout as described in section 7.6.2.2 of the OpenGL specification. It is up to the QSGMaterialShader implementation to ensure data gets placed at the right location in this QByteArray, taking alignment requirements into account. Shader code translated to other shading languages is expected to use the same offsets for block members, even when the target language uses different packing rules by default.

Note

Avoid copying from C++ POD types, such as, structs, in order to update multiple members at once, unless it has been verified that the layouts of the C++ struct and the GLSL uniform block match.

viewportRect()
Return type:

QRect

Returns the viewport rect of the surface being rendered to.

class GraphicsPipelineState

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description

class BlendFactor

Constant

Description

QSGMaterialShader.GraphicsPipelineState.Zero

QSGMaterialShader.GraphicsPipelineState.One

QSGMaterialShader.GraphicsPipelineState.SrcColor

QSGMaterialShader.GraphicsPipelineState.OneMinusSrcColor

QSGMaterialShader.GraphicsPipelineState.DstColor

QSGMaterialShader.GraphicsPipelineState.OneMinusDstColor

QSGMaterialShader.GraphicsPipelineState.SrcAlpha

QSGMaterialShader.GraphicsPipelineState.OneMinusSrcAlpha

QSGMaterialShader.GraphicsPipelineState.DstAlpha

QSGMaterialShader.GraphicsPipelineState.OneMinusDstAlpha

QSGMaterialShader.GraphicsPipelineState.ConstantColor

QSGMaterialShader.GraphicsPipelineState.OneMinusConstantColor

QSGMaterialShader.GraphicsPipelineState.ConstantAlpha

QSGMaterialShader.GraphicsPipelineState.OneMinusConstantAlpha

QSGMaterialShader.GraphicsPipelineState.SrcAlphaSaturate

QSGMaterialShader.GraphicsPipelineState.Src1Color

QSGMaterialShader.GraphicsPipelineState.OneMinusSrc1Color

QSGMaterialShader.GraphicsPipelineState.Src1Alpha

QSGMaterialShader.GraphicsPipelineState.OneMinusSrc1Alpha
class BlendOp

Constant

Description

QSGMaterialShader.GraphicsPipelineState.BlendOp.Add

QSGMaterialShader.GraphicsPipelineState.BlendOp.Subtract

QSGMaterialShader.GraphicsPipelineState.BlendOp.ReverseSubtract

QSGMaterialShader.GraphicsPipelineState.BlendOp.Min

QSGMaterialShader.GraphicsPipelineState.BlendOp.Max

Added in version 6.8.

class ColorMaskComponent

Constant

Description

QSGMaterialShader.GraphicsPipelineState.R

QSGMaterialShader.GraphicsPipelineState.G

QSGMaterialShader.GraphicsPipelineState.B

QSGMaterialShader.GraphicsPipelineState.A
class CullMode

Constant

Description

QSGMaterialShader.GraphicsPipelineState.CullNone

QSGMaterialShader.GraphicsPipelineState.CullFront

QSGMaterialShader.GraphicsPipelineState.CullBack
class PolygonMode

Specifies the polygon rasterization mode

Polygon Mode (Triangle Fill Mode in Metal, Fill Mode in D3D) specifies the fill mode used when rasterizing polygons. Polygons may be drawn as solids (Fill), or as a wire mesh (Line).

Warning

OpenGL ES does not support the Line polygon mode. OpenGL ES will rasterize all polygons as filled no matter what polygon mode is set. Using Line will make your application non-portable.

Constant

Description

QSGMaterialShader.GraphicsPipelineState.Fill

The interior of the polygon is filled (default)

QSGMaterialShader.GraphicsPipelineState.Line

Boundary edges of the polygon are drawn as line segments.
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.blendEnable
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.srcColor
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.dstColor
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.colorWrite
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.blendConstant
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.cullMode
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.polygonMode
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.separateBlendFactors
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.srcAlpha
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.dstAlpha
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.opColor
PySide6.QtQuick.QSGMaterialShader.GraphicsPipelineState.opAlpha