QRhi Class

Detailed Description

The Qt Rendering Hardware Interface is an abstraction for hardware accelerated graphics APIs, such as, OpenGL, OpenGL ES, Direct3D, Metal, and Vulkan.

Each QRhi instance is backed by a backend for a specific graphics API. The selection of the backend is a run time choice and is up to the application or library that creates the QRhi instance. Some backends are available on multiple platforms (OpenGL, Vulkan, Null), while APIs specific to a given platform are only available when running on the platform in question (Metal on macOS/iOS, Direct3D on Windows).

The available backends currently are:

• OpenGL 2.1 / OpenGL ES 2.0 or newer. Some extensions and newer core specification features are utilized when present, for example to enable multisample framebuffers or compute shaders. Operating in core profile contexts is supported as well. If necessary, applications can query the feature flags at runtime to check for features that are not supported in the OpenGL context backing the QRhi. The OpenGL backend builds on QOpenGLContext, QOpenGLFunctions, and the related cross-platform infrastructure of the Qt GUI module.
• Direct3D 11.1 or newer, with Shader Model 5.0 or newer. When the D3D runtime has no support for 11.1 features or Shader Model 5.0, initialization using an accelerated graphics device will fail, but using the software adapter is still an option.
• Direct3D 12 on Windows 10 version 1703 and newer, with Shader Model 5.0 or newer. Qt requires ID3D12Device2 to be present, hence the requirement for at least version 1703 of Windows 10. The D3D12 device is by default created with specifying a minimum feature level of D3D_FEATURE_LEVEL_11_0.
• Metal 1.2 or newer.
• Vulkan 1.0 or newer, optionally utilizing some Vulkan 1.1 level features.
• Null, a "dummy" backend that issues no graphics calls at all.

In order to allow shader code to be written once in Qt applications and libraries, all shaders are expected to be written in a single language which is then compiled into SPIR-V. Versions for various shading language are then generated from that, together with reflection information (inputs, outputs, shader resources). This is then packed into easily and efficiently serializable QShader instances. The compilers and tools to generate such shaders are not part of QRhi and the Qt GUI module, but the core classes for using such shaders, QShader and QShaderDescription, are. The APIs and tools for performing compilation and translation are part of the Qt Shader Tools module.

See the RHI Window Example for an introductory example of creating a portable, cross-platform application that performs accelerated 3D rendering onto a QWindow using QRhi.

An Impression of the API

To provide a quick look at the API with a short yet complete example that does not involve window-related setup, the following is a complete, runnable cross-platform application that renders 20 frames off-screen, and then saves the generated images to files after reading back the texture contents from the GPU. For an example that renders on-screen, which then involves setting up a QWindow and a swapchain, refer to the RHI Window Example.

