QRhi Class

멤버 함수 문서

[noexcept] QRhi::~QRhi()

디스트럭터. 백엔드를 파괴하고 리소스를 해제합니다.

void QRhi::addCleanupCallback(const QRhi::CleanupCallback &callback)

QRhi 이 소멸되거나 runCleanup()가 호출될 때 호출되는 callback 을 등록합니다.

콜백은 그래픽 리소스를 계속 사용할 수 있는 상태에서 실행되므로 애플리케이션이 QRhi 에 속한 QRhiResource 인스턴스를 깨끗하게 해제할 수 있습니다. 이는 캐시가 QRhiResources 또는 QRhiResources를 포함하는 객체를 보유하는 cache 유형의 객체에 저장된 리소스의 수명을 관리할 때 특히 유용합니다.

runCleanup() 및 ~QRhi()도 참조하세요 .

void QRhi::addCleanupCallback(const void *key, const QRhi::CleanupCallback &callback)

이 함수는 오버로드된 함수입니다.

QRhi 이 소멸되거나 runCleanup()가 호출될 때 호출되도록 callback 을 등록합니다. 이 오버로드는 지정된 콜백이 한 번만 등록(소위 호출)되도록 하는 데 사용되는 불투명 포인터 key 를 받습니다.

removeCleanupCallback()도 참조하세요 .

QRhi::Implementation QRhi::backend() const

이 QRhi 에 대한 백엔드 유형을 반환합니다.

const char *QRhi::backendName() const

이 QRhi 에 대한 백엔드 유형을 문자열로 반환합니다.

[static] const char *QRhi::backendName(QRhi::Implementation impl)

백엔드의 친숙한 이름 impl(일반적으로 사용 중인 3D API의 이름)을 반환합니다.

QRhi::FrameOpResult QRhi::beginFrame(QRhiSwapChain *swapChain, QRhi::BeginFrameFlags flags = {})

다음 사용 가능한 버퍼 swapChain 를 대상으로 새 프레임을 시작합니다.

프레임은 리소스 업데이트와 하나 이상의 렌더링 및 계산 패스로 구성됩니다.

flags 는 특정 특수한 경우를 나타낼 수 있습니다.

스왑체인을 사용하여 QWindow 로 렌더링하는 높은 수준의 패턴입니다:

• 스왑체인을 생성합니다.
• 표면 크기가 이전과 다를 때마다 QRhiSwapChain::createOrResize()를 호출합니다.
• QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed 에서 QRhiSwapChain::destroy()를 호출합니다.
• 그런 다음 모든 프레임에서:

  beginFrame(sc);
  updates = nextResourceUpdateBatch();
  updates->...
  QRhiCommandBuffer *cb = sc->currentFrameCommandBuffer();
  cb->beginPass(sc->currentFrameRenderTarget(), colorClear, dsClear, updates);
  ...
  cb->endPass();
  ... // more passes as necessary
  endFrame(sc);

성공하면 QRhi::FrameOpSuccess 를 반환하고 실패하면 다른 QRhi::FrameOpResult 값을 반환합니다. 이 중 일부는 "나중에 다시 시도" 유형의 부드러운 오류로 처리해야 합니다: QRhi::FrameOpSwapChainOutOfDate 가 반환되면 QRhiSwapChain::createOrResize()를 호출하여 스왑체인의 크기를 조정하거나 업데이트해야 합니다. QRhi::FrameOpDeviceLost 은 그래픽 장치가 손실되었음을 의미하지만 QRhi 자체를 포함한 모든 리소스를 해제하고 모든 리소스를 다시 생성하면 복구할 수 있습니다. 자세한 내용은 isDeviceLost()를 참조하세요.

endFrame(), beginOffscreenFrame() 및 isDeviceLost()도 참조하세요 .

QRhi::FrameOpResult QRhi::beginOffscreenFrame(QRhiCommandBuffer **cb, QRhi::BeginFrameFlags flags = {})

새 오프스크린 프레임을 시작합니다. cb 에 렌더링 명령을 기록하는 데 적합한 명령 버퍼를 제공합니다. flags 은 beginFrame()와 마찬가지로 특정 특수한 경우를 나타내는 데 사용됩니다.

스왑체인 없이 렌더링하는 것도 가능합니다. 일반적인 사용 사례는 창을 표시하지 않고 렌더링하고 다시 읽어 이미지 시퀀스를 생성하는 등 완전히 화면 밖 애플리케이션에서 사용하는 것입니다.

화면 내 애플리케이션(예: beginFrame, endFrame, beginOffscreenFrame, endOffscreenFrame, beginFrame, ...)에서도 사용할 수 있지만 병렬성이 저하되므로 드물게만 사용해야 합니다.

