QRhiSwapChain Class

Swapchain resource. 更多...

头：	#include <QRhiSwapChain>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake:	QT += gui
Since:	Qt 6.6
继承：	QRhiResource

所有成员列表，包括继承成员

公共类型

enum	Flag { SurfaceHasPreMulAlpha, SurfaceHasNonPreMulAlpha, sRGB, UsedAsTransferSource, NoVSync, MinimalBufferCount }
flags	Flags
enum	Format { SDR, HDRExtendedSrgbLinear, HDR10, HDRExtendedDisplayP3Linear }
enum	StereoTargetBuffer { LeftBuffer, RightBuffer }

公共函数

virtual bool	createOrResize () = 0
virtual QRhiCommandBuffer *	currentFrameCommandBuffer () = 0
virtual QRhiRenderTarget *	currentFrameRenderTarget () = 0
virtual QRhiRenderTarget *	currentFrameRenderTarget (QRhiSwapChain::StereoTargetBuffer targetBuffer )
QSize	currentPixelSize () const
QRhiRenderBuffer *	depthStencil () const
QRhiSwapChain::Flags	flags () const
QRhiSwapChain::Format	format () const
virtual QRhiSwapChainHdrInfo	hdrInfo ()
virtual bool	isFormatSupported (QRhiSwapChain::Format f ) = 0
virtual QRhiRenderPassDescriptor *	newCompatibleRenderPassDescriptor () = 0
QRhiSwapChainProxyData	proxyData () const
QRhiRenderPassDescriptor *	renderPassDescriptor () const
int	sampleCount () const
void	setDepthStencil (QRhiRenderBuffer * ds )
void	setFlags (QRhiSwapChain::Flags f )
void	setFormat (QRhiSwapChain::Format f )
void	setProxyData (const QRhiSwapChainProxyData & d )
void	setRenderPassDescriptor (QRhiRenderPassDescriptor * desc )
void	setSampleCount (int samples )
void	setWindow (QWindow * window )
virtual QSize	surfacePixelSize () = 0
QWindow *	window () const

重实现公共函数

virtual QRhiResource::Type

resourceType () const override

详细描述

A swapchain enables presenting rendering results to a surface. A swapchain is typically backed by a set of color buffers. Of these, one is displayed at a time.

Below is a typical pattern for creating and managing a swapchain and some associated resources in order to render onto a QWindow :

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

Avoid relying on QWindow resize events to resize swapchains, especially considering that surface sizes may not always fully match the QWindow reported dimensions. The safe, cross-platform approach is to do the check via surfacePixelSize () whenever starting a new frame.

Releasing the swapchain must happen while the QWindow and the underlying native window is fully up and running. Building on the previous example:

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

Initializing the swapchain and starting to render the first frame cannot start at any time. The safe, cross-platform approach is to rely on expose events. QExposeEvent is a loosely specified event that is sent whenever a window gets mapped, obscured, and resized, depending on the platform.

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

Once the rendering has started, a simple way to request a new frame is QWindow::requestUpdate (). While on some platforms this is merely a small timer, on others it has a specific implementation: for instance on macOS or iOS it may be backed by CVDisplayLink . The example above is already prepared for update requests by handling QEvent::UpdateRequest .

While acting as a QRhiRenderTarget , QRhiSwapChain also manages a QRhiCommandBuffer 。调用 QRhi::endFrame () submits the recorded commands and also enqueues a present request. The default behavior is to do this with a swap interval of 1, meaning synchronizing to the display's vertical refresh is enabled. Thus the rendering thread calling beginFrame() and endFrame() will get throttled to vsync. On some backends this can be disabled by passing QRhiSwapChain: NoVSync in flags ().

Multisampling (MSAA) is handled transparently to the applications when requested via setSampleCount (). Where applicable, QRhiSwapChain will take care of creating additional color buffers and issuing a multisample resolve command at the end of a frame. For OpenGL, it is necessary to request the appropriate sample count also via QSurfaceFormat , by calling QSurfaceFormat::setDefaultFormat () before initializing the QRhi .

注意： This is a RHI API with limited compatibility guarantees, see QRhi 了解细节。

成员类型文档编制

enum QRhiSwapChain:: Flag
flags QRhiSwapChain:: Flags

Flag values to describe swapchain properties

