- Qt 5.15
- Qt Quick
- C++ Classes
- QSGMaterialRhiShader
- Qt 5.15.19 Reference Documentation

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

- List of all members, including inherited members

## Public Types

struct | GraphicsPipelineState
class | RenderState
enum | Flag { UpdatesGraphicsPipelineState }
flags | Flags

## Public Functions

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

## Protected Functions

void | setShader(Stage stage, const QShader &shader)
void | setShaderFileName(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.

Constant | Value | Description
--- | --- | ---
`QSGMaterialRhiShader::UpdatesGraphicsPipelineState` | `0x0001` | Setting 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.

### Flags QSGMaterialRhiShader::flags() const

Returns the currently set flags for this material shader.

### void QSGMaterialRhiShader::setFlag(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(Stage stage, const QShader &shader)

Sets the shader for the specified stage.

### `[protected]` void QSGMaterialRhiShader::setShaderFileName(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(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. 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(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(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.