QSGMaterial Class Reference

The QSGMaterial class encapsulates rendering state for a shader program. More...

#include <qsgmaterial.h>

Inheritance diagram for QSGMaterial:

Collaboration diagram for QSGMaterial:

Public Types
enum	Flag {   Blending = 0x0001 , RequiresDeterminant = 0x0002 , RequiresFullMatrixExceptTranslate = 0x0004 | RequiresDeterminant , RequiresFullMatrix = 0x0008 | RequiresFullMatrixExceptTranslate ,   NoBatching = 0x0010 }
	\value Blending Set this flag to true if the material requires blending to be enabled during rendering. More...

Public Member Functions
	QSGMaterial ()
virtual	~QSGMaterial ()
virtual QSGMaterialType *	type () const =0
	This function is called by the scene graph to query an identifier that is unique to the QSGMaterialShader instantiated by createShader().
virtual QSGMaterialShader *	createShader (QSGRendererInterface::RenderMode renderMode) const =0
	This function returns a new instance of a the QSGMaterialShader implementation used to render geometry for a specific implementation of QSGMaterial.
virtual int	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.
QSGMaterial::Flags	flags () const
	Returns the material's flags.
void	setFlag (Flags flags, bool on=true)
	Sets the flags flags on this material if on is true; otherwise clears the attribute.

Detailed Description

The QSGMaterial class encapsulates rendering state for a shader program.

