QRhiCommandBuffer Class

成员函数文档

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

开始新计算传递的记录。

resourceUpdates，如果不为空，则指定要提交然后释放的资源更新批次。

flags 目前尚未使用。

void QRhiCommandBuffer::beginExternal()

在应用程序通过直接调用图形 API 函数将命令顺序排列到当前传递的命令缓冲区之前调用。

使用 Vulkan、Metal 或 Direct3D 12 时，可以通过nativeHandles() 查询本地命令缓冲区或编码器对象，并向它们发出命令。对于 OpenGL 或 Direct3D 11，可以通过QRhi::nativeHandles() 获取（设备）上下文。但是，在这样做时必须确保QRhiCommandBuffer 的状态保持最新。因此，需要在 beginExternal() 和endExternal() 之间封装任何外部添加的命令记录。从概念上讲，这与QPainter 的beginNativePainting() 和endNativePainting() 函数相同。

特别是对于 OpenGL，该函数还有一个额外的任务：确保上下文在当前线程上是当前的。

另请参阅 endExternal() 和nativeHandles()。

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

记录针对rt 渲染目标开始新的渲染传递。

resourceUpdates如果不为空，则指定了一个要提交然后释放的资源更新批次。

渲染目标的颜色和深度/模板缓冲区通常会被清空。清除值在colorClearValue 和depthStencilClearValue 中指定。使用QRhiTextureRenderTarget::PreserveColorContents 和/或QRhiTextureRenderTarget::PreserveDepthStencilContents 创建渲染目标时例外。此时，清除值将被忽略。

如果rt 是QRhiTextureRenderTarget ，beginPass( ) 会执行检查，查看从呈现目标引用的纹理和呈现缓冲区对象是否是最新的。这类似于setShaderResources() 对QRhiShaderResourceBindings 所做的检查。如果任何附件在QRhiTextureRenderTarget::create() 之后被重建，则会在rt 上隐式调用 create()。因此，如果rt 有一个QRhiTexture 颜色附件texture ，并且需要将纹理做成不同的大小，那么下面的方法就有效：

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 允许控制某些高级功能。一个常用的标志是 。只要在本函数启动的传递中调用 () 时，就应指定该标志。ExternalContents beginExternal

另请参阅 endPass() 和BeginPassFlags 。

void QRhiCommandBuffer::debugMarkBegin(const QByteArray &name)

用指定的name 在命令缓冲区记录一个命名的调试组。这将显示在RenderDoc和XCode 等图形调试工具中。组的结束用debugMarkEnd() 表示。

void QRhiCommandBuffer::debugMarkEnd()

记录调试组的结束。

void QRhiCommandBuffer::debugMarkMsg(const QByteArray &msg)

在命令流中插入调试信息msg 。

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

记录调度计算工作项，其中x,y, 和z 指定相应维度中本地工作组的数量。

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

记录非索引绘制。

顶点数在vertexCount 中指定。若要绘制实例，请将instanceCount 设置为 1 以外的值。firstVertex 是要绘制的第一个顶点的索引。绘制多个实例时，第一个实例 ID 由firstInstance 指定。

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

记录索引绘制。

顶点数在indexCount 中指定。firstIndex 是基本索引。索引缓冲区中的有效偏移量由indexOffset + firstIndex * n 给出，其中n 根据索引元素类型为 2 或 4。indexOffset 在setVertexInput() 中指定。

对于实例绘制，请将instanceCount 设置为 1 以外的值。绘制多个实例时，第一个实例 ID 由firstInstance 指定。

