summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLaszlo Agocs <laszlo.agocs@qt.io>2021-02-18 18:51:10 +0100
committerQt Cherry-pick Bot <cherrypick_bot@qt-project.org>2021-02-19 12:49:12 +0000
commit07049417c3c121fe8935871cee54b8f5e3deb1b1 (patch)
treea23cc43c5062f9d425cd2ac7f158686a1f590adb
parentf31cedd27537c11fe4196a51bbe197e41b564384 (diff)
Improve QSGMaterial docs
Remove a Qt 6.0 editing issue where the docs continue saying "QSGMaterialShader and QSGMaterialShader", which is a leftover from 5.14/5.15 times when QSGRhiMaterialShader still existed. While we are at it, improve the code snippets and talk a bit more about type(), inspired by recent mailing list discussions. Change-Id: I4b21ed00285bf18e22e64a7574a273abdf8be3e5 Reviewed-by: Andy Nichols <andy.nichols@qt.io> (cherry picked from commit 258077e00eb8f3f4b0ef21a9a0395268b6c86532) Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
-rw-r--r--src/quick/scenegraph/coreapi/qsgmaterial.cpp46
1 files changed, 31 insertions, 15 deletions
diff --git a/src/quick/scenegraph/coreapi/qsgmaterial.cpp b/src/quick/scenegraph/coreapi/qsgmaterial.cpp
index 24cb778254..be18504f9b 100644
--- a/src/quick/scenegraph/coreapi/qsgmaterial.cpp
+++ b/src/quick/scenegraph/coreapi/qsgmaterial.cpp
@@ -98,28 +98,26 @@ static void qt_print_material_count()
\inmodule QtQuick
\ingroup qtquick-scenegraph-materials
- The QSGMaterial, QSGMaterialShader and QSGMaterialShader subclasses
- form a tight relationship. For one scene graph (including nested graphs),
- there is one unique QSGMaterialShader or 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 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 or QSGMaterialShader, specific to that subclass of
- QSGMaterial.
+ of QSGMaterialShader, specific to that subclass of QSGMaterial.
A minimal QSGMaterial implementation could look like this:
\code
class Material : public QSGMaterial
{
public:
- QSGMaterialType *type() const { static QSGMaterialType type; return &type; }
- QSGMaterialShader *createShader(QSGRendererInterface::RenderMode) const { return new Shader; }
+ QSGMaterialType *type() const override { static QSGMaterialType type; return &type; }
+ QSGMaterialShader *createShader(QSGRendererInterface::RenderMode) const override { return new Shader; }
};
\endcode
@@ -127,6 +125,12 @@ static void qt_print_material_count()
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 \l {Scene Graph and Rendering} for more information.
@@ -236,10 +240,22 @@ int QSGMaterial::compare(const QSGMaterial *other) const
/*!
- \fn QSGMaterialType QSGMaterial::type() const
+ \fn 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().
- This function is called by the scene graph to return a unique instance
- per subclass.
+ 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.
+ \code
+ QSGMaterialType *type() const override
+ {
+ static QSGMaterialType type;
+ return &type;
+ }
+ \endcode
*/