QRhi Class

멤버 함수 설명서

[noexcept] QRhi::~QRhi()

소멸자. 백엔드를 소멸시키고 리소스를 해제합니다.

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

QRhi 가 소멸될 때 호출되는 callback 를 등록합니다.

이 콜백은 그래픽 리소스가 여전히 사용 가능한 상태에서 실행되므로, 애플리케이션이 QRhi 에 속한 QRhiResource 인스턴스를 깔끔하게 해제할 수 있는 기회를 제공합니다. 이는 특히 cache 유형의 객체에 저장된 리소스의 수명 주기를 관리하는 데 유용하며, 이 경우 캐시에는 QRhiResources 또는 QRhiResources를 포함하는 객체가 저장됩니다.

~QRhi()도 참조하십시오 .

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

QRhi 가 소멸될 때 호출될 콜백 함수 ` 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 등)에서도 사용할 수 있습니다.

texture 이나 buffer 리드백이 예약된 경우, 오프스크린 프레임은 GPU가 이전 프레임을 처리하는 동안 CPU가 다른 프레임을 생성할 가능성을 차단합니다. 이로 인해 리드백이 예약되어 있다면, endOffscreenFrame()이 반환될 때 결과가 보장된다는 부수적인 효과가 있습니다. 스왑체인(swapchain)을 대상으로 하는 프레임의 경우 상황은 다릅니다. 스왑체인을 사용하면 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()에 기반한 분기 처리를 피할 수 있습니다(비록 특정 고급 그래픽 기술을 구현할 때는 이러한 로직이 여전히 필요할 수 있지만).

Vulkan 관점에서 이 주제에 대한 논의는 이 페이지를 참조하십시오.

[static] QRhi *QRhi::create(QRhi::Implementation impl, QRhiInitParams *params, QRhi::Flags flags, QRhiNativeHandles *importDevice, QRhiAdapter *adapter)

impl 로 지정된 그래픽 API에 대한 백엔드와 지정된 flags 를 갖는 새로운 QRhi 인스턴스를 반환합니다. 함수 실행에 실패하면 nullptr 를 반환합니다.

params must는 QRhiInitParams 의 백엔드별 하위 클래스(예: QRhiVulkanInitParams, QRhiMetalInitParams, QRhiD3D11InitParams, QRhiD3D12InitParams, QRhiGles2InitParams) 중 하나의 인스턴스를 가리켜야 합니다. QRhi 생성 예제는 해당 클래스를 참조하십시오.

QRhi 설계상 어떠한 대체 로직도 구현하지 않습니다. 지정된 API를 초기화할 수 없는 경우, create()는 실패하며 백엔드에서 디버그 출력에 경고 메시지가 표시됩니다. 그러나 QRhi 의 클라이언트(예: Qt Quick)는 플랫폼에 따라 요청된 것과 다른 API로 대체할 수 있는 추가 로직을 제공할 수 있습니다. 나중에 create()를 호출했을 때 초기화가 성공할지 여부를 단순히 테스트하려는 목적이라면, create() 대신 probe()를 사용하는 것이 바람직합니다. 일부 백엔드에서는 create()가 인프라의 전체 초기화를 수행하여 QRhi 인스턴스가 즉시 버려질 경우 자원이 낭비되는 반면, probing은 create()보다 더 가벼운 방식으로 구현될 수 있기 때문입니다.

importDevice QRhi 가 자체적으로 생성하지 않고, 이미 존재하는 그래픽 장치를 사용할 수 있게 해줍니다. null이 아닐 경우, 이 매개변수는 의 하위 클래스 중 하나인 , , , , 의 인스턴스를 가리켜야 합니다. 정확한 세부 사항과 의미는 백엔드 및 기본 그래픽 API에 따라 다릅니다. QRhiNativeHandles QRhiVulkanNativeHandles QRhiD3D11NativeHandles QRhiD3D12NativeHandles QRhiMetalNativeHandles QRhiGles2NativeHandles

adapter 에서 QRhiAdapter 를 지정하면, QRhiVulkanNativeHandles 를 통해 VkPhysicalDevice 를 전달하거나 QRhiD3D12NativeHandles 를 통해 어댑터 LUID를 전달하는 대신, 투명하고 API 간 호환이 가능한 대안을 제공합니다. adapter 의 소유권은 확보되지 않습니다. 이 접근 방식에 대한 자세한 내용은 enumerateAdapters()을 참조하십시오.

probe()도 참조하십시오 .

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

create(impl, params, flags, importDevice, nullptr)와 동일합니다.

int QRhi::currentFrameSlot() const

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

Vulkan이나 Metal과 같은 백엔드의 경우, 새로운 프레임을 시작할 때마다 CPU가 GPU보다 FramesInFlight - 1 프레임 앞서 있는 것을 감지하면(프레임 번호 current - FramesInFlight 에서 제출된 명령 버퍼가 아직 완료되지 않았기 때문), QRhi 백엔드가 이를 차단해야 할 책임이 있습니다.

프레임 간에 변경되는 경향이 있는 리소스(예: 유형 QRhiBuffer::Dynamic 인 QRhiBuffer 을 뒷받침하는 네이티브 버퍼 객체)는 여러 버전이 존재하므로, 이전 프레임이 아직 처리 중인 동안 제출될 수 있는 각 프레임은 자체 사본을 사용하여 작동하며, 이로 인해 프레임을 준비할 때 파이프라인을 정지시킬 필요가 없습니다. (GPU에서 아직 사용 중일 수 있는 리소스의 내용은 건드리지 말아야 하지만, 단순히 이전 프레임이 끝날 때까지 항상 기다리기만 한다면 GPU 활용도가 떨어지고, 결과적으로 성능과 효율성도 저하될 것입니다.)

개념적으로 이는 일부 C++ 컨테이너 및 기타 유형에서 사용하는 ‘쓰기 시 복사(copy-on-write)’ 방식과 다소 유사합니다. 또한 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 = {})

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

더블(또는 트리플) 버퍼링은 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 = {})

오프스크린 프레임을 종료하고, 제출하며, 필요한 경우 완료를 기다립니다.

endFrame()와 달리, 이 함수는 활성 버퍼 또는 텍스처 리드백이 있는 경우 GPU 측 작업이 완료될 때까지 차단되어 대기합니다.

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

beginOffscreenFrame()도 참조하십시오 .

[static, since 6.10] QRhi::AdapterList QRhi::enumerateAdapters(QRhi::Implementation impl, QRhiInitParams *params, QRhiNativeHandles *nativeHandles = nullptr)

현재 존재하는 어댑터(물리적 장치)의 목록을 반환하거나, 지정된 그래픽 API에서 해당 제어 기능이 지원되지 않는 경우 빈 목록을 반환합니다.

이러한 수준의 제어가 불가능한 백엔드의 경우, 반환되는 리스트는 항상 비어 있습니다. 따라서 빈 리스트는 시스템에 그래픽 장치가 없다는 것을 의미하는 것이 아니라, 사용할 장치를 선택하는 데 필요한 세밀한 제어 기능이 제공되지 않음을 나타냅니다.

Direct 3D 11, Direct 3D 12 및 Vulkan용 백엔드는 어댑터 열거를 완전히 지원할 것으로 예상됩니다. 그 외의 백엔드는 지원하지 않을 수 있습니다. 백엔드는 ` impl`로 지정됩니다. 이 함수에서 반환된 ` QRhiAdapter `는 반드시 동일한 ` impl`를 사용하는 ` create()` 호출에서만 사용되어야 합니다. 일부 기본 API는 추가적인 제한 사항을 가질 수 있으며, 특히 Vulkan의 경우 ` QRhiAdapter `가 ` QVulkanInstance `(`VkInstance`)로 지정됩니다.

호출자는 목록에 있는 QRhiAdapter 객체들을 소멸시켜야 합니다. info()를 조회하는 것 외에, 이 객체들의 유일한 용도는 create() 또는 Qt Quick 과 같은 상위 계층의 해당 함수에 전달되는 것입니다.

Vulkan을 위해 특별히 작성된 다음 코드 조각은 사용 가능한 물리적 장치를 열거하고, 선택한 장치에 대한 QRhi 생성을 요청하는 방법을 보여줍니다. 이는 실제로 QRhiVulkanNativeHandles 를 통해 VkPhysicalDevice 를 create()에 전달하는 것과 동일하지만, 애플리케이션 측에서 API에 특화된 코드를 덜 사용하게 됩니다:

QRhiVulkanInitParams initParams;
initParams.inst = &vulkanInstance;
QRhi::AdapterList adapters = QRhi::enumerateAdapters(QRhi::Vulkan, &initParams);
QRhiAdapter*chosenAdapter = nullptr;
for (QRhiAdapter*adapter: adapters) {
    if (looksGood(adapter->info())) {
        chosenAdapter = adapter;
        break;
    }
}
QRhi*rhi = QRhi::create(QRhi::Vulkan, &initParams, {}, nullptr, chosenAdapter);
qDeleteAll(adapters);

params 에 매개변수를 전달해야 하는 것은 일부 기본 그래픽 API의 설계 방식 때문입니다. 특히 Vulkan의 경우, QVulkanInstance 를 반드시 제공해야 하는데, 이 매개변수가 없으면 열거(enumeration)가 불가능하기 때문입니다. 백엔드별 params 의 다른 필드들은 이 함수에서 실제로 사용되지 않습니다.

nativeHandles 는 선택 사항입니다. 지정될 경우, create()와 마찬가지로 유효한 QRhiD3D11NativeHandles, QRhiD3D12NativeHandles 또는 QRhiVulkanNativeHandles 여야 합니다. 그러나 create()와 달리, (Vulkan의 경우) 물리적 장치 필드나 (D3D의 경우) 어댑터 LUID 필드만 사용되며, 그 외의 모든 필드는 무시됩니다. 이를 통해 결과를 특정 어댑터로 제한할 수 있습니다. 이 경우 반환되는 목록에는 1개 또는 0개의 요소가 포함됩니다.

앞서 제시된 코드 스니펫에서 looksGood() 함수 구현은 Windows의 어댑터 LUID나 Vulkan의 VkPhysicalDevice와 같이 실제 어댑터/물리적 장치의 식별 정보를 기반으로 한 플랫폼별 필터링을 수행할 수 없다는 점에 유의하십시오. 이는 QRhiDriverInfo 에 플랫폼별 데이터가 포함되어 있지 않기 때문입니다. 대신, ` nativeHandles `을 사용하여 `enumerateAdapters()` 내부에서 이미 필터링된 결과를 가져오십시오.

다음 두 코드 조각은 Direct 3D 12를 예로 들었으나, 실제로는 동등한 기능을 수행합니다:

// Qt 6.10부터 적용되는 enumerateAdapters 기반 접근 방식
QRhiD3D12InitParams initParams;
QRhiD3D12NativeHandles nativeHandles;
nativeHandles.adapterLuidLow = luid.LowPart; // 어딘가에서 LUID를 가져왔으므로, 이제 이를 Qt로 전달합니다.
nativeHandles.adapterLuidHigh = luid.HighPart;
QRhi::AdapterList adapters = QRhi::enumerateAdapters(QRhi::D3D12, &initParams, &nativeHandles);
if (adapters.isEmpty()) { qWarning("요청한 어댑터를 찾을 수 없습니다"); }
QRhi*rhi = QRhi::create(QRhi::D3D12, &initParams, {}, nullptr, adapters[0]);
qDeleteAll(adapters);

// traditional approach, more lightweight
QRhiD3D12InitParams initParams;
QRhiD3D12NativeHandles nativeHandles;
nativeHandles.adapterLuidLow = luid.LowPart; // retrieved a LUID from somewhere, now pass it on to Qt
nativeHandles.adapterLuidHigh = luid.HighPart;
QRhi *rhi = QRhi::create(QRhi::D3D12, &initParams, {}, &nativeHandles, nullptr);

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

create()도 참조하십시오 .

QRhi::FrameOpResult QRhi::finish()

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

bool QRhi::isClipDepthZeroToOne() const

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

실제로는 OpenGL에서만 false 을 반환합니다. OpenGL은 투영 후 깊이 범위 [-1, 1]을 사용하기 때문입니다. (glDepthRange()로 제어되는 NDC-to-window 매핑과 혼동해서는 안 됩니다. 이 매핑은 QRhiViewport 에 의해 재정의되지 않는 한 [0, 1] 범위를 사용합니다.) 일부 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 고유의 프레임워크(예: Qt Quick)는 장치 손실이 발생할 때 이를 처리하고 적절한 조치를 취할 것으로 기대할 수 있습니다. 텍스처나 버퍼와 같은 그래픽 리소스에 대한 데이터가 CPU 측에 여전히 남아 있다면, 그래픽 리소스를 원활하게 재초기화할 수 있으므로 이러한 이벤트는 애플리케이션 수준에서 전혀 감지되지 않을 수 있습니다. 그러나 QRhi 을 직접 사용하는 애플리케이션과 라이브러리는 장치 손실 상황을 스스로 확인하고 처리할 준비가 되어 있어야 합니다.

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

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

bool QRhi::isRecordingFrame() const

활성 프레임이 있을 때 true를 반환합니다. 즉, beginFrame() (또는 beginOffscreenFrame())가 호출되었으나, 이에 대응하는 endFrame() (또는 endOffscreenFrame())가 아직 호출되지 않은 경우를 의미합니다.

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 프레임워크 코드에서, QRhi 가 OpenGL 백엔드를 사용하는 한, 애플리케이션에서 제공하는 외부 OpenGL 코드가 이전과 마찬가지로 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()도 참조하십시오 .

[since 6.9] QRhiShadingRateMap *QRhi::newShadingRateMap()

새로운 셰이딩 레이트 맵 객체를 반환합니다.

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

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 텍스처를 반환합니다.

1차원 텍스처의 경우 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으로 설정해야 합니다.

1차원 텍스처의 경우 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 를 갖는 새로운 1차원 또는 2차원 텍스처 배열을 반환합니다.

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

1차원 텍스처 배열의 경우 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::setPipelineCacheData(const QByteArray &data)

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

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

pipelineCacheData()가 반환하는 blob은 항상 Qt 버전, QRhi 백엔드, 그리고 경우에 따라 그래픽 장치 및 특정 버전의 그래픽 드라이버에 따라 달라집니다. QRhi 는 적절한 헤더를 추가하고, 데이터가 항상 이 함수로 안전하게 전달될 수 있도록 보장하는 안전 장치를 처리합니다. 드라이버가 최신 버전으로 업그레이드되었거나, 데이터가 다른 QRhi 백엔드에서 생성된 경우와 같이 불일치가 발생하면 경고가 출력되며, data 는 안전하게 무시됩니다.

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

다른 API의 경우 실제 파이프라인 캐시는 없지만, 셰이더 컴파일 결과인 바이트코드(D3D)나 프로그램 바이너리(OpenGL)를 저장하는 캐시를 제공할 수 있습니다. 실행 시 소스 코드로부터 대량의 셰이더 컴파일을 수행하는 애플리케이션의 경우, 이 함수를 사용하여 이전 실행에서 “파이프라인 캐시”를 미리 채워두면 후속 실행 시 성능이 크게 향상될 수 있습니다.

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

pipelineCacheData() 및 isFeatureSupported()도 참조하십시오 .

[since 6.9] void QRhi::setQueueSubmitParams(QRhiNativeHandles *params)

해당되는 백엔드 및 그래픽 API의 경우, 이 함수를 사용하면 그래픽 명령 큐에 다음에 제출될 명령에 추가 인수를 전달할 수 있습니다.

특히 Vulkan의 경우, 이를 통해 ` vkQueueSubmit() `가 신호를 보내고 대기할 Vulkan 세마포어 객체 목록을 전달할 수 있습니다. 이때 ` params `는 ` QRhiVulkanQueueSubmitParams`여야 합니다. 이는 애플리케이션의 사용자 정의 Vulkan 렌더링 또는 컴퓨팅 코드가 관리하는 `VkSemaphore`에 대한 신호 전송 및 대기가 필요한 네이티브 Vulkan 호출을 수행하는 경우와 같은 특정 고급 사용 사례에서 필수적입니다. 또한, 이를 통해 다음 ` vkQueuePresentKHR()`에서 대기할 추가 세마포어를 지정할 수도 있습니다.

다른 많은 백엔드에서는 이 함수의 구현이 아무 작업도 수행하지 않습니다.

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

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

지정된 ` mipLevel`에 대한 텍스처 이미지 크기를 반환하며, 이 크기는 ` baseLevelSize`에 명시된 레벨 0 크기를 기준으로 계산됩니다.

QRhiStats QRhi::statistics() const

그래픽 리소스의 사용 시간 및 할당 현황에 대한 통계를 수집하여 반환합니다.

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

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

Direct 3D 12의 경우도 마찬가지입니다. 메모리 할당기 라이브러리의 통계 정보 외에도, 여기서는 DXGI가 보고하는 바와 같이 메모리 할당기 라이브러리의 제어 범위를 벗어난 추가 리소스(스왑체인 버퍼, 디스크립터 힙 등)를 포함한 총 크기를 나타내는 ‘ totalUsageBytes ’ 필드도 결과에 포함됩니다.

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

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

QList<int> QRhi::supportedSampleCounts() const

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

전형적인 예로는 (1, 2, 4, 8)이 있습니다.

일부 백엔드의 경우 지원되는 값 목록이 사전에 고정되어 있는 반면, 다른 백엔드의 경우 (물리적) 장치 속성을 통해 실행 시점에 지원되는 항목이 결정됩니다.

QRhiRenderBuffer::setSampleCount(), QRhiTexture::setSampleCount(), QRhiGraphicsPipeline::setSampleCount() 및 QRhiSwapChain::setSampleCount()도 참조하십시오 .

[since 6.9] QList<QSize> QRhi::supportedShadingRates(int sampleCount) const

지정된 sampleCount 에 대해 지원되는 가변 음영율 목록을 반환합니다.

1x1은 항상 지원됩니다.

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

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 는 스왑체인(swapchain)이 대상으로 하는 그래픽 시스템( QWindow )입니다.

반환된 구조체는 ` QRhiSwapChain::setProxyData()`에 전달될 수 있습니다. 이는 스레드 기반 렌더링 시스템에서 의미가 있습니다. 이 정적 함수는 모든 ` QRhi ` 작업과 달리 메인(GUI) 스레드에서 호출된 후, ` QRhi ` 및 ` QRhiSwapChain `을 처리하는 스레드로 전송되어 스왑체인에 전달되는 방식으로 작동합니다. 이를 통해 메인 스레드에서만 안전하게 호출할 수 있는 네이티브 플랫폼 쿼리(예: NSView에서 CAMetalLayer 조회)를 수행한 후, 해당 데이터를 렌더링 스레드에 상주하는 QRhiSwapChain 로 전달할 수 있습니다. Metal 예제의 경우, 전용 렌더링 스레드에서 view.layer에 접근하면 Xcode 스레드 검사기에서 경고가 발생합니다. 데이터 프록시 메커니즘을 사용하면 이러한 문제를 피할 수 있습니다.

스레드가 관여하지 않는 경우, ` QRhiSwapChainProxyData `을 생성하여 전달할 필요가 없습니다. 백엔드는 필요한 모든 정보를 자체적으로 조회할 수 있도록 보장되며, 모든 것이 메인(GUI) 스레드에서 처리된다면 그것으로 충분합니다.