PySide6.QtGui.QRhiCommandBuffer

class QRhiCommandBuffer

Command buffer resource.

Details

Not creatable by applications at the moment. The only ways to obtain a valid QRhiCommandBuffer are to get it from the targeted swapchain via currentFrameCommandBuffer() , or, in case of rendering completely offscreen, initializing one via beginOffscreenFrame() .

Note

This is a RHI API with limited compatibility guarantees, see QRhi for details.

Inheritance diagram of PySide6.QtGui.QRhiCommandBuffer

Added in version 6.6.

Synopsis

Methods

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

class IndexFormat

Specifies the index data type

Constant

Description

QRhiCommandBuffer.IndexFormat.IndexUInt16

Unsigned 16-bit (quint16)

QRhiCommandBuffer.IndexFormat.IndexUInt32

Unsigned 32-bit (quint32)
class BeginPassFlag

(inherits enum.Flag) Flag values for QRhi::beginPass()

Constant

Description

QRhiCommandBuffer.BeginPassFlag.ExternalContent

Specifies that there will be a call to beginExternal() in this pass. Some backends, Vulkan in particular, will fail if this flag is not set and beginExternal() is still called.

QRhiCommandBuffer.BeginPassFlag.DoNotTrackResourcesForCompute

Specifies that there is no need to track resources used in this pass if the only purpose of such tracking is to generate barriers for compute. Implies that there are no compute passes in the frame. This is an optimization hint that may be taken into account by certain backends, OpenGL in particular, allowing them to skip certain operations. When this flag is set for a render pass in a frame, calling beginComputePass() in that frame may lead to unexpected behavior, depending on the resource dependencies between the render and compute passes.
beginComputePass([resourceUpdates=None[, flags={}]])
Parameters:

Records starting a new compute pass.

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

Note

Do not assume that any state or resource bindings persist between passes.

Note

A compute pass can record setComputePipeline() , setShaderResources() , and dispatch() calls, not graphics ones. General functionality, such as, debug markers and beginExternal() is available both in render and compute passes.

Note

Compute is only available when the Compute feature is reported as supported.

flags is not currently used.

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.

Note

This is only available when the intent was declared upfront in beginPass() or beginComputePass() . Therefore this function must only be called when the pass recording was started with specifying ExternalContent .

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

Note

Once beginExternal() is called, no other render pass specific functions (set* or draw*) must be called on the QRhiCommandBuffer until endExternal() .

Warning

Some backends may return a native command buffer object from nativeHandles() that is different from the primary one when inside a beginExternal() - endExternal() block. Therefore it is important to (re)query the native command buffer object after calling beginExternal(). In practical terms this means that with Vulkan for example the externally recorded Vulkan commands are placed onto a secondary command buffer (with VK_COMMAND_BUFFER_USAGE_RENDER_PASS_CONTINUE_BIT). nativeHandles() returns this secondary command buffer when called between begin/ endExternal .

See also

endExternal() nativeHandles()

beginPass(rt, colorClearValue, depthStencilClearValue[, resourceUpdates=None[, flags={}]])
Parameters:

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 PreserveColorContents and/or PreserveDepthStencilContents . The clear values are ignored then.

Note

Enabling preserved color or depth contents leads to decreased performance depending on the underlying hardware. Mobile GPUs with tiled architecture benefit from not having to reload the previous contents into the tile buffer. Similarly, a QRhiTextureRenderTarget with a QRhiTexture as the depth buffer is less efficient than a QRhiRenderBuffer since using a depth texture triggers requiring writing the data out to it, while with renderbuffers this is not needed (as the API does not allow sampling or reading from a renderbuffer).

Note

Do not assume that any state or resource bindings persist between passes.

Note

The QRhiCommandBuffer ‘s set and draw functions can only be called inside a pass. Also, with the exception of setGraphicsPipeline() , they expect to have a pipeline set already on the command buffer. Unspecified issues may arise otherwise, depending on the backend.

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

debugMarkBegin(name)
Parameters:

name – QByteArray

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

Note

Ignored when DebugMarkers are not supported or EnableDebugMarkers is not set.

