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 의 상태를 최신 상태로 유지하지 않고는 이 작업을 수행해서는 안 됩니다. 따라서 외부에서 추가된 모든 명령 기록을 startExternal()과 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.

resourceUpdatesnull이 아닌 경우 커밋한 후 해제할 리소스 업데이트 배치를 지정합니다.

렌더링 대상의 색상 및 깊이/스텐실 버퍼는 일반적으로 지워집니다. 지우기 값은 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)

현재 컴퓨팅 패스를 종료하는 레코드입니다.

resourceUpdatesnull이 아닌 경우 커밋한 후 해제할 리소스 업데이트 배치를 지정합니다.

void QRhiCommandBuffer::endExternal()

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

beginExternal() 및 nativeHandles()도 참조하세요 .

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

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

resourceUpdatesnull이 아닌 경우 커밋한 후 해제할 리소스 업데이트 배치를 지정합니다.

beginPass()도 참조하세요 .

double QRhiCommandBuffer::lastCompletedGpuTime()

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

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

beginFrame() 및 endFrame()로 프레임이 기록된 경우, 즉 스왑체인을 사용하는 경우 타이밍 값은 비동기적으로 사용할 수 있습니다. 따라서 반환된 값은 0(예: 처음 1~2프레임)이거나 이전 프레임을 참조하는 마지막 알려진 값일 수 있습니다. 창 크기를 조정할 때와 같은 특정 조건에서는 값이 다시 0이 될 수도 있습니다. 가장 최신의 사용 가능한 값은 beginFrame()에서 검색되며, beginFrame()이 반환되면 이 함수를 통해 쿼리할 수 있게 됩니다.

반면 오프스크린 프레임의 경우, 오프스크린 프레임은 GPU 파이프라이닝을 줄이고 명령이 완료될 때까지 기다리기 때문에 endOffscreenFrame()가 반환되면 반환된 값은 최신 값입니다.

플랫폼에 따라 GPU 주파수 스케일링 및 GPU 클럭 변경의 결과에 주의하세요. 예를 들어, Windows에서는 워크로드가 비슷하거나 동일한 프레임을 제출하더라도 최신 그래픽 카드를 사용하는 프레임 간에 반환되는 타이밍이 상당히 큰 범위에서 달라질 수 있습니다. 이는 일반적으로 Qt가 제어하고 해결할 수 있는 범위를 벗어납니다. 하지만 D3D12 백엔드는 환경 변수 QT_D3D_STABLE_POWER_STATE 가 0이 아닌 값으로 설정될 때마다 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() const.

리소스 타입을 리턴합니다.

void QRhiCommandBuffer::resourceUpdate(QRhiResourceUpdateBatch *resourceUpdates)

때로는 렌더 패스를 시작하지 않고 리소스 업데이트를 커밋하는 것이 필요하거나 더 편리할 때가 있습니다. resourceUpdates 으로 이 함수를 호출하는 것은 resourceUpdates 을 beginPass() 호출(또는 읽기백의 경우 일반적으로 사용되는 endPass())로 전달하는 대신 사용할 수 있습니다.

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 이 null이 아닌 경우 layout-compatible 이어야 하며, 이는 레이아웃(바인딩 수, 각 바인딩의 유형 및 바인딩 번호)이 파이프라인의 create() 호출 시 파이프라인과 연결된 QRhiShaderResourceBindings 과 완전히 일치해야 함을 의미합니다.

srb 에서 참조된 리소스를 리빌드할 때, 예를 들어 QRhiBuffer 의 크기를 변경한 후 QRhiBuffer::create()를 호출하는 경우와 같이 불필요해 보이는 setShaderResources() 호출이 필수인 경우가 있는데, 이는 srb 에서 참조된 QRhiBuffer, QRhiTexture, QRhiSampler 객체를 뒷받침하는 현재 네이티브 리소스를 참조하도록 연결된 네이티브 객체(Vulkan의 경우 설명자 세트 등)가 업데이트되는 곳입니다. 이 경우 srb 이 마지막 호출과 동일하더라도 setShaderResources()를 호출해야 합니다.

srb 가 null이 아닌 경우, create()에서 파이프라인이 빌드된 QRhiShaderResourceBindings 오브젝트는 어떤 형태로든 액세스되지 않도록 보장됩니다. 사실, 이 시점에서도 유효할 필요는 없습니다. create() 이후 파이프라인의 연관된 srb를 삭제하고 대신 모든 setShaderResources() 호출에서 명시적으로 다른 layout compatible 하나를 지정하면 유효합니다.

dynamicOffsets 를 통해 QRhiShaderResourceBinding::uniformBufferWithDynamicOffset()를 통해 srb 에 연결된 균일 버퍼에 대한 버퍼 오프셋을 지정할 수 있습니다. 이는 srb 자체에 오프셋을 제공하는 것과는 다릅니다. 동적 오프셋은 다른 오프셋마다 QRhiShaderResourceBindings 을 새로 만들 필요가 없고, 기본 디스크립터(해당하는 경우 백엔드 포함)를 작성하지 않아도 되므로 더 효율적일 수 있습니다. dynamicOffsets 의 각 요소는 binding - offset 쌍입니다. dynamicOffsetCount 은 dynamicOffsets 의 요소 수를 지정합니다.

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 이 설정되어 있지 않을 때마다 이 함수가 뷰포트와 일치하도록 가위질을 설정합니다.