Interface for a swap chain. More...

#include <rendering_api.hpp>

Inherited by LiteFX::Rendering::SwapChain< IDirectX12Image >, LiteFX::Rendering::SwapChain< IVulkanImage >, and LiteFX::Rendering::SwapChain< TImageInterface >.

Classes
struct	ResetEventArgs
	Event arguments for a ISwapChain::reseted event. More...

Public Member Functions
virtual	~ISwapChain () noexcept=default

SharedPtr< const TimingEvent >	registerTimingEvent (StringView name="")
	Creates a new instance of a TimingEvent.

virtual const Array< SharedPtr< const TimingEvent > > &	timingEvents () const =0
	Returns all registered timing events.

virtual SharedPtr< const TimingEvent >	timingEvent (UInt32 queryId) const =0
	Returns the timing event registered for queryId .

virtual UInt64	readTimingEvent (SharedPtr< const TimingEvent > timingEvent) const =0
	Reads the current time stamp value (in ticks) of a timing event.

virtual UInt32	resolveQueryId (SharedPtr< const TimingEvent > timingEvent) const =0
	Returns the query ID for the timing event.

virtual const IGraphicsDevice &	device () const =0
	Returns the swap chain's parent device instance.

virtual Format	surfaceFormat () const noexcept=0
	Returns the swap chain image format.

virtual UInt32	buffers () const noexcept=0
	Returns the number of images in the swap chain.

virtual const Size2d &	renderArea () const noexcept=0
	Returns the size of the render area.

virtual bool	verticalSynchronization () const noexcept=0
	Returns `true`, if vertical synchronization should be used, otherwise `false`.

virtual IImage *	image (UInt32 backBuffer) const =0
	Returns the swap chain present image for backBuffer .

virtual const IImage &	image () const noexcept=0
	Returns the current swap chain back buffer image.

Enumerable< IImage & >	images () const
	Returns an array of the swap chain present images.

virtual void	present (UInt64 fence) const =0
	Queues a present that gets executed after fence has been signaled on the default graphics queue.

virtual Enumerable< Format >	getSurfaceFormats () const =0
	Returns an array of supported formats, that can be drawn to the surface.

virtual void	reset (Format surfaceFormat, const Size2d &renderArea, UInt32 buffers, bool enableVsync=false)=0
	Causes the swap chain to be re-created. All frame and command buffers will be invalidated and rebuilt.

virtual UInt32	swapBackBuffer () const =0
	Swaps the front buffer with the next back buffer in order.

Public Attributes
Event< EventArgs >	swapped
	Invoked, when the swap chain has swapped the back buffers.

Event< ResetEventArgs >	reseted
	Invoked, after the swap chain has been reseted.

Protected Member Functions
	ISwapChain () noexcept=default

	ISwapChain (ISwapChain &&) noexcept=default

	ISwapChain (const ISwapChain &)=default

ISwapChain &	operator= (const ISwapChain &)=default

ISwapChain &	operator= (ISwapChain &&) noexcept=default

Detailed Description

Interface for a swap chain.

Constructor & Destructor Documentation

◆ ISwapChain() [1/3]

LiteFX::Rendering::ISwapChain::ISwapChain ( )

protecteddefaultnoexcept

◆ ISwapChain() [2/3]

LiteFX::Rendering::ISwapChain::ISwapChain ( ISwapChain && )

protecteddefaultnoexcept

◆ ISwapChain() [3/3]

LiteFX::Rendering::ISwapChain::ISwapChain ( const ISwapChain & )

protecteddefault

◆ ~ISwapChain()

virtual LiteFX::Rendering::ISwapChain::~ISwapChain ( )

virtualdefaultnoexcept

Member Function Documentation

◆ buffers()

virtual UInt32 LiteFX::Rendering::ISwapChain::buffers ( ) const

pure virtualnoexcept

Returns the number of images in the swap chain.

Returns: The number of images in the swap chain.

Implemented in LiteFX::Rendering::Backends::DirectX12SwapChain, and LiteFX::Rendering::Backends::VulkanSwapChain.

◆ device()

virtual const IGraphicsDevice & LiteFX::Rendering::ISwapChain::device ( ) const

pure virtual

Returns the swap chain's parent device instance.

Returns: A reference of the swap chain's parent device instance.

Exceptions

RuntimeException Thrown, if the device is already released.

Implemented in LiteFX::Rendering::Backends::DirectX12SwapChain, and LiteFX::Rendering::Backends::VulkanSwapChain.

