QRhiSwapChain Class

void init()
{
    sc = rhi->newSwapChain();
    ds = rhi->newRenderBuffer(QRhiRenderBuffer::DepthStencil,
                              QSize(), // no need to set the size here due to UsedWithSwapChainOnly
                              1,
                              QRhiRenderBuffer::UsedWithSwapChainOnly);
    sc->setWindow(window);
    sc->setDepthStencil(ds);
    rp = sc->newCompatibleRenderPassDescriptor();
    sc->setRenderPassDescriptor(rp);
    resizeSwapChain();
}

void resizeSwapChain()
{
    hasSwapChain = sc->createOrResize();
}

void render()
{
    if (!hasSwapChain || notExposed)
        return;

    if (sc->currentPixelSize() != sc->surfacePixelSize() || newlyExposed) {
        resizeSwapChain();
        if (!hasSwapChain)
            return;
        newlyExposed = false;
    }

    rhi->beginFrame(sc);
    // ...
    rhi->endFrame(sc);
}

void releaseSwapChain()
{
    if (hasSwapChain) {
        sc->destroy();
        hasSwapChain = false;
    }
}

// assuming Window is our QWindow subclass
bool Window::event(QEvent *e)
{
    switch (e->type()) {
    case QEvent::UpdateRequest: // for QWindow::requestUpdate()
        render();
        break;
    case QEvent::PlatformSurface:
        if (static_cast<QPlatformSurfaceEvent *>(e)->surfaceEventType() == QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed)
            releaseSwapChain();
        break;
    default:
        break;
    }
    return QWindow::event(e);
}

void Window::exposeEvent(QExposeEvent *)
{
    // initialize and start rendering when the window becomes usable for graphics purposes
    if (isExposed() && !running) {
        running = true;
        init();
    }

    // stop pushing frames when not exposed or size becomes 0
    if ((!isExposed() || (hasSwapChain && sc->surfacePixelSize().isEmpty())) && running)
        notExposed = true;

    // continue when exposed again and the surface has a valid size
    if (isExposed() && running && notExposed && !sc->surfacePixelSize().isEmpty()) {
        notExposed = false;
        newlyExposed = true;
    }

    if (isExposed() && !sc->surfacePixelSize().isEmpty())
        render();
}

멤버 함수 설명

[pure virtual] bool QRhiSwapChain::createOrResize()

아직 생성되지 않은 경우 스왑체인을 생성하고, 대상 표면의 현재 크기에 맞춰 스왑체인 버퍼의 크기를 조정합니다. 대상 표면의 크기가 이전과 다를 때마다 이 함수를 호출하십시오.

성공 시 true 를 반환하고, 그래픽 작업이 실패한 경우 false 를 반환합니다. 반환 값과 관계없이 destroy()를 호출하는 것은 항상 안전합니다.

[pure virtual] QRhiCommandBuffer *QRhiSwapChain::currentFrameCommandBuffer()

이 스왑체인(swapchain)을 사용하여 beginFrame()이 호출되었다고 가정할 때, ` beginFrame ` - ` endFrame ` 블록 내에서 렌더링 명령어와 리소스 업데이트를 기록할 수 있는 명령어 버퍼를 반환합니다.

[pure virtual] QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget()

스왑체인(swapchain)의 현재 백버퍼를 렌더링하기 위해 beginPass()와 함께 사용할 수 있는 렌더 타겟을 반환합니다. 이 스왑체인을 사용하여 beginFrame()이 호출된 QRhi::beginFrame() - QRhi::endFrame() 블록 내에서만 유효합니다.

[virtual] QRhiRenderTarget *QRhiSwapChain::currentFrameRenderTarget(QRhiSwapChain::StereoTargetBuffer targetBuffer)

스왑체인(swapchain)의 왼쪽 또는 오른쪽 백버퍼에 렌더링하기 위해 beginPass()와 함께 사용할 수 있는 렌더 타깃을 반환합니다. 이 오버로드는 입체 렌더링, 즉 연관된 렌더 타깃( QWindow )이 하나의 버퍼가 아닌 각 눈마다 하나씩 총 두 개의 컬러 버퍼로 구성된 경우에만 사용해야 합니다.