오프스크린 프레임은 GPU가 이전 프레임을 처리하는 동안 CPU가 잠재적으로 다른 프레임을 생성하지 못하게 합니다. 이로 인해 읽기백이 예약된 경우 endOffscreenFrame()가 반환되면 결과를 사용할 수 있다는 부작용이 있습니다. 스왑체인을 대상으로 하는 프레임은 그렇지 않습니다. 이 경우 GPU를 더 잘 활용할 수 있지만 endFrame()는 endOffscreenFrame()와 달리 그 시점에서 읽기백의 결과를 사용할 수 있다는 보장이 없기 때문에 애플리케이션에서 읽기백 작업을 할 때는 더 많은 주의가 필요합니다.

스왑체인 없이 프레임을 렌더링한 다음 프레임 내용을 다시 읽어오는 골격은 다음과 같습니다:

QRhiReadbackResult rbResult;
QRhiCommandBuffer *cb;
rhi->beginOffscreenFrame(&cb);
cb->beginPass(rt, colorClear, dsClear);
// ...
u = nextResourceUpdateBatch();
u->readBackTexture(rb, &rbResult);
cb->endPass(u);
rhi->endOffscreenFrame();
// image data available in rbResult

endOffscreenFrame() 및 beginFrame()도 참조하세요 .

QMatrix4x4 QRhi::clipSpaceCorrMatrix() const

활성 QRhi 백엔드에 관계없이 애플리케이션이 OpenGL 대상 버텍스 데이터와 원근 투영 행렬(예: QMatrix4x4::perspective()에서 생성된 행렬)을 계속 사용할 수 있도록 하는 데 사용할 수 있는 행렬을 반환합니다.

일반적인 렌더러에서 mvp 대신 this_matrix * mvp 을 사용하면 런타임에 어떤 백엔드(따라서 그래픽 API)를 사용할지 고려하지 않고도 Y가 위로 향한 버텍스 데이터와 깊이 범위가 0~1인 뷰포트를 사용할 수 있습니다. 이렇게 하면 isYUpInNDC() 및 isClipDepthZeroToOne()에 기반한 분기를 피할 수 있습니다(특정 고급 그래픽 기술을 구현할 때 이러한 로직이 여전히 필요할 수 있음).

벌칸 관점에서 이 주제에 대한 논의는 이 페이지를 참조하세요.

[static] QRhi *QRhi::create(QRhi::Implementation impl, QRhiInitParams *params, QRhi::Flags flags = {}, QRhiNativeHandles *importDevice = nullptr)

impl 에서 지정한 그래픽 API의 백엔드가 있는 새 QRhi 인스턴스를 flags 로 반환합니다. 함수가 실패하면 nullptr 를 반환합니다.

params 는 QRhiVulkanInitParams, QRhiMetalInitParams, QRhiD3D11InitParams, QRhiD3D12InitParams, QRhiGles2InitParams 와 같은 QRhiInitParams 의 백엔드별 서브클래스 중 하나의 인스턴스를 가리켜야 합니다. QRhi 를 만드는 예제는 이 클래스를 참조하세요.

QRhi 는 설계상 폴백 로직을 구현하지 않습니다. 지정된 API를 초기화할 수 없는 경우 백엔드에서 디버그 출력에 경고를 출력하면서 create()가 실패합니다. 그러나 QRhi 의 클라이언트(예: Qt Quick)는 플랫폼에 따라 요청된 것과 다른 API로 폴백할 수 있는 추가 로직을 제공할 수 있습니다. 나중에 create()를 호출할 때 초기화가 성공하는지 테스트하는 것이 목적이라면, 일부 백엔드에서는 인프라의 전체 초기화를 수행하고 해당 QRhi 인스턴스가 즉시 버려지는 경우 낭비되는 create()와 달리 프로빙을 더 가벼운 방식으로 구현할 수 있으므로 create() 대신 probe()를 사용하는 것이 바람직합니다.

importDevice 를 사용하면 QRhi 를 새로 만들지 않고도 이미 존재하는 그래픽 장치를 사용할 수 있습니다. 이 매개변수는 null이 아닌 경우, QRhiNativeHandles 의 서브클래스 중 하나의 인스턴스를 가리켜야 합니다: QRhiVulkanNativeHandles, QRhiD3D11NativeHandles, QRhiD3D12NativeHandles, QRhiMetalNativeHandles, QRhiGles2NativeHandles. 정확한 세부 사항과 의미는 백엔드 및 기본 그래픽 API에 따라 다릅니다.

probe()도 참조하세요 .

int QRhi::currentFrameSlot() const

프레임을 녹화하는 동안 현재 프레임 슬롯 인덱스를 반환합니다. 활성 프레임 외부에서 호출될 때(즉, isRecordingFrame()가 false 인 경우) 지정되지 않습니다.