◆ getSurfaceFormats()

virtual Enumerable< Format > LiteFX::Rendering::ISwapChain::getSurfaceFormats ( ) const

pure virtual

Returns an array of supported formats, that can be drawn to the surface.

Returns: An array of supported formats, that can be drawn to the surface.

surface

See also: ISurface

Implemented in LiteFX::Rendering::Backends::DirectX12SwapChain, and LiteFX::Rendering::Backends::VulkanSwapChain.

◆ image() [1/2]

virtual const IImage & LiteFX::Rendering::ISwapChain::image ( ) const

pure virtualnoexcept

Returns the current swap chain back buffer image.

Returns: A reference of the current swap chain back buffer image.

Implemented in LiteFX::Rendering::Backends::DirectX12SwapChain, and LiteFX::Rendering::Backends::VulkanSwapChain.

◆ image() [2/2]

virtual IImage * LiteFX::Rendering::ISwapChain::image ( UInt32 backBuffer ) const

pure virtual

Returns the swap chain present image for backBuffer .

Parameters

backBuffer The index of the back buffer for which to return the swap chain present image.

Returns: A pointer to the back buffers swap chain present image.

Implemented in LiteFX::Rendering::Backends::DirectX12SwapChain, and LiteFX::Rendering::Backends::VulkanSwapChain.

◆ images()

Enumerable< IImage & > LiteFX::Rendering::ISwapChain::images ( ) const

inline

Returns an array of the swap chain present images.

Returns: Returns an array of the swap chain present images.

◆ operator=() [1/2]

ISwapChain & LiteFX::Rendering::ISwapChain::operator= ( const ISwapChain & )

protecteddefault

◆ operator=() [2/2]

ISwapChain & LiteFX::Rendering::ISwapChain::operator= ( ISwapChain && )

protecteddefaultnoexcept

◆ present()

virtual void LiteFX::Rendering::ISwapChain::present ( UInt64 fence ) const

pure virtual

Queues a present that gets executed after fence has been signaled on the default graphics queue.

You can use this overload in situations where you do not have an IRenderPass or IFrameBuffer to render into before presenting. Instead, you typically copy into the swap chain back buffer images directly (image). This copy is done in a command buffer that must be submitted to the default graphics queue. The swap chain can then wait for the copy to finish before presenting it. Example scenarios where this is useful are, where you want to write to the back buffer from a compute shader, that does not have an equivalent to render passes.

Parameters

fence The fence to pass on the default graphics queue after which the present is executed.

Implemented in LiteFX::Rendering::Backends::DirectX12SwapChain, and LiteFX::Rendering::Backends::VulkanSwapChain.

◆ readTimingEvent()

virtual UInt64 LiteFX::Rendering::ISwapChain::readTimingEvent ( SharedPtr< const TimingEvent > timingEvent ) const

pure virtual

Reads the current time stamp value (in ticks) of a timing event.

In order to convert the number of ticks to (milli-)seconds, this value needs to be divided by IGraphicsDevice::ticksPerMillisecond. To improve precision, calculate the difference between two time stamps in ticks first and only then convert them to seconds.

Parameters

timingEvent The timing event to read the current value for.

Returns: The current time stamp value of the timing event in ticks.

See also: TimingEvent::readTimestamp

Implemented in LiteFX::Rendering::Backends::DirectX12SwapChain, and LiteFX::Rendering::Backends::VulkanSwapChain.

◆ registerTimingEvent()

SharedPtr< const TimingEvent > LiteFX::Rendering::ISwapChain::registerTimingEvent ( StringView name = "" )

inlinenodiscard

Creates a new instance of a TimingEvent.

Note that registering a new timing event does invalidate previously registered events, i.e. they do not return meaningful time stamps for the next frame. Timing events should only be registered during application startup, before the first frame is rendered.

Parameters

name	The name of the timing event.

Returns: A pointer with shared ownership to the newly created timing event instance.

◆ renderArea()

virtual const Size2d & LiteFX::Rendering::ISwapChain::renderArea ( ) const

pure virtualnoexcept

Returns the size of the render area.

Returns: The size of the render area.

Implemented in LiteFX::Rendering::Backends::DirectX12SwapChain, and LiteFX::Rendering::Backends::VulkanSwapChain.

◆ reset()

virtual void LiteFX::Rendering::ISwapChain::reset	(	Format	surfaceFormat,
		const Size2d &	renderArea,
		UInt32	buffers,
		bool	enableVsync = false )

pure virtual

