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()` 配合使用，以渲染交换链的当前后缓冲区。仅在使用此交换链调用 `beginFrame()` 的 `QRhi::beginFrame()` - `QRhi::endFrame()` 代码块内有效。

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

返回一个渲染目标，该目标可与 `beginPass()` 配合使用，以将渲染结果写入交换链的左侧或右侧后缓冲区。此重载仅应在立体渲染场景中使用，即当关联的 `QWindow ` 由两个颜色缓冲区（每只眼睛各一个）支持，而非仅有一个颜色缓冲区时。

当不支持立体渲染时，返回值将为默认渲染目标。除 Metal 之外，所有硬件后端均支持此功能（需配合QSurfaceFormat::StereoBuffers 使用），前提是图形和显示驱动程序堆栈在运行时支持该功能。Metal 和 Null 后端调用此重载时将返回默认渲染目标。

QSize QRhiSwapChain::currentPixelSize() const

返回 swapchain 上一次成功构建时使用的尺寸。可利用此值判断是否需要再次调用 `createOrResize()`：如果 `currentPixelSize() != surfacePixelSize() `，则需要调整 swapchain 的大小。

虽然在许多情况下该值与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()函数。渲染通道描述符（render pass descriptor）描述了附件（颜色、深度/模板）以及可能受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 输出。

有关高动态范围输出的更多信息，请参阅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()`。