Swap-chain interface. More...

#include <SwapChain.h>

Inheritance diagram for LLGL::SwapChain:

Public Member Functions
	~SwapChain ()
	Release the internal data.
Extent2D	GetResolution () const final
	Returns the resolution of the current video mode.
std::uint32_t	GetNumColorAttachments () const final
	Returns 1, since each swap-chain has always a single color attachment.
bool	HasDepthAttachment () const final
	Returns true if this swap-chain has a depth format.
bool	HasStencilAttachment () const final
	Returns true if this swap-chain has a stencil format.
virtual bool	IsPresentable () const =0
	Returns true if this swap-chain is ready for rendering and presenting. Otherwise, the native surface or back buffer are not available.
virtual void	Present ()=0
	Swaps the current back buffer with the front buffer to present it on the screen.
virtual std::uint32_t	GetCurrentSwapIndex () const =0
	Returns the current swap-buffer index.
virtual std::uint32_t	GetNumSwapBuffers () const =0
	Returns the actual number of swap-buffers in this swap-chain.
virtual Format	GetColorFormat () const =0
	Returns the color format of this swap-chain.
virtual Format	GetDepthStencilFormat () const =0
	Returns the depth-stencil format of this swap-chain.
bool	ResizeBuffers (const Extent2D &resolution, long flags=0)
	Resizes all swap buffers of this swap-chain.
virtual bool	SetVsyncInterval (std::uint32_t vsyncInterval)=0
	Sets the new vertical synchronization (V-sync) interval for this swap chain.
bool	SwitchFullscreen (bool enable)
	Puts the display, the swap-chain's surface is resident in, into fullscreen mode or puts it back into normal mode.
Surface &	GetSurface () const
	Returns the surface which is used to present the content on the screen.
Public Member Functions inherited from LLGL::RenderTarget
virtual std::uint32_t	GetSamples () const =0
	Returns the number of samples this render target was created with.
virtual const RenderPass *	GetRenderPass () const =0
	Returns the RenderPass object this render target is associated with, or null if render passes are optional for the the render system.
Public Member Functions inherited from LLGL::RenderSystemChild
virtual void	SetDebugName (const char *name)
	Sets the name of this class instance for debugging purposes.
Public Member Functions inherited from LLGL::Interface
virtual bool	IsInstanceOf (int id) const
	Returns true if this object is an instance of the specified interface.
Public Member Functions inherited from LLGL::NonCopyable
	NonCopyable (const NonCopyable &)=delete
NonCopyable &	operator= (const NonCopyable &)=delete
virtual	~NonCopyable ()=default

Protected Member Functions
virtual Extent2D	ResizeBuffersPrimary (const Extent2D &resolution)=0
	Primary function to resize all swap buffers.
	SwapChain ()
	Allocates the internal data.
	SwapChain (const SwapChainDescriptor &desc)
	Constructor to initialize the swap-chain with the specified video mode and V-sync.
void	SetOrCreateSurface (const std::shared_ptr< Surface > &surface, const UTF8String &title, const SwapChainDescriptor &swapChainDesc, const void *windowContext=nullptr, std::size_t windowContextSize=0)
	Sets the swap-chain surface or creates one if 'surface' is null, and switches to fullscreen mode if enabled.
void	ShowSurface ()
	Shows the swap-chain surface if it's not the same as the input surface.
void	ShareSurfaceAndConfig (SwapChain &other)
	Shares the surface and resolution with another swap-chain.
bool	SetDisplayFullscreenMode (const Extent2D &resolution)
	Puts the display the swap-chain's surface is resident in into fullscreen mode.
bool	ResetDisplayFullscreenMode ()
	Puts the display the swap-chain's surface is resident in back into normal mode.
void	SetResolution (const Extent2D &resolution)
	Overrides the reported swap-chain resolution with the one that was actually allocated.
Protected Member Functions inherited from LLGL::RenderTarget
void	ValidateResolution (const Extent2D &attachmentResolution)
	Validates the specified attachment resolution for this render target.
void	ValidateMipResolution (const Texture &texture, std::uint32_t mipLevel)
	Applies the resolution of the texture MIP level.
Protected Member Functions inherited from LLGL::NonCopyable
	NonCopyable ()=default