Causes the swap chain to be re-created. All frame and command buffers will be invalidated and rebuilt.

There is no guarantee, that the swap chain images will end up in the exact format, as specified by surfaceFormat . If the format itself is not supported, a compatible format may be looked up. If the lookup fails, the method may raise an exception.

Similarly, it is not guaranteed, that the number of images returned by images matches the number specified in buffers . A swap chain may require a minimum number of images or may constraint a maximum number of images. In both cases, buffers will be clamped.

Parameters

surfaceFormat	The swap chain image format.
renderArea	The dimensions of the frame buffers.
buffers	The number of buffers in the swap chain.
enableVsync	`true`, if vertical synchronization should be used, otherwise `false`.

See also: multiSamplingLevel

Implemented in LiteFX::Rendering::Backends::DirectX12SwapChain, and LiteFX::Rendering::Backends::VulkanSwapChain.

◆ resolveQueryId()

virtual UInt32 LiteFX::Rendering::ISwapChain::resolveQueryId ( SharedPtr< const TimingEvent > timingEvent ) const

pure virtual

Returns the query ID for the timing event.

Parameters

timingEvent The timing event to return the query ID for.

Returns: The query ID for the timingEvent .

See also: TimingEvent::queryId

Implemented in LiteFX::Rendering::Backends::DirectX12SwapChain, and LiteFX::Rendering::Backends::VulkanSwapChain.

◆ surfaceFormat()

virtual Format LiteFX::Rendering::ISwapChain::surfaceFormat ( ) const

pure virtualnoexcept

Returns the swap chain image format.

Returns: The swap chain image format.

Implemented in LiteFX::Rendering::Backends::DirectX12SwapChain, and LiteFX::Rendering::Backends::VulkanSwapChain.

◆ swapBackBuffer()

virtual UInt32 LiteFX::Rendering::ISwapChain::swapBackBuffer ( ) const

nodiscardpure virtual

Swaps the front buffer with the next back buffer in order.

Returns: A reference of the front buffer after the buffer swap.

Implemented in LiteFX::Rendering::Backends::DirectX12SwapChain, and LiteFX::Rendering::Backends::VulkanSwapChain.

◆ timingEvent()

virtual SharedPtr< const TimingEvent > LiteFX::Rendering::ISwapChain::timingEvent ( UInt32 queryId ) const

pure virtual

Returns the timing event registered for queryId .

Parameters

queryId The query ID of the timing event.

Returns: The timing event registered for queryId .

Implemented in LiteFX::Rendering::Backends::DirectX12SwapChain, and LiteFX::Rendering::Backends::VulkanSwapChain.

◆ timingEvents()

virtual const Array< SharedPtr< const TimingEvent > > & LiteFX::Rendering::ISwapChain::timingEvents ( ) const

pure virtual

Returns all registered timing events.

Returns: An array, containing all registered timing events.

Implemented in LiteFX::Rendering::Backends::DirectX12SwapChain, and LiteFX::Rendering::Backends::VulkanSwapChain.

◆ verticalSynchronization()

virtual bool LiteFX::Rendering::ISwapChain::verticalSynchronization ( ) const

pure virtualnoexcept

Returns true, if vertical synchronization should be used, otherwise false.

Returns: true, if vertical synchronization should be used, otherwise false.

Implemented in LiteFX::Rendering::Backends::DirectX12SwapChain, and LiteFX::Rendering::Backends::VulkanSwapChain.

Member Data Documentation

◆ reseted

Event<ResetEventArgs> LiteFX::Rendering::ISwapChain::reseted

mutable

Invoked, after the swap chain has been reseted.

See also: reset

◆ swapped

Event<EventArgs> LiteFX::Rendering::ISwapChain::swapped

mutable

Invoked, when the swap chain has swapped the back buffers.

See also: swapBackBuffer

Classes

Public Member Functions

Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ISwapChain() [1/3]

◆ ISwapChain() [2/3]

◆ ISwapChain() [3/3]

◆ ~ISwapChain()

Member Function Documentation

◆ buffers()

◆ device()

◆ getSurfaceFormats()

◆ image() [1/2]

◆ image() [2/2]

◆ images()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ present()

◆ readTimingEvent()

◆ registerTimingEvent()

◆ renderArea()

◆ reset()

◆ resolveQueryId()

◆ surfaceFormat()

◆ swapBackBuffer()

◆ timingEvent()

◆ timingEvents()

◆ verticalSynchronization()

Member Data Documentation

◆ reseted

◆ swapped