QSGMaterial#
The QSGMaterial
class encapsulates rendering state for a shader program. More…
Inherited by: QSGVertexColorMaterial, QSGFlatColorMaterial, QSGOpaqueTextureMaterial, QSGTextureMaterial
Synopsis#
Functions#
Virtual functions#
def
compare
(other)def
createShader
(renderMode)def
type
()
Note
This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE
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.
- class PySide6.QtQuick.QSGMaterial#
- PySide6.QtQuick.QSGMaterial.Flag#
Constant
Description
QSGMaterial.Blending
(inherits
enum.Flag
) Set this flag to true if the material requires blending to be enabled during rendering.QSGMaterial.RequiresDeterminant
Set this flag to true if the material relies on the determinant of the matrix of the geometry nodes for rendering.
QSGMaterial.RequiresFullMatrixExceptTranslate
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
Set this flag to true if the material relies on the full matrix of the geometry nodes for rendering.
QSGMaterial.NoBatching
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
In Qt 6 this flag is identical to NoBatching. Prefer using NoBatching instead.
- PySide6.QtQuick.QSGMaterial.compare(other)#
- Parameters:
other –
PySide6.QtQuick.QSGMaterial
- Return type:
int
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()
.
- abstract PySide6.QtQuick.QSGMaterial.createShader(renderMode)#
- Parameters:
renderMode –
RenderMode
- Return type:
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.
- PySide6.QtQuick.QSGMaterial.flags()#
- Return type:
Combination of
QSGMaterial.Flag
Returns the material’s flags.
- PySide6.QtQuick.QSGMaterial.setFlag(flags[, on=true])#
- Parameters:
flags – Combination of
QSGMaterial.Flag
on – bool
Sets the flags flags
on this material if on
is true; otherwise clears the attribute.
- abstract PySide6.QtQuick.QSGMaterial.type()#
- Return type:
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; }