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

Member Function Documentation

[pure virtual] bool QRhiSwapChain::createOrResize()

Creates the swapchain if not already done and resizes the swapchain buffers to match the current size of the targeted surface. Call this whenever the size of the target surface is different than before.

Returns true when successful, false when a graphics operation failed. Regardless of the return value, calling destroy() is always safe.

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

Returns a command buffer on which rendering commands and resource updates can be recorded within a beginFrame - endFrame block, assuming beginFrame() was called with this swapchain.

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

Returns a render target that can used with beginPass() in order to render the swapchain's current backbuffer. Only valid within a QRhi::beginFrame() - QRhi::endFrame() block where beginFrame() was called with this swapchain.

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

Returns a render target that can be used with beginPass() in order to render to the swapchain's left or right backbuffer. This overload should be used only with stereoscopic rendering, that is, when the associated QWindow is backed by two color buffers, one for each eye, instead of just one.

When stereoscopic rendering is not supported, the return value will be the default target. It is supported by all hardware backends except for Metal, in combination with QSurfaceFormat::StereoBuffers, assuming it is supported by the graphics and display driver stack at run time. Metal and Null backends are going to return the default render target from this overload.

QSize QRhiSwapChain::currentPixelSize() const

Returns the size with which the swapchain was last successfully built. Use this to decide if createOrResize() needs to be called again: if currentPixelSize() != surfacePixelSize() then the swapchain needs to be resized.

While in many cases the value is the same as QWindow::size() * QWindow::devicePixelRatio(), relying on the QWindow-reported size is not guaranteed to be correct on all platforms and graphics API implementations. Using this function is therefore strongly recommended whenever there is a need to identify the dimensions, in pixels, of the output layer or surface.

This also has the added benefit of avoiding potential data races when QRhi is used on a dedicated rendering thread, because the need to call QWindow functions, that may then access data updated on the main thread, is avoided.

See also surfacePixelSize().

QRhiRenderBuffer *QRhiSwapChain::depthStencil() const

Returns the currently associated renderbuffer for depth-stencil.

See also setDepthStencil().

QRhiSwapChain::Flags QRhiSwapChain::flags() const

Returns the currently set flags.

See also setFlags().

QRhiSwapChain::Format QRhiSwapChain::format() const

Returns the currently set format.

See also setFormat().

[virtual] QRhiSwapChainHdrInfo QRhiSwapChain::hdrInfo()

Returns the HDR information for the associated display.

Do not assume that this is a cheap operation. Depending on the platform, this function makes various platform queries which may have a performance impact.

See also QRhiSwapChainHdrInfo.

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

Returns true if the given swapchain format f is supported. SDR is always supported.

The main use of this function is to call it before the first createOrResize() after the window is already set. This allow the QRhi backends to perform platform or windowing system specific queries to determine if the window (and the screen it is on) is capable of true HDR output with the specified format.

When the format is reported as supported, call setFormat() to set the requested format and call createOrResize(). Be aware of the consequences however: successfully requesting a HDR format will involve having to deal with a different color space, possibly doing white level correction for non-HDR-aware content, adjusting tonemapping methods, adjusting offscreen render target settings, etc.

See also setFormat().

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

Returns a new QRhiRenderPassDescriptor that is compatible with this swapchain.

The returned value is used in two ways: it can be passed to setRenderPassDescriptor() and QRhiGraphicsPipeline::setRenderPassDescriptor(). A render pass descriptor describes the attachments (color, depth/stencil) and the load/store behavior that can be affected by flags(). A QRhiGraphicsPipeline can only be used in combination with a swapchain that has a compatible QRhiRenderPassDescriptor set.

See also createOrResize().

QRhiSwapChainProxyData QRhiSwapChain::proxyData() const

Returns the currently set proxy data.

See also setProxyData().

QRhiRenderPassDescriptor *QRhiSwapChain::renderPassDescriptor() const

Returns the currently associated QRhiRenderPassDescriptor object.

See also setRenderPassDescriptor().

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

Reimplements: QRhiResource::resourceType() const.

Returns the resource type.

int QRhiSwapChain::sampleCount() const

Returns the currently set sample count. 1 means no multisample antialiasing.

See also setSampleCount().

void QRhiSwapChain::setDepthStencil(QRhiRenderBuffer *ds)

Sets the renderbuffer ds for use as a depth-stencil buffer.

See also depthStencil().

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

Sets the flags f.

See also flags().

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

Sets the format f.

Avoid setting formats that are reported as unsupported from isFormatSupported(). Note that support for a given format may depend on the screen the swapchain's associated window is opened on. On some platforms, such as Windows and macOS, for HDR output to work it is necessary to have HDR output enabled in the display settings.

See isFormatSupported(), QRhiSwapChainHdrInfo, and Format for more information on high dynamic range output.

See also format().

void QRhiSwapChain::setProxyData(const QRhiSwapChainProxyData &d)

Sets the proxy data d.

See also proxyData() and QRhi::updateSwapChainProxyData().

void QRhiSwapChain::setRenderPassDescriptor(QRhiRenderPassDescriptor *desc)

Associates with the QRhiRenderPassDescriptor desc.

See also renderPassDescriptor().

void QRhiSwapChain::setSampleCount(int samples)

Sets the sample count. Common values for samples are 1 (no MSAA), 4 (4x MSAA), or 8 (8x MSAA).

See also sampleCount() and QRhi::supportedSampleCounts().

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

Associates with the specified QRhiShadingRateMap map. This is functional only when the QRhi::VariableRateShadingMap feature is reported as supported.

When QRhiCommandBuffer::setShadingRate() is also called, the higher of two the shading rates are used for each tile. There is currently no control offered over the combiner behavior.

This function was introduced in Qt 6.9.

See also shadingRateMap().

void QRhiSwapChain::setWindow(QWindow *window)

Sets the window.

See also window().

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

Returns the currently set QRhiShadingRateMap. By default this is nullptr.

This function was introduced in Qt 6.9.

See also setShadingRateMap().

[pure virtual] QSize QRhiSwapChain::surfacePixelSize()

Returns The size of the window's associated surface or layer.

See also currentPixelSize().

QWindow *QRhiSwapChain::window() const

Returns the currently set window.

See also setWindow().