Add the rhitextureitem example

fboitem, the OpenGL-based QQuickFramebufferObject example is now gone,
replaced by the rhitextureitem example.

It is now possible to implement a custom QQuickItem that renders into a
QRhiTexture and then draws a triangle/strip geometry textured with that
texture using just public Qt Quick APIs and the semi-public QRhi APIs.

There should be conveniences provided for this in future Qt versions,
but for the time being we provide an example how applications can do
this in Qt 6.6 already. This complements the rhiunderqml example which
shows the underlay/overlay approach, and the customrendernode example
that shows the "inline" approach with a custom QSGRenderNode. The
rhitextureitem example added here shows the third, "offscreen" approach
that goes through a texture.

The example docs are better than before but not yet complete.
To be extended separately.

Task-number: QTBUG-113331
Change-Id: I83000c08b057dd72371e2909905120dc496cb34d
Reviewed-by: Andy Nichols <andy.nichols@qt.io>

2 files changed, 61 insertions, 0 deletions

diff --git a/examples/quick/scenegraph/rhitextureitem/doc/images/rhitextureitem-example.jpg b/examples/quick/scenegraph/rhitextureitem/doc/images/rhitextureitem-example.jpg
new file mode 100644
index 0000000000..4f50f94f04
--- /dev/null
+++ b/examples/quick/scenegraph/rhitextureitem/doc/images/rhitextureitem-example.jpg
diff --git a/examples/quick/scenegraph/rhitextureitem/doc/src/rhitextureitem.qdoc b/examples/quick/scenegraph/rhitextureitem/doc/src/rhitextureitem.qdoc
new file mode 100644
index 0000000000..97f0588314
--- /dev/null
+++ b/examples/quick/scenegraph/rhitextureitem/doc/src/rhitextureitem.qdoc
@@ -0,0 +1,61 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \example scenegraph/rhitextureitem
+    \title Scene Graph - RHI Texture Item
+    \ingroup qtquickexamples
+
+    \brief Shows how to implement a custom QQuickItem that displays a QRhi-rendered texture.
+
+    \image rhitextureitem-example.jpg
+
+    This example shows how to implement an item that performs cross-platform,
+    portable 3D rendering into a texture using the QRhi APIs and then displays
+    that image.
+
+    The \l{Scene Graph - RHI Under QML}{RHI Under QML} example shows how to
+    implement portable, cross-platform 3D rendering with the \l QRhi APIs in a
+    manner where the custom rendering is issued before the Qt Quick scene
+    graph's own rendering, effectively providing an "underlay". That approach
+    is efficient since now additional render targets and render passes are
+    needed, the custom rendering is injected in the main render pass before the
+    scene graph's own draw calls.
+
+    In contrast, this example involves a separate render target (a QRhiTexture,
+    the \l{QRhiTexture::pixelSize()}{dimensions} of which match the
+    QQuickItem's size in the scene) and a whole render pass that is used to
+    clear and then draw into that texture. The texture is then used with an
+    instance of a custom QQuickItem subclass that is implemented using the \l
+    QSGSimpleTextureNode helper class.
+
+    Compared to the underlay/overlay approach, this allows displaying,
+    blending, and transforming the flattened 2D image of the 3D rendering
+    anywhere in the Qt Quick scene since here we have a true QQuickItem. This
+    comes at the expense of being more expensive in terms of resources and
+    performance since it involves rendering to a texture first.
+
+    \section1 Walkthrough
+
+    \c ExampleRhiItem is the QQuickItem subclass that is exposed to QML
+    and is instantied in the scene.
+
+    \snippet scenegraph/rhitextureitem/rhitextureitem.h item
+
+    The \c angle property has a \l NumberAnimation on it, this is what drives
+    the continuous rotation of the 3D mesh.
+
+    \snippet scenegraph/rhitextureitem/main.qml 0
+
+    \c ExampleRhiItem drives from \c RhiItem, which contains the generic
+    implementation of a \l QQuickItem that maintains and displays a \l
+    QRhiTexture.
+
+    \snippet scenegraph/rhitextureitem/rhitextureitem.h itembase
+
+    The corresponding scene graph node is implemented using \l
+    QSGSimpleTextureNode.
+
+    \snippet scenegraph/rhitextureitem/rhitextureitem.h itemnode
+
+ */