Static Protected Member Functions
static UTF8String	BuildDefaultSurfaceTitle (const RendererInfo &info)
	Builds a default title for the swap-chain surface when no custom surface is specified.

Detailed Description

Swap-chain interface.

Remarks: Each swap-chain has its own surface and swap buffers to draw into.

See also: RenderSystem::CreateSwapChain; CommandBuffer::BeginRenderPass

Constructor & Destructor Documentation

◆ ~SwapChain()

LLGL::SwapChain::~SwapChain ( )

Release the internal data.

◆ SwapChain() [1/2]

LLGL::SwapChain::SwapChain ( )

protected

Allocates the internal data.

◆ SwapChain() [2/2]

LLGL::SwapChain::SwapChain ( const SwapChainDescriptor & desc )

protected

Constructor to initialize the swap-chain with the specified video mode and V-sync.

Member Function Documentation

◆ BuildDefaultSurfaceTitle()

UTF8String LLGL::SwapChain::BuildDefaultSurfaceTitle ( const RendererInfo & info )

staticprotected

Builds a default title for the swap-chain surface when no custom surface is specified.

Remarks

This has the format "LLGL SURFACE NUMBER ( RENDERER )":

SURFACE is either "Window" on desktop platforms or "Canvas" on mobile platforms.
NUMBER denotes the number of the swap-chain starting at 1.
RENDERER denotes the renderer name (see RendererInfo::rendererName).

◆ GetColorFormat()

virtual Format LLGL::SwapChain::GetColorFormat ( ) const

pure virtual

Returns the color format of this swap-chain.

Remarks: This may depend on the settings specified for the video mode. A common value for a swap-chain color format is Format::BGRA8UNorm.

See also: AttachmentFormatDescriptor::format; Format

◆ GetCurrentSwapIndex()

virtual std::uint32_t LLGL::SwapChain::GetCurrentSwapIndex ( ) const

pure virtual

Returns the current swap-buffer index.

Remarks: If the renderer supports control over swap-chain sizes, this function returns the current swap-buffer index. Otherwise, this function always returns 0.; This function is guaranteed to never return a value greater than or equal to the swap-chain size that was specified when this swap-chain was created.; Can be used to encode a command buffer for a specific swap-buffer.

Returns: \(i \in \left[ 0, \texttt{GetNumSwapBuffers()} \right)\)

See also: GetNumSwapBuffers; CommandBuffer::BeginRenderPass

◆ GetDepthStencilFormat()

virtual Format LLGL::SwapChain::GetDepthStencilFormat ( ) const

pure virtual

Returns the depth-stencil format of this swap-chain.

Remarks: This may depend on the settings specified for the video mode.

See also: AttachmentFormatDescriptor::format; Format

◆ GetNumColorAttachments()

std::uint32_t LLGL::SwapChain::GetNumColorAttachments ( ) const

finalvirtual

Returns 1, since each swap-chain has always a single color attachment.

Implements LLGL::RenderTarget.

◆ GetNumSwapBuffers()

virtual std::uint32_t LLGL::SwapChain::GetNumSwapBuffers ( ) const

pure virtual

Returns the actual number of swap-buffers in this swap-chain.

Remarks: This value is either 1 if the renderer does not support swap-chain size control or a value derived from SwapChainDescriptor::swapBuffers this swap-chain was created with. It is not guaranteed to be equal SwapChainDescriptor::swapBuffers even if the renderer supports swap-chain size control, because there are different limitations of how many swap buffers can be created.

Returns: A value in the range \(\left[ 1, \infty+ \right)\) but usually in the range \( \left[1, 3\right]\).

See also: GetCurrentSwapIndex; SwapChainDescriptor::swapBuffers

◆ GetResolution()

Extent2D LLGL::SwapChain::GetResolution ( ) const

finalvirtual

Returns the resolution of the current video mode.

See also: ResizeBuffers

Implements LLGL::RenderTarget.

◆ GetSurface()

Surface & LLGL::SwapChain::GetSurface ( ) const

Returns the surface which is used to present the content on the screen.

Remarks: On desktop platforms, this can be statically casted to 'LLGL::Window&', and on mobile platforms, this can be statically casted to 'LLGL::Canvas&':
auto& myWindow = static_cast<LLGL::Window&>(mySwapChain->GetSurface());

