#include <qrhivulkan_p.h>

Inheritance diagram for QVkSwapChain:

Collaboration diagram for QVkSwapChain:

Classes
struct	FrameResources
struct	ImageResources

Public Member Functions
	QVkSwapChain (QRhiImplementation *rhi)
	~QVkSwapChain ()
void	destroy () override
	Releases (or requests deferred releasing of) the underlying native graphics resources.
QRhiCommandBuffer *	currentFrameCommandBuffer () override
QRhiRenderTarget *	currentFrameRenderTarget () override
QRhiRenderTarget *	currentFrameRenderTarget (StereoTargetBuffer targetBuffer) override
QSize	surfacePixelSize () override
bool	isFormatSupported (Format f) override
QRhiSwapChainHdrInfo	hdrInfo () override
	\variable QRhiSwapChainHdrInfo::limitsType
QRhiRenderPassDescriptor *	newCompatibleRenderPassDescriptor () override
bool	createOrResize () override
	Creates the swapchain if not already done and resizes the swapchain buffers to match the current size of the targeted surface.
bool	ensureSurface ()
Public Member Functions inherited from QRhiSwapChain
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.
QRhiShadingRateMap *	shadingRateMap () const
void	setShadingRateMap (QRhiShadingRateMap *map)
	Associates with the specified QRhiShadingRateMap map.
QSize	currentPixelSize () const
Public Member Functions inherited from QRhiResource
virtual	~QRhiResource ()
	Destructor.
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

Public Attributes
QWindow *	window = nullptr
QSize	pixelSize
bool	supportsReadback = false
bool	stereo = false
VkSwapchainKHR	sc = VK_NULL_HANDLE
int	bufferCount = 0
VkSurfaceKHR	surface = VK_NULL_HANDLE
VkSurfaceKHR	lastConnectedSurface = VK_NULL_HANDLE
VkFormat	colorFormat = VK_FORMAT_B8G8R8A8_UNORM
VkColorSpaceKHR	colorSpace = VK_COLOR_SPACE_SRGB_NONLINEAR_KHR
QVkRenderBuffer *	ds = nullptr
VkSampleCountFlagBits	samples = VK_SAMPLE_COUNT_1_BIT
QVarLengthArray< VkPresentModeKHR, 8 >	supportedPresentationModes
VkDeviceMemory	msaaImageMem = VK_NULL_HANDLE
QVkSwapChainRenderTarget	rtWrapper
QVkSwapChainRenderTarget	rtWrapperRight
QVkCommandBuffer	cbWrapper
VkImageView	shadingRateMapView = VK_NULL_HANDLE
QVarLengthArray< ImageResources, EXPECTED_MAX_BUFFER_COUNT >	imageRes
struct QVkSwapChain::FrameResources	frameRes [QVK_FRAMES_IN_FLIGHT]
quint32	currentImageIndex = 0
quint32	currentFrameSlot = 0
int	frameCount = 0

Static Public Attributes
static const quint32	EXPECTED_MAX_BUFFER_COUNT = 4

Friends
class	QRhiVulkan

Additional Inherited Members
Public Types inherited from QRhiSwapChain
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 , ShadingRateMap }
	Specifies type of the resource. More...
Protected Member Functions inherited from QRhiSwapChain
	QRhiSwapChain (QRhiImplementation *rhi)
Protected Member Functions inherited from QRhiResource
	QRhiResource (QRhiImplementation *rhi)
Protected Attributes inherited from QRhiSwapChain
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
QRhiShadingRateMap *	m_shadingRateMap = nullptr
Protected Attributes inherited from QRhiResource
QRhiImplementation *	m_rhi = nullptr
quint64	m_id
QByteArray	m_objectName

Detailed Description

Definition at line 599 of file qrhivulkan_p.h.

Constructor & Destructor Documentation

◆ QVkSwapChain()

QVkSwapChain::QVkSwapChain ( QRhiImplementation * rhi )

Definition at line 8618 of file qrhivulkan.cpp.

References QVkSwapChain().

