// Copyright (C) 2022 The Qt Company Ltd. // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \example scenegraph/customrendernode \title Scene Graph - Custom QSGRenderNode \examplecategory {Graphics & Multimedia} \ingroup qtquickexamples \brief Shows how to use QSGRenderNode to implement custom rendering in the Qt Quick scenegraph. The custom render node example shows how to implement a QQuickItem subclass that is backed by a scene graph node derived from QSGRenderNode, providing it's own QRhi-based rendering. \image customrendernode-example.jpg \note This example demonstrates advanced, low-level functionality performing portable, cross-platform 3D rendering, while relying on APIs with limited compatibility guarantee from the Qt Gui module. To be able to use the QRhi APIs, the application links to \c{Qt::GuiPrivate} and includes \c{}. QSGRenderNode allows direct access to the Render Hardware Interface (RHI) within the scenegraph. This example demonstrates how to create QSGRenderNode based render node and manage it with a custom item. The render node creates an RHI pipeline, updates vertex and uniform buffers, and renders into the RHI command buffer. In practice this is a portable, cross-platform approach to perform custom rendering inline with the scenegraph's own rendering, without resorting to a native 3D API such as OpenGL, Metal, or Vulkan. Rather, the application uses Qt's graphics and shader abstraction layer. QSGRenderNode is the enabler for one of the three ways to integrate custom 2D/3D rendering into a Qt Quick scene. The other two options are to perform the rendering \c before or \c after the Qt Quick scene's own rendering, or to generate a whole separate render pass targeting a dedicated render target (a texture) and then have an item in the scene display the texture. The QSGRenderNode-based approach is similar to the former, in the sense that no additional render passes or render targets are involved, and allows injecting custom rendering commands "inline" with the Qt Quick scene's own rendering. Refer to the following examples for these three approaches: \list \li \l{Scene Graph - RHI Under QML} - Demonstrates an "underlay" approach based on the \l{QQuickWindow::beforeRendering()} signal. No additional render pass and resources are needed, but composition and blending with the rest of the Qt Quick scene is quite limited. Rendering "under" or "over" the Qt Quick scene is the simplest approach. \li \l{Scene Graph - RHI Texture Item} - Demonstrates creating a custom QQuickItem that renders into a texture and displays a quad textured with the generated content. This is very flexible and allows complete blending and composition of the resulting 2D image with the rest of the Qt Quick scene. That comes at the expense of an additional render pass and render target. \li This example - Demonstrates the "inline" approach, where the Qt Quick scene graph calls into the custom item and node implementation during the main render pass. This approach can be great for performance (no extra render passes, texturing, and blending are involved), but has potential pitfalls and is the most complicated method. \endlist The custom item derives from QQuickItem. Most importantly, it reimplements \l{QQuickItem::}updatePaintNode(). \snippet scenegraph/customrendernode/customrender.h item The constructor sets the \l{QQuickItem::}ItemHasContents flag to indicate that this is a visual item. \snippet scenegraph/customrendernode/customrender.cpp item-ctor The updatePaintNode() implementation creates an instance of the custom scenegraph node, if not yet done. The backing QSGNode tree for this item consists of a single node, an instance of a QSGRenderNode-derived class. When Qt Quick's threaded rendering model is in use, this function is called on the render thread with the main thread blocked. That is why it is safe to access main thread data (such as data stored in QQuickItems). The node, the instance of the QSGRenderNode subclass, is going to "live on" the render thread. \snippet scenegraph/customrendernode/customrender.cpp item-update The \c CustomRenderNode class derives from QSGRenderNode, reimplementing a number of virtual functions. To manage QRhi resources (buffers, pipelines, etc.), smart pointers are quite useful in this case, because the node is destroyed by the scene graph together with the rest of the scene on the render thread (if there is one) while the QRhi is still available, and therefore releasing resources from the destructor or via smart pointers is legal and safe. \snippet scenegraph/customrendernode/customrender.cpp node Well-behaving QSGRenderNode subclasses also reimplement \l{QSGRenderNode::}releaseResources(),which in this case can be a simple set of reset() calls. \snippet scenegraph/customrendernode/customrender.cpp node-release This QSGRenderNode is performing its rendering through the QRhi APIs (and not directly through OpenGL, Vulkan, Metal, etc.), and it takes the item transform into account (as it only really does 2D rendering). Hence specifying the appropriate flags, which may bring a small performance improvement. \snippet scenegraph/customrendernode/customrender.cpp node-flags The prepare() and render() functions are called every time the Qt Quick scene renders. The first is called when preparing (but not yet recording) the render pass. This typically creates resources, such as buffers, textures, and graphics pipelines, if not yet done, and enqueues uploading data to them. \snippet scenegraph/customrendernode/customrender.cpp node-prepare The render() function is called while the recording of a render pass, targeting either the QQuickWindow's swapchain, or a texture (in case of layered items, or when within a ShaderEffectSource), is active. \snippet scenegraph/customrendernode/customrender.cpp node-render \sa QSGRenderNode, QRhi, {Scene Graph - RHI Under QML}, {Scene Graph - RHI Texture Item}, {Qt Quick Scene Graph} */