Note

Can be called anywhere within the frame, both inside and outside of passes.

debugMarkEnd()

Records the end of a debug group.

Note

Ignored when DebugMarkers are not supported or EnableDebugMarkers is not set.

Note

Can be called anywhere within the frame, both inside and outside of passes.

debugMarkMsg(msg)
Parameters:

msg – QByteArray

Inserts a debug message msg into the command stream.

Note

Ignored when DebugMarkers are not supported or EnableDebugMarkers is not set.

Note

With some backends debugMarkMsg() is only supported inside a pass and is ignored when called outside a pass. With others it is recorded anywhere within the frame.

dispatch(x, y, z)
Parameters:

  • x – int

  • y – int

  • z – int

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

Note

This function can only be called inside a compute pass, meaning between a beginComputePass() and endComputePass() call.

Note

x, y, and z must fit the limits from the underlying graphics API implementation at run time. The maximum values are typically 65535.

Note

Watch out for possible limits on the local workgroup size as well. This is specified in the shader, for example: layout(local_size_x = 16, local_size_y = 16) in;. For example, with OpenGL the minimum value mandated by the specification for the number of invocations in a single local work group (the product of local_size_x, local_size_y, and local_size_z) is 1024, while with OpenGL ES (3.1) the value may be as low as 128. This means that the example given above may be rejected by some OpenGL ES implementations as the number of invocations is 256.

draw(vertexCount[, instanceCount=1[, firstVertex=0[, firstInstance=0]]])
Parameters:

  • vertexCount – int

  • instanceCount – int

  • firstVertex – int

  • firstInstance – int

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.

Note

firstInstance may not be supported, and is ignored when the BaseInstance feature is reported as not supported. The first instance ID is always 0 in that case. BaseInstance is never supported with OpenGL at the moment, mainly due to OpenGL ES limitations, and therefore portable applications should not be designed to rely on this argument.

Note

Shaders that need to access the index of the current vertex or instance must use gl_VertexIndex and gl_InstanceIndex, i.e., the Vulkan-compatible built-in variables, instead of gl_VertexID and gl_InstanceID.

Note

This function can only be called inside a render pass, meaning between a beginPass() and endPass() call.

drawIndexed(indexCount[, instanceCount=1[, firstIndex=0[, vertexOffset=0[, firstInstance=0]]]])
Parameters:

  • indexCount – int

  • instanceCount – int

  • firstIndex – int

  • vertexOffset – int

  • firstInstance – int

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

Note

The effective offset in the index buffer must be 4 byte aligned with some backends (for example, Metal). With these backends the NonFourAlignedEffectiveIndexBufferOffset feature will be reported as not-supported.

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

Note

firstInstance may not be supported, and is ignored when the BaseInstance feature is reported as not supported. The first instance ID is always 0 in that case. BaseInstance is never supported with OpenGL at the moment, mainly due to OpenGL ES limitations, and therefore portable applications should not be designed to rely on this argument.

Note

Shaders that need to access the index of the current vertex or instance must use gl_VertexIndex and gl_InstanceIndex, i.e., the Vulkan-compatible built-in variables, instead of gl_VertexID and gl_InstanceID.

Note

This function can only be called inside a render pass, meaning between a beginPass() and endPass() call.

endComputePass([resourceUpdates=None])
Parameters:

resourceUpdates – QRhiResourceUpdateBatch

Records ending the current compute pass.

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

endExternal()

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

Note

All QRhiCommandBuffer state must be assumed as invalid after calling this function. Pipelines, vertex and index buffers, and other state must be set again if more draw calls are recorded after the external commands.

See also

beginExternal() nativeHandles()

endPass([resourceUpdates=None])
Parameters:

resourceUpdates – QRhiResourceUpdateBatch

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

lastCompletedGpuTime()
Return type:

float

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

Note

Do not expect results other than 0 when the Timestamps feature is not reported as supported, or when EnableTimestamps was not passed to create() . There are exceptions to this, because with some graphics APIs (Metal) timings are available without having to perform extra operations (timestamp queries), but portable applications should always consciously opt-in to timestamp collection when they know it is needed, and call this function accordingly.

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.