Referenced by QVkSwapChain().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ~QVkSwapChain()

QVkSwapChain::~QVkSwapChain ( )

Definition at line 8626 of file qrhivulkan.cpp.

References destroy().

Here is the call graph for this function:

Member Function Documentation

◆ createOrResize()

bool QVkSwapChain::createOrResize ( )

overridevirtual

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.

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

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

Implements QRhiSwapChain.

Definition at line 8843 of file qrhivulkan.cpp.

References bufferCount, destroy(), QRhiVulkan::df, ds, frameCount, QRhiVulkan::recreateSwapChain(), and stereo.

Here is the call graph for this function:

◆ currentFrameCommandBuffer()

QRhiCommandBuffer * QVkSwapChain::currentFrameCommandBuffer ( )

overridevirtual

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

Note: 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 \l{QRhiCommandBuffer::lastCompletedGpuTime()}{lastCompletedGpuTime()}.; The value must not be cached and reused between frames. The caller should not hold on to the returned object once \l{QRhi::beginFrame()}{beginFrame()} is called again. Instead, the command buffer object should be queried again by calling this function.

Implements QRhiSwapChain.

Definition at line 8654 of file qrhivulkan.cpp.

◆ currentFrameRenderTarget() [1/2]

QRhiRenderTarget * QVkSwapChain::currentFrameRenderTarget ( )

overridevirtual

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.

Note: the value must not be cached and reused between frames

Implements QRhiSwapChain.

Definition at line 8659 of file qrhivulkan.cpp.

◆ currentFrameRenderTarget() [2/2]

QRhiRenderTarget * QVkSwapChain::currentFrameRenderTarget ( StereoTargetBuffer targetBuffer )

overridevirtual

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 \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.

Note: the value must not be cached and reused between frames

Reimplemented from QRhiSwapChain.

Definition at line 8664 of file qrhivulkan.cpp.

◆ destroy()

void QVkSwapChain::destroy ( )

overridevirtual

Releases (or requests deferred releasing of) the underlying native graphics resources.

Safe to call multiple times, subsequent invocations will be a no-op then.

Once destroy() is called, the QRhiResource instance can be reused, by calling create() again. That will then result in creating new native graphics resources underneath.

Note: Resources referenced by commands for the current frame should not be released until the frame is submitted by QRhi::endFrame().

The QRhiResource destructor also performs the same task, so calling this function is not necessary before deleting a QRhiResource.

See also: deleteLater()

Implements QRhiResource.

Definition at line 8631 of file qrhivulkan.cpp.

References QVK_FRAMES_IN_FLIGHT, QRhiVulkan::releaseSwapChainResources(), and QVkSwapChain::FrameResources::timestampQueryIndex.

Referenced by ~QVkSwapChain(), and createOrResize().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ensureSurface()

bool QVkSwapChain::ensureSurface ( )

Definition at line 8786 of file qrhivulkan.cpp.

Referenced by newCompatibleRenderPassDescriptor(), and surfacePixelSize().

Here is the caller graph for this function:

◆ hdrInfo()

QRhiSwapChainHdrInfo QVkSwapChain::hdrInfo ( )

overridevirtual

\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.

See also: QRhiSwapChain::hdrInfo()

\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:

struct {
    float minLuminance;
    float maxLuminance;
} luminanceInNits;

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.

Note: The Windows compositor works in scene-referred mode for HDR content. A color component value of 1.0 corresponds to a luminance of 80 nits. When rendering non-HDR content (e.g. 2D UI elements), the correction of the white level is often necessary. (e.g., outputting the fragment color (1, 1, 1) will likely lead to showing a shade of white that is too dim on-screen) See \l sdrWhiteLevel.

For macOS/iOS, the current maximum and potential maximum color component values are provided:

struct {
    float maxColorComponentValue;
    float maxPotentialColorComponentValue;
} colorComponentValue;

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.

