QRhiCommandBuffer Class

Member Function Documentation

void QRhiCommandBuffer::beginComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr, QRhiCommandBuffer::BeginPassFlags flags = {})

Records starting a new compute pass.

resourceUpdates, when not null, specifies a resource update batch that is to be committed and then released.

flags is not currently used.

void QRhiCommandBuffer::beginExternal()

To be called when the application before the application is about to enqueue commands to the current pass' command buffer by calling graphics API functions directly.

With Vulkan, Metal, or Direct3D 12 one can query the native command buffer or encoder objects via nativeHandles() and enqueue commands to them. With OpenGL or Direct3D 11 the (device) context can be retrieved from QRhi::nativeHandles(). However, this must never be done without ensuring the QRhiCommandBuffer's state stays up-to-date. Hence the requirement for wrapping any externally added command recording between beginExternal() and endExternal(). Conceptually this is the same as QPainter's beginNativePainting() and endNativePainting() functions.

For OpenGL in particular, this function has an additional task: it makes sure the context is made current on the current thread.

See also endExternal() and nativeHandles().

void QRhiCommandBuffer::beginPass(QRhiRenderTarget *rt, const QColor &colorClearValue, const QRhiDepthStencilClearValue &depthStencilClearValue, QRhiResourceUpdateBatch *resourceUpdates = nullptr, QRhiCommandBuffer::BeginPassFlags flags = {})

Records starting a new render pass targeting the render target rt.

resourceUpdates, when not null, specifies a resource update batch that is to be committed and then released.

The color and depth/stencil buffers of the render target are normally cleared. The clear values are specified in colorClearValue and depthStencilClearValue. The exception is when the render target was created with QRhiTextureRenderTarget::PreserveColorContents and/or QRhiTextureRenderTarget::PreserveDepthStencilContents. The clear values are ignored then.

If rt is a QRhiTextureRenderTarget, beginPass() performs a check to see if the texture and renderbuffer objects referenced from the render target are up-to-date. This is similar to what setShaderResources() does for QRhiShaderResourceBindings. If any of the attachments had been rebuilt since QRhiTextureRenderTarget::create(), an implicit call to create() is made on rt. Therefore, if rt has a QRhiTexture color attachment texture, and one needs to make the texture a different size, the following is then valid:

QRhiTextureRenderTarget *rt = rhi->newTextureRenderTarget({ { texture } });
rt->create();
// ...
texture->setPixelSize(new_size);
texture->create();
cb->beginPass(rt, colorClear, dsClear); // this is ok, no explicit rt->create() is required before

flags allow controlling certain advanced functionality. One commonly used flag is ExternalContents. This should be specified whenever beginExternal() will be called within the pass started by this function.

See also endPass() and BeginPassFlags.

void QRhiCommandBuffer::debugMarkBegin(const QByteArray &name)

Records a named debug group on the command buffer with the specified name. This is shown in graphics debugging tools such as RenderDoc and XCode. The end of the grouping is indicated by debugMarkEnd().

void QRhiCommandBuffer::debugMarkEnd()

Records the end of a debug group.

void QRhiCommandBuffer::debugMarkMsg(const QByteArray &msg)

Inserts a debug message msg into the command stream.

void QRhiCommandBuffer::dispatch(int x, int y, int z)

Records dispatching compute work items, with x, y, and z specifying the number of local workgroups in the corresponding dimension.

void QRhiCommandBuffer::draw(quint32 vertexCount, quint32 instanceCount = 1, quint32 firstVertex = 0, quint32 firstInstance = 0)

Records a non-indexed draw.

The number of vertices is specified in vertexCount. For instanced drawing set instanceCount to a value other than 1. firstVertex is the index of the first vertex to draw. When drawing multiple instances, the first instance ID is specified by firstInstance.

void QRhiCommandBuffer::drawIndexed(quint32 indexCount, quint32 instanceCount = 1, quint32 firstIndex = 0, qint32 vertexOffset = 0, quint32 firstInstance = 0)

Records an indexed draw.

The number of vertices is specified in indexCount. firstIndex is the base index. The effective offset in the index buffer is given by indexOffset + firstIndex * n where n is 2 or 4 depending on the index element type. indexOffset is specified in setVertexInput().

For instanced drawing set instanceCount to a value other than 1. When drawing multiple instances, the first instance ID is specified by firstInstance.

