QSGMaterial Class

The QSGMaterial class encapsulates rendering state for a shader program. 更多...

Header: #include <QSGMaterial>
CMake: find_package(Qt6 COMPONENTS Quick REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmake: QT += quick

QSGFlatColorMaterial , QSGOpaqueTextureMaterial ,和 QSGVertexColorMaterial


enum Flag { Blending, RequiresDeterminant, RequiresFullMatrixExceptTranslate, RequiresFullMatrix, CustomCompileStep }
flags Flags


virtual int compare (const QSGMaterial * other ) const
virtual QSGMaterialShader * createShader (QSGRendererInterface::RenderMode renderMode ) const = 0
QSGMaterial::Flags flags () const
void setFlag (QSGMaterial::Flags flags , bool on = true)
virtual QSGMaterialType * type () const = 0


QSGMaterial and QSGMaterialShader subclasses form a tight relationship. For one scene graph (including nested graphs), there is one unique QSGMaterialShader instance which encapsulates the shaders the scene graph uses to render that material, such as a shader to flat coloring of geometry. Each QSGGeometryNode can have a unique QSGMaterial containing the how the shader should be configured when drawing that node, such as the actual color to used to render the geometry.

QSGMaterial has two virtual functions that both need to be implemented. The function type () should return a unique instance for all instances of a specific subclass. The createShader () function should return a new instance of QSGMaterialShader , specific to that subclass of QSGMaterial.

A minimal QSGMaterial implementation could look like this:

class Material : public QSGMaterial
    QSGMaterialType *type() const override { static QSGMaterialType type; return &type; }
    QSGMaterialShader *createShader(QSGRendererInterface::RenderMode) const override { return new Shader; }

Custom Material example for an introduction on implementing a QQuickItem subclass backed by a QSGGeometryNode and a custom material.

注意: createShader () is called only once per QSGMaterialType , to reduce redundant work with shader preparation. If a QSGMaterial is backed by multiple sets of vertex and fragment shader combinations, the implementation of type () must return a different, unique QSGMaterialType pointer for each combination of shaders.

注意: All classes with QSG prefix should be used solely on the scene graph's rendering thread. See 场景图形和渲染 了解更多信息。

另请参阅 QSGMaterialShader , 场景图形 - 自定义材质 , 场景图形 - 2 纹理提供程序 ,和 场景图形 - 图形 .


enum QSGMaterial:: Flag
flags QSGMaterial:: Flags

常量 描述
QSGMaterial::Blending 0x0001 Set this flag to true if the material requires GL_BLEND to be enabled during rendering.
QSGMaterial::RequiresDeterminant 0x0002 Set this flag to true if the material relies on the determinant of the matrix of the geometry nodes for rendering.
QSGMaterial::RequiresFullMatrixExceptTranslate 0x0004 | RequiresDeterminant Set this flag to true if the material relies on the full matrix of the geometry nodes for rendering, except the translation part.
QSGMaterial::RequiresFullMatrix 0x0008 | RequiresFullMatrixExceptTranslate Set this flag to true if the material relies on the full matrix of the geometry nodes for rendering.
QSGMaterial::CustomCompileStep 0x0010 Starting with Qt 5.2, the scene graph will not always call QSGMaterialShader::compile() when its shader program is compiled and linked. Set this flag to enforce that the function is called.

Flags 类型是 typedef 对于 QFlags <Flag>。它存储 Flag 值的 OR 组合。


[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 为 true;否则清零属性。

[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;