常量	值	描述
`QRhiSwapChain::SurfaceHasPreMulAlpha`	`1 << 0`	Indicates that the target surface has transparency with premultiplied alpha. For example, this is what Qt Quick uses when the alpha channel is enabled on the target QWindow , because the scenegraph rendrerer always outputs fragments with alpha multiplied into the red, green, and blue values. To ensure identical behavior across platforms, always set QSurfaceFormat::alphaBufferSize () to a non-zero value on the target QWindow whenever this flag is set on the swapchain.
`QRhiSwapChain::SurfaceHasNonPreMulAlpha`	`1 << 1`	Indicates the target surface has transparency with non-premultiplied alpha. Be aware that this may not be supported on some systems, if the system compositor always expects content with premultiplied alpha. In that case the behavior with this flag set is expected to be equivalent to SurfaceHasPreMulAlpha.
`QRhiSwapChain::sRGB`	`1 << 2`	Requests to pick an sRGB format for the swapchain's color buffers and/or render target views, where applicable. Note that this implies that sRGB framebuffer update and blending will get enabled for all content targeting this swapchain, and opting out is not possible. For OpenGL, set sRGBColorSpace 在 QSurfaceFormat 的 QWindow in addition. Applicable only when the swapchain format is set to QRhiSwapChain::SDR .
`QRhiSwapChain::UsedAsTransferSource`	`1 << 3`	Indicates the swapchain will be used as the source of a readback in QRhiResourceUpdateBatch::readBackTexture ().
`QRhiSwapChain::NoVSync`	`1 << 4`	Requests disabling waiting for vertical sync, also avoiding throttling the rendering thread. The behavior is backend specific and applicable only where it is possible to control this. Some may ignore the request altogether. For OpenGL, try instead setting the swap interval to 0 on the QWindow 凭借 QSurfaceFormat::setSwapInterval ().
`QRhiSwapChain::MinimalBufferCount`	`1 << 5`	Requests creating the swapchain with the minimum number of buffers, which is in practice 2, unless the graphics implementation has a higher minimum number than that. Only applicable with backends where such control is available via the graphics API, for example, Vulkan. By default it is up to the backend to decide what number of buffers it requests (in practice this is almost always either 2 or 3), and it is not the applications' concern. However, on Vulkan for instance the backend will likely prefer the higher number (3), for example to avoid odd performance issues with some Vulkan implementations on mobile devices. It could be that on some platforms it can prove to be beneficial to force the lower buffer count (2), so this flag allows forcing that. Note that all this has no effect on the number of frames kept in flight, so the CPU ( QRhi ) will still prepare frames at most `N - 1` frames ahead of the GPU, even when the swapchain image buffer count larger than `N` . ( `N` = QRhi::FramesInFlight and typically 2).

Flags 类型是 typedef 对于 QFlags <Flag>。它存储 Flag 值的 OR 组合。

enum QRhiSwapChain:: Format

Describes the swapchain format. The default format is SDR.

此枚举用于 isFormatSupported () to check upfront if creating the swapchain with the given format is supported by the platform and the window's associated screen, and with setFormat () to set the requested format in the swapchain before calling createOrResize () for the first time.

常量	值	描述
`QRhiSwapChain::SDR`	`0`	8-bit RGBA or BGRA, depending on the backend and platform. With OpenGL ES in particular, it could happen that the platform provides less than 8 bits (e.g. due to EGL and the QSurfaceFormat choosing a 565 or 444 format - this is outside the control of QRhi ). Standard dynamic range. May be combined with setting the QRhiSwapChain::sRGB 标志。
`QRhiSwapChain::HDRExtendedSrgbLinear`	`1`	16-bit float RGBA, high dynamic range, extended linear sRGB (scRGB) color space. This involves Rec. 709 primaries (same as SDR/sRGB) and linear colors. Conversion to the display's native color space (such as, HDR10) is performed by the windowing system. On Windows this is the canonical color space of the system compositor, and is the recommended format for HDR swapchains in general on desktop platforms.
`QRhiSwapChain::HDR10`	`2`	10-bit unsigned int RGB or BGR with 2 bit alpha, high dynamic range, HDR10 (Rec. 2020) color space with an ST2084 PQ transfer function.
`QRhiSwapChain::HDRExtendedDisplayP3Linear`	`3`	16-bit float RGBA, high dynamic range, extended linear Display P3 color space. The primary choice for HDR on platforms such as iOS and VisionOS.

enum QRhiSwapChain:: StereoTargetBuffer

Selects the backbuffer to use with a stereoscopic swapchain.

常量	值
`QRhiSwapChain::LeftBuffer`	`0`
`QRhiSwapChain::RightBuffer`	`1`

成员函数文档编制