For brevity, the initialization of the QRhi is done based on the platform: the sample code here chooses Direct 3D 12 on Windows, Metal on macOS and iOS, and Vulkan otherwise. OpenGL and Direct 3D 11 are never used by this application, but support for those could be introduced with a few additional lines.

 #include <QGuiApplication>
 #include <QImage>
 #include <QFile>
 #include <rhi/qrhi.h>

 int main(int argc, char **argv)
 {
     QGuiApplication app(argc, argv);

 #if QT_CONFIG(vulkan)
     QVulkanInstance inst;
 #endif
     std::unique_ptr<QRhi> rhi;
 #if defined(Q_OS_WIN)
     QRhiD3D12InitParams params;
     rhi.reset(QRhi::create(QRhi::D3D12, &params));
 #elif defined(Q_OS_MACOS) || defined(Q_OS_IOS)
     QRhiMetalInitParams params;
     rhi.reset(QRhi::create(QRhi::Metal, &params));
 #elif QT_CONFIG(vulkan)
     inst.setExtensions(QRhiVulkanInitParams::preferredInstanceExtensions());
     if (inst.create()) {
         QRhiVulkanInitParams params;
         params.inst = &inst;
         rhi.reset(QRhi::create(QRhi::Vulkan, &params));
     } else {
         qFatal("Failed to create Vulkan instance");
     }
 #endif
     if (rhi)
         qDebug() << rhi->backendName() << rhi->driverInfo();
     else
         qFatal("Failed to initialize RHI");

     float rotation = 0.0f;
     float opacity = 1.0f;
     int opacityDir = 1;

     std::unique_ptr<QRhiTexture> tex(rhi->newTexture(QRhiTexture::RGBA8,
                                                      QSize(1280, 720),
                                                      1,
                                                      QRhiTexture::RenderTarget | QRhiTexture::UsedAsTransferSource));
     tex->create();
     std::unique_ptr<QRhiTextureRenderTarget> rt(rhi->newTextureRenderTarget({ tex.get() }));
     std::unique_ptr<QRhiRenderPassDescriptor> rp(rt->newCompatibleRenderPassDescriptor());
     rt->setRenderPassDescriptor(rp.get());
     rt->create();

     QMatrix4x4 viewProjection = rhi->clipSpaceCorrMatrix();
     viewProjection.perspective(45.0f, 1280 / 720.f, 0.01f, 1000.0f);
     viewProjection.translate(0, 0, -4);

     static float vertexData[] = { // Y up, CCW
         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,
     };

     std::unique_ptr<QRhiBuffer> vbuf(rhi->newBuffer(QRhiBuffer::Immutable,
                                                     QRhiBuffer::VertexBuffer,
                                                     sizeof(vertexData)));
     vbuf->create();

     std::unique_ptr<QRhiBuffer> ubuf(rhi->newBuffer(QRhiBuffer::Dynamic,
                                                     QRhiBuffer::UniformBuffer,
                                                     64 + 4));
     ubuf->create();

     std::unique_ptr<QRhiShaderResourceBindings> srb(rhi->newShaderResourceBindings());
     srb->setBindings({
         QRhiShaderResourceBinding::uniformBuffer(0,
                                                  QRhiShaderResourceBinding::VertexStage | QRhiShaderResourceBinding::FragmentStage,
                                                  ubuf.get())
     });
     srb->create();

     std::unique_ptr<QRhiGraphicsPipeline> ps(rhi->newGraphicsPipeline());
     QRhiGraphicsPipeline::TargetBlend premulAlphaBlend;
     premulAlphaBlend.enable = true;
     ps->setTargetBlends({ premulAlphaBlend });
     static auto getShader = [](const QString &name) {
         QFile f(name);
         return f.open(QIODevice::ReadOnly) ? QShader::fromSerialized(f.readAll()) : QShader();
     };
     ps->setShaderStages({
         { QRhiShaderStage::Vertex, getShader(QLatin1String("color.vert.qsb")) },
         { QRhiShaderStage::Fragment, getShader(QLatin1String("color.frag.qsb")) }
     });
     QRhiVertexInputLayout inputLayout;
     inputLayout.setBindings({
         { 5 * sizeof(float) }
     });
     inputLayout.setAttributes({
         { 0, 0, QRhiVertexInputAttribute::Float2, 0 },
         { 0, 1, QRhiVertexInputAttribute::Float3, 2 * sizeof(float) }
     });
     ps->setVertexInputLayout(inputLayout);
     ps->setShaderResourceBindings(srb.get());
     ps->setRenderPassDescriptor(rp.get());
     ps->create();

     QRhiCommandBuffer *cb;
     for (int frame = 0; frame < 20; ++frame) {
         rhi->beginOffscreenFrame(&cb);

         QRhiResourceUpdateBatch *u = rhi->nextResourceUpdateBatch();
         if (frame == 0)
             u->uploadStaticBuffer(vbuf.get(), vertexData);

         QMatrix4x4 mvp = viewProjection;
         mvp.rotate(rotation, 0, 1, 0);
         u->updateDynamicBuffer(ubuf.get(), 0, 64, mvp.constData());
         rotation += 5.0f;

         u->updateDynamicBuffer(ubuf.get(), 64, 4, &opacity);
         opacity += opacityDir * 0.2f;
         if (opacity < 0.0f || opacity > 1.0f) {
             opacityDir *= -1;
             opacity = qBound(0.0f, opacity, 1.0f);
         }

         cb->beginPass(rt.get(), Qt::green, { 1.0f, 0 }, u);
         cb->setGraphicsPipeline(ps.get());
         cb->setViewport({ 0, 0, 1280, 720 });
         cb->setShaderResources();
         const QRhiCommandBuffer::VertexInput vbufBinding(vbuf.get(), 0);
         cb->setVertexInput(0, 1, &vbufBinding);
         cb->draw(3);
         QRhiReadbackResult readbackResult;
         u = rhi->nextResourceUpdateBatch();
         u->readBackTexture({ tex.get() }, &readbackResult);
         cb->endPass(u);

         rhi->endOffscreenFrame();

         QImage image(reinterpret_cast<const uchar *>(readbackResult.data.constData()),
                      readbackResult.pixelSize.width(),
                      readbackResult.pixelSize.height(),
                      QImage::Format_RGBA8888_Premultiplied);
         if (rhi->isYUpInFramebuffer())
             image = image.mirrored();
         image.save(QString::asprintf("frame%d.png", frame));
     }

     return 0;
 }