LLGL::Window
Window interface for desktop platforms.
Definition Window.h:32

◆ HasDepthAttachment()

bool LLGL::SwapChain::HasDepthAttachment ( ) const

finalvirtual

Returns true if this swap-chain has a depth format.

See also: GetDepthStencilFormat; IsDepthFormat

Implements LLGL::RenderTarget.

◆ HasStencilAttachment()

bool LLGL::SwapChain::HasStencilAttachment ( ) const

finalvirtual

Returns true if this swap-chain has a stencil format.

See also: GetDepthStencilFormat; IsStencilFormat

Implements LLGL::RenderTarget.

◆ IsPresentable()

virtual bool LLGL::SwapChain::IsPresentable ( ) const

pure virtual

Returns true if this swap-chain is ready for rendering and presenting. Otherwise, the native surface or back buffer are not available.

Remarks: This is mostly used for mobile platforms where the surface can be temporarily destroyed when the app is paused and later re-initialized when the app resumes. If this is false, no rendering to this swap-chain must be performed nor can the back buffer be presented.; A safe way to handle the event of a lost native surface is to skip the entire rendering when this returns false as shown below:
while (LLGL::Surface::ProcessEvents()) {

// Skip frame if swap-chain is currently not presentable

if (!swapChain->IsPresentable()) {

std::this_thread::yield();

continue;

}

// Render frame ...

// Present swap-chain back buffer

swapChain->Present();

}

LLGL::Surface::ProcessEvents
static bool ProcessEvents()
Processes all windowing system events, i.e. input-, movement-, resize-, and other events for all surf...

◆ Present()

virtual void LLGL::SwapChain::Present ( )

pure virtual

Swaps the current back buffer with the front buffer to present it on the screen.

See also: GetCurrentSwapIndex

◆ ResetDisplayFullscreenMode()

bool LLGL::SwapChain::ResetDisplayFullscreenMode ( )

protected

Puts the display the swap-chain's surface is resident in back into normal mode.

See also: SetDisplayFullscreenMode

◆ ResizeBuffers()

bool LLGL::SwapChain::ResizeBuffers	(	const Extent2D &	resolution,
		long	flags = 0 )

Resizes all swap buffers of this swap-chain.

Parameters

[in]	resolution	Specifies the new resolution. This is only a hint: the platform may clamp it to what the surface permits.
[in]	flags	Optional flags to specify whether the swap-chain's surface is to be adjusted as well and to toggle fullscreen mode.

Returns: True if the swap buffers were resized to a valid resolution, which may differ from the requested one; use GetResolution to query what was actually allocated. If the ResizeBuffersFlags::StrictResolution flag is specified, only returns true if the swap buffers were resized to the exact resolution requested.

See also: GetResolution; ResizeBuffersFlags

◆ ResizeBuffersPrimary()

virtual Extent2D LLGL::SwapChain::ResizeBuffersPrimary ( const Extent2D & resolution )

protectedpure virtual

Primary function to resize all swap buffers.

Parameters

[in] resolution Specifies the requested resolution. This is only a hint: the platform may clamp it to what the surface permits.

Returns: The resolution that was actually allocated, which becomes the value GetResolution() reports. Return a zero extent (i.e. Extent2D{ 0, 0 }) to indicate failure, in which case the previously reported resolution remains unchanged.

See also: ResizeBuffers; SetResolution

◆ SetDisplayFullscreenMode()

bool LLGL::SwapChain::SetDisplayFullscreenMode ( const Extent2D & resolution )

protected

Puts the display the swap-chain's surface is resident in into fullscreen mode.

See also: ResetDisplayFullscreenMode

◆ SetOrCreateSurface()

void LLGL::SwapChain::SetOrCreateSurface	(	const std::shared_ptr< Surface > &	surface,
		const UTF8String &	title,
		const SwapChainDescriptor &	swapChainDesc,
		const void *	windowContext = nullptr,
		std::size_t	windowContextSize = 0 )

protected

Sets the swap-chain surface or creates one if 'surface' is null, and switches to fullscreen mode if enabled.

Parameters