vertexOffset (also called base vertex) is a signed value that is added to the element index before indexing into the vertex buffer. Support for this is not always available, and the value is ignored when the feature QRhi::BaseVertex is reported as unsupported.

void QRhiCommandBuffer::endComputePass(QRhiResourceUpdateBatch *resourceUpdates = nullptr)

Records ending the current compute pass.

resourceUpdates, when not null, specifies a resource update batch that is to be committed and then released.

void QRhiCommandBuffer::endExternal()

To be called once the externally added commands are recorded to the command buffer or context.

See also beginExternal() and nativeHandles().

void QRhiCommandBuffer::endPass(QRhiResourceUpdateBatch *resourceUpdates = nullptr)

Records ending the current render pass.

resourceUpdates, when not null, specifies a resource update batch that is to be committed and then released.

See also beginPass().

double QRhiCommandBuffer::lastCompletedGpuTime()

Returns the last available timestamp, in seconds, when QRhi::EnableTimestamps was enabled when creating the QRhi. The value indicates the elapsed time on the GPU during the last completed frame.

Care must be exercised with the interpretation of the value, as its precision and granularity is often not controlled by Qt, and depends on the underlying graphics API and its implementation. In particular, comparing the values between different graphics APIs and hardware is discouraged and may be meaningless.

When the frame was recorded with beginFrame() and endFrame(), i.e., with a swapchain, the timing values will likely become available asynchronously. The returned value may therefore be 0 (e.g., for the first 1-2 frames) or the last known value referring to some previous frame. The value my also become 0 again under certain conditions, such as when resizing the window. It can be expected that the most up-to-date available value is retrieved in beginFrame() and becomes queriable via this function once beginFrame() returns.

On the other hand, with offscreen frames the returned value is up-to-date once endOffscreenFrame() returns, because offscreen frames reduce GPU pipelining and wait the the commands to be complete.

Watch out for the consequences of GPU frequency scaling and GPU clock changes, depending on the platform. For example, on Windows the returned timing may vary in a quite wide range between frames with modern graphics cards, even when submitting frames with a similar, or the same workload. This is out of scope for Qt to control and solve, generally speaking. However, the D3D12 backend automatically calls ID3D12Device::SetStablePowerState() whenever the environment variable QT_D3D_STABLE_POWER_STATE is set to a non-zero value. This can greatly stabilize the result. It can also have a non-insignificant effect on the CPU-side timings measured via QElapsedTimer for example, especially when offscreen frames are involved.

See also QRhi::Timestamps and QRhi::EnableTimestamps.

const QRhiNativeHandles *QRhiCommandBuffer::nativeHandles()

Returns a pointer to a backend-specific QRhiNativeHandles subclass, such as QRhiVulkanCommandBufferNativeHandles. The returned value is nullptr when exposing the underlying native resources is not supported by, or not applicable to, the backend.

See also QRhiVulkanCommandBufferNativeHandles, QRhiMetalCommandBufferNativeHandles, beginExternal(), and endExternal().

[override virtual] QRhiResource::Type QRhiCommandBuffer::resourceType() const

Reimplements: QRhiResource::resourceType() const.

Returns the resource type.

void QRhiCommandBuffer::resourceUpdate(QRhiResourceUpdateBatch *resourceUpdates)

Sometimes committing resource updates is necessary or just more convenient without starting a render pass. Calling this function with resourceUpdates is an alternative to passing resourceUpdates to a beginPass() call (or endPass(), which would be typical in case of readbacks).

void QRhiCommandBuffer::setBlendConstants(const QColor &c)

Records setting the active blend constants to c.

This can only be called when the bound pipeline has QRhiGraphicsPipeline::UsesBlendConstants set.

void QRhiCommandBuffer::setComputePipeline(QRhiComputePipeline *ps)

Records setting a new compute pipeline ps.

void QRhiCommandBuffer::setGraphicsPipeline(QRhiGraphicsPipeline *ps)

Records setting a new graphics pipeline ps.

void QRhiCommandBuffer::setScissor(const QRhiScissor &scissor)

Records setting the active scissor rectangle specified in scissor.

This can only be called when the bound pipeline has UsesScissor set. When the flag is set on the active pipeline, this function must be called because scissor testing will get enabled and so a scissor rectangle must be provided.

