QSGMaterialRhiShader Class

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

Header: #include <QSGMaterialRhiShader>
qmake: QT += quick
Since: Qt 5.14
Inherits: QSGMaterialShader

This class was introduced in Qt 5.14.

Public Types

struct GraphicsPipelineState
class RenderState
enum Flag { UpdatesGraphicsPipelineState }
flags Flags

Public Functions

QSGMaterialRhiShader()
QSGMaterialRhiShader::Flags flags() const
void setFlag(QSGMaterialRhiShader::Flags flags, bool on = true)
virtual bool updateGraphicsPipelineState(QSGMaterialRhiShader::RenderState &state, QSGMaterialRhiShader::GraphicsPipelineState *ps, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
virtual void updateSampledImage(QSGMaterialRhiShader::RenderState &state, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
virtual bool updateUniformData(QSGMaterialRhiShader::RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

Protected Functions

void setShader(QSGMaterialRhiShader::Stage stage, const QShader &shader)
void setShaderFileName(QSGMaterialRhiShader::Stage stage, const QString &filename)

Detailed Description

QSGMaterialRhiShader is a modern, cross-platform alternative to QSGMaterialShader. The latter is tied to OpenGL and GLSL by design, whereas QSGMaterialRhiShader is based on QShader, a container for multiple versions of a graphics shader together with reflection information.

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.

Member Type Documentation

enum QSGMaterialRhiShader::Flag
flags QSGMaterialRhiShader::Flags

Flag values to indicate special material properties.

ConstantValueDescription
QSGMaterialRhiShader::UpdatesGraphicsPipelineState0x0001Setting this flag enables calling updateGraphicsPipelineState().

The Flags type is a typedef for QFlags<Flag>. It stores an OR combination of Flag values.

Member Function Documentation

QSGMaterialRhiShader::QSGMaterialRhiShader()

Constructs a new QSGMaterialRhiShader.

QSGMaterialRhiShader::Flags QSGMaterialRhiShader::flags() const

Returns the currently set flags for this material shader.

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

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

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

Sets the shader for the specified stage.

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

Sets the filename for the shader for the specified stage.

The file is expected to contain a serialized QRhiShader.

[virtual] bool QSGMaterialRhiShader::updateGraphicsPipelineState(QSGMaterialRhiShader::RenderState &state, QSGMaterialRhiShader::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. 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.

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

This function is called by the scene graph to prepare using a sampled image in the shader, typically in form of a combined image sampler.

binding is the binding number of the sampler. The function is called for each variable in the material's shaders' QShaderDescription::combinedImageSamplers().

When *texture is null, it must be set to a 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. It is up to the material to enqueue the texture data uploads to the QRhiResourceUpdateBatch retriveable via RenderState::resourceUpdateBatch().

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.

[virtual] bool QSGMaterialRhiShader::updateUniformData(QSGMaterialRhiShader::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. 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.

© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.