`[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.

注意： call destroy () only when the swapchain needs to be released completely, typically upon QPlatformSurfaceEvent::SurfaceAboutToBeDestroyed . To perform resizing, just call createOrResize().

返回 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.

注意： The returned object is valid also after endFrame(), up until the next beginFrame(), but the returned command buffer should not be used to record any commands then. Rather, it can be used to query data collected during the frame (or previous frames), for example by calling lastCompletedGpuTime ().

注意： The value must not be cached and reused between frames. The caller should not hold on to the returned object once beginFrame () is called again. Instead, the command buffer object should be queried again by calling this function.

`[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.

注意： the value must not be cached and reused between frames

`[虚拟]` 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.

注意： the value must not be cached and reused between frames

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.

注意： Typical rendering logic will call this function to get the output size when starting to prepare a new frame, and base dependent calculations (such as, the viewport) on the size returned from this function.

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.

另请参阅 surfacePixelSize ().

QRhiRenderBuffer *QRhiSwapChain:: depthStencil () const

Returns the currently associated renderbuffer for depth-stencil.

另请参阅 setDepthStencil ().

QRhiSwapChain::Flags QRhiSwapChain:: flags () const

Returns the currently set flags.

另请参阅 setFlags ().

QRhiSwapChain::Format QRhiSwapChain:: format () const

Returns the currently set format.

另请参阅 setFormat ().

`[虚拟]` 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.

注意： Can be called before createOrResize () as long as the window is set .

注意： What happens when moving a window with an initialized swapchain between displays (HDR to HDR with different characteristics, HDR to SDR, etc.) is not currently well-defined and depends heavily on the windowing system and compositor, with potentially varying behavior between platforms. Currently QRhi only guarantees that hdrInfo() returns valid data, if available, for the display to which the swapchain's associated window belonged at the time of createOrResize ().

另请参阅 QRhiSwapChainHdrInfo .

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

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

注意： Can be called independently of createOrResize ()，但 window () must already be set. Calling without the window set may lead to unexpected results depending on the backend and platform (most likely false for any HDR format), because HDR format support is usually tied to the output (screen) to which the swapchain's associated window belongs at any given time. If the result is true for a HDR format, then creating the swapchain with that format is expected to succeed as long as the window is not moved to another screen in the meantime.

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.

另请参阅 setFormat ().

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

返回新的 QRhiRenderPassDescriptor that is compatible with this swapchain.

The returned value is used in two ways: it can be passed to setRenderPassDescriptor () 和 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.

另请参阅 createOrResize ().

QRhiSwapChainProxyData QRhiSwapChain:: proxyData () const

Returns the currently set proxy data.

另请参阅 setProxyData ().

QRhiRenderPassDescriptor *QRhiSwapChain:: renderPassDescriptor () const

Returns the currently associated QRhiRenderPassDescriptor 对象。

另请参阅 setRenderPassDescriptor ().

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

重实现： QRhiResource::resourceType() const .

Returns the resource type.

int QRhiSwapChain:: sampleCount () const

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

另请参阅 setSampleCount ().

void QRhiSwapChain:: setDepthStencil ( QRhiRenderBuffer * ds )

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

另请参阅 depthStencil ().

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

Sets the flags f .

另请参阅 flags ().

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

设置格式 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.

见 isFormatSupported (), QRhiSwapChainHdrInfo ，和 Format for more information on high dynamic range output.

另请参阅 format ().

void QRhiSwapChain:: setProxyData (const QRhiSwapChainProxyData & d )

Sets the proxy data d .

另请参阅 proxyData () 和 QRhi::updateSwapChainProxyData ().

void QRhiSwapChain:: setRenderPassDescriptor ( QRhiRenderPassDescriptor * desc )

Associates with the QRhiRenderPassDescriptor desc .

另请参阅 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).

另请参阅 sampleCount () 和 QRhi::supportedSampleCounts ().

void QRhiSwapChain:: setWindow ( QWindow * window )

设置 window .

另请参阅 window ().

`[pure virtual]` QSize QRhiSwapChain:: surfacePixelSize ()

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

警告： Do not assume this is the same as QWindow::size() * QWindow::devicePixelRatio() . With some graphics APIs and windowing system interfaces (for example, Vulkan) there is a theoretical possibility for a surface to assume a size different from the associated window. To support these cases, rendering logic must always base size-derived calculations (such as, viewports) on the size reported from QRhiSwapChain , and never on the size queried from QWindow .

注意： Can also be called before createOrResize (), if at least window () is already set. This in combination with currentPixelSize () allows to detect when a swapchain needs to be resized. However, watch out for the fact that the size of the underlying native object (surface, layer, or similar) is "live", so whenever this function is called, it returns the latest value reported by the underlying implementation, without any atomicity guarantee. Therefore, using this function to determine pixel sizes for graphics resources that are used in a frame is strongly discouraged. Rely on currentPixelSize () instead which returns a size that is atomic and will not change between createOrResize () invocations.

注意： For depth-stencil buffers used in combination with the swapchain's color buffers, it is strongly recommended to rely on the automatic sizing and rebuilding behavior provided by the QRhiRenderBuffer :UsedWithSwapChainOnly flag. Avoid querying the surface size via this function just to get a size that can be passed to QRhiRenderBuffer::setPixelSize () as that would suffer from the lack of atomicity as described above.

另请参阅 currentPixelSize ().

QWindow *QRhiSwapChain:: window () const

Returns the currently set window.

另请参阅 setWindow ().