vertexOffset (也称为 ）是一个带符号的值，在索引到顶点缓冲区之前会添加到元素索引中。并不总是支持该值，当特征 被报告为不支持时，该值将被忽略。base vertex QRhi::BaseVertex

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

结束当前计算传递的记录。

resourceUpdates如果不为空，则指定要提交然后释放的资源更新批次。

void QRhiCommandBuffer::endExternal()

外部添加的命令记录到命令缓冲区或上下文后调用。

另请参阅 beginExternal() 和nativeHandles()。

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

结束当前渲染传递的记录。

resourceUpdates，如果不为空，则指定要提交然后释放的资源更新批次。

另请参见 beginPass()。

double QRhiCommandBuffer::lastCompletedGpuTime()

返回在创建QRhi 时启用QRhi::EnableTimestamps 的最后可用时间戳（以秒为单位）。该值表示在最后完成的帧中 GPU 上经过的时间。

必须谨慎解释该值，因为其精度和粒度通常不受 Qt 控制，而取决于底层图形 API 及其实现。尤其不鼓励在不同图形 API 和硬件之间比较数值，这样做可能毫无意义。

当使用beginFrame() 和endFrame() 记录帧时，即使用交换链时，时序值可能会异步可用。因此，返回的值可能是 0（例如，前 1-2 帧），或者是某个前一帧的最后已知值。在某些情况下，例如调整窗口大小时，该值可能会再次变为 0。可以预期的是，最新的可用值会在 beginFrame() 中获取，并在 beginFrame() 返回后通过该函数进行查询。

另一方面，对于离屏帧，一旦endOffscreenFrame() 返回，返回值就是最新的，因为离屏帧减少了 GPU 的流水线操作，等待命令完成。

请注意 GPU 频率缩放和 GPU 时钟变化的后果，具体取决于平台。例如，在 Windows 平台上，即使提交的帧具有相似或相同的工作负载，使用现代显卡的帧之间返回的时序可能会有相当大的差异。一般来说，这超出了 Qt 控制和解决的范围。不过，只要环境变量QT_D3D_STABLE_POWER_STATE 设置为非零值，D3D12 后端就会自动调用ID3D12Device::SetStablePowerState()。这可以极大地稳定结果。例如，它还会对通过QElapsedTimer 测得的 CPU 端时序产生非显著影响，尤其是涉及到离屏帧时。

另请参阅 QRhi::Timestamps 和QRhi::EnableTimestamps 。

const QRhiNativeHandles *QRhiCommandBuffer::nativeHandles()

返回指向特定于后端QRhiNativeHandles 子类（如QRhiVulkanCommandBufferNativeHandles ）的指针。当后端不支持或不适用底层本地资源时，返回值为nullptr 。

另请参阅 QRhiVulkanCommandBufferNativeHandles,QRhiMetalCommandBufferNativeHandles,beginExternal() 和endExternal() 。

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

重实现：QRhiResource::resourceType() 常量。

返回资源类型。

void QRhiCommandBuffer::resourceUpdate(QRhiResourceUpdateBatch *resourceUpdates)

有时，提交资源更新是必要的，或者在不启动渲染传递的情况下更方便。resourceUpdates 在调用beginPass() 或endPass() 时，可以通过resourceUpdates 调用此函数，这在回读情况下比较常见。

void QRhiCommandBuffer::setBlendConstants(const QColor &c)

将活动混合常量设置为c 的记录。

只有在绑定流水线已设置QRhiGraphicsPipeline::UsesBlendConstants 时才能调用此函数。

void QRhiCommandBuffer::setComputePipeline(QRhiComputePipeline *ps)

记录设置新计算管道ps 。

void QRhiCommandBuffer::setGraphicsPipeline(QRhiGraphicsPipeline *ps)

记录设置新图形流水线ps 。

void QRhiCommandBuffer::setScissor(const QRhiScissor &scissor)

记录设置scissor 中指定的活动剪刀矩形。

只有当绑定流水线已设置UsesScissor 时，才能调用此函数。当活动流水线上的标志被设置时，必须调用此函数，因为剪刀测试将被启用，因此必须提供一个剪刀矩形。

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

绑定一组着色器资源（如均匀缓冲区或纹理）的记录，这些资源对一个或多个着色器阶段可见。

srb 可以为空，在这种情况下，将使用当前图形或计算流水线的相关 。当 为非空时，它必须是 ，这意味着布局（绑定的数量、每个绑定的类型和绑定编号）必须与调用管道的创建（）时与管道关联的 完全匹配。QRhiShaderResourceBindings srb layout-compatible QRhiShaderResourceBindings

在某些情况下，调用 setShaderResources() 看似没有必要，但却是必须的：在重建从srb 引用的资源时，例如改变QRhiBuffer 的大小，然后是QRhiBuffer::create() 时，相关的本地对象（如 Vulkan 的描述符集）会在此处更新，以引用当前的本地资源，这些资源支持从srb 引用的QRhiBuffer 、QRhiTexture 、QRhiSampler 对象。在这种情况下，即使srb 与上次调用的相同，也必须调用 setShaderResources()。

当srb 不为空时，管道在 create() 中创建的QRhiShaderResourceBindings 对象保证不会以任何形式被访问。事实上，即使在这一点上，它也不需要是有效的：在 create() 之后销毁管道的相关 srb，并在每次 setShaderResources() 调用中明确指定另一个layout compatible 的 srb 也是有效的。

dynamicOffsets 允许为通过 () 与 关联的统一缓冲区指定缓冲区偏移量。这与在 中提供偏移量本身不同：动态偏移量不需要为每个不同的偏移量构建新的 ，可以避免写入底层描述符（如果适用，还可以写入后端），因此可能更高效。 中的每个元素都是一对 - 。 指定 中元素的数量。QRhiShaderResourceBinding::uniformBufferWithDynamicOffset srb srb QRhiShaderResourceBindings dynamicOffsets binding offset dynamicOffsetCount dynamicOffsets

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

将后续绘制调用的着色率设置为coarsePixelSize 。

默认为 1x1。

仅当报告支持QRhi::VariableRateShading 功能，且绑定在命令缓冲区上的QRhiGraphicsPipeline(s) 在创建时声明QRhiGraphicsPipeline::UsesShadingRate 时才起作用。

调用QRhi::supportedShadingRates() 检查给定采样计数支持哪些着色率。

当QRhiShadingRateMap 和此函数同时使用时，每个磁贴将使用两个着色率中较高的一个。目前无法控制组合器行为。

此函数在 Qt 6.9 中引入。

void QRhiCommandBuffer::setStencilRef(quint32 refValue)

将活动模板参考值设置为refValue 的记录。

只有在绑定流水线已设置QRhiGraphicsPipeline::UsesStencilRef 时才能调用此函数。

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

记录顶点输入绑定。

后续drawIndexed() 命令使用的索引缓冲区由indexBuf 、indexOffset 和indexFormat 指定。当不需要索引绘图时，可将indexBuf 设置为空。

顶点缓冲区绑定是分批进行的。startBinding 指定第一个绑定编号。然后，记录命令将bindings 中的每个缓冲区绑定到绑定点startBinding + i ，其中i 是bindings 中的索引。bindings 中的每个元素都指定了QRhiBuffer 和偏移量。

大多数后端都会自动忽略同一传递中多余的顶点输入和索引变化，因此应用程序无需过度优化以避免调用此函数。

举个简单的例子，顶点着色器有两个输入：

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

假设我们有交错格式的数据，位置只使用 2 个浮点（因此每个顶点有 5 个浮点：x、y、r、g、b）。然后就可以使用输入布局为该着色器创建QRhiGraphicsPipeline ：

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

这里有一个缓冲绑定（绑定编号 0），并有两个输入引用它。在记录通道时，一旦设置了流水线，就可以像下面这样简单地指定顶点绑定，假定 vbuf 是包含所有交错位置+颜色数据的QRhiBuffer ：

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

void QRhiCommandBuffer::setViewport(const QRhiViewport &viewport)

记录设置viewport 中指定的活动视口矩形。

在底层图形 API 始终启用剪刀差的后端，只要活动QRhiGraphicsPipeline 没有设置UsesScissor ，此函数也会设置剪刀差以匹配视口。