The result of the application is 20 PNG images (frame0.png - frame19.png). These contain a rotating triangle with varying opacity over a green background.

The vertex and fragment shaders are expected to be processed and packaged into .qsb files. The Vulkan-compatible GLSL source code is the following:

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;
     float opacity;
 };

 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;

 layout(std140, binding = 0) uniform buf {
     mat4 mvp;
     float opacity;
 };

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

To manually compile and transpile these shaders to a number of targets (SPIR-V, HLSL, MSL, GLSL) and generate the .qsb files the application loads at run time, run qsb --qt6 color.vert -o color.vert.qsb and qsb --qt6 color.frag -o color.frag.qsb. Alternatively, the Qt Shader Tools module offers build system integration for CMake, the qt_add_shaders() CMake function, that can achieve the same at build time.

Design Fundamentals

A QRhi cannot be instantiated directly. Instead, use the create() function. Delete the QRhi instance normally to release the graphics device.

Resources

Instances of classes deriving from QRhiResource, such as, QRhiBuffer, QRhiTexture, etc., encapsulate zero, one, or more native graphics resources. Instances of such classes are always created via the new functions of the QRhi, such as, newBuffer(), newTexture(), newTextureRenderTarget(), newSwapChain().

 QRhiBuffer *vbuf = rhi->newBuffer(QRhiBuffer::Immutable, QRhiBuffer::VertexBuffer, sizeof(vertexData));
 if (!vbuf->create()) { error(); }
 // ...
 delete vbuf;

• The returned value from functions like newBuffer() is always owned by the caller.
• Just creating an instance of a QRhiResource subclass never allocates or initializes any native resources. That is only done when calling the create() function of a subclass, for example, QRhiBuffer::create() or QRhiTexture::create().
• The exceptions are QRhiTextureRenderTarget::newCompatibleRenderPassDescriptor(), QRhiSwapChain::newCompatibleRenderPassDescriptor(), and QRhiRenderPassDescriptor::newCompatibleRenderPassDescriptor(). There is no create() operation for these and the returned object is immediately active.
• The resource objects themselves are treated as immutable: once a resource has create() called, changing any parameters via the setters, such as, QRhiTexture::setPixelSize(), has no effect, unless the underlying native resource is released and create() is called again. See more about resource reuse in the sections below.
• The underlying native resources are scheduled for releasing by the QRhiResource destructor, or by calling QRhiResource::destroy(). Backends often queue release requests and defer executing them to an unspecified time, this is hidden from the applications. This way applications do not have to worry about releasing native resources that may still be in use by an in-flight frame.
• Note that this does not mean that a QRhiResource can freely be destroy()'ed or deleted within a frame (that is, in a beginFrame() - endFrame() section). As a general rule, all referenced QRhiResource objects must stay unchanged until the frame is submitted by calling endFrame(). To ease this, QRhiResource::deleteLater() is provided as a convenience.

Command buffers and deferred command execution

Regardless of the design and capabilities of the underlying graphics API, all QRhi backends implement some level of command buffers. No QRhiCommandBuffer function issues any native bind or draw command (such as, glDrawElements) directly. Commands are always recorded in a queue, either native or provided by the QRhi backend. The command buffer is submitted, and so execution starts only upon QRhi::endFrame() or QRhi::finish().

The deferred nature has consequences for some types of objects. For example, writing to a dynamic buffer multiple times within a frame, in case such buffers are backed by host-visible memory, will result in making the results of all writes are visible to all draw calls in the command buffer of the frame, regardless of when the dynamic buffer update was recorded relative to a draw call.

Furthermore, instances of QRhiResource subclasses must be treated immutable within a frame in which they are referenced in any way. Create all resources upfront, before starting to record commands for the next frame. Reusing a QRhiResource instance within a frame (by calling create() then referencing it again in the same beginFrame - endFrame section) should be avoided as it may lead to unexpected results, depending on the backend.