[in]	surface	Optional shared pointer to a surface which will be used as main render target. If this is null, a new surface is created for this swap-chain.
[in]	title	Specifies the surface title. This is only used if `surface` is null.
[in]	swapChainDesc	Specifies the swap-chain descriptor. Use the resolution for the surface content size, fullscreen, and resiable flags.
[in]	windowContext	Optional pointer to a NativeHandle structure. This is only used for desktop platforms.
[in]	windowContextSize	Size (in bytes) of the native handle `windowContext` points to. This must be equal to `sizeof(LLGL::NativeHandle)`.

See also: WindowDescriptor::windowContext; Surface::GetContentSize; SwitchFullscreenMode

◆ SetResolution()

void LLGL::SwapChain::SetResolution ( const Extent2D & resolution )

protected

Overrides the reported swap-chain resolution with the one that was actually allocated.

Remarks: A requested resolution is only ever a hint: the platform may clamp it to what the surface permits, e.g. Vulkan clamps every swap-chain extent to VkSurfaceCapabilitiesKHR::minImageExtent and maxImageExtent, which on most windowing systems both equal the window's current client area. GetResolution() must describe the buffers that exist rather than the ones that were asked for; reporting the request instead leaves callers deriving viewports, scissors and projection matrices from a resolution the backbuffer does not have. During ResizeBuffers() this is handled by the return value of ResizeBuffersPrimary(); backends that (re-)allocate their swap buffers outside of that function - e.g. at creation time or when recreating an out-of-date swap-chain - should call this function from wherever the allocation happens.

See also: GetResolution; ResizeBuffersPrimary

◆ SetVsyncInterval()

virtual bool LLGL::SwapChain::SetVsyncInterval ( std::uint32_t vsyncInterval )

pure virtual

Sets the new vertical synchronization (V-sync) interval for this swap chain.

Parameters

[in] vsyncInterval Specifies the new V-sync interface.

Returns: True on success, otherwise the V-sync value is invalid for this swap chain.

Remarks: This is typically 0 to disable V-sync or 1 to enable V-sync, but higher values are possible, too. A value of 2 for instance effectively halves the frame refresh rate that the active display is capable of, e.g. a display with a refresh rate of 60 Hz and a V-sync value of 2 limits the frame rate to 30 Hz.

◆ ShareSurfaceAndConfig()

void LLGL::SwapChain::ShareSurfaceAndConfig ( SwapChain & other )

protected

Shares the surface and resolution with another swap-chain.

Note: This is only used by the renderer debug layer.

◆ ShowSurface()

void LLGL::SwapChain::ShowSurface ( )

protected

Shows the swap-chain surface if it's not the same as the input surface.

◆ SwitchFullscreen()

bool LLGL::SwapChain::SwitchFullscreen ( bool enable )

Puts the display, the swap-chain's surface is resident in, into fullscreen mode or puts it back into normal mode.

Parameters

[in] enable If true, puts the display into fullscreen mode (Display::SetDisplayMode). Otherwise, puts the display back into normal mode (Display::ResetDisplayMode).

Returns: True on success, otherwise the display does not support the resolution of this swap-chain.

Remarks: When switching back from fullscreen into normal mode, this function restores the previous position of the swap-chain's surface.

See also: Display::SetDisplayMode; Display::ResetDisplayMode

The documentation for this class was generated from the following file:

SwapChain.h

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~SwapChain()

◆ SwapChain() [1/2]

◆ SwapChain() [2/2]

Member Function Documentation

◆ BuildDefaultSurfaceTitle()

◆ GetColorFormat()

◆ GetCurrentSwapIndex()

◆ GetDepthStencilFormat()

◆ GetNumColorAttachments()

◆ GetNumSwapBuffers()

◆ GetResolution()

◆ GetSurface()

◆ HasDepthAttachment()

◆ HasStencilAttachment()

◆ IsPresentable()

◆ Present()

◆ ResetDisplayFullscreenMode()

◆ ResizeBuffers()

◆ ResizeBuffersPrimary()

◆ SetDisplayFullscreenMode()

◆ SetOrCreateSurface()

◆ SetResolution()

◆ SetVsyncInterval()

◆ ShareSurfaceAndConfig()

◆ ShowSurface()

◆ SwitchFullscreen()