From 07049417c3c121fe8935871cee54b8f5e3deb1b1 Mon Sep 17 00:00:00 2001
From: Laszlo Agocs <laszlo.agocs@qt.io>
Date: Thu, 18 Feb 2021 18:51:10 +0100
Subject: 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>
---
 src/quick/scenegraph/coreapi/qsgmaterial.cpp | 46 +++++++++++++++++++---------
 1 file 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
  */
 
 
-- 
cgit v1.2.3