Note: Apple's EDR is display-referred. 1.0 corresponds to a luminance level of SDR white (e.g. 200 nits), the value of which varies based on the screen brightness and possibly other settings. The exact luminance value for that, or the maximum luminance of the display, are not exposed to the applications.; It has been observed that the color component values are not set to the correct larger-than-1 value right away on startup on some macOS systems, but the values tend to change during or after the first frame.

See also: QRhiSwapChain::hdrInfo()

\variable QRhiSwapChainHdrInfo::luminanceBehavior

Describes the platform's presumed behavior with regards to color values.

See also: sdrWhiteLevel

\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.

See also: luminanceBehavior

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.

Note: Can be called before createOrResize() as long as the window is \l{setWindow()}{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().

See also: QRhiSwapChainHdrInfo

Reimplemented from QRhiSwapChain.

Definition at line 8733 of file qrhivulkan.cpp.

◆ isFormatSupported()

bool QVkSwapChain::isFormatSupported ( Format f )

overridevirtual

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

Note: Can be called independently of createOrResize(), but 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.

See also: setFormat()

Implements QRhiSwapChain.

Definition at line 8705 of file qrhivulkan.cpp.

◆ newCompatibleRenderPassDescriptor()

QRhiRenderPassDescriptor * QVkSwapChain::newCompatibleRenderPassDescriptor ( )

overridevirtual

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 \l{QRhiRenderPassDescriptor::isCompatible()}{compatible} QRhiRenderPassDescriptor set.

See also: createOrResize()

Implements QRhiSwapChain.

Definition at line 8745 of file qrhivulkan.cpp.

References ensureSurface(), QVkRenderPassDescriptor::ownsRp, and QVkRenderPassDescriptor::updateSerializedFormat().

Here is the call graph for this function:

◆ surfacePixelSize()

QSize QVkSwapChain::surfacePixelSize ( )

overridevirtual

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

Warning: 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}.