Note

Do not assume that the value refers to the previous (currently_recorded - 1) frame. It may refer to currently_recorded - 2 or currently_recorded - 3 as well. The exact behavior may depend on the graphics API and its implementation.

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.

Note

This means that, unlike with swapchain frames, with offscreen frames the returned value is guaranteed to refer to the frame that has just been submitted and completed. (assuming this function is called after endOffscreenFrame() but before the next beginOffscreenFrame())

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.

Note

Do not and never ship applications to production with QT_D3D_STABLE_POWER_STATE set. See the Windows API documentation for details.

See also

Timestamps EnableTimestamps

nativeHandles()
Return type:

QRhiNativeHandles

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

See also

QRhiVulkanCommandBufferNativeHandles QRhiMetalCommandBufferNativeHandles beginExternal() endExternal()

resourceUpdate(resourceUpdates)
Parameters:

resourceUpdates – QRhiResourceUpdateBatch

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

Note

Cannot be called inside a pass.

setBlendConstants(c)
Parameters:

c – QColor

Records setting the active blend constants to c.

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

Note

This function can only be called inside a render pass, meaning between a beginPass() and endPass() call.

setComputePipeline(ps)
Parameters:

ps – QRhiComputePipeline

Records setting a new compute pipeline ps.

Note

This function must be called before recording setShaderResources() or dispatch() commands on the command buffer.

Note

QRhi will optimize out unnecessary invocations within a pass, so therefore overoptimizing to avoid calls to this function is not necessary on the applications’ side.

Note

This function can only be called inside a compute pass, meaning between a beginComputePass() and endComputePass() call.

setGraphicsPipeline(ps)
Parameters:

ps – QRhiGraphicsPipeline

Records setting a new graphics pipeline ps.

Note

This function must be called before recording other set or draw commands on the command buffer.

Note

QRhi will optimize out unnecessary invocations within a pass, so therefore overoptimizing to avoid calls to this function is not necessary on the applications’ side.

Note

This function can only be called inside a render pass, meaning between a beginPass() and endPass() call.

Note

The new graphics pipeline ps must be a valid pointer.

setScissor(scissor)
Parameters:

scissor – QRhiScissor

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.

Note

QRhi assumes OpenGL-style viewport coordinates, meaning x and y are bottom-left.

Note

This function can only be called inside a render pass, meaning between a beginPass() and endPass() call.

setShaderResources([srb=None[, dynamicOffsetCount=0[, dynamicOffsets=None]]])
Parameters:

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

Note

All offsets in dynamicOffsets must be byte aligned to the value returned from ubufAlignment() .

Note

Some backends may limit the number of supported dynamic offsets. Avoid using a dynamicOffsetCount larger than 8.

Note

QRhi will optimize out unnecessary invocations within a pass (taking the conditions described above into account), so therefore overoptimizing to avoid calls to this function is not necessary on the applications’ side.

Note

This function can only be called inside a render or compute pass, meaning between a beginPass() and endPass() , or beginComputePass() and endComputePass() .

setShadingRate(coarsePixelSize)
Parameters:

coarsePixelSize – QSize

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

The default is 1x1.

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

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

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

setStencilRef(refValue)
Parameters:

refValue – int

Records setting the active stencil reference value to refValue.

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

Note

This function can only be called inside a render pass, meaning between a beginPass() and endPass() call.

setVertexInput(startBinding, bindings[, indexBuf=None[, indexOffset=0[, indexFormat=QRhiCommandBuffer.IndexUInt16]]])
Parameters:

  • startBinding – int

  • bindings – .list of std.pairQRhiBuffer,quint32

  • indexBuf – QRhiBuffer

  • indexOffset – int

  • indexFormat – IndexFormat

setViewport(viewport)
Parameters:

viewport – QRhiViewport

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.

Note

QRhi assumes OpenGL-style viewport coordinates, meaning x and y are bottom-left.

Note

This function can only be called inside a render pass, meaning between a beginPass() and endPass() call.