QSGMaterial Class

Member Function Documentation

[virtual] int QSGMaterial::compare(const QSGMaterial *other) const

Compares this material to other and returns 0 if they are equal; -1 if this material should sort before other and 1 if 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 other is guaranteed to have the same type().

[pure virtual] 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 renderMode and will be cached internally.

For most materials, the 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.

QSGMaterial::Flags QSGMaterial::flags() const

Returns the material's flags.

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

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

[pure virtual] 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.

QSGMaterialType *type() const override
{
    static QSGMaterialType type;
    return &type;
}

[since 6.8] int QSGMaterial::viewCount() const

Returns The number of views in case of the material is used in multiview rendering.

Normally the return value is 1. A view count greater than 2 implies a 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 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:

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

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 qsb tool has to be invoked with --view-count 2 or, if using the CMake integration, VIEW_COUNT 2 must be specified in the qt_add_shaders() command.

Developers are encouraged to use the automatically injected preprocessor variable 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:

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

The same source file can now be run through qsb or 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 :/shaders/example.vert.qsb and :/shaders/multiview/example.vert.qsb based on the value of viewCount(). (same goes for the fragment shader)

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
)

As a convenience, there is also a MULTIVIEW option for qt_add_shaders(). This first runs the qsb tool normally, then overrides VIEW_COUNT to 2, sets GLSL, HLSL, MSL to some suitable defaults, and runs qsb again, this time outputting .qsb files with a suffix added. The material implementation can then use the QSGMaterialShader::setShaderFileName() overload taking a 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.

qt_add_shaders(application "application_multiview_shaders"
    MULTIVIEW
    PREFIX
        /
    FILES
        shaders/example.vert
        shaders/example.frag
)

See QRhi::MultiView, QRhiColorAttachment::setMultiViewCount(), and 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 QQuickRenderTarget::fromRhiRenderTarget() or the 3D API specific functions, such as fromVulkanImage() with an arraySize argument greater than 1. The renderer will then propagate the view count to graphics pipelines and the materials.

This function was introduced in Qt 6.8.