\inmodule QtQuick

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 \l{Scene Graph - Custom Material}{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.

All classes with QSG prefix should be used solely on the scene graph's rendering thread. See \l {Scene Graph and Rendering} for more information.

See also

QSGMaterialShader, {Scene Graph - Custom Material}, {Scene Graph - Two Texture Providers}, {Scene Graph - Graph}

Definition at line 14 of file qsgmaterial.h.

Member Enumeration Documentation

Flag

enum QSGMaterial::Flag

\value Blending Set this flag to true if the material requires blending to be enabled during rendering.

\value RequiresDeterminant Set this flag to true if the material relies on the determinant of the matrix of the geometry nodes for rendering.

\value RequiresFullMatrixExceptTranslate Set this flag to true if the material relies on the full matrix of the geometry nodes for rendering, except the translation part.

\value RequiresFullMatrix Set this flag to true if the material relies on the full matrix of the geometry nodes for rendering.

\value NoBatching Set this flag to true if the material uses shaders that are incompatible with the \l{Qt Quick Scene Graph Default Renderer}{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.

\value CustomCompileStep In Qt 6 this flag is identical to NoBatching. Prefer using NoBatching instead.

Enumerator
Blending
RequiresDeterminant
RequiresFullMatrixExceptTranslate
RequiresFullMatrix
NoBatching

Definition at line 17 of file qsgmaterial.h.

Constructor & Destructor Documentation

QSGMaterial()

QSGMaterial::QSGMaterial

(

)

Definition at line 104 of file qsgmaterial.cpp.

References _q_sg_leak_check, Q_UNUSED, qt_material_count, and qt_print_material_count().

Here is the call graph for this function:

~QSGMaterial()

QSGMaterial::~QSGMaterial ( )

virtual

Definition at line 124 of file qsgmaterial.cpp.

References _q_sg_leak_check, qDebug, and qt_material_count.

Member Function Documentation

compare()

int QSGMaterial::compare ( const QSGMaterial *  other ) const

virtual

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().

Reimplemented in QSGTextMaskMaterial, QSGStyledTextMaterial, QSGSmoothColorMaterial, QSGDistanceFieldTextMaterial, QSGDistanceFieldStyledTextMaterial, QSGDistanceFieldShiftedStyleTextMaterial, QSGRhiShaderEffectMaterial, QSGFlatColorMaterial, QSGOpaqueTextureMaterial, QSGVertexColorMaterial, QQuickShapeCurveMaterial, QQuickShapeLinearGradientMaterial, QQuickShapeRadialGradientMaterial, QQuickShapeConicalGradientMaterial, QQuickShapeStrokeMaterial, QSGVideoMaterial, and QSGVivanteVideoMaterial.

Definition at line 202 of file qsgmaterial.cpp.

References other(), Q_ASSERT, and type().

Referenced by QSGBatchRenderer::Batch::isMaterialCompatible().

Here is the call graph for this function:

Here is the caller graph for this function:

createShader()

QSGMaterialShader * QSGMaterial::createShader ( QSGRendererInterface::RenderMode  renderMode ) const

pure virtual

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.

Implemented in TabledMaterial, DeformableMaterial, SpriteMaterial, ColoredPointMaterial, ColoredMaterial, SimplePointMaterial, QSGTextMaskMaterial, QSGStyledTextMaterial, QSGOutlinedTextMaterial, QSGSmoothTextureMaterial, QSGSmoothColorMaterial, QQuickSpriteMaterial, QSGDistanceFieldTextMaterial, QSGDistanceFieldOutlineTextMaterial, QSGDistanceFieldShiftedStyleTextMaterial, QSGHiQSubPixelDistanceFieldTextMaterial, QSGLoQSubPixelDistanceFieldTextMaterial, QSGRhiShaderEffectMaterial, QSGFlatColorMaterial, QSGOpaqueTextureMaterial, QSGTextureMaterial, QSGVertexColorMaterial, QQuickShapeCurveMaterial, QQuickShapeLinearGradientMaterial, QQuickShapeRadialGradientMaterial, QQuickShapeConicalGradientMaterial, QSGDistanceFieldStyledTextMaterial, QQuickShapeStrokeMaterial, QSGVideoMaterial, and QSGVivanteVideoMaterial.

Referenced by QSGBatchRenderer::ShaderManager::prepareMaterial(), and QSGBatchRenderer::ShaderManager::prepareMaterialNoRewrite().

Here is the caller graph for this function:

flags()

QSGMaterial::Flags QSGMaterial::flags ( ) const

inline

Returns the material's flags.

Definition at line 40 of file qsgmaterial.h.

Referenced by setFlag(), QSGRhiShaderEffectNode::syncMaterial(), QSGDefaultInternalImageNode::updateMaterialBlending(), and QSGDefaultInternalRectangleNode::updateMaterialBlending().

Here is the caller graph for this function:

setFlag()

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

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

Definition at line 179 of file qsgmaterial.cpp.

References flags().

Referenced by QQuickShapeConicalGradientMaterial::QQuickShapeConicalGradientMaterial(), QQuickShapeCurveMaterial::QQuickShapeCurveMaterial(), QQuickShapeLinearGradientMaterial::QQuickShapeLinearGradientMaterial(), QQuickShapeRadialGradientMaterial::QQuickShapeRadialGradientMaterial(), QQuickShapeStrokeMaterial::QQuickShapeStrokeMaterial(), QQuickSpriteMaterial::QQuickSpriteMaterial(), QSGDistanceFieldTextMaterial::QSGDistanceFieldTextMaterial(), QSGRhiShaderEffectMaterial::QSGRhiShaderEffectMaterial(), QSGSmoothColorMaterial::QSGSmoothColorMaterial(), QSGSmoothTextureMaterial::QSGSmoothTextureMaterial(), QSGVertexColorMaterial::QSGVertexColorMaterial(), QSGVideoMaterial::QSGVideoMaterial(), QSGVivanteVideoMaterial::QSGVivanteVideoMaterial(), QSGFlatColorMaterial::setColor(), QSGOpaqueTextureMaterial::setTexture(), QSGRhiShaderEffectNode::syncMaterial(), QSGVideoMaterial::updateBlending(), QSGVivanteVideoMaterial::updateBlending(), QSGDefaultInternalImageNode::updateMaterialBlending(), and QSGDefaultInternalRectangleNode::updateMaterialBlending().

Here is the call graph for this function:

Here is the caller graph for this function:

type()

QSGMaterialType * QSGMaterial::type ( ) const

pure virtual

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

Implemented in TabledMaterial, DeformableMaterial, SpriteMaterial, ColoredPointMaterial, ColoredMaterial, SimplePointMaterial, QSGTextMaskMaterial, QSGStyledTextMaterial, QSGOutlinedTextMaterial, QSGSmoothTextureMaterial, QSGSmoothColorMaterial, QQuickSpriteMaterial, QSGDistanceFieldTextMaterial, QSGDistanceFieldOutlineTextMaterial, QSGDistanceFieldShiftedStyleTextMaterial, QSGHiQSubPixelDistanceFieldTextMaterial, QSGLoQSubPixelDistanceFieldTextMaterial, QSGRhiShaderEffectMaterial, QSGFlatColorMaterial, QSGOpaqueTextureMaterial, QSGTextureMaterial, QSGVertexColorMaterial, QQuickShapeCurveMaterial, QQuickShapeLinearGradientMaterial, QQuickShapeRadialGradientMaterial, QQuickShapeConicalGradientMaterial, QQuickShapeStrokeMaterial, QSGVideoMaterial, QSGVivanteVideoMaterial, and QSGDistanceFieldStyledTextMaterial.

Referenced by compare(), QSGVivanteVideoMaterial::compare(), QSGBatchRenderer::Batch::isMaterialCompatible(), QSGBatchRenderer::ShaderManager::prepareMaterial(), QSGBatchRenderer::ShaderManager::prepareMaterialNoRewrite(), SpriteMaterialRhiShader::updateSampledImage(), QSGOpaqueTextureMaterialRhiShader::updateSampledImage(), QSGTextMaskRhiShader::updateUniformData(), SpriteMaterialRhiShader::updateUniformData(), QSGDistanceFieldTextMaterialRhiShader::updateUniformData(), FlatColorMaterialRhiShader::updateUniformData(), QQuickShapeLinearGradientRhiShader::updateUniformData(), QQuickShapeRadialGradientRhiShader::updateUniformData(), and QQuickShapeConicalGradientRhiShader::updateUniformData().

Here is the caller graph for this function:

---

The documentation for this class was generated from the following files:

• qtdeclarative/src/quick/scenegraph/coreapi/qsgmaterial.h
• qtdeclarative/src/quick/scenegraph/coreapi/qsgmaterial.cpp