벌칸이나 메탈과 같은 백엔드의 경우, 새 프레임을 시작하고 CPU가 이미 GPU보다 FramesInFlight - 1 프레임 앞서 있는 경우(프레임 번호 current - FramesInFlight 에 제출된 명령 버퍼가 아직 완료되지 않았기 때문에) 이를 차단하는 것은 QRhi 백엔드의 책임입니다.

프레임 간에 변경되는 경향이 있는 리소스(예: 유형이 QRhiBuffer::Dynamic 인 QRhiBuffer 을 지원하는 기본 버퍼 객체)는 여러 버전으로 존재하므로 이전 프레임이 처리되는 동안 제출할 수 있는 각 프레임은 자체 복사본으로 작동하므로 프레임 준비 시 파이프라인을 중단할 필요가 없습니다. (GPU에서 아직 사용 중인 리소스의 콘텐츠는 건드리지 않아야 하지만, 이전 프레임이 완료될 때까지 항상 기다리면 GPU 사용률이 감소하고 궁극적으로 성능과 효율성이 저하됩니다.)

개념적으로 이것은 일부 C++ 컨테이너 및 기타 유형에서 사용하는 복사-온-쓰기 방식과 다소 유사합니다. 또한 특정 유형의 오브젝트에 대해 OpenGL 또는 Direct 3D 11 구현이 내부적으로 수행하는 것과 유사할 수도 있습니다.

실제로 이러한 이중(또는 삼중) 버퍼링 리소스는 Vulkan, Metal 및 이와 유사한 QRhi 백엔드에서 QRhiResource 뒤에 고정된 수의 기본 리소스(예: VkBuffer) slots 를 배치하여 구현됩니다. 그런 다음 0, 1, ..., FramesInFlight-1로 실행되는 프레임 슬롯 인덱스로 색인한 다음 래핑할 수 있습니다.

이 모든 것은 QRhi 사용자에게 투명하게 관리됩니다. 그러나 렌더링을 그래픽 API와 직접 통합하는 애플리케이션은 자체 그래픽 리소스에 대해 유사한 이중 또는 삼중 버퍼링을 수행하고자 할 수 있습니다. 이 경우 최대 인플라이트 프레임 수( resourceLimit()를 통해 검색 가능)와 현재 프레임(슬롯) 인덱스(이 함수에서 반환됨)의 값을 알면 가장 쉽게 수행할 수 있습니다.

isRecordingFrame(), beginFrame() 및 endFrame()도 참조하세요 .

QRhiDriverInfo QRhi::driverInfo() const

성공적으로 초기화된 QRhi 인스턴스에서 사용하는 그래픽 장치의 메타데이터를 반환합니다.

QRhi::FrameOpResult QRhi::endFrame(QRhiSwapChain *swapChain, QRhi::EndFrameFlags flags = {})

마지막 beginFrame()에서 시작된 프레임을 종료하고, 커밋하고, swapChain 에 표시합니다.

이중(또는 삼중) 버퍼링은 내부적으로 QRhiSwapChain 와 QRhi 에서 관리합니다.

flags 를 선택적으로 사용하여 특정 방식으로 동작을 변경할 수 있습니다. QRhi::SkipPresent 을 전달하면 Present 명령을 대기열에 넣거나 swapBuffers를 호출하는 것을 건너뜁니다.

성공하면 QRhi::FrameOpSuccess, 실패하면 다른 QRhi::FrameOpResult 값을 반환합니다. 이 중 일부는 "나중에 다시 시도" 유형의 소프트 에러로 처리해야 합니다: QRhi::FrameOpSwapChainOutOfDate 가 반환되면 QRhiSwapChain::createOrResize()를 호출하여 스왑체인의 크기를 조정하거나 업데이트해야 합니다. QRhi::FrameOpDeviceLost 은 그래픽 장치가 손실되었음을 의미하지만 QRhi 자체를 포함한 모든 리소스를 해제하고 모든 리소스를 다시 생성하면 복구할 수 있습니다. 자세한 내용은 isDeviceLost()를 참조하세요.

beginFrame() 및 isDeviceLost()도 참조하세요 .

QRhi::FrameOpResult QRhi::endOffscreenFrame(QRhi::EndFrameFlags flags = {})

종료, 제출 및 화면 밖 프레임을 기다립니다.

flags 현재 사용되지 않습니다.

beginOffscreenFrame()도 참조하세요 .

QRhi::FrameOpResult QRhi::finish()

그래픽 대기열의 모든 작업(해당되는 경우)이 완료될 때까지 기다린 다음 읽기 백 및 리소스 릴리스 완료와 같은 모든 지연된 작업을 실행합니다. 프레임 안팎에서 호출할 수 있지만 패스 안에서는 호출할 수 없습니다. 프레임 내부에서는 명령 버퍼에 작업을 제출하는 것을 의미합니다.

