QQuickRhiItem Class

Detailed Description

QQuickRhiItem is effectively the counterpart of QRhiWidget in the world of Qt Quick. Both of these are meant to be subclassed, and they both enable recording QRhi-based rendering that targets an offscreen color buffer. The resulting 2D image is then composited with the rest of the Qt Quick scene.

QQuickRhiItem is a replacement for the legacy QQuickFramebufferObject class. The latter is inherently tied to OpenGL / OpenGL ES, whereas QQuickRhiItem works with the QRhi classes, allowing to run the same rendering code with Vulkan, Metal, Direct 3D 11/12, and OpenGL / OpenGL ES. Conceptually and functionally they are very close, and migrating from QQuickFramebufferObject to QQuickRhiItem is straightforward. QQuickFramebufferObject continues to be available to ensure compatibility for existing application code that works directly with the OpenGL API.

On most platforms, the scene graph rendering, and thus the rendering performed by the QQuickRhiItem will occur on a dedicated thread. For this reason, the QQuickRhiItem class enforces a strict separation between the item implementation (the QQuickItem subclass) and the actual rendering logic. All item logic, such as properties and UI-related helper functions exposed to QML must be located in the QQuickRhiItem subclass. Everything that relates to rendering must be located in the QQuickRhiItemRenderer class. To avoid race conditions and read/write issues from two threads it is important that the renderer and the item never read or write shared variables. Communication between the item and the renderer should primarily happen via the QQuickRhiItem::synchronize() function. This function will be called on the render thread while the GUI thread is blocked. Using queued connections or events for communication between item and renderer is also possible.

Applications must subclass both QQuickRhiItem and QQuickRhiItemRenderer. The pure virtual createRenderer() function must be reimplemented to return a new instance of the QQuickRhiItemRenderer subclass.

As with QRhiWidget, QQuickRhiItem automatically managed the color buffer, which is a 2D texture (QRhiTexture) normally, or a QRhiRenderBuffer when multisampling is in use. (some 3D APIs differentiate between textures and renderbuffers, while with some others the underlying native resource is the same; renderbuffers are used mainly to allow multisampling with OpenGL ES 3.0)

The size of the texture will by default adapt to the size of the item (with the device pixel ratio taken into account). If the item size changes, the texture is recreated with the correct size. If a fixed size is preferred, set fixedColorBufferWidth and fixedColorBufferHeight to non-zero values.

QQuickRhiItem is a texture provider and can be used directly in ShaderEffects and other classes that consume texture providers.

While not a primary use case, QQuickRhiItem also allows incorporating rendering code that directly uses a 3D graphics API such as Vulkan, Metal, Direct 3D, or OpenGL. See QRhiCommandBuffer::beginExternal() for details on recording native commands within a QRhi render pass, as well as QRhiTexture::createFrom() for a way to wrap an existing native texture and then use it with QRhi in a subsequent render pass. See also QQuickGraphicsConfiguration regarding configuring the native 3D API environment (e.g. device extensions) and note that the QQuickWindow can be associated with a custom QVulkanInstance by calling QWindow::setVulkanInstance() early enough.

A simple example

