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 , MultiView2 = 0x10000 , MultiView3 = 0x20000 , MultiView4 = 0x40000 }
	\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.

int	viewCount () const

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.

\omitvalue MultiView2 \omitvalue MultiView3 \omitvalue MultiView4

Enumerator
Blending
RequiresDeterminant
RequiresFullMatrixExceptTranslate
RequiresFullMatrix
NoBatching
MultiView2
MultiView3
MultiView4

Definition at line 17 of file qsgmaterial.h.

Constructor & Destructor Documentation

◆ QSGMaterial()

QSGMaterial::QSGMaterial ( )

Definition at line 104 of file qsgmaterial.cpp.

◆ ~QSGMaterial()

QSGMaterial::~QSGMaterial ( )

virtual

Definition at line 124 of file qsgmaterial.cpp.

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 QQuickShapeConicalGradientMaterial, QQuickShapeLinearGradientMaterial, QQuickShapeRadialGradientMaterial, QQuickShapeTextureFillMaterial, QSGCurveFillMaterial, QSGCurveStrokeMaterial, QSGDistanceFieldShiftedStyleTextMaterial, QSGDistanceFieldStyledTextMaterial, QSGDistanceFieldTextMaterial, QSGFlatColorMaterial, QSGOpaqueTextureMaterial, QSGRhiShaderEffectMaterial, QSGSmoothColorMaterial, QSGStyledTextMaterial, QSGTextMaskMaterial, QSGVertexColorMaterial, QSGVideoMaterial, and QSGVideoMaterial.

Definition at line 206 of file qsgmaterial.cpp.

◆ createShader()

virtual 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 ColoredMaterial, ColoredMaterial, ColoredPointMaterial, ColoredPointMaterial, DeformableMaterial, DeformableMaterial, QQuickShapeConicalGradientMaterial, QQuickShapeLinearGradientMaterial, QQuickShapeRadialGradientMaterial, QQuickShapeTextureFillMaterial, QQuickSpriteMaterial, QQuickSpriteMaterial, QSGCurveFillMaterial, QSGCurveStrokeMaterial, QSGDistanceFieldOutlineTextMaterial, QSGDistanceFieldShiftedStyleTextMaterial, QSGDistanceFieldStyledTextMaterial, QSGDistanceFieldTextMaterial, QSGFlatColorMaterial, QSGHiQSubPixelDistanceFieldTextMaterial, QSGLoQSubPixelDistanceFieldTextMaterial, QSGOpaqueTextureMaterial, QSGOutlinedTextMaterial, QSGRhiShaderEffectMaterial, QSGSmoothColorMaterial, QSGSmoothTextureMaterial, QSGStyledTextMaterial, QSGTextMaskMaterial, QSGTextureMaterial, QSGVertexColorMaterial, QSGVideoMaterial, QSGVideoMaterial, SimplePointMaterial, SimplePointMaterial, SpriteMaterial, SpriteMaterial, TabledMaterial, and TabledMaterial.

◆ flags()

QSGMaterial::Flags QSGMaterial::flags ( ) const

inline

Returns the material's flags.

Definition at line 44 of file qsgmaterial.h.

◆ 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 183 of file qsgmaterial.cpp.

◆ type()

virtual 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 ColoredMaterial, ColoredMaterial, ColoredPointMaterial, ColoredPointMaterial, DeformableMaterial, DeformableMaterial, QQuickShapeConicalGradientMaterial, QQuickShapeLinearGradientMaterial, QQuickShapeRadialGradientMaterial, QQuickShapeTextureFillMaterial, QQuickSpriteMaterial, QQuickSpriteMaterial, QSGCurveFillMaterial, QSGCurveStrokeMaterial, QSGDistanceFieldOutlineTextMaterial, QSGDistanceFieldShiftedStyleTextMaterial, QSGDistanceFieldStyledTextMaterial, QSGDistanceFieldTextMaterial, QSGFlatColorMaterial, QSGHiQSubPixelDistanceFieldTextMaterial, QSGLoQSubPixelDistanceFieldTextMaterial, QSGOpaqueTextureMaterial, QSGOutlinedTextMaterial, QSGRhiShaderEffectMaterial, QSGSmoothColorMaterial, QSGSmoothTextureMaterial, QSGStyledTextMaterial, QSGTextMaskMaterial, QSGTextureMaterial, QSGVertexColorMaterial, QSGVideoMaterial, QSGVideoMaterial, SimplePointMaterial, SimplePointMaterial, SpriteMaterial, SpriteMaterial, TabledMaterial, and TabledMaterial.

◆ viewCount()

int QSGMaterial::viewCount ( ) const

Returns: The number of views in case of the material is used in multiview rendering.

Note: The return value is valid only when called from createShader(), and afterwards. The value is not necessarily up-to-date before createShader() is invokved by the scene graph.

Normally the return value is 1. A view count greater than 2 implies a {multiview render pass}. Materials that support multiview are expected to query viewCount() in createShader(), or in their QSGMaterialShader constructor, and ensure the appropriate shaders are picked. The vertex shader is then expected to use {gl_ViewIndex} to index the modelview-projection matrix array as there are multiple matrices in multiview mode. (one for each view)