Note: {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.

See also: currentPixelSize()

Implements QRhiSwapChain.

Definition at line 8669 of file qrhivulkan.cpp.

References ensureSurface().

Here is the call graph for this function:

◆ QRhiVulkan

friend class QRhiVulkan

friend

Definition at line 669 of file qrhivulkan_p.h.

Member Data Documentation

◆ bufferCount

int QVkSwapChain::bufferCount = 0

Definition at line 625 of file qrhivulkan_p.h.

Referenced by QRhiVulkan::beginFrame(), createOrResize(), QRhiVulkan::endFrame(), QRhiVulkan::recreateSwapChain(), and QRhiVulkan::releaseSwapChainResources().

◆ cbWrapper

QVkCommandBuffer QVkSwapChain::cbWrapper

Definition at line 636 of file qrhivulkan_p.h.

◆ colorFormat

VkFormat QVkSwapChain::colorFormat = VK_FORMAT_B8G8R8A8_UNORM

Definition at line 628 of file qrhivulkan_p.h.

◆ colorSpace

VkColorSpaceKHR QVkSwapChain::colorSpace = VK_COLOR_SPACE_SRGB_NONLINEAR_KHR

Definition at line 629 of file qrhivulkan_p.h.

◆ currentFrameSlot

quint32 QVkSwapChain::currentFrameSlot = 0

Definition at line 666 of file qrhivulkan_p.h.

◆ currentImageIndex

quint32 QVkSwapChain::currentImageIndex = 0

Definition at line 665 of file qrhivulkan_p.h.

◆ ds

QVkRenderBuffer* QVkSwapChain::ds = nullptr

Definition at line 630 of file qrhivulkan_p.h.

Referenced by createOrResize().

◆ EXPECTED_MAX_BUFFER_COUNT

const quint32 QVkSwapChain::EXPECTED_MAX_BUFFER_COUNT = 4

static

Definition at line 618 of file qrhivulkan_p.h.

◆ frameCount

int QVkSwapChain::frameCount = 0

Definition at line 667 of file qrhivulkan_p.h.

Referenced by createOrResize(), and QRhiVulkan::endFrame().

◆ frameRes

struct QVkSwapChain::FrameResources QVkSwapChain::frameRes[QVK_FRAMES_IN_FLIGHT]

◆ imageRes

QVarLengthArray<ImageResources, EXPECTED_MAX_BUFFER_COUNT> QVkSwapChain::imageRes

Definition at line 653 of file qrhivulkan_p.h.

◆ lastConnectedSurface

VkSurfaceKHR QVkSwapChain::lastConnectedSurface = VK_NULL_HANDLE

Definition at line 627 of file qrhivulkan_p.h.

◆ msaaImageMem

VkDeviceMemory QVkSwapChain::msaaImageMem = VK_NULL_HANDLE

Definition at line 633 of file qrhivulkan_p.h.

◆ pixelSize

QSize QVkSwapChain::pixelSize

Definition at line 621 of file qrhivulkan_p.h.

◆ rtWrapper

QVkSwapChainRenderTarget QVkSwapChain::rtWrapper

Definition at line 634 of file qrhivulkan_p.h.

◆ rtWrapperRight

QVkSwapChainRenderTarget QVkSwapChain::rtWrapperRight

Definition at line 635 of file qrhivulkan_p.h.

◆ samples

VkSampleCountFlagBits QVkSwapChain::samples = VK_SAMPLE_COUNT_1_BIT

Definition at line 631 of file qrhivulkan_p.h.

◆ sc

VkSwapchainKHR QVkSwapChain::sc = VK_NULL_HANDLE

Definition at line 624 of file qrhivulkan_p.h.

◆ shadingRateMapView

VkImageView QVkSwapChain::shadingRateMapView = VK_NULL_HANDLE

Definition at line 637 of file qrhivulkan_p.h.

◆ stereo

bool QVkSwapChain::stereo = false

Definition at line 623 of file qrhivulkan_p.h.

Referenced by QRhiVulkan::beginFrame(), createOrResize(), QRhiVulkan::recreateSwapChain(), and QRhiVulkan::releaseSwapChainResources().

◆ supportedPresentationModes

QVarLengthArray<VkPresentModeKHR, 8> QVkSwapChain::supportedPresentationModes

Definition at line 632 of file qrhivulkan_p.h.

◆ supportsReadback

bool QVkSwapChain::supportsReadback = false

Definition at line 622 of file qrhivulkan_p.h.

Referenced by QRhiVulkan::enqueueResourceUpdates().

◆ surface

VkSurfaceKHR QVkSwapChain::surface = VK_NULL_HANDLE

Definition at line 626 of file qrhivulkan_p.h.

◆ window

QWindow* QVkSwapChain::window = nullptr

Definition at line 620 of file qrhivulkan_p.h.

The documentation for this struct was generated from the following files:

qtbase/src/gui/rhi/qrhivulkan_p.h (0e51db1eb51d15463b70e35fcdda772594e63aac)
qtbase/src/gui/rhi/qrhivulkan.cpp (73a18c3eba6fe5b4ff80f386028dd892da5944d6)

Classes

Public Member Functions

Public Attributes

Static Public Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QVkSwapChain()

◆ ~QVkSwapChain()

Member Function Documentation

◆ createOrResize()

◆ currentFrameCommandBuffer()

◆ currentFrameRenderTarget() [1/2]

◆ currentFrameRenderTarget() [2/2]

◆ destroy()

◆ ensureSurface()

◆ hdrInfo()

◆ isFormatSupported()

◆ newCompatibleRenderPassDescriptor()

◆ surfacePixelSize()

Friends And Related Symbol Documentation

◆ QRhiVulkan

Member Data Documentation

◆ bufferCount

◆ cbWrapper

◆ colorFormat

◆ colorSpace

◆ currentFrameSlot

◆ currentImageIndex

◆ ds

◆ EXPECTED_MAX_BUFFER_COUNT

◆ frameCount

◆ frameRes

◆ imageRes

◆ lastConnectedSurface

◆ msaaImageMem

◆ pixelSize

◆ rtWrapper

◆ rtWrapperRight

◆ samples

◆ sc

◆ shadingRateMapView

◆ stereo

◆ supportedPresentationModes

◆ supportsReadback

◆ surface

◆ window