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::buildIndirect(QRhiIndirectCommandBuffer *icb, const QRhiIndirectCommandBufferBuildInfo &info)

Records populating the indirect command buffer icb from the buffer and parameters described by info.

This is the GPU-driven counterpart of recording draw() or drawIndexed() calls on the QRhiIndirectCommandBuffer: the commands come from info.sourceBuffer, which is typically written by a compute shader earlier in the frame. Any commands recorded on the CPU side are ignored from this point on.

info.topology and, for an indirect command buffer of type QRhiIndirectCommandBuffer::IndexedDraws, info.indexBuffer have to be specified because some backends need them in order to build their native indirect command buffer object, and neither is available outside of a render pass. They must match what is set on the command buffer when executeIndirect() is called.

info.commandCount is the number of commands to take from info.sourceBuffer, and becomes what QRhiIndirectCommandBuffer::commandCount() reports from here on. Leaving it at 0 means icb's QRhiIndirectCommandBuffer::maxCommandCount(); a larger value is clamped to that, with a warning. The size of info.sourceBuffer is not consulted. When info.countBuffer is set, info.commandCount becomes an upper bound instead, with the device-side count deciding how many commands are executed.

See also executeIndirect() and QRhiIndirectCommandBuffer.

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.

[since 6.13] void QRhiCommandBuffer::dispatchIndirect(QRhiBuffer *indirectBuffer, quint32 indirectBufferOffset = 0)

Records an indirect compute dispatch.

The work group counts are read by the device from indirectBuffer at indirectBufferOffset, as a single QRhiDispatchIndirectCommand. indirectBuffer must have QRhiBuffer::IndirectBuffer usage and indirectBufferOffset must be 4-byte aligned.

Only one dispatch per call; no native multi-dispatch variant exists. Requires QRhi::DispatchIndirect.

This function was introduced in Qt 6.13.

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

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.

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

[since 6.12] void QRhiCommandBuffer::drawIndexedIndirect(QRhiBuffer *indirectBuffer, quint32 indirectBufferOffset, quint32 drawCount, quint32 stride = sizeof(QRhiIndexedIndirectDrawCommand))

Records an indexed, indirect draw.

The draw parameters are provided by the buffer specified in indirectBuffer, which must contain an array of elements of type QRhiIndexedIndirectDrawCommand. The parameters in QRhiIndexedIndirectDrawCommand have the same meaning as in drawIndexed().

The offset, in bytes, from which the parameters are read in the buffer is specified by indirectBufferOffset.

drawCount specifies the number of such draw commands to issue.

stride indicates the byte size of each individual draw command structure in the buffer. This allows interleaving custom data between commands if needed. The value must be a multiple of 4 and greater than or equal to sizeof(QRhiIndexedIndirectDrawCommand).

This function was introduced in Qt 6.12.

See also drawIndirect(), drawIndirectCount(), and drawIndexedIndirectCount().

[since 6.13] void QRhiCommandBuffer::drawIndexedIndirectCount(QRhiBuffer *indirectBuffer, quint32 indirectBufferOffset, QRhiBuffer *countBuffer, quint32 countBufferOffset, quint32 maxDrawCount, quint32 stride = sizeof(QRhiIndexedIndirectDrawCommand))

Indexed variant of drawIndirectCount(). indirectBuffer contains, at byte offset indirectBufferOffset, QRhiIndexedIndirectDrawCommand entries, spaced stride bytes apart, and stride must be at least sizeof(QRhiIndexedIndirectDrawCommand). All other requirements, including how countBuffer, countBufferOffset and maxDrawCount are interpreted, are as described for drawIndirectCount().

This function was introduced in Qt 6.13.

See also drawIndirect(), drawIndexedIndirect(), and drawIndirectCount().

[since 6.12] void QRhiCommandBuffer::drawIndirect(QRhiBuffer *indirectBuffer, quint32 indirectBufferOffset, quint32 drawCount, quint32 stride = sizeof(QRhiIndirectDrawCommand))

Records a non-indexed, indirect draw.

The draw parameters are provided by the buffer specified in indirectBuffer, which must contain an array of elements of type QRhiIndirectDrawCommand. The parameters in QRhiIndirectDrawCommand have the same meaning as in draw().