Take the following subclass of QQuickRhiItem. It is shown here in complete form. It renders a single triangle with a perspective projection, where the triangle is rotated based on the angle property of the custom item. (meaning it can be driven for example with animations such as NumberAnimation from QML)

 class ExampleRhiItemRenderer : public QQuickRhiItemRenderer
 {
 public:
     void initialize(QRhiCommandBuffer *cb) override;
     void synchronize(QQuickRhiItem *item) override;
     void render(QRhiCommandBuffer *cb) override;

 private:
     QRhi *m_rhi = nullptr;
     std::unique_ptr<QRhiBuffer> m_vbuf;
     std::unique_ptr<QRhiBuffer> m_ubuf;
     std::unique_ptr<QRhiShaderResourceBindings> m_srb;
     std::unique_ptr<QRhiGraphicsPipeline> m_pipeline;
     QMatrix4x4 m_viewProjection;
     float m_angle = 0.0f;
 };

 class ExampleRhiItem : public QQuickRhiItem
 {
     Q_OBJECT
     QML_NAMED_ELEMENT(ExampleRhiItem)
     Q_PROPERTY(float angle READ angle WRITE setAngle NOTIFY angleChanged)

 public:
     QQuickRhiItemRenderer *createRenderer() override;

     float angle() const { return m_angle; }
     void setAngle(float a);

 signals:
     void angleChanged();

 private:
     float m_angle = 0.0f;
 };

 QQuickRhiItemRenderer *ExampleRhiItem::createRenderer()
 {
     return new ExampleRhiItemRenderer;
 }

 void ExampleRhiItem::setAngle(float a)
 {
     if (m_angle == a)
         return;

     m_angle = a;
     emit angleChanged();
     update();
 }

 void ExampleRhiItemRenderer::synchronize(QQuickRhiItem *rhiItem)
 {
     ExampleRhiItem *item = static_cast<ExampleRhiItem *>(rhiItem);
     if (item->angle() != m_angle)
         m_angle = item->angle();
 }

 static QShader getShader(const QString &name)
 {
     QFile f(name);
     return f.open(QIODevice::ReadOnly) ? QShader::fromSerialized(f.readAll()) : QShader();
 }

 static float vertexData[] = {
     0.0f,   0.5f,   1.0f, 0.0f, 0.0f,
     -0.5f,  -0.5f,   0.0f, 1.0f, 0.0f,
     0.5f,  -0.5f,   0.0f, 0.0f, 1.0f,
 };

 void ExampleRhiItemRenderer::initialize(QRhiCommandBuffer *cb)
 {
     if (m_rhi != rhi()) {
         m_pipeline.reset();
         m_rhi = rhi();
     }

     if (!m_pipeline) {
         m_vbuf.reset(m_rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertexData)));
         m_vbuf->create();

         m_ubuf.reset(m_rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, 64));
         m_ubuf->create();

         m_srb.reset(m_rhi->newShaderResourceBindings());
         m_srb->setBindings({
             QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage, m_ubuf.get()),
         });
         m_srb->create();

         m_pipeline.reset(m_rhi->newGraphicsPipeline());
         m_pipeline->setShaderStages({
             { QRhiShaderStage::Vertex, getShader(QLatin1String(":/shaders/color.vert.qsb")) },
             { QRhiShaderStage::Fragment, getShader(QLatin1String(":/shaders/color.frag.qsb")) }
         });
         QRhiVertexInputLayout inputLayout;
         inputLayout.setBindings({
             { 5 * sizeof(float) }
         });
         inputLayout.setAttributes({
             { 0, 0, QRhiVertexInputAttribute::Float2, 0 },
             { 0, 1, QRhiVertexInputAttribute::Float3, 2 * sizeof(float) }
         });
         m_pipeline->setVertexInputLayout(inputLayout);
         m_pipeline->setShaderResourceBindings(m_srb.get());
         m_pipeline->setRenderPassDescriptor(renderTarget()->renderPassDescriptor());
         m_pipeline->create();

         QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch();
         resourceUpdates->uploadStaticBuffer(m_vbuf.get(), vertexData);
         cb->resourceUpdate(resourceUpdates);
     }

     const QSize outputSize = renderTarget()->pixelSize();
     m_viewProjection = m_rhi->clipSpaceCorrMatrix();
     m_viewProjection.perspective(45.0f, outputSize.width() / (float) outputSize.height(), 0.01f, 1000.0f);
     m_viewProjection.translate(0, 0, -4);
 }

 void ExampleRhiItemRenderer::render(QRhiCommandBuffer *cb)
 {
     QRhiResourceUpdateBatch *resourceUpdates = m_rhi->nextResourceUpdateBatch();
     QMatrix4x4 modelViewProjection = m_viewProjection;
     modelViewProjection.rotate(m_angle, 0, 1, 0);
     resourceUpdates->updateDynamicBuffer(m_ubuf.get(), 0, 64, modelViewProjection.constData());

     const QColor clearColor = QColor::fromRgbF(0.4f, 0.7f, 0.0f, 1.0f);
     cb->beginPass(renderTarget(), clearColor, { 1.0f, 0 }, resourceUpdates);

     cb->setGraphicsPipeline(m_pipeline.get());
     const QSize outputSize = renderTarget()->pixelSize();
     cb->setViewport(QRhiViewport(0, 0, outputSize.width(), outputSize.height()));
     cb->setShaderResources();
     const QRhiCommandBuffer::VertexInput vbufBinding(m_vbuf.get(), 0);
     cb->setVertexInput(0, 1, &vbufBinding);
     cb->draw(3);

     cb->endPass();
 }

It is notable that this simple class is almost exactly the same as the code shown in the QRhiWidget introduction. The vertex and fragment shaders are the same as well. These are provided as Vulkan-style GLSL source code and must be processed first by the Qt shader infrastructure first. This is achieved either by running the qsb command-line tool manually, or by using the qt_add_shaders() function in CMake. The QQuickRhiItem loads these pre-processed .qsb files that are shipped with the application. See Qt Shader Tools for more information about Qt's shader translation infrastructure.

color.vert

 #version 440
 layout(location = 0) in vec4 position;
 layout(location = 1) in vec3 color;
 layout(location = 0) out vec3 v_color;
 layout(std140, binding = 0) uniform buf {
     mat4 mvp;
 };

 void main()
 {
     v_color = color;
     gl_Position = mvp * position;
 }

color.frag

 #version 440
 layout(location = 0) in vec3 v_color;
 layout(location = 0) out vec4 fragColor;

 void main()
 {
     fragColor = vec4(v_color, 1.0);
 }

Once exposed to QML (note the QML_NAMED_ELEMENT), our custom item can be instantiated in any scene. (after importing the appropriate URI specified for qt_add_qml_module in the CMake project)

 ExampleRhiItem {
     anchors.fill: parent
     anchors.margins: 10
     NumberAnimation on angle { from: 0; to: 360; duration: 5000; loops: Animation.Infinite }
 }

See Scene Graph - RHI Texture Item for a more complex example.