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()

返回一个命令缓冲区，在beginFrame -endFrame 块中记录渲染命令和资源更新，前提是调用了该交换链的 beginFrame()。

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

返回一个可与 beginPass() 一起使用的渲染目标，以渲染 swapchain 的当前 backbuffer。仅在QRhi::beginFrame() -QRhi::endFrame() 块中有效，其中 beginFrame() 已被调用。

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

返回一个可与 beginPass() 一起使用的渲染目标，以便渲染到交换链的左侧或右侧背缓冲区。此重载只能用于立体渲染，即相关QWindow 由两个颜色缓冲区（每只眼睛一个）支持，而不是只有一个。

不支持立体渲染时，返回值将是默认目标值。除 Metal 外，所有硬件后端都支持立体渲染，并与QSurfaceFormat::StereoBuffers 结合使用，前提是运行时图形和显示驱动程序栈支持立体渲染。Metal 和 Null 后端将通过此重载返回默认渲染目标。

QSize QRhiSwapChain::currentPixelSize() const

返回上次成功构建交换链的大小。用它来决定是否需要再次调用createOrResize(): 如果currentPixelSize() != surfacePixelSize() ，则需要调整 swapchain 的大小。

虽然在很多情况下，该值与QWindow::size() * QWindow::devicePixelRatio() 相同，但并不能保证在所有平台和图形 API 实现中，依赖QWindow 报告的尺寸都是正确的。因此，如果需要确定输出图层或曲面的像素尺寸，强烈建议使用此函数。

当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() 常量。

返回资源类型。

int QRhiSwapChain::sampleCount() const

返回当前设置的采样计数。1 表示无多采样抗锯齿。

另请参见 setSampleCount()。

void QRhiSwapChain::setDepthStencil(QRhiRenderBuffer *ds)

设置 renderbufferds ，以用作深度模版缓冲区。

另请参见 depthStencil().

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

设置标志f 。

另请参阅 flags() 。

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

设置格式f 。

避免设置isFormatSupported() 报告为不支持的格式。请注意，对特定格式的支持可能取决于打开交换链相关窗口的屏幕。在某些平台（如 Windows 和 macOS）上，要实现 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（4x MSAA）或 8（8x 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()。