Command buffer resource. 更多...
| 头： | #include <QRhiCommandBuffer> |
| CMake: |
find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Since: | Qt 6.6 |
| 继承： | QRhiResource |
| enum | BeginPassFlag { ExternalContent, DoNotTrackResourcesForCompute } |
| flags | BeginPassFlags |
| DynamicOffset | |
| enum | IndexFormat { IndexUInt16, IndexUInt32 } |
| VertexInput |
| void | beginComputePass (QRhiResourceUpdateBatch * resourceUpdates = nullptr, QRhiCommandBuffer::BeginPassFlags flags = {}) |
| void | beginExternal () |
| void | beginPass (QRhiRenderTarget * rt , const QColor & colorClearValue , const QRhiDepthStencilClearValue & depthStencilClearValue , QRhiResourceUpdateBatch * resourceUpdates = nullptr, QRhiCommandBuffer::BeginPassFlags flags = {}) |
| void | debugMarkBegin (const QByteArray & name ) |
| void | debugMarkEnd () |
| void | debugMarkMsg (const QByteArray & msg ) |
| void | dispatch (int x , int y , int z ) |
| void | draw (quint32 vertexCount , quint32 instanceCount = 1, quint32 firstVertex = 0, quint32 firstInstance = 0) |
| void | drawIndexed (quint32 indexCount , quint32 instanceCount = 1, quint32 firstIndex = 0, qint32 vertexOffset = 0, quint32 firstInstance = 0) |
| void | endComputePass (QRhiResourceUpdateBatch * resourceUpdates = nullptr) |
| void | endExternal () |
| void | endPass (QRhiResourceUpdateBatch * resourceUpdates = nullptr) |
| double | lastCompletedGpuTime () |
| const QRhiNativeHandles * | nativeHandles () |
| void | resourceUpdate (QRhiResourceUpdateBatch * resourceUpdates ) |
| void | setBlendConstants (const QColor & c ) |
| void | setComputePipeline (QRhiComputePipeline * ps ) |
| void | setGraphicsPipeline (QRhiGraphicsPipeline * ps ) |
| void | setScissor (const QRhiScissor & scissor ) |
| void | setShaderResources (QRhiShaderResourceBindings * srb = nullptr, int dynamicOffsetCount = 0, const QRhiCommandBuffer::DynamicOffset * dynamicOffsets = nullptr) |
| void | setStencilRef (quint32 refValue ) |
| void | setVertexInput (int startBinding , int bindingCount , const QRhiCommandBuffer::VertexInput * bindings , QRhiBuffer * indexBuf = nullptr, quint32 indexOffset = 0, QRhiCommandBuffer::IndexFormat indexFormat = IndexUInt16) |
| void | setViewport (const QRhiViewport & viewport ) |
| virtual QRhiResource::Type | resourceType () const override |
Not creatable by applications at the moment. The only ways to obtain a valid QRhiCommandBuffer are to get it from the targeted swapchain via QRhiSwapChain::currentFrameCommandBuffer (), or, in case of rendering completely offscreen, initializing one via QRhi::beginOffscreenFrame ().
注意： This is a RHI API with limited compatibility guarantees, see QRhi 了解细节。
Flag values for QRhi::beginPass()
| 常量 | 值 | 描述 |
|---|---|---|
QRhiCommandBuffer::ExternalContent
|
0x01
|
Specifies that there will be a call to QRhiCommandBuffer::beginExternal () in this pass. Some backends, Vulkan in particular, will fail if this flag is not set and beginExternal () is still called. |
QRhiCommandBuffer::DoNotTrackResourcesForCompute
|
0x02
|
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. |
The BeginPassFlags type is a typedef for QFlags <BeginPassFlag>. It stores an OR combination of BeginPassFlag values.
[alias]
QRhiCommandBuffer::
DynamicOffset
同义词 QPair <int, quint32>. The first entry is the binding, the second is the offset in the buffer.
Specifies the index data type
| 常量 | 值 | 描述 |
|---|---|---|
QRhiCommandBuffer::IndexUInt16
|
0
|
Unsigned 16-bit (quint16) |
QRhiCommandBuffer::IndexUInt32
|
1
|
Unsigned 32-bit (quint32) |
[alias]
QRhiCommandBuffer::
VertexInput
同义词 QPair < QRhiBuffer *, quint32>. The second entry is an offset in the buffer specified by the first.
Records starting a new compute pass.
resourceUpdates , when not null, specifies a resource update batch that is to be committed and then released.
注意： Do not assume that any state or resource bindings persist between passes.
注意： A compute pass can record setComputePipeline (), setShaderResources ()，和 dispatch () calls, not graphics ones. General functionality, such as, debug markers and beginExternal () is available both in render and compute passes.
注意： Compute is only available when the Compute feature is reported as supported.
flags is not currently used.
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.
注意： This is only available when the intent was declared upfront in beginPass () 或 beginComputePass (). Therefore this function must only be called when the pass recording was started with specifying QRhiCommandBuffer::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 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 () 和 endNativePainting () 函数。
For OpenGL in particular, this function has an additional task: it makes sure the context is made current on the current thread.
注意：
Once beginExternal() is called, no other render pass specific functions (
set*
or
draw*
) must be called on the
QRhiCommandBuffer
直到
endExternal
().
警告： Some backends may return a native command buffer object from QRhiCommandBuffer::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 .
另请参阅 endExternal () 和 nativeHandles ().
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.
注意： 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 采用 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).
注意： Do not assume that any state or resource bindings persist between passes.
注意：
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.
若
rt
是
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
拥有
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.
另请参阅 endPass () 和 BeginPassFlags .
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 ().
注意： Ignored when QRhi::DebugMarkers are not supported or QRhi::EnableDebugMarkers is not set.
注意： Can be called anywhere within the frame, both inside and outside of passes.
Records the end of a debug group.
注意： Ignored when QRhi::DebugMarkers are not supported or QRhi::EnableDebugMarkers is not set.
注意： Can be called anywhere within the frame, both inside and outside of passes.
Inserts a debug message msg into the command stream.
注意： Ignored when QRhi::DebugMarkers are not supported or QRhi::EnableDebugMarkers is not set.
注意： 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.
Records dispatching compute work items, with x , y ，和 z specifying the number of local workgroups in the corresponding dimension.
注意： This function can only be called inside a compute pass, meaning between a beginComputePass () 和 endComputePass () 调用。
注意： x , y ，和 z must fit the limits from the underlying graphics API implementation at run time. The maximum values are typically 65535.
注意：
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
，和
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.
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 .
注意： firstInstance may not be supported, and is ignored when the QRhi::BaseInstance feature is reported as not supported. The first ID is always 0 in that case.
注意： This function can only be called inside a render pass, meaning between a beginPass () 和 endPass () 调用。
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
指定在
setVertexInput
().
注意： 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.
For instanced drawing set instanceCount to a value other than 1. When drawing multiple instances, the first instance ID is specified by firstInstance .
注意： firstInstance may not be supported, and is ignored when the QRhi::BaseInstance feature is reported as not supported. The first ID is always 0 in that case.
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.
注意： This function can only be called inside a render pass, meaning between a beginPass () 和 endPass () 调用。
Records ending the current compute pass.
resourceUpdates , when not null, specifies a resource update batch that is to be committed and then released.
To be called once the externally added commands are recorded to the command buffer or context.
注意： 所有 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.
另请参阅 beginExternal () 和 nativeHandles ().
Records ending the current render pass.
resourceUpdates , when not null, specifies a resource update batch that is to be committed and then released.
另请参阅 beginPass ().
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.
注意： Do not expect results other than 0 when the QRhi::Timestamps feature is not reported as supported, or when QRhi::EnableTimestamps was not passed to QRhi::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 () 和 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.
注意：
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.
注意： 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.
注意：
Do not and never ship applications to production with
QT_D3D_STABLE_POWER_STATE
set. See the Windows API documentation for details.
另请参阅 QRhi::Timestamps and QRhi::EnableTimestamps .
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.
另请参阅 QRhiVulkanCommandBufferNativeHandles , QRhiMetalCommandBufferNativeHandles , beginExternal ()，和 endExternal ().
[override virtual]
QRhiResource::Type
QRhiCommandBuffer::
resourceType
() const
重实现： QRhiResource::resourceType() const .
Returns the resource type.
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 到 beginPass () call (or endPass (), which would be typical in case of readbacks).
注意： Cannot be called inside a pass.
Records setting the active blend constants to c .
This can only be called when the bound pipeline has QRhiGraphicsPipeline::UsesBlendConstants set.
注意： This function can only be called inside a render pass, meaning between a beginPass () 和 endPass () 调用。
Records setting a new compute pipeline ps .
注意： This function must be called before recording setShaderResources () 或 dispatch () commands on the command buffer.
注意： 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.
注意： This function can only be called inside a compute pass, meaning between a beginComputePass () 和 endComputePass () 调用。
Records setting a new graphics pipeline ps .
注意：
This function must be called before recording other
set
or
draw
commands on the command buffer.
注意： 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.
注意： This function can only be called inside a render pass, meaning between a beginPass () 和 endPass () 调用。
注意： The new graphics pipeline ps must be a valid pointer.
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.
注意： QRhi assumes OpenGL-style viewport coordinates, meaning x and y are bottom-left.
注意： This function can only be called inside a render pass, meaning between a beginPass () 和 endPass () 调用。
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.
当 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
凭借
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
是
binding
-
offset
pair.
dynamicOffsetCount
specifies the number of elements in
dynamicOffsets
.
注意： All offsets in dynamicOffsets must be byte aligned to the value returned from QRhi::ubufAlignment ().
注意： Some backends may limit the number of supported dynamic offsets. Avoid using a dynamicOffsetCount larger than 8.
注意： 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.
注意： This function can only be called inside a render or compute pass, meaning between a beginPass () 和 endPass ()，或 beginComputePass () 和 endComputePass ().
Records setting the active stencil reference value to refValue .
This can only be called when the bound pipeline has QRhiGraphicsPipeline::UsesStencilRef set.
注意： This function can only be called inside a render pass, meaning between a beginPass () 和 endPass () 调用。
Records vertex input bindings.
The index buffer used by subsequent drawIndexed () commands is specified by indexBuf , indexOffset ，和 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.
注意： Some backends may limit the number of vertex buffer bindings. Avoid using a bindingCount larger than 8.
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.
注意： This function can only be called inside a render pass, meaning between a beginPass () 和 endPass () 调用。
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);
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 没有 UsesScissor set.
注意： QRhi assumes OpenGL-style viewport coordinates, meaning x and y are bottom-left.
注意： This function can only be called inside a render pass, meaning between a beginPass () 和 endPass () 调用。