입체 렌더링이 지원되지 않는 경우, 반환 값은 기본 타겟이 됩니다. 이 오버로드는 Metal을 제외한 모든 하드웨어 백엔드에서 QSurfaceFormat::StereoBuffers 와 함께 지원되며, 이는 런타임 시 그래픽 및 디스플레이 드라이버 스택에서 지원된다는 전제 하에 적용됩니다. Metal 및 Null 백엔드는 이 오버로드를 호출할 때 기본 렌더 타겟을 반환합니다.

QSize QRhiSwapChain::currentPixelSize() const

스왑 체인이 마지막으로 성공적으로 구축되었을 때의 크기를 반환합니다. 이 값을 사용하여 ` createOrResize()`를 다시 호출해야 할지 여부를 결정할 수 있습니다. ` currentPixelSize() != surfacePixelSize() `인 경우 스왑 체인의 크기를 조정해야 합니다.

대부분의 경우 이 값은 QWindow::size() * QWindow::devicePixelRatio() 와 동일하지만, QWindow 에서 보고된 크기를 신뢰한다고 해서 모든 플랫폼 및 그래픽 API 구현에서 정확함이 보장되지는 않습니다. 따라서 출력 레이어나 서페이스의 크기를 픽셀 단위로 확인해야 할 때는 이 함수를 사용하는 것이 강력히 권장됩니다.

또한, 전용 렌더링 스레드에서 QRhi 를 사용할 때 발생할 수 있는 잠재적인 데이터 경합을 피할 수 있다는 추가적인 이점도 있습니다. 이는 메인 스레드에서 업데이트된 데이터에 접근할 수 있는 QWindow 함수를 호출할 필요가 없기 때문입니다.

surfacePixelSize()도 참조하십시오 .

QRhiRenderBuffer *QRhiSwapChain::depthStencil() const

현재 깊이-스텐실용으로 연결된 렌더 버퍼를 반환합니다.

setDepthStencil()도 참조하십시오 .

QRhiSwapChain::Flags QRhiSwapChain::flags() const

현재 설정된 플래그를 반환합니다.

setFlags()도 참조하십시오 .

QRhiSwapChain::Format QRhiSwapChain::format() const

현재 설정된 형식을 반환합니다.

setFormat()도 참조하십시오 .

[virtual] QRhiSwapChainHdrInfo QRhiSwapChain::hdrInfo()

연관된 디스플레이에 대한 HDR 정보를 반환합니다.

이 작업이 비용이 적게 드는 작업이라고 가정해서는 안 됩니다. 플랫폼에 따라 이 함수는 다양한 플랫폼 쿼리를 수행하며, 이로 인해 성능에 영향을 미칠 수 있습니다.

QRhiSwapChainHdrInfo도 참조하십시오 .

[pure virtual] bool QRhiSwapChain::isFormatSupported(QRhiSwapChain::Format f)

지정된 스왑체인 형식 f 이 지원되는 경우 true를 반환합니다. SDR은 항상 지원됩니다.

이 함수의 주요 용도는 창이 이미 설정된 후 첫 번째 ` createOrResize()`를 호출하기 전에 이 함수를 호출하는 것입니다. 이를 통해 ` QRhi ` 백엔드는 플랫폼 또는 윈도우 시스템에 특화된 쿼리를 수행하여, 해당 창(및 창이 표시된 화면)이 지정된 형식으로 진정한 HDR 출력이 가능한지 확인할 수 있습니다.

포맷이 지원된다고 보고되면, ` setFormat()`를 호출하여 요청된 포맷을 설정하고 ` createOrResize()`를 호출하십시오. 그러나 이에 따른 결과를 유의해야 합니다. HDR 포맷을 성공적으로 요청하면 다른 색 공간을 처리해야 하며, HDR을 지원하지 않는 콘텐츠에 대해 화이트 레벨 보정을 수행하거나, 톤 매핑 방법을 조정하거나, 오프스크린 렌더 타겟 설정을 조정하는 등의 작업이 필요할 수 있습니다.

setFormat()도 참조하십시오 .

[pure virtual] QRhiRenderPassDescriptor *QRhiSwapChain::newCompatibleRenderPassDescriptor()

이 스왑체인과 호환되는 새로운 ` QRhiRenderPassDescriptor ` 객체를 반환합니다.

