QRhi Class

Detailed Description

Accelerated 2D/3D graphics API abstraction.

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

Some of the main design goals are:

• Simple, minimal, understandable, extensible. Follow the proven path of the Qt Quick scenegraph.
• Aim to be a product - and in the bigger picture, part of a product (Qt) - that is usable out of the box both by internal (such as, Qt Quick) and, eventually, external users.
• Not a complete 1:1 wrapper for any of the underlying APIs. The feature set is tuned towards the needs of Qt's 2D and 3D offering (QPainter, Qt Quick, Qt 3D Studio). Iterate and evolve in a sustainable manner.
• Intrinsically cross-platform, without reinventing: abstracting cross-platform aspects of certain APIs (such as, OpenGL context creation and windowing system interfaces, Vulkan instance and surface management) is not in scope here. These are delegated to the existing QtGui facilities (QWindow, QOpenGLContext, QVulkanInstance) and its backing QPA architecture.

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/tvOS, Direct3D on Windows).

The available backends currently are:

• OpenGL 2.1 or OpenGL ES 2.0 or newer. Some extensions are utilized when present, for example to enable multisample framebuffers.
• Direct3D 11.1
• Metal
• Vulkan 1.0, optionally with some extensions that are part of Vulkan 1.1
• 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, but the core classes for using such shaders, QShader and QShaderDescription, are.

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().

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

• The returned value from both create() and functions like newBuffer() is owned by the caller.
• Just creating a QRhiResource subclass never allocates or initializes any native resources. That is only done when calling the build function of a subclass, for example, QRhiBuffer::build() or QRhiTexture::build().
• The exception is QRhiTextureRenderTarget::newCompatibleRenderPassDescriptor() and QRhiSwapChain::newCompatibleRenderPassDescriptor(). There is no build operation for these and the returned object is immediately active.
• The resource objects themselves are treated as immutable: once a resource is built, changing any parameters via the setters, such as, QRhiTexture::setPixelSize(), has no effect, unless the underlying native resource is released and build 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::release(). 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 destroyed or release()'d 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::releaseAndDestroyLater() 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 or rebuild all resources upfront, before starting to record commands for the next frame. Reusing a QRhiResource instance within a frame (by rebuilding it and 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 release() or destroying 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)build resources - begin frame - record uploads and copies - start renderpass - record draw calls - end renderpass - 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.

Note: Resources within a render or compute pass are expected to be bound to a single usage during that pass. For example, a buffer can be used as vertex, index, uniform, or storage buffer, but not a combination of them within a single pass. However, it is perfectly fine to use a buffer as a storage buffer in a compute pass, and then as a vertex buffer in a render pass, for example, assuming the buffer declared both usages upon creation.

Note: Textures have this rule relaxed in certain cases, because using two subresources (typically two different mip levels) of the same texture for different access (one for load, one for store) is supported even within the same pass.

Resource reuse

From the user's point of view a QRhiResource is reusable immediately after calling QRhiResource::release(). With the exception of swapchains, calling build() on an already built object does an implicit release(). 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::build(), 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.

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

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

  ...

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

  // that's it, srb needs no changes whatsoever

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();
  cb->beginPass(swapchain->currentFrameRenderTarget(), clearCol, clearDs, resUpdates);

Swapchain specifics

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

• It has no build but rather a QRhiSwapChain::buildOrResize(). Repeatedly calling this function is not the same as calling QRhiSwapChain::release() followed by QRhiSwapChain::buildOrResize(). 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 release(), 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::nativeHandles(). Most importantly, passing pointers in structs and via setters does not transfer ownership.