The offset, in bytes, from which the parameters are read in the buffer is specified by indirectBufferOffset.

drawCount specifies the number of such draw commands to issue.

stride indicates the byte size of each individual draw command structure in the buffer. This allows interleaving custom data between commands if needed. The value must be a multiple of 4 and greater than or equal to sizeof(QRhiIndirectDrawCommand).

This function was introduced in Qt 6.12.

See also drawIndexedIndirect(), drawIndirectCount(), and drawIndexedIndirectCount().

[since 6.13] void QRhiCommandBuffer::drawIndirectCount(QRhiBuffer *indirectBuffer, quint32 indirectBufferOffset, QRhiBuffer *countBuffer, quint32 countBufferOffset, quint32 maxDrawCount, quint32 stride = sizeof(QRhiIndirectDrawCommand))

Records a non-indexed, indirect draw, with the draw count itself read from a buffer at execution time.

Draw parameters are read from indirectBuffer at byte offset indirectBufferOffset as an array of QRhiIndirectDrawCommand entries spaced stride bytes apart. The number of draws issued is the 32-bit unsigned integer stored at countBufferOffset in countBuffer, clamped to maxDrawCount.

Both buffers must have QRhiBuffer::IndirectBuffer usage. Offsets must be 4-byte aligned; stride must be 4-byte aligned and at least sizeof(QRhiIndirectDrawCommand).

Only available when QRhi::DrawIndirectCount is reported as supported. On other backends this is a no-op and a warning is logged. With Metal there are additional requirements, see QRhi::DrawIndirectCount.

This function was introduced in Qt 6.13.

See also drawIndirect(), drawIndexedIndirect(), and drawIndexedIndirectCount().

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

void QRhiCommandBuffer::executeIndirect(QRhiIndirectCommandBuffer *icb, quint32 firstCommand = 0, quint32 commandCount = 0xFFFFFFFFu)

Records executing the commands held by the indirect command buffer icb, starting at firstCommand and executing at most commandCount of them. By default all commands are executed.

Everything else - the graphics pipeline, the vertex and index buffers, the shader resources, the viewport, the scissor - is taken from the current state of the command buffer, exactly like with drawIndirect().

The number of draws issued is qMin(commandCount, icb->commandCount() - firstCommand), so leaving commandCount at its default executes everything from firstCommand onwards. What QRhiIndirectCommandBuffer::commandCount() means depends on how icb was populated: it is the number of draw() and drawIndexed() calls recorded on it, or, after a buildIndirect(), the count resolved from QRhiIndirectCommandBufferBuildInfo::commandCount. Nothing is drawn when firstCommand is at or past that count.

When icb was populated by recording draw() or drawIndexed() calls on it, the recorded contents must have been flushed with QRhiResourceUpdateBatch::commitIndirectCommandBuffer() beforehand. When it was populated with buildIndirect(), and a count buffer was specified there, the device-side count reduces the number of draws further: the number actually executed is the smallest of that, commandCount, and what is left in icb after firstCommand.

See also buildIndirect(), drawIndirect(), and QRhiIndirectCommandBuffer.

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.

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.

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.

Setting a graphics pipeline that does not have the UsesScissor flag will either disable scissoring, with graphics APIs where that is applicable, or set the scissor rectangle to match the viewport that was last set (with graphics APIs where scissoring is effectively always active), in order to ensure a uniform behavior across QRhi backends.

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.

[since 6.9] void QRhiCommandBuffer::setShadingRate(const QSize &coarsePixelSize)

Sets the shading rate for the following draw calls to coarsePixelSize.

The default is 1x1.

Functional only when the QRhi::VariableRateShading feature is reported as supported and the QRhiGraphicsPipeline(s) bound on the command buffer were declaring QRhiGraphicsPipeline::UsesShadingRate when creating them.

Call QRhi::supportedShadingRates() to check what shading rates are supported for a given sample count.

When both a QRhiShadingRateMap and this function are in use, the higher of the two shading rates is used for each tile. There is currently no control offered over the combiner behavior.

This function was introduced in Qt 6.9.

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.