QSGMaterial Class
The QSGMaterial class encapsulates rendering state for a shader program. More...
Header: | #include <QSGMaterial> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS Quick) target_link_libraries(mytarget PRIVATE Qt6::Quick) |
qmake: | QT += quick |
Inherited By: | QSGFlatColorMaterial, QSGOpaqueTextureMaterial, and QSGVertexColorMaterial |
- List of all members, including inherited members
- QSGMaterial is part of Qt Quick Scene Graph Material Classes.
Public Types
enum | Flag { Blending, RequiresDeterminant, RequiresFullMatrixExceptTranslate, RequiresFullMatrix, NoBatching, CustomCompileStep } |
flags | Flags |
Public Functions
Detailed Description
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 { public: QSGMaterialType *type() const override { static QSGMaterialType type; return &type; } QSGMaterialShader *createShader(QSGRendererInterface::RenderMode) const override { return new Shader; } };
See the Custom Material example for an introduction on implementing a QQuickItem subclass backed by a QSGGeometryNode and a custom material.
Note: 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.
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 QSGMaterialShader, Scene Graph - Custom Material, Scene Graph - Two Texture Providers, and Scene Graph - Graph.
Member Type Documentation
enum QSGMaterial::Flag
flags QSGMaterial::Flags
Constant | Value | Description |
---|---|---|
QSGMaterial::Blending | 0x0001 | Set this flag to true if the material requires blending 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::NoBatching | 0x0010 | Set this flag to true if the material uses shaders that are incompatible with the scene graph's batching mechanism. This is relevant in certain advanced usages, such as, directly manipulating gl_Position.z in the vertex shader. Such solutions are often tied to a specific scene structure, and are likely not safe to use with arbitrary contents in a scene. Thus this flag should only be set after appropriate investigation, and will never be needed for the vast majority of materials. Setting this flag can lead to reduced performance due to having to issue more draw calls. This flag was introduced in Qt 6.3. |
QSGMaterial::CustomCompileStep | NoBatching | In Qt 6 this flag is identical to NoBatching. Prefer using NoBatching instead. |
The Flags type is a typedef for QFlags<Flag>. It stores an OR combination of Flag values.
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().
void QSGMaterial::setFlag(Flags flags, bool on = true)
Sets the flags flags on this material if on is true; otherwise clears the attribute.