QRhiCommandBuffer Class

멤버 함수 설명서

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

새로운 연산 패스를 시작하는 레코드입니다.

resourceUpdates, null이 아닐 경우, 커밋된 후 해제될 리소스 업데이트 배치를 지정합니다.

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, null이 아닐 경우, 커밋된 후 해제될 리소스 업데이트 배치를 지정합니다.

렌더 타겟의 색상 및 깊이/스텐실 버퍼는 일반적으로 지워집니다. 지우기 값은 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()`에서 지정됩니다.

vertexOffset ( base vertex 라고도 함)은 버텍스 버퍼에 인덱싱하기 전에 요소 인덱스에 더해지는 부호 있는 값입니다. 이 기능에 대한 지원이 항상 제공되는 것은 아니며, QRhi::BaseVertex 기능이 지원되지 않는 것으로 보고될 경우 이 값은 무시됩니다.

인스턴스 드로잉의 경우 instanceCount 을 1 이외의 값으로 설정하십시오. 여러 인스턴스를 그릴 때 첫 번째 인스턴스 ID는 firstInstance 으로 지정됩니다.

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

인덱스가 지정된 간접 드로우를 기록합니다.

드로우 매개변수는 ` indirectBuffer`에 지정된 버퍼에서 제공되며, 이 버퍼에는 ` QRhiIndexedIndirectDrawCommand` 유형의 요소로 구성된 배열이 포함되어야 합니다. ` QRhiIndexedIndirectDrawCommand `의 매개변수는 ` drawIndexed()`의 매개변수와 동일한 의미를 가집니다.

버퍼에서 매개변수를 읽기 시작하는 오프셋(바이트 단위)은 indirectBufferOffset 에 의해 지정됩니다.

drawCount 발행할 해당 그리기 명령의 수를 지정합니다.

stride 버퍼 내 각 개별 드로잉 명령 구조체의 바이트 크기를 나타냅니다. 이를 통해 필요한 경우 명령들 사이에 사용자 정의 데이터를 삽입할 수 있습니다. 이 값은 4의 배수여야 하며 sizeof(QRhiIndexedIndirectDrawCommand) 이상이어야 합니다.

이 함수는 Qt 6.12에서 도입되었습니다.

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

인덱스가 지정되지 않은 간접 드로우를 기록합니다.

드로우 매개변수는 indirectBuffer 에 지정된 버퍼에서 제공되며, 이 버퍼는 QRhiIndirectDrawCommand 유형의 요소로 구성된 배열을 포함해야 합니다. QRhiIndirectDrawCommand 의 매개변수는 draw()에서와 동일한 의미를 가집니다.

버퍼에서 매개변수를 읽기 시작하는 오프셋(바이트 단위)은 indirectBufferOffset 에 의해 지정됩니다.

drawCount 발행할 해당 그리기 명령의 수를 지정합니다.

stride 버퍼 내 각 개별 그리기 명령 구조체의 바이트 크기를 나타냅니다. 이를 통해 필요한 경우 명령어 사이에 사용자 정의 데이터를 삽입할 수 있습니다. 이 값은 4의 배수여야 하며, sizeof(QRhiIndirectDrawCommand) 이상이어야 합니다.

이 함수는 Qt 6.12에서 도입되었습니다.

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

현재 계산 패스를 종료하는 레코드입니다.

resourceUpdates, null이 아닐 경우, 커밋된 후 해제될 리소스 업데이트 배치를 지정합니다.

void QRhiCommandBuffer::endExternal()

외부에서 추가된 명령이 명령 버퍼나 컨텍스트에 기록되면 호출됩니다.

beginExternal() 및 nativeHandles()도 참조하십시오 .

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

현재 렌더링 패스를 종료하는 레코드입니다.

resourceUpdates, null이 아닐 경우, 커밋된 후 해제될 리소스 업데이트 배치를 지정합니다.

beginPass()도 참조하십시오 .

double QRhiCommandBuffer::lastCompletedGpuTime()

QRhi 를 생성할 때 ‘ QRhi::EnableTimestamps ’ 기능이 활성화된 상태에서 사용 가능한 가장 최근의 타임스탬프를 초 단위로 반환합니다. 이 값은 마지막으로 완료된 프레임 동안 GPU에서 경과한 시간을 나타냅니다.

값의 해석에는 주의를 기울여야 합니다. 그 정밀도와 세분성은 종종 Qt에 의해 제어되지 않으며, 기본 그래픽 API와 그 구현에 따라 달라지기 때문입니다. 특히, 서로 다른 그래픽 API와 하드웨어 간의 값을 비교하는 것은 권장되지 않으며, 의미가 없을 수도 있습니다.

타이밍 값은 비동기적으로 제공될 가능성이 높습니다. 따라서 반환된 값은 0(예: 처음 1~2 프레임)이거나, 이전 프레임을 참조하는 마지막으로 알려진 값일 수 있습니다. 또한 창 크기 조정과 같은 특정 조건에서는 값이 다시 0이 될 수도 있습니다. beginFrame()에서 가장 최신의 사용 가능한 값이 가져와지며, beginFrame()이 반환되면 이 함수를 통해 해당 값을 조회할 수 있게 될 것으로 예상됩니다.

플랫폼에 따라 GPU 주파수 스케일링 및 GPU 클럭 변경으로 인한 결과를 주의 깊게 살펴보아야 합니다. 예를 들어, Windows 환경에서 최신 그래픽 카드를 사용하는 경우, 유사하거나 동일한 워크로드로 프레임을 제출하더라도 프레임 간 반환되는 타이밍이 상당히 넓은 범위에서 변동할 수 있습니다. 일반적으로 말해서, 이는 Qt가 제어하거나 해결할 수 있는 범위를 벗어납니다. 그러나 D3D12 백엔드는 환경 변수 ` QT_D3D_STABLE_POWER_STATE `가 0이 아닌 값으로 설정될 때마다 자동으로 ` ID3D12Device::SetStablePowerState()`를 호출합니다. 이를 통해 결과를 상당히 안정화할 수 있습니다. 또한, 특히 오프스크린 프레임이 포함된 경우, 예를 들어 ` QElapsedTimer `을 통해 측정된 CPU 측 타이밍에 무시할 수 없는 영향을 미칠 수도 있습니다.

QRhi::Timestamps 및 QRhi::EnableTimestamps항목도 참조하십시오 .

const QRhiNativeHandles *QRhiCommandBuffer::nativeHandles()

QRhiVulkanCommandBufferNativeHandles 과 같은 백엔드별 QRhiNativeHandles 하위 클래스에 대한 포인터를 반환합니다. 백엔드에서 기본 네이티브 리소스의 노출을 지원하지 않거나 해당 리소스가 적용되지 않는 경우, 반환 값은 nullptr 입니다.

QRhiVulkanCommandBufferNativeHandles, QRhiMetalCommandBufferNativeHandles, beginExternal(), endExternal()도 참조하십시오 .

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

QRhiResource::resourceType() const를 재구현합니다.

리소스 유형을 반환합니다.

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.

UsesScissor 플래그가 없는 그래픽 파이프라인을 설정하면, 해당 기능이 적용되는 그래픽 API의 경우 시저링이 비활성화되거나, QRhi 백엔드 전반에 걸쳐 일관된 동작을 보장하기 위해 (시저링이 사실상 항상 활성화된 그래픽 API의 경우) 시저링 사각형이 마지막으로 설정된 뷰포트에 맞춰집니다.

void QRhiCommandBuffer::setScissor(const QRhiScissor &scissor)

scissor 에 지정된 활성 가위 사각형을 설정하는 레코드입니다.

이 함수는 바인딩된 파이프라인에 UsesScissor 가 설정된 경우에만 호출할 수 있습니다. 활성 파이프라인에서 이 플래그가 설정되면, 시저 테스트가 활성화되므로 시저 사각형을 반드시 제공해야 하므로 이 함수를 호출해야 합니다.

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

하나 이상의 셰이더 단계에서 사용할 수 있도록 설정된, 유니폼 버퍼나 텍스처와 같은 셰이더 리소스 집합을 묶어주는 레코드입니다.

srb null일 수 있으며, 이 경우 현재 그래픽 또는 컴퓨트 파이프라인과 연관된 ` QRhiShaderResourceBindings `가 사용됩니다. ` srb `가 null이 아닐 경우, 반드시 ` layout-compatible`이어야 합니다. 즉, 레이아웃(바인딩 수, 각 바인딩의 유형 및 바인딩 번호)은 파이프라인의 `create()`를 호출할 당시 파이프라인에 연관되어 있던 ` QRhiShaderResourceBindings `와 완전히 일치해야 합니다.

겉보기에는 불필요해 보이는 setShaderResources() 호출이 필수적인 경우가 있습니다. srb 에서 참조되는 리소스를 재구축할 때, 예를 들어 QRhiBuffer 의 크기를 변경한 후 QRhiBuffer::create()를 호출하는 경우입니다. 이 시점에서 연관된 네이티브 객체(Vulkan의 경우 디스크립터 세트 등)가 업데이트되어, srb 에서 참조되는 QRhiBuffer, QRhiTexture, QRhiSampler 객체를 뒷받침하는 현재의 네이티브 리소스를 가리키게 됩니다. 이 경우 srb 가 마지막 호출 시와 동일하더라도 setShaderResources()를 반드시 호출해야 합니다.

srb 가 null이 아닐 경우, 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 가 생성될 때 ' 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 를 null로 설정할 수 있습니다.

버텍스 버퍼 바인딩은 일괄 처리됩니다. 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 가 설정되어 있지 않을 때마다 뷰포트에 맞춰 시저를 설정합니다.