bool QRhi::isClipDepthZeroToOne() const

기본 그래픽 API가 클립 공간에서 깊이 범위 [0, 1]을 사용하는 경우 true 을 반환합니다.

OpenGL은 포스트 프로젝션 깊이 범위를 [-1, 1]로 사용하기 때문에 실제로는 OpenGL 전용 false 입니다. ( QRhiViewport 에서 재정의하지 않는 한 [0, 1] 범위를 사용하는 glDepthRange()로 제어되는 NDC-윈도우 매핑과 혼동하지 마세요.) 일부 OpenGL 버전에서는 glClipControl()을 사용하여 이를 변경할 수 있지만 QRhi 의 OpenGL 백엔드에서는 이 기능을 사용할 수 없으므로 OpenGL ES 또는 4.5 미만의 OpenGL 버전에서는 이 함수를 사용하지 않습니다.

bool QRhi::isDeviceLost() const

그래픽 디바이스가 분실된 경우 true를 반환합니다.

장치 분실은 일반적으로 백엔드 및 기본 네이티브 API에 따라 beginFrame(), endFrame() 또는 QRhiSwapChain::createOrResize()에서 감지됩니다. 프레젠테이션이 이루어지는 곳이기 때문에 endFrame()가 가장 일반적입니다. 일부 백엔드의 경우 QRhiSwapChain::createOrResize()도 디바이스 손실로 인해 실패할 수 있습니다. 따라서 이 함수는 이전 작업에서 디바이스 분실이 감지되었는지 확인하는 일반적인 방법으로 제공됩니다.

장치가 손실된 경우 QRhi 을 통해 더 이상 작업을 수행하지 말고 QRhi 리소스를 모두 해제하고 QRhi 을 파괴한 다음 새 QRhi 생성을 시도해야 합니다. 성공하면 모든 그래픽 리소스를 다시 초기화해야 합니다. 그렇지 않은 경우 나중에 반복해서 다시 시도하세요.

간단한 애플리케이션에서는 장치 손실에 대해 신경 쓰지 않을 수 있지만, 일반적으로 사용되는 데스크톱 플랫폼에서는 그래픽 어댑터의 물리적 분리, 장치 또는 드라이버 비활성화, 그래픽 드라이버 제거 또는 업그레이드, 그래픽 장치 재설정으로 이어지는 오류 등 다양한 이유로 인해 장치 손실이 발생할 수 있습니다. 이 중 일부는 완전히 정상적인 상황에서도 발생할 수 있는데, 예를 들어 그래픽 드라이버를 최신 버전으로 업그레이드하는 것은 Qt 애플리케이션이 실행 중일 때 언제든지 발생할 수 있는 일반적인 작업입니다. 사용자는 애플리케이션이 OpenGL이나 Direct3D와 같은 API를 적극적으로 사용하는 경우에도 애플리케이션이 이러한 상황을 견뎌낼 수 있을 것으로 기대할 수 있습니다.

QRhi, 예를 들어 Qt Quick 과 같은 Qt의 자체 프레임워크는 장치 손실이 발생하면 이를 처리하고 적절한 조치를 취할 것으로 기대할 수 있습니다. 텍스처 및 버퍼와 같은 그래픽 리소스에 대한 데이터가 CPU 측에서 계속 사용 가능한 경우 그래픽 리소스를 원활하게 다시 초기화할 수 있으므로 이러한 이벤트가 애플리케이션 수준에서 전혀 눈에 띄지 않을 수 있습니다. 그러나 QRhi 에서 직접 작업하는 애플리케이션과 라이브러리는 디바이스 손실 상황을 스스로 확인하고 처리할 수 있도록 준비해야 합니다.

bool QRhi::isFeatureSupported(QRhi::Feature feature) const

지정된 feature 이 지원되는 경우 true 을 반환합니다.

bool QRhi::isRecordingFrame() const

활성 프레임이 있을 때, 즉 아직 해당 endFrame() (또는 endOffscreenFrame())가 없는 beginFrame() (또는 beginOffscreenFrame())가 있을 때 true를 반환합니다.

currentFrameSlot(), beginFrame() 및 endFrame()도 참조하세요 .

bool QRhi::isTextureFormatSupported(QRhiTexture::Format format, QRhiTexture::Flags flags = {}) const

flags 에서 수정한 지정된 텍스처 format 가 지원되는 경우 true 를 반환합니다.

이 쿼리는 비압축 형식과 압축 형식 모두에 대해 지원됩니다.

bool QRhi::isYUpInFramebuffer() const

기본 그래픽 API의 프레임버퍼와 이미지에서 Y축이 위를 가리키는 경우 true 를 반환합니다.