As an example, take the following simple vertex shader:

\badcode #version 440

layout(location = 0) in vec4 vertexCoord; layout(location = 1) in vec4 vertexColor;

layout(location = 0) out vec4 color;

layout(std140, binding = 0) uniform buf { mat4 matrix[2]; float opacity; };

void main() { gl_Position = matrix[gl_ViewIndex] * vertexCoord; color = vertexColor * opacity; }

This shader is prepared to handle 2 views, and 2 views only. It is not compatible with other view counts. When conditioning the shader, the qsb tool has to be invoked with {–view-count 2} or, if using the CMake integration, {VIEW_COUNT 2} must be specified in the {qt_add_shaders()} command.

Note: A line with {extension GL_EXT_multiview : require} is injected automatically by qsb whenever a view count of 2 or greater is set.

Developers are encouraged to use the automatically injected preprocessor variable {QSHADER_VIEW_COUNT} to simplify the handling of the different number of views. For example, if there is a need to support both non-multiview and multiview with a view count of 2 in the same source file, the following could be done:

\badcode #version 440

layout(location = 0) in vec4 vertexCoord; layout(location = 1) in vec4 vertexColor;

layout(location = 0) out vec4 color;

layout(std140, binding = 0) uniform buf { if QSHADER_VIEW_COUNT >= 2 mat4 matrix[QSHADER_VIEW_COUNT]; else mat4 matrix; #endif float opacity; };

void main() { if QSHADER_VIEW_COUNT >= 2 gl_Position = matrix[gl_ViewIndex] * vertexCoord; else gl_Position = matrix * vertexCoord; #endif color = vertexColor * opacity; }

The same source file can now be run through qsb or {qt_add_shaders()} twice, once without specify the view count, and once with the view count set to 2. The material can then pick the appropriate .qsb file based on viewCount() at run time.

With CMake, this could looks similar to the following. With this example the corresponding QSGMaterialShader is expected to choose between {:/shaders/example.vert.qsb} and {:/shaders/multiview/example.vert.qsb} based on the value of viewCount(). (same goes for the fragment shader)

\badcode qt_add_shaders(application "application_shaders" PREFIX / FILES shaders/example.vert shaders/example.frag )

qt_add_shaders(application "application_multiview_shaders" GLSL 330,300es HLSL 61 MSL 12 VIEW_COUNT 2 PREFIX / FILES shaders/example.vert shaders/example.frag OUTPUTS shaders/multiview/example.vert shaders/multiview/example.frag )

Note: The fragment shader should be treated the same way the vertex shader is, even though the fragment shader code cannot have any dependency on the view count ({gl_ViewIndex}), for maximum portability. There are two reasons for including fragment shaders too in the multiview set. One is that mixing different shader versions within the same graphics pipeline can be problematic, depending on the underlying graphics API: with D3D12 for example, mixing HLSL shaders for shader model 5.0 and 6.1 would generate an error. The other is that having QSHADER_VIEW_COUNT defined in fragment shaders can be very useful, for example when sharing a uniform buffer layout between the vertex and fragment stages.; For OpenGL the minimum GLSL version for vertex shaders relying on {gl_ViewIndex} is 330. Lower versions may be accepted at build time, but may lead to an error at run time, depending on the OpenGL implementation.

As a convenience, there is also a MULTIVIEW option for qt_add_shaders(). This first runs the qsb tool normally, then overrides VIEW_COUNT to 2, sets GLSL, HLSL, MSL to some suitable defaults, and runs qsb again, this time outputting .qsb files with a suffix added. The material implementation can then use the \l QSGMaterialShader::setShaderFileName() overload taking a viewCount argument, that automatically picks the correct .qsb file.

The following is therefore mostly equivalent to the example call shown above, except that no manually managed output files need to be specified. Note that there can be cases when the automatically chosen shading language versions are not sufficient, in which case applications should continue specify everything explicitly.

\badcode qt_add_shaders(application "application_multiview_shaders" MULTIVIEW PREFIX / FILES shaders/example.vert shaders/example.frag )

See \l QRhi::MultiView, \l QRhiColorAttachment::setMultiViewCount(), and \l QRhiGraphicsPipeline::setMultiViewCount() for further, lower-level details on multiview support in Qt. The Qt Quick scene graph renderer is prepared to recognize multiview render targets, when specified via \l QQuickRenderTarget::fromRhiRenderTarget() or the 3D API specific functions, such as \l{QQuickRenderTarget::}{fromVulkanImage()} with an arraySize argument greater than 1. The renderer will then propagate the view count to graphics pipelines and the materials.

Since: 6.8

Definition at line 423 of file qsgmaterial.cpp.

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

qtdeclarative/src/quick/scenegraph/coreapi/qsgmaterial.h (b5a05e4e7e97f8ef5c4cc65fee0cfcfd9e4c5cc4)
qtdeclarative/src/quick/scenegraph/coreapi/qsgmaterial.cpp (08bfc40091f03f01e2866c88516e03dbd6342db5)

Public Types

Public Member Functions