Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
|
\inmodule QtGui More...
#include <qrhi.h>
Public Types | |
enum | Flag { SurfaceHasPreMulAlpha = 1 << 0 , SurfaceHasNonPreMulAlpha = 1 << 1 , sRGB = 1 << 2 , UsedAsTransferSource = 1 << 3 , NoVSync = 1 << 4 , MinimalBufferCount = 1 << 5 } |
Flag values to describe swapchain properties. More... | |
enum | Format { SDR , HDRExtendedSrgbLinear , HDR10 , HDRExtendedDisplayP3Linear } |
Describes the swapchain format. More... | |
enum | StereoTargetBuffer { LeftBuffer , RightBuffer } |
Selects the backbuffer to use with a stereoscopic swapchain. More... | |
Public Types inherited from QRhiResource | |
enum | Type { Buffer , Texture , Sampler , RenderBuffer , RenderPassDescriptor , SwapChainRenderTarget , TextureRenderTarget , ShaderResourceBindings , GraphicsPipeline , SwapChain , ComputePipeline , CommandBuffer } |
Specifies type of the resource. More... | |
Public Member Functions | |
QRhiResource::Type | resourceType () const override |
QWindow * | window () const |
void | setWindow (QWindow *window) |
Sets the window. | |
QRhiSwapChainProxyData | proxyData () const |
void | setProxyData (const QRhiSwapChainProxyData &d) |
Sets the proxy data d. | |
Flags | flags () const |
void | setFlags (Flags f) |
Sets the flags f. | |
Format | format () const |
void | setFormat (Format f) |
Sets the format f. | |
QRhiRenderBuffer * | depthStencil () const |
void | setDepthStencil (QRhiRenderBuffer *ds) |
Sets the renderbuffer ds for use as a depth-stencil buffer. | |
int | sampleCount () const |
void | setSampleCount (int samples) |
Sets the sample count. | |
QRhiRenderPassDescriptor * | renderPassDescriptor () const |
void | setRenderPassDescriptor (QRhiRenderPassDescriptor *desc) |
Associates with the QRhiRenderPassDescriptor desc. | |
QSize | currentPixelSize () const |
virtual QRhiCommandBuffer * | currentFrameCommandBuffer ()=0 |
virtual QRhiRenderTarget * | currentFrameRenderTarget ()=0 |
virtual QRhiRenderTarget * | currentFrameRenderTarget (StereoTargetBuffer targetBuffer) |
virtual QSize | surfacePixelSize ()=0 |
virtual bool | isFormatSupported (Format f)=0 |
virtual QRhiRenderPassDescriptor * | newCompatibleRenderPassDescriptor ()=0 |
virtual bool | createOrResize ()=0 |
Creates the swapchain if not already done and resizes the swapchain buffers to match the current size of the targeted surface. | |
virtual QRhiSwapChainHdrInfo | hdrInfo () |
\variable QRhiSwapChainHdrInfo::limitsType | |
Public Member Functions inherited from QRhiResource | |
virtual | ~QRhiResource () |
Destructor. | |
virtual void | destroy ()=0 |
Releases (or requests deferred releasing of) the underlying native graphics resources. | |
void | deleteLater () |
When called without a frame being recorded, this function is equivalent to deleting the object. | |
QByteArray | name () const |
void | setName (const QByteArray &name) |
Sets a name for the object. | |
quint64 | globalResourceId () const |
QRhi * | rhi () const |
Protected Member Functions | |
QRhiSwapChain (QRhiImplementation *rhi) | |
Protected Member Functions inherited from QRhiResource | |
QRhiResource (QRhiImplementation *rhi) | |
Protected Attributes | |
QWindow * | m_window = nullptr |
Flags | m_flags |
Format | m_format = SDR |
QRhiRenderBuffer * | m_depthStencil = nullptr |
int | m_sampleCount = 1 |
QRhiRenderPassDescriptor * | m_renderPassDesc = nullptr |
QSize | m_currentPixelSize |
QRhiSwapChainProxyData | m_proxyData |
Protected Attributes inherited from QRhiResource | |
QRhiImplementation * | m_rhi = nullptr |
quint64 | m_id |
QByteArray | m_objectName |
\inmodule QtGui
Swapchain resource.
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:
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:
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.
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 \l{https://developer.apple.com/documentation/corevideo/cvdisplaylink?language=objc}{CVDisplayLink}. The example above is already prepared for update requests by handling QEvent::UpdateRequest.
While acting as a QRhiRenderTarget, QRhiSwapChain also manages a QRhiCommandBuffer. Calling 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.
enum QRhiSwapChain::Flag |
Flag values to describe swapchain properties.
\value SurfaceHasPreMulAlpha 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.
\value SurfaceHasNonPreMulAlpha 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.
\value sRGB 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 \l{QSurfaceFormat::sRGBColorSpace}{sRGBColorSpace} on the QSurfaceFormat of the QWindow in addition. Applicable only when the swapchain format is set to QRhiSwapChain::SDR.
\value UsedAsTransferSource Indicates the swapchain will be used as the source of a readback in QRhiResourceUpdateBatch::readBackTexture().
\value NoVSync 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 via QSurfaceFormat::setSwapInterval().
\value MinimalBufferCount 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).
Enumerator | |
---|---|
SurfaceHasPreMulAlpha | |
SurfaceHasNonPreMulAlpha | |
sRGB | |
UsedAsTransferSource | |
NoVSync | |
MinimalBufferCount |
Describes the swapchain format.
The default format is SDR.
This enum is used with \l{QRhiSwapChain::isFormatSupported()}{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 \l{QRhiSwapChain::setFormat()}{setFormat()} to set the requested format in the swapchain before calling \l{QRhiSwapChain::createOrResize()}{createOrResize()} for the first time.
\value SDR 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 flag.
\value HDRExtendedSrgbLinear 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.
\value HDR10 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.
\value HDRExtendedDisplayP3Linear 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.
Enumerator | |
---|---|
SDR | |
HDRExtendedSrgbLinear | |
HDR10 | |
HDRExtendedDisplayP3Linear |
|
protected |
|
pure virtual |
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.
true
when successful, false
when a graphics operation failed. Regardless of the return value, calling destroy() is always safe. Implemented in QD3D11SwapChain, QGles2SwapChain, QMetalSwapChain, QNullSwapChain, and QVkSwapChain.
Referenced by QBackingStoreDefaultCompositor::flush(), QSGGuiThreadRenderLoop::renderWindow(), QBackingStoreRhiSupport::swapChainForWindow(), and QSGRenderThread::syncAndRender().
|
pure virtual |
Implemented in QD3D11SwapChain, QGles2SwapChain, QMetalSwapChain, QNullSwapChain, and QVkSwapChain.
Referenced by QSGRenderThread::event(), QBackingStoreDefaultCompositor::flush(), QSGGuiThreadRenderLoop::grab(), QQuickRhiItemNode::queryCommandBuffer(), QQuick3DSceneRenderer::renderToRhiTexture(), QSGGuiThreadRenderLoop::renderWindow(), and QSGRenderThread::syncAndRender().
|
pure virtual |
Implemented in QD3D11SwapChain, QGles2SwapChain, QMetalSwapChain, QNullSwapChain, and QVkSwapChain.
Referenced by currentFrameRenderTarget(), and QBackingStoreDefaultCompositor::flush().
|
virtual |
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 \l 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.
Reimplemented in QD3D11SwapChain, QGles2SwapChain, and QVkSwapChain.
Definition at line 7471 of file qrhi.cpp.
References currentFrameRenderTarget(), and Q_UNUSED.
|
inline |
{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.
Definition at line 1596 of file qrhi.h.
Referenced by QBackingStoreDefaultCompositor::flush(), QSGGuiThreadRenderLoop::renderWindow(), QRhiNull::resourceUpdate(), and QSGRenderThread::syncAndRender().
|
inline |
|
inline |
|
inline |
Definition at line 1584 of file qrhi.h.
Referenced by QD3D11SwapChain::newColorBuffer(), and qShouldUpdateSwapChainFormat().
|
virtual |
\variable QRhiSwapChainHdrInfo::limitsType
With Metal on macOS/iOS, there is no luminance values exposed in the platform APIs. Instead, the maximum color component value, that would be 1.0 in a non-HDR setup, is provided. This value indicates what kind of information is available in \l limits.
\variable QRhiSwapChainHdrInfo::limits
Contains the actual values queried from the graphics API or the platform. The type of data is indicated by \l limitsType. This is therefore a union. There are currently two options:
Luminance values in nits:
On Windows the minimum and maximum luminance depends on the screen brightness. While not relevant for desktops, on laptops the screen brightness may change at any time. Increasing brightness implies decreased maximum luminance. In addition, the results may also be dependent on the HDR Content Brightness set in Windows Settings' System/Display/HDR view, if there is such a setting.
Note however that the changes made to the laptop screen's brightness or in the system settings while the application is running are not necessarily reflected in the returned values, meaning calling hdrInfo() again may still return the same luminance range as before for the rest of the process' lifetime. The exact behavior is up to DXGI and Qt has no control over it.
For macOS/iOS, the current maximum and potential maximum color component values are provided:
The value may depend on the screen brightness, which on laptops means that the result may change in the next call to hdrInfo() if the brightness was changed in the meantime. The maximum screen brightness implies a maximum color value of 1.0.
\variable QRhiSwapChainHdrInfo::luminanceBehavior
Describes the platform's presumed behavior with regards to color values.
\variable QRhiSwapChainHdrInfo::sdrWhiteLevel
On Windows this is the dynamic SDR white level in nits. The value is dependent on the screen brightness (on laptops), and the SDR or HDR Content Brightness settings in the Windows settings' System/Display/HDR view.
To perform white level correction for non-HDR (SDR) content, such as 2D UI elemenents, multiply the final color with sdrWhiteLevel / 80.0 whenever \l luminanceBehavior is SceneReferred. (assuming Windows and a linear extended sRGB (scRGB) color space)
On other platforms the value is always a pre-defined value, 200. This may not match the system's actual SDR white level, but the value of this variable is not relevant in practice when the \l luminanceBehavior is DisplayReferred, because then the color component value of 1.0 refers to the SDR white by default.
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.
Reimplemented in QD3D11SwapChain, and QMetalSwapChain.
Definition at line 7797 of file qrhi.cpp.
References info, QRhiSwapChainHdrInfo::LuminanceInNits, and QRhiSwapChainHdrInfo::SceneReferred.
Referenced by QD3D11SwapChain::hdrInfo().
|
pure virtual |
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.
Implemented in QD3D11SwapChain, QGles2SwapChain, QMetalSwapChain, QNullSwapChain, and QVkSwapChain.
Referenced by qShouldUpdateSwapChainFormat().
|
pure virtual |
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 \l{QRhiRenderPassDescriptor::isCompatible()}{compatible} QRhiRenderPassDescriptor set.
Implemented in QD3D11SwapChain, QGles2SwapChain, QMetalSwapChain, QNullSwapChain, and QVkSwapChain.
Referenced by QSGRenderThread::ensureRhi(), QSGGuiThreadRenderLoop::ensureRhi(), and QBackingStoreRhiSupport::swapChainForWindow().
|
inline |
|
inline |
Definition at line 1593 of file qrhi.h.
Referenced by QBackingStoreDefaultCompositor::flush(), and QBackingStoreRhiSupport::swapChainForWindow().
|
overridevirtual |
Implements QRhiResource.
Definition at line 7321 of file qrhi.cpp.
References QRhiResource::SwapChain.
|
inline |
|
inline |
Sets the renderbuffer ds for use as a depth-stencil buffer.
Definition at line 1588 of file qrhi.h.
Referenced by QSGRenderThread::ensureRhi(), and QSGGuiThreadRenderLoop::ensureRhi().
Sets the flags f.
Definition at line 1582 of file qrhi.h.
Referenced by QSGRenderThread::ensureRhi(), QSGGuiThreadRenderLoop::ensureRhi(), and QBackingStoreRhiSupport::swapChainForWindow().
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(), \l QRhiSwapChainHdrInfo, and \l Format for more information on high dynamic range output.
|
inline |
Sets the proxy data d.
Definition at line 1579 of file qrhi.h.
References d.
Referenced by QSGRenderThread::ensureRhi(), and QSGRenderThread::syncAndRender().
|
inline |
Associates with the QRhiRenderPassDescriptor desc.
Definition at line 1594 of file qrhi.h.
Referenced by QSGRenderThread::ensureRhi(), QSGGuiThreadRenderLoop::ensureRhi(), and QBackingStoreRhiSupport::swapChainForWindow().
|
inline |
Sets the sample count.
Common values for samples are 1 (no MSAA), 4 (4x MSAA), or 8 (8x MSAA).
Definition at line 1591 of file qrhi.h.
Referenced by QSGRenderThread::ensureRhi(), and QSGGuiThreadRenderLoop::ensureRhi().
Sets the window.
Definition at line 1576 of file qrhi.h.
References window().
Referenced by QSGRenderThread::ensureRhi(), QSGGuiThreadRenderLoop::ensureRhi(), and QBackingStoreRhiSupport::swapChainForWindow().
|
pure virtual |
{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}.Implemented in QD3D11SwapChain, QGles2SwapChain, QMetalSwapChain, QNullSwapChain, and QVkSwapChain.
Referenced by QSGGuiThreadRenderLoop::exposureChanged(), QSGThreadedRenderLoop::exposureChanged(), QBackingStoreDefaultCompositor::flush(), QSGGuiThreadRenderLoop::renderWindow(), and QSGRenderThread::syncAndRender().
|
inline |
Definition at line 1575 of file qrhi.h.
Referenced by QBackingStoreDefaultCompositor::flush().
|
protected |
Definition at line 1615 of file qrhi.h.
Referenced by QD3D11SwapChain::createOrResize(), QGles2SwapChain::createOrResize(), QMetalSwapChain::createOrResize(), QNullSwapChain::createOrResize(), and QVkSwapChain::createOrResize().
|
protected |
Definition at line 1612 of file qrhi.h.
Referenced by QD3D11SwapChain::createOrResize(), QGles2SwapChain::createOrResize(), QMetalSwapChain::createOrResize(), QVkSwapChain::createOrResize(), QGles2SwapChain::initSwapChainRenderTarget(), QMetalSwapChain::newCompatibleRenderPassDescriptor(), and QVkSwapChain::newCompatibleRenderPassDescriptor().
|
protected |
Definition at line 1610 of file qrhi.h.
Referenced by QMetalSwapChain::chooseFormats(), QD3D11SwapChain::createOrResize(), QMetalSwapChain::createOrResize(), QVkSwapChain::ensureSurface(), and QGles2SwapChain::initSwapChainRenderTarget().
Definition at line 1611 of file qrhi.h.
Referenced by QMetalSwapChain::chooseFormats(), QD3D11SwapChain::createOrResize(), QMetalSwapChain::createOrResize(), and QVkSwapChain::ensureSurface().
|
protected |
Definition at line 1616 of file qrhi.h.
Referenced by QMetalSwapChain::createOrResize(), QMetalSwapChain::destroy(), and QMetalSwapChain::surfacePixelSize().
|
protected |
Definition at line 1614 of file qrhi.h.
Referenced by QD3D11SwapChain::createOrResize(), QMetalSwapChain::createOrResize(), QNullSwapChain::createOrResize(), QVkSwapChain::createOrResize(), and QGles2SwapChain::initSwapChainRenderTarget().
|
protected |
Definition at line 1613 of file qrhi.h.
Referenced by QMetalSwapChain::chooseFormats(), QD3D11SwapChain::createOrResize(), QMetalSwapChain::createOrResize(), QVkSwapChain::createOrResize(), QVkSwapChain::ensureSurface(), and QGles2SwapChain::initSwapChainRenderTarget().
Definition at line 1609 of file qrhi.h.
Referenced by QD3D11SwapChain::createOrResize(), QGles2SwapChain::createOrResize(), QMetalSwapChain::createOrResize(), QNullSwapChain::createOrResize(), QVkSwapChain::createOrResize(), QVkSwapChain::ensureSurface(), QD3D11SwapChain::hdrInfo(), QMetalSwapChain::hdrInfo(), QGles2SwapChain::initSwapChainRenderTarget(), QD3D11SwapChain::isFormatSupported(), QVkSwapChain::isFormatSupported(), QD3D11SwapChain::surfacePixelSize(), QGles2SwapChain::surfacePixelSize(), QMetalSwapChain::surfacePixelSize(), and QVkSwapChain::surfacePixelSize().