실제로는 OpenGL 전용으로 true 입니다.

bool QRhi::isYUpInNDC() const

기본 그래픽 API의 정규화된 디바이스 좌표계에서 Y축이 위를 가리키면 true 을 반환합니다.

실제로는 Vulkan의 경우 false 입니다.

bool QRhi::makeThreadLocalNativeContextCurrent()

OpenGL을 사용하면 현재 스레드에서 OpenGL 컨텍스트가 최신 상태가 됩니다. 이 함수는 다른 백엔드에는 영향을 미치지 않습니다.

이 함수를 호출하는 것은 일반적으로 Qt 프레임워크 코드에서 응용 프로그램에서 제공하는 외부 OpenGL 코드가 OpenGL을 직접 사용하는 이전과 마찬가지로 실행될 수 있도록 해야 할 때, QRhi 가 OpenGL 백엔드를 사용하는 한 관련이 있습니다.

실패하면 QOpenGLContext::makeCurrent()와 유사하게 false를 반환합니다. 작업이 실패하면 isDeviceLost()를 호출하여 컨텍스트 손실 상황이 발생했는지 확인할 수 있습니다. 이러한 확인은 QOpenGLContext::isValid()를 통한 확인과 동일합니다.

QOpenGLContext::makeCurrent() 및 QOpenGLContext::isValid()도 참조하세요 .

[static] int QRhi::mipLevelsForSize(const QSize &size)

주어진 size 에 대한 밉 레벨 수를 반환합니다.

const QRhiNativeHandles *QRhi::nativeHandles()

백엔드에서 사용하는 장치, 컨텍스트 및 유사한 개념에 대한 백엔드별 네이티브 객체 컬렉션에 대한 포인터를 반환합니다.

QRhiVulkanNativeHandles, QRhiD3D11NativeHandles, QRhiD3D12NativeHandles, QRhiGles2NativeHandles, 또는 QRhiMetalNativeHandles 로 적절히 캐스팅합니다.

QRhiBuffer *QRhi::newBuffer(QRhiBuffer::Type type, QRhiBuffer::UsageFlags usage, quint32 size)

지정된 type, usage, size 으로 새 버퍼를 반환합니다.

QRhiResource::destroy()도 참조하세요 .

QRhiComputePipeline *QRhi::newComputePipeline()

새 컴퓨팅 파이프라인 리소스를 반환합니다.

QRhiResource::destroy()도 참조하세요 .

QRhiGraphicsPipeline *QRhi::newGraphicsPipeline()

새 그래픽 파이프라인 리소스를 반환합니다.

QRhiResource::destroy()도 참조하세요 .

QRhiRenderBuffer *QRhi::newRenderBuffer(QRhiRenderBuffer::Type type, const QSize &pixelSize, int sampleCount = 1, QRhiRenderBuffer::Flags flags = {}, QRhiTexture::Format backingFormatHint = QRhiTexture::UnknownFormat)

지정된 type, pixelSize, sampleCount, flags 으로 새 렌더버퍼를 반환합니다.

backingFormatHint 가 QRhiTexture::UnknownFormat 이외의 텍스처 포맷으로 설정된 경우 백엔드에서 렌더버퍼를 뒷받침하는 스토리지에 사용할 포맷을 결정하는 데 사용할 수 있습니다.

QRhiResource::destroy()도 참조하세요 .

QRhiSampler *QRhi::newSampler(QRhiSampler::Filter magFilter, QRhiSampler::Filter minFilter, QRhiSampler::Filter mipmapMode, QRhiSampler::AddressMode addressU, QRhiSampler::AddressMode addressV, QRhiSampler::AddressMode addressW = QRhiSampler::Repeat)

지정된 확대 필터 magFilter, 축소 필터 minFilter, 밉매핑 모드 mipmapMode, 주소 지정(랩) 모드 addressU, addressV, addressW 를 포함한 새 샘플러를 반환합니다.

QRhiResource::destroy()도 참조하세요 .

QRhiShaderResourceBindings *QRhi::newShaderResourceBindings()

새 셰이더 리소스 바인딩 컬렉션 리소스를 반환합니다.

QRhiResource::destroy()도 참조하십시오 .

QRhiSwapChain *QRhi::newSwapChain()

새 스왑체인을 반환합니다.

QRhiResource::destroy() 및 QRhiSwapChain::createOrResize()도 참조하세요 .

QRhiTexture *QRhi::newTexture(QRhiTexture::Format format, const QSize &pixelSize, int sampleCount = 1, QRhiTexture::Flags flags = {})

지정된 format, pixelSize, sampleCount, flags 으로 새 1D 또는 2D 텍스처를 반환합니다.

1D 텍스처 배열에는 flags 에 QRhiTexture::OneDimensional 가 설정되어 있어야 합니다. pixelSize 높이가 0이면 이 함수는 이 플래그를 암시적으로 설정합니다.

QRhiResource::destroy()도 참조하세요 .

QRhiTexture *QRhi::newTexture(QRhiTexture::Format format, int width, int height, int depth, int sampleCount = 1, QRhiTexture::Flags flags = {})

지정된 format, width, height, depth, sampleCount, flags 를 사용하여 새로운 1D, 2D 또는 3D 텍스처를 반환합니다.

이 오버로드는 depth 를 지정할 수 있기 때문에 3D 텍스처에 적합합니다. 3D 텍스처에는 flags 에 QRhiTexture::ThreeDimensional 가 설정되어 있어야 하지만 depth 가 0보다 클 때마다 플래그가 암시적으로 설정되므로 이 오버로드를 사용하면 생략할 수 있습니다. 1D, 2D 및 큐브 텍스처의 경우 depth 를 0으로 설정해야 합니다.

1D 텍스처는 flags 에 QRhiTexture::OneDimensional 가 설정되어 있어야 합니다. height 와 depth 이 모두 0이면 이 오버로드는 이 플래그를 암시적으로 설정합니다.

이는 오버로드된 함수입니다.

QRhiTexture *QRhi::newTextureArray(QRhiTexture::Format format, int arraySize, const QSize &pixelSize, int sampleCount = 1, QRhiTexture::Flags flags = {})

지정된 format, arraySize, pixelSize, sampleCount, flags 로 새 1D 또는 2D 텍스처 배열을 반환합니다.

이 함수는 flags 에 QRhiTexture::TextureArray 를 암시적으로 설정합니다.

1D 텍스처 배열에는 flags 에 QRhiTexture::OneDimensional 가 설정되어 있어야 합니다. 이 함수는 pixelSize 높이가 0인 경우 이 플래그를 암시적으로 설정합니다.

newTexture()도 참조하세요 .

QRhiTextureRenderTarget *QRhi::newTextureRenderTarget(const QRhiTextureRenderTargetDescription &desc, QRhiTextureRenderTarget::Flags flags = {})

desc 에 지정된 색상 및 뎁스/스텐실 첨부 파일과 지정된 flags 을 사용하여 새 텍스처 렌더링 타깃을 반환합니다.

QRhiResource::destroy()도 참조하십시오 .

QRhiResourceUpdateBatch *QRhi::nextResourceUpdateBatch()

복사 유형의 작업을 기록할 수 있는 사용 가능한 빈 배치를 반환합니다.

기록 중인 프레임에 묶여 있지 않기 때문에 예를 들어 다음 순서가 유효합니다:

rhi->beginFrame(swapchain);
QRhiResourceUpdateBatch *u = rhi->nextResourceUpdateBatch();
u->uploadStaticBuffer(buf, data);
// ... do not commit the batch
rhi->endFrame();
// u stays valid (assuming buf stays valid as well)
rhi->beginFrame(swapchain);
swapchain->currentFrameCommandBuffer()->resourceUpdate(u);
// ... draw with buf
rhi->endFrame();

QByteArray QRhi::pipelineCacheData()

이 QRhi 의 수명 기간 동안 성공적으로 생성된 QRhiGraphicsPipeline 및 QRhiComputePipeline 에서 수집한 데이터가 포함된 바이너리 데이터 블롭을 반환합니다.

저장한 다음 이후 동일한 애플리케이션을 실행할 때 캐시 데이터를 다시 로드하면 파이프라인 및 셰이더 생성 시간을 줄일 수 있습니다. 캐시 및 직렬화된 버전에 정확히 무엇이 포함되는지는 명시되어 있지 않으며, 항상 사용되는 백엔드에 따라 다르며 경우에 따라서는 그래픽 API의 특정 구현에 따라 달라질 수 있습니다.

PipelineCacheDataLoadSave 가 지원되지 않는 것으로 보고되면 반환된 QByteArray 은 비어 있습니다.

create() 호출 시 EnablePipelineCacheDataSave 플래그가 지정되지 않은 경우 PipelineCacheDataLoadSave 기능이 지원되는 경우에도 반환된 QByteArray 이 비어 있을 수 있습니다.

반환된 데이터가 비어 있지 않은 경우, 항상 Qt 버전과 QRhi 백엔드에 따라 다릅니다. 또한 그래픽 장치 및 사용된 정확한 드라이버 버전에 대한 종속성이 강한 경우도 있습니다. QRhi 은 적절한 헤더를 추가하고 데이터를 항상 setPipelineCacheData()에 안전하게 전달할 수 있도록 안전장치를 처리하므로 다른 버전의 드라이버에서 실행된 데이터를 로드하려는 시도가 안전하고 정상적으로 처리됩니다.

이 기능에 대한 자세한 내용은 EnablePipelineCacheDataSave 을 참조하세요.

setPipelineCacheData(), create() 및 isFeatureSupported()도 참조하세요 .

[static] bool QRhi::probe(QRhi::Implementation impl, QRhiInitParams *params)

주어진 impl 및 params 을 호출했을 때 create()가 성공할 것으로 예상할 수 있으면 true를 반환합니다.

일부 백엔드의 경우 이는 create()를 호출하고 반환값을 확인한 다음 결과 QRhi 을 삭제하는 것과 같습니다.

다른 경우, 특히 Metal의 경우 특정 프로빙 구현이 있을 수 있으며, 이를 통해 실패 시 경고로 디버그 출력을 오염시키지 않고 보다 가벼운 방식으로 테스트할 수 있습니다.

create()도 참조하세요 .

void QRhi::releaseCachedResources()

백엔드의 캐시에서 리소스를 해제하려고 시도합니다. 여기에는 CPU 및 GPU 리소스가 모두 포함될 수 있습니다. 자동으로 재생성할 수 있는 메모리와 리소스만 범위에 포함됩니다. 예를 들어 백엔드의 QRhiGraphicsPipeline 구현이 셰이더 컴파일 결과의 캐시를 유지하는 경우 이 함수를 호출하면 해당 캐시가 비워져 메모리와 그래픽 리소스를 확보할 수 있습니다.

이 함수를 호출하는 것은 특정 시점에서 성능을 희생하더라도 리소스 사용량을 최소화해야 하는 리소스 제약 환경에서 유용합니다.

void QRhi::removeCleanupCallback(const void *key)

콜백을 key 으로 등록 취소합니다. key 에 정리 콜백이 등록되지 않은 경우 이 함수는 아무 작업도 수행하지 않습니다. 키 없이 등록된 콜백은 제거할 수 없습니다.

addCleanupCallback()도 참조하세요 .

int QRhi::resourceLimit(QRhi::ResourceLimit limit) const

지정된 리소스의 값을 반환합니다 limit.

이 값은 초기화 시 백엔드에서 쿼리할 것으로 예상되므로 이 함수를 호출하는 것은 가벼운 작업입니다.

void QRhi::runCleanup()

등록된 모든 정리 함수를 호출합니다. 그런 다음 정리 콜백 목록을 지웁니다. 일반적으로 QRhi 을 삭제하면 이 작업이 자동으로 수행되지만 때로는 캐시된 비필수 리소스를 모두 해제하기 위해 정리를 트리거하는 것이 유용할 수 있습니다.

addCleanupCallback()도 참조하세요 .

void QRhi::setPipelineCacheData(const QByteArray &data)

해당되는 경우 data 을 파이프라인 캐시에 로드합니다.

PipelineCacheDataLoadSave 이 지원되지 않는 것으로 보고되면 이 함수는 호출해도 안전하지만 아무런 효과가 없습니다.

pipelineCacheData()가 반환하는 블롭은 항상 Qt 버전, QRhi 백엔드, 경우에 따라 그래픽 디바이스 및 지정된 그래픽 드라이버 버전에 따라 다릅니다. QRhi 은 적절한 헤더를 추가하고 데이터를 항상 이 함수에 안전하게 전달할 수 있도록 안전장치를 처리합니다. 드라이버가 최신 버전으로 업그레이드되었거나 데이터가 다른 QRhi 백엔드에서 생성되어 불일치하는 경우 경고가 표시되고 data 은 안전하게 무시됩니다.

Vulkan에서는 이 함수가 VkPipelineCache에 직접 매핑됩니다. 이 함수를 호출하면 data 에서 초기 데이터를 가져온 새 Vulkan 파이프라인 캐시 객체가 생성됩니다. 그러면 이후 생성되는 모든 QRhiGraphicsPipeline 및 QRhiComputePipeline 객체에서 파이프라인 캐시 객체를 사용하므로 잠재적으로 파이프라인 생성을 가속화할 수 있습니다.

다른 API의 경우 실제 파이프라인 캐시는 없지만 셰이더 컴파일(D3D) 또는 프로그램 바이너리(OpenGL)의 바이트코드가 포함된 캐시를 제공할 수 있습니다. 런타임에 소스에서 셰이더 컴파일을 많이 수행하는 애플리케이션의 경우 이 기능을 사용하여 '파이프라인 캐시'를 이전 실행에서 미리 시드하면 후속 실행에서 상당한 성능 향상을 제공할 수 있습니다.

이 기능에 대한 자세한 내용은 EnablePipelineCacheDataSave 을 참조하세요.

pipelineCacheData() 및 isFeatureSupported()도 참조하세요 .

[static] QSize QRhi::sizeForMipLevel(int mipLevel, const QSize &baseLevelSize)

주어진 mipLevel 에 대한 텍스처 이미지 크기를 반환하며, baseLevelSize 에 주어진 레벨 0 크기를 기준으로 계산합니다.

QRhiStats QRhi::statistics() const

그래픽 리소스의 타이밍과 할당에 대한 통계를 수집하고 반환합니다.

메모리 할당에 대한 데이터는 해당 작업이 Qt의 제어 하에 있는 일부 백엔드에서만 사용할 수 있습니다. 리소스 메모리 할당에 대한 하위 수준 제어가 없는 그래픽 API에서는 이 기능이 지원되지 않으며 결과의 모든 관련 필드는 0입니다.

특히 Vulkan에서는 값이 항상 유효하며 기본 메모리 할당자 라이브러리에서 쿼리됩니다. 이를 통해 활성 버퍼와 텍스처의 메모리 요구 사항을 파악할 수 있습니다.

Direct 3D 12도 마찬가지입니다. 여기에는 메모리 할당자 라이브러리의 통계 외에도 메모리 할당자 라이브러리가 제어하지 않는 추가 리소스(스왑체인 버퍼, 디스크립터 힙 등)를 포함한 총 크기를 보고하는 totalUsageBytes 필드도 포함되어 있습니다(DXGI에서 보고).

이 값은 사용된 모든 유형의 메모리를 합친 값에 해당합니다. (예: 디스크리트 GPU의 경우 비디오 + 시스템).

그래픽 및 컴퓨팅 파이프라인 생성에 소요된 총 시간(밀리초)과 같은 추가 데이터(일반적으로 셰이더 컴파일 또는 캐시 조회, 잠재적으로 비용이 많이 드는 프로세싱이 포함됨)는 대부분의 백엔드에서 사용할 수 있습니다.

QList<int> QRhi::supportedSampleCounts() const

지원되는 샘플 개수 목록을 반환합니다.

일반적인 예는 (1, 2, 4, 8)입니다.

일부 백엔드에서는 지원되는 값 목록이 미리 고정되어 있는 반면, 다른 백엔드에서는 (물리적) 장치 속성이 런타임에 지원되는 항목을 나타냅니다.

QRhiRenderBuffer::setSampleCount(), QRhiTexture::setSampleCount(), QRhiGraphicsPipeline::setSampleCount() 및 QRhiSwapChain::setSampleCount()도 참조하세요 .

QThread *QRhi::thread() const

QRhi 이 initialized 이었던 스레드를 반환합니다.

int QRhi::ubufAligned(int v) const

ubufAlignment()에 의해 지정된 균일한 버퍼 정렬에 맞춰 정렬된 값(일반적으로 오프셋)을 v 반환합니다.

int QRhi::ubufAlignment() const

최소 균일한 버퍼 오프셋 정렬을 바이트 단위로 반환합니다. 이 값은 일반적으로 256입니다.

이 값에 맞지 않는 오프셋으로 균일한 버퍼 영역을 바인딩하려고 하면 백엔드 및 기본 그래픽 API에 따라 실패로 이어질 수 있습니다.

ubufAligned()도 참조하세요 .

[static] QRhiSwapChainProxyData QRhi::updateSwapChainProxyData(QRhi::Implementation impl, QWindow *window)

impl 에 지정된 백엔드 및 그래픽 API와 관련된 불투명 데이터를 포함하는 QRhiSwapChainProxyData 구조체를 생성하고 반환합니다. window 는 스왑체인이 타겟팅하는 QWindow 입니다.

반환된 구조체는 QRhiSwapChain::setProxyData()로 전달할 수 있습니다. 이 정적 함수는 모든 QRhi 연산과 달리 메인(gui) 스레드에서 호출된 다음 QRhi 및 QRhiSwapChain 작업하는 스레드로 전송되어 스왑체인에 전달될 것으로 예상되므로 스레드 렌더링 시스템에서 의미가 있습니다. 이를 통해 메인 스레드에서만 호출되는 것이 안전한 네이티브 플랫폼 쿼리를 수행할 수 있습니다(예: NSView에서 CAMetalLayer를 쿼리한 다음 렌더링 스레드에 있는 QRhiSwapChain 에 데이터를 전달). Metal 예제에서 전용 렌더링 스레드에서 view.layer 액세스를 수행하면 Xcode 스레드 검사기에 경고가 표시됩니다. 데이터 프록시 메커니즘을 사용하면 이 문제를 방지할 수 있습니다.

스레드가 관여하지 않는 경우 QRhiSwapChainProxyData 을 생성하여 전달할 필요가 없습니다. 백엔드는 필요한 모든 것을 자체적으로 쿼리할 수 있으며 모든 것이 메인(GUI) 스레드에 있는 경우 이것으로 충분합니다.