반환된 값은 두 가지 방식으로 사용됩니다. 즉, ` setRenderPassDescriptor()` 및 ` QRhiGraphicsPipeline::setRenderPassDescriptor()`에 전달될 수 있습니다. 렌더 패스 디스크립터는 ` flags()`에 의해 영향을 받을 수 있는 첨부 정보(색상, 깊이/스텐실)와 로드/저장 동작을 설명합니다. ` QRhiGraphicsPipeline `는 ` compatible ` QRhiRenderPassDescriptor 가 설정된 스왑체인에서만 사용할 수 있습니다.

createOrResize()도 참조하십시오 .

QRhiSwapChainProxyData QRhiSwapChain::proxyData() const

현재 설정된 프록시 데이터를 반환합니다.

setProxyData()도 참조하십시오 .

QRhiRenderPassDescriptor *QRhiSwapChain::renderPassDescriptor() const

현재 연결된 QRhiRenderPassDescriptor 객체를 반환합니다.

setRenderPassDescriptor()도 참조하십시오 .

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

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

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

int QRhiSwapChain::sampleCount() const

현재 설정된 샘플 수를 반환합니다. 1은 멀티샘플 앤티앨리어싱이 적용되지 않음을 의미합니다.

setSampleCount()도 참조하십시오 .

void QRhiSwapChain::setDepthStencil(QRhiRenderBuffer *ds)

렌더 버퍼 ds 를 뎁스-스텐실 버퍼로 사용하도록 설정합니다.

depthStencil()도 참조하십시오 .

void QRhiSwapChain::setFlags(QRhiSwapChain::Flags f)

f 플래그를 설정합니다.

flags()도 참조하십시오 .

void QRhiSwapChain::setFormat(QRhiSwapChain::Format f)

f 의 형식을 설정합니다.

isFormatSupported()에서 지원되지 않는 것으로 보고되는 형식은 설정하지 마십시오. 특정 형식에 대한 지원 여부는 스왑체인에 연결된 창이 열려 있는 화면에 따라 달라질 수 있습니다. Windows 및 macOS와 같은 일부 플랫폼에서는 HDR 출력이 작동하려면 디스플레이 설정에서 HDR 출력이 활성화되어 있어야 합니다.

고동적 범위(HDR) 출력에 대한 자세한 내용은 isFormatSupported(), QRhiSwapChainHdrInfo 및 Format 을 참조하십시오.

format()도 참조하십시오 .

void QRhiSwapChain::setProxyData(const QRhiSwapChainProxyData &d)

d 의 프록시 데이터를 설정합니다.

proxyData() 및 QRhi::updateSwapChainProxyData()도 참조하십시오 .

void QRhiSwapChain::setRenderPassDescriptor(QRhiRenderPassDescriptor *desc)

QRhiRenderPassDescriptor ( desc)와 제휴하고 있습니다.

renderPassDescriptor()도 참조하십시오 .

void QRhiSwapChain::setSampleCount(int samples)

샘플 수를 설정합니다. ` samples `의 일반적인 값은 1(MSAA 없음), 4(4배 MSAA) 또는 8(8배 MSAA)입니다.

sampleCount() 및 QRhi::supportedSampleCounts()도 참조하십시오 .

[since 6.9] void QRhiSwapChain::setShadingRateMap(QRhiShadingRateMap *map)

지정된 QRhiShadingRateMap map 와 연결됩니다. 이 기능은 QRhi::VariableRateShadingMap 기능이 지원되는 것으로 보고된 경우에만 작동합니다.

QRhiCommandBuffer::setShadingRate()도 호출되는 경우, 각 타일에 대해 두 셰이딩 속도 중 더 높은 쪽이 사용됩니다. 현재 콤바이너의 동작을 제어할 수 있는 방법은 제공되지 않습니다.

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

shadingRateMap()도 참조하십시오 .

void QRhiSwapChain::setWindow(QWindow *window)

window 를 설정합니다.

window()도 참조하십시오 .

[since 6.9] QRhiShadingRateMap *QRhiSwapChain::shadingRateMap() const

현재 설정된 QRhiShadingRateMap 를 반환합니다. 기본값은 nullptr 입니다.

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

setShadingRateMap()도 참조하십시오 .

[pure virtual] QSize QRhiSwapChain::surfacePixelSize()

반환값: 창과 연결된 서피스 또는 레이어의 크기.

currentPixelSize()도 참조하십시오 .

QWindow *QRhiSwapChain::window() const

현재 설정된 창을 반환합니다.

setWindow()도 참조하십시오 .