As a general rule, all referenced QRhiResource objects must stay valid and unmodified until the frame is submitted by calling endFrame(). On the other hand, calling destroy() or deleting the QRhiResource are always safe once the frame is submitted, regardless of the status of the underlying native resources (which may still be in use by the GPU - but that is taken care of internally).

Unlike APIs like OpenGL, upload and copy type of commands cannot be mixed with draw commands. The typical renderer will involve a sequence similar to the following:

• (re)create resources
• begin frame
• record/issue uploads and copies
• start recording a render pass
• record draw calls
• end render pass
• end frame

Recording copy type of operations happens via QRhiResourceUpdateBatch. Such operations are committed typically on beginPass().

When working with legacy rendering engines designed for OpenGL, the migration to QRhi often involves redesigning from having a single render step (that performs copies and uploads, clears buffers, and issues draw calls, all mixed together) to a clearly separated, two phase prepare - render setup where the render step only starts a renderpass and records draw calls, while all resource creation and queuing of updates, uploads and copies happens beforehand, in the prepare step.

QRhi does not at the moment allow freely creating and submitting command buffers. This may be lifted in the future to some extent, in particular if compute support is introduced, but the model of well defined frame-start and frame-end points, combined with a dedicated, "frame" command buffer, where frame-end implies presenting, is going to remain the primary way of operating since this is what fits Qt's various UI technologies best.

Threading

A QRhi instance and the associated resources can be created and used on any thread but all usage must be limited to that one single thread. When rendering to multiple QWindows in an application, having a dedicated thread and QRhi instance for each window is often advisable, as this can eliminate issues with unexpected throttling caused by presenting to multiple windows. Conceptually that is then the same as how Qt Quick scene graph's threaded render loop operates when working directly with OpenGL: one thread for each window, one QOpenGLContext for each thread. When moving onto QRhi, QOpenGLContext is replaced by QRhi, making the migration straightforward.

When it comes to externally created native objects, such as OpenGL contexts passed in via QRhiGles2NativeHandles, it is up to the application to ensure they are not misused by other threads.

Resources are not shareable between QRhi instances. This is an intentional choice since QRhi hides most queue, command buffer, and resource synchronization related tasks, and provides no API for them. Safe and efficient concurrent use of graphics resources from multiple threads is tied to those concepts, however, and is thus a topic that is currently out of scope, but may be introduced in the future.

Resource synchronization

QRhi does not expose APIs for resource barriers or image layout transitions. Such synchronization is done implicitly by the backends, where applicable (for example, Vulkan), by tracking resource usage as necessary. Buffer and image barriers are inserted before render or compute passes transparently to the application.

Resource reuse

From the user's point of view a QRhiResource is reusable immediately after calling QRhiResource::destroy(). With the exception of swapchains, calling create() on an already created object does an implicit destroy(). This provides a handy shortcut to reuse a QRhiResource instance with different parameters, with a new native graphics object underneath.

The importance of reusing the same object lies in the fact that some objects reference other objects: for example, a QRhiShaderResourceBindings can reference QRhiBuffer, QRhiTexture, and QRhiSampler instances. If in a later frame one of these buffers need to be resized or a sampler parameter needs changing, destroying and creating a whole new QRhiBuffer or QRhiSampler would invalidate all references to the old instance. By just changing the appropriate parameters via QRhiBuffer::setSize() or similar and then calling QRhiBuffer::create(), everything works as expected and there is no need to touch the QRhiShaderResourceBindings at all, even though there is a good chance that under the hood the QRhiBuffer is now backed by a whole new native buffer.

 QRhiBuffer *ubuf = rhi->newBuffer(QRhiBuffer::Dynamic, QRhiBuffer::UniformBuffer, 256);
 ubuf->create();

 QRhiShaderResourceBindings *srb = rhi->newShaderResourceBindings()
 srb->setBindings({
     QRhiShaderResourceBinding::uniformBuffer(0, QRhiShaderResourceBinding::VertexStage | QRhiShaderResourceBinding::FragmentStage, ubuf)
 });
 srb->create();

 // ...

 // now in a later frame we need to grow the buffer to a larger size
 ubuf->setSize(512);
 ubuf->create(); // same as ubuf->destroy(); ubuf->create();

 // srb needs no changes whatsoever, any references in it to ubuf
 // stay valid. When it comes to internal details, such as that
 // ubuf may now be backed by a completely different native buffer
 // resource, that is is recognized and handled automatically by the
 // next setShaderResources().