void QRhiCommandBuffer::setShaderResources(QRhiShaderResourceBindings *srb = nullptr, int dynamicOffsetCount = 0, const QRhiCommandBuffer::DynamicOffset *dynamicOffsets = nullptr)

Records binding a set of shader resources, such as, uniform buffers or textures, that are made visible to one or more shader stages.

srb can be null in which case the current graphics or compute pipeline's associated QRhiShaderResourceBindings is used. When srb is non-null, it must be layout-compatible, meaning the layout (number of bindings, the type and binding number of each binding) must fully match the QRhiShaderResourceBindings that was associated with the pipeline at the time of calling the pipeline's create().

There are cases when a seemingly unnecessary setShaderResources() call is mandatory: when rebuilding a resource referenced from srb, for example changing the size of a QRhiBuffer followed by a QRhiBuffer::create(), this is the place where associated native objects (such as descriptor sets in case of Vulkan) are updated to refer to the current native resources that back the QRhiBuffer, QRhiTexture, QRhiSampler objects referenced from srb. In this case setShaderResources() must be called even if srb is the same as in the last call.

When srb is not null, the QRhiShaderResourceBindings object the pipeline was built with in create() is guaranteed to be not accessed in any form. In fact, it does not need to be valid even at this point: destroying the pipeline's associated srb after create() and instead explicitly specifying another, layout compatible one in every setShaderResources() call is valid.

dynamicOffsets allows specifying buffer offsets for uniform buffers that were associated with srb via QRhiShaderResourceBinding::uniformBufferWithDynamicOffset(). This is different from providing the offset in the srb itself: dynamic offsets do not require building a new QRhiShaderResourceBindings for every different offset, can avoid writing the underlying descriptors (with backends where applicable), and so they may be more efficient. Each element of dynamicOffsets is a binding - offset pair. dynamicOffsetCount specifies the number of elements in dynamicOffsets.

void QRhiCommandBuffer::setStencilRef(quint32 refValue)

Records setting the active stencil reference value to refValue.

This can only be called when the bound pipeline has QRhiGraphicsPipeline::UsesStencilRef set.

void QRhiCommandBuffer::setVertexInput(int startBinding, int bindingCount, const QRhiCommandBuffer::VertexInput *bindings, QRhiBuffer *indexBuf = nullptr, quint32 indexOffset = 0, QRhiCommandBuffer::IndexFormat indexFormat = IndexUInt16)

Records vertex input bindings.

The index buffer used by subsequent drawIndexed() commands is specified by indexBuf, indexOffset, and indexFormat. indexBuf can be set to null when indexed drawing is not needed.

Vertex buffer bindings are batched. startBinding specifies the first binding number. The recorded command then binds each buffer from bindings to the binding point startBinding + i where i is the index in bindings. Each element in bindings specifies a QRhiBuffer and an offset.

Superfluous vertex input and index changes in the same pass are ignored automatically with most backends and therefore applications do not need to overoptimize to avoid calls to this function.

As a simple example, take a vertex shader with two inputs:

layout(location = 0) in vec4 position;
layout(location = 1) in vec3 color;

and assume we have the data available in interleaved format, using only 2 floats for position (so 5 floats per vertex: x, y, r, g, b). A QRhiGraphicsPipeline for this shader can then be created using the input layout:

QRhiVertexInputLayout inputLayout;
inputLayout.setBindings({
    { 5 * sizeof(float) }
});
inputLayout.setAttributes({
    { 0, 0, QRhiVertexInputAttribute::Float2, 0 },
    { 0, 1, QRhiVertexInputAttribute::Float3, 2 * sizeof(float) }
});

Here there is one buffer binding (binding number 0), with two inputs referencing it. When recording the pass, once the pipeline is set, the vertex bindings can be specified simply like the following, assuming vbuf is the QRhiBuffer with all the interleaved position+color data:

const QRhiCommandBuffer::VertexInput vbufBinding(vbuf, 0);
cb->setVertexInput(0, 1, &vbufBinding);

void QRhiCommandBuffer::setViewport(const QRhiViewport &viewport)

Records setting the active viewport rectangle specified in viewport.

With backends where the underlying graphics API has scissoring always enabled, this function also sets the scissor to match the viewport whenever the active QRhiGraphicsPipeline does not have UsesScissor set.