QRhiTextureRenderTarget offers the same contract: calling QRhiCommandBuffer::beginPass() is safe even when one of the render target's associated textures or renderbuffers has been rebuilt (by calling create() on it) since the creation of the render target object. This allows the application to resize a texture by setting a new pixel size on the QRhiTexture and calling create(), thus creating a whole new native texture resource underneath, without having to update the QRhiTextureRenderTarget as that will be done implicitly in beginPass().

Pooled objects

In addition to resources, there are pooled objects as well, such as, QRhiResourceUpdateBatch. An instance is retrieved via a next function, such as, nextResourceUpdateBatch(). The caller does not own the returned instance in this case. The only valid way of operating here is calling functions on the QRhiResourceUpdateBatch and then passing it to QRhiCommandBuffer::beginPass() or QRhiCommandBuffer::endPass(). These functions take care of returning the batch to the pool. Alternatively, a batch can be "canceled" and returned to the pool without processing by calling QRhiResourceUpdateBatch::release().

A typical pattern is thus:

 QRhiResourceUpdateBatch *resUpdates = rhi->nextResourceUpdateBatch();
 // ...
 resUpdates->updateDynamicBuffer(ubuf, 0, 64, mvp.constData());
 if (!image.isNull()) {
     resUpdates->uploadTexture(texture, image);
     image = QImage();
 }
 // ...
 QRhiCommandBuffer *cb = m_sc->currentFrameCommandBuffer();
 // note the last argument
 cb->beginPass(swapchain->currentFrameRenderTarget(), clearCol, clearDs, resUpdates);

Swapchain specifics

QRhiSwapChain features some special semantics due to the peculiar nature of swapchains.

• It has no create() but rather a QRhiSwapChain::createOrResize(). Repeatedly calling this function is not the same as calling QRhiSwapChain::destroy() followed by QRhiSwapChain::createOrResize(). This is because swapchains often have ways to handle the case where buffers need to be resized in a manner that is more efficient than a brute force destroying and recreating from scratch.
• An active QRhiSwapChain must be released by calling destroy(), or by destroying the object, before the QWindow's underlying QPlatformWindow, and so the associated native window object, is destroyed. It should not be postponed because releasing the swapchain may become problematic (and with some APIs, like Vulkan, is explicitly disallowed) when the native window is not around anymore, for example because the QPlatformWindow got destroyed upon getting a QWindow::close(). Therefore, releasing the swapchain must happen whenever the targeted QWindow sends the QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed event. If the event does not arrive before the destruction of the QWindow - this can happen when using QCoreApplication::quit() -, then check QWindow::handle() after the event loop exits and invoke the swapchain release when non-null (meaning the underlying native window is still around).

Ownership

The general rule is no ownership transfer. Creating a QRhi with an already existing graphics device does not mean the QRhi takes ownership of the device object. Similarly, ownership is not given away when a device or texture object is "exported" via QRhi::nativeHandles() or QRhiTexture::nativeTexture(). Most importantly, passing pointers in structs and via setters does not transfer ownership.

Troubleshooting and Profiling

Error reporting

Functions such as QRhi::create() and the resource classes' create() member functions (e.g., QRhiBuffer::create()) indicate failure with the return value (nullptr or false, respectively). When working with QShader, QShader::fromSerialized() returns an invalid QShader (for which isValid() returns false) when the data passed to the function cannot be successfully deserialized. Some functions, beginFrame() in particular, may also sometimes report "soft failures", such as FrameOpSwapChainOutOfDate, which do not indicate an unrecoverable error, but rather should be seen as a "try again later" response.

Warnings and errors may get printed at any time to the debug output via qWarning(). It is therefore always advisable to inspect the output of the application.

Additional debug messages can be enabled via the following logging categories. Messages from these categories are not printed by default unless explicitly enabled via QLoggingCategory or the QT_LOGGING_RULES environment variable. For better interoperation with Qt Quick, the environment variable QSG_INFO also enables these debug prints.

• qt.rhi.general

Additionally, applications can query the QRhi backend name and graphics device information from a successfully initialized QRhi. This can then be printed to the user or stored in the application logs even in production builds, if desired.

Investigating rendering problems

When the rendering results are not as expected, or the application is experiencing problems, always consider checking with the the native 3D APIs' debug and validation facilities. QRhi itself features limited error checking since replicating the already existing, vast amount of functionality in the underlying layers is not reasonable.

• For Vulkan, controlling the Vulkan Validation Layers is not in the scope of the QRhi, but rather can be achieved by configuring the QVulkanInstance with the appropriate layers. For example, call instance.setLayers({ "VK_LAYER_KHRONOS_validation" }); before invoking create() on the QVulkanInstance. (note that this assumes that the validation layers are actually installed and available, e.g. from the Vulkan SDK) By default, QVulkanInstance conveniently redirects the Vulkan debug messages to qDebug, meaning the validation messages get printed just like other Qt warnings.
• With Direct 3D 11 and 12, a graphics device with the debug layer enabled can be requested by toggling the enableDebugLayer flag in the appropriate init params struct. The messages appear on the debug output, which is visible in Qt Creator's messages panel or via a tool such as DebugView.
• For Metal, controlling Metal Validation is outside of QRhi's scope. Rather, to enable validation, run the application with the environment variable METAL_DEVICE_WRAPPER_TYPE=1 set, or run the application within XCode. There may also be further settings and environment variable in modern XCode and macOS versions. See for instance this page.

Frame captures and performance profiling

A Qt application rendering with QRhi to a window while relying on a 3D API under the hood, is, from the windowing and graphics pipeline perspective at least, no different from any other (non-Qt) applications using the same 3D API. This means that tools and practices for debugging and profiling applications involving 3D graphics, such as games, all apply to such a Qt application as well.

A few examples of tools that can provide insights into the rendering internals of Qt applications that use QRhi, which includes Qt Quick and Qt Quick 3D based projects as well:

• RenderDoc allows taking frame captures and introspecting the recorded commands and pipeline state on Windows and Linux for applications using OpenGL, Vulkan, D3D11, or D3D12. When trying to figure out why some parts of the 3D scene do not show up as expected, RenderDoc is often a fast and efficient way to check the pipeline stages and the related state and discover the missing or incorrect value. It is also a tool that is actively used when developing Qt itself.
• For NVIDIA-based systems, Nsight Graphics provides a graphics debugger tool on Windows and Linux. In addition to investigating the commands in the frame and the pipeline, the vendor-specific tools allow looking at timings and hardware performance information, which is not something simple frame captures can provide.
• For AMD-based systems, the Radeon GPU Profiler can be used to gain deeper insights into the application's rendering and its performance.
• As QRhi supports Direct 3D 12, using PIX, a performance tuning and debugging tool for DirectX 12 games on Windows is an option as well.
• On macOS, the XCode Metal debugger can be used to take and introspect frame captures, to investigate performance details, and debug shaders. In macOS 13 it is also possible to enable an overlay that displays frame rate and other information for any Metal-based window by setting the environment variable MTL_HUD_ENABLED=1.

On mobile and embedded platforms, there may be vendor and platform-specific tools, provided by the GPU or SoC vendor, available to perform performance profiling of application using OpenGL ES or Vulkan.

When capturing frames, remember that objects and groups of commands can be named via debug markers, as long as debug markers were enabled for the QRhi, and the graphics API in use supports this. To annotate the command stream, call debugMarkBegin(), debugMarkEnd() and/or debugMarkMsg(). This can be particularly useful in larger frames with multiple render passes. Resources are named by calling setName() before create().

To perform basic timing measurements on the CPU and GPU side within the application, QElapsedTimer and QRhiCommandBuffer::lastCompletedGpuTime() can be used. The latter is only available with select graphics APIs at the moment and requires opting in via the QRhi::EnableTimestamps flag.

Resource leak checking

When destroying a QRhi object without properly destroying all buffers, textures, and other resources created from it, warnings about this are printed to the debug output whenever the application is a debug build, or when the QT_RHI_LEAK_CHECK environment variable is set to a non-zero value. This is a simple way to discover design issues around resource handling within the application rendering logic. Note however that some platforms and underlying graphics APIs may perform their own allocation and resource leak detection as well, over which Qt will have no direct control. For example, when using Vulkan, the memory allocator may raise failing assertions in debug builds when resources that own graphics memory allocations are not destroyed before the QRhi. In addition, the Vulkan validation layer, when enabled, will issue warnings about native graphics resources that were not released. Similarly, with Direct 3D warnings may get printed about unreleased COM objects when the application does not destroy the QRhi and its resources in the correct order.