The interface for a command queue. More...

#include <rendering_api.hpp>

Inherited by LiteFX::Rendering::CommandQueue< DirectX12CommandBuffer >, LiteFX::Rendering::CommandQueue< VulkanCommandBuffer >, and LiteFX::Rendering::CommandQueue< TCommandBuffer >.

Classes
struct	QueueSubmittedEventArgs
	Event arguments for a ICommandQueue::submitted event. More...

struct	QueueSubmittingEventArgs
	Event arguments for a ICommandQueue::submitting event. More...

Public Member Functions
	~ICommandQueue () noexcept override=default

virtual QueuePriority	priority () const noexcept=0
	Returns the priority of the queue.

virtual QueueType	type () const noexcept=0
	Returns the type of the queue.

virtual void	beginDebugRegion (const String &label, const Vectors::ByteVector3 &color=DEFAULT_DEBUG_COLOR) const noexcept
	Starts a new debug region.

virtual void	endDebugRegion () const noexcept
	Ends the current debug region.

virtual void	setDebugMarker (const String &label, const Vectors::ByteVector3 &color=DEFAULT_DEBUG_COLOR) const noexcept
	Inserts a debug marker.

SharedPtr< ICommandBuffer >	createCommandBuffer (bool beginRecording=false, bool secondary=false) const
	Creates a command buffer that can be used to allocate commands on the queue.

UInt64	submit (const SharedPtr< const ICommandBuffer > &commandBuffer) const
	Submits a single command buffer with shared ownership and inserts a fence to wait for it.

UInt64	submit (const SharedPtr< ICommandBuffer > &commandBuffer) const
	Submits a single command buffer with shared ownership and inserts a fence to wait for it.

UInt64	submit (Enumerable< SharedPtr< const ICommandBuffer > > commandBuffers) const
	Submits a set of command buffers with shared ownership and inserts a fence to wait for them.

virtual void	waitFor (UInt64 fence) const =0
	Lets the CPU wait for a certain fence value to complete on the command queue.

void	waitFor (const ICommandQueue &queue, UInt64 fence) const
	Lets the command queue wait for a certain fence value to complete on another queue.

virtual UInt64	currentFence () const noexcept=0
	Returns the value of the latest fence inserted into the queue.

Public Member Functions inherited from LiteFX::SharedObject
virtual	~SharedObject () noexcept=default
	Destroys the shared object.

template<typename TSelf >
auto	shared_from_this (this TSelf &&self) noexcept
	Returns a shared pointer to the current object instance.

template<typename TSelf >
auto	weak_from_this (this TSelf &&self) noexcept -> WeakPtr< std::remove_reference_t< TSelf > >
	Returns a weak pointer to the current object instance.

Public Attributes
Event< QueueSubmittingEventArgs >	submitting
	Invoked, when one or more command buffers are submitted to the queue.

Event< QueueSubmittedEventArgs >	submitted
	Invoked, after one or more command buffers have been submitted to the queue.

Static Public Attributes
static constexpr Vectors::ByteVector3	DEFAULT_DEBUG_COLOR = { 128_b, 128_b, 128_b }
	The default color value for a debug region or marker, if no other has been specified.

Protected Member Functions
	ICommandQueue () noexcept=default

	ICommandQueue (const ICommandQueue &)=default

	ICommandQueue (ICommandQueue &&) noexcept=default

ICommandQueue &	operator= (const ICommandQueue &)=default

ICommandQueue &	operator= (ICommandQueue &&) noexcept=default

void	releaseSharedState (const ICommandBuffer &commandBuffer) const

Protected Member Functions inherited from LiteFX::SharedObject
	SharedObject () noexcept=default
	Initializes a new shared object.

	SharedObject (SharedObject &&) noexcept=default

	SharedObject (const SharedObject &)=default

SharedObject &	operator= (SharedObject &&) noexcept=default

SharedObject &	operator= (const SharedObject &)=default

Additional Inherited Members
Static Protected Member Functions inherited from LiteFX::SharedObject
template<typename T , typename... TArgs>
static auto	create (TArgs &&... args) -> SharedPtr< T >
	Generic factory method used to create instances of the shared object.

Detailed Description

The interface for a command queue.

Constructor & Destructor Documentation

◆ ICommandQueue() [1/3]

LiteFX::Rendering::ICommandQueue::ICommandQueue ( )

protecteddefaultnoexcept

◆ ICommandQueue() [2/3]

LiteFX::Rendering::ICommandQueue::ICommandQueue ( const ICommandQueue & )

protecteddefault

◆ ICommandQueue() [3/3]

LiteFX::Rendering::ICommandQueue::ICommandQueue ( ICommandQueue && )

protecteddefaultnoexcept

◆ ~ICommandQueue()

LiteFX::Rendering::ICommandQueue::~ICommandQueue ( )

overridedefaultnoexcept

Member Function Documentation

◆ beginDebugRegion()

virtual void LiteFX::Rendering::ICommandQueue::beginDebugRegion	(	const String &	label,
		const Vectors::ByteVector3 &	color = DEFAULT_DEBUG_COLOR ) const

inlinevirtualnoexcept

Starts a new debug region.

This method is a debug helper, that is not required to be implemented. In the built-in backends, it will no-op by default in non-debug builds.

Parameters

label	The name of the debug region.
color	The color of the debug region.

◆ createCommandBuffer()

SharedPtr< ICommandBuffer > LiteFX::Rendering::ICommandQueue::createCommandBuffer	(	bool	beginRecording = false,
		bool	secondary = false ) const

inline

Creates a command buffer that can be used to allocate commands on the queue.

Specifying secondary allows to create secondary command buffers (aka. bundles). Those are intended to be used as efficient pre-recorded command buffers that are re-used multiple times. Using such a command buffer allows drivers to pre-apply optimizations, which causes a one-time cost during setup, but reduces cost when re- applying the command buffer multiple times. Ideally they are used as small chunks of re-occurring workloads.

A secondary command buffer must not be submitted to a queue, but rather to a primary command buffer by calling ICommandBuffer::execute.

Parameters

beginRecording	If set to `true`, the command buffer will be initialized in recording state and can receive commands straight away.
secondary	If set to `true`, the method will create a secondary command buffer/bundle.

Returns: The instance of the command buffer.

◆ currentFence()

virtual UInt64 LiteFX::Rendering::ICommandQueue::currentFence ( ) const

pure virtualnoexcept

Returns the value of the latest fence inserted into the queue.

Returns: The value of the latest fence inserted into the queue.

See also: waitFor

Implemented in LiteFX::Rendering::Backends::DirectX12Queue, and LiteFX::Rendering::Backends::VulkanQueue.

◆ endDebugRegion()

virtual void LiteFX::Rendering::ICommandQueue::endDebugRegion ( ) const

inlinevirtualnoexcept

Ends the current debug region.

This is a debug helper, that is not required to be implemented. In the built-in backends, it will no-op by default in non-debug builds.

◆ operator=() [1/2]

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

protecteddefault

◆ operator=() [2/2]

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

protecteddefaultnoexcept

◆ priority()

virtual QueuePriority LiteFX::Rendering::ICommandQueue::priority ( ) const

pure virtualnoexcept

Returns the priority of the queue.

Returns: The priority of the queue.

Implemented in LiteFX::Rendering::Backends::DirectX12Queue, and LiteFX::Rendering::Backends::VulkanQueue.

◆ releaseSharedState()

void LiteFX::Rendering::ICommandQueue::releaseSharedState ( const ICommandBuffer & commandBuffer ) const

inlineprotected

◆ setDebugMarker()

virtual void LiteFX::Rendering::ICommandQueue::setDebugMarker	(	const String &	label,
		const Vectors::ByteVector3 &	color = DEFAULT_DEBUG_COLOR ) const

inlinevirtualnoexcept

Inserts a debug marker.

This method is a debug helper, that is not required to be implemented. In the built-in backends, it will no-op by default in non-debug builds.

Parameters

label	The name of the debug marker.
color	The color of the debug marker.

◆ submit() [1/3]

UInt64 LiteFX::Rendering::ICommandQueue::submit ( const SharedPtr< const ICommandBuffer > & commandBuffer ) const

inline

Submits a single command buffer with shared ownership and inserts a fence to wait for it.

By calling this method, the queue takes shared ownership over the commandBuffer until the fence is passed. The reference will be released during a waitFor, if the awaited fence is inserted after the associated one.

Note that submitting a command buffer that is currently recording will implicitly close the command buffer.

Parameters

commandBuffer The command buffer to submit to the command queue.

Returns: The value of the fence, inserted after the command buffer.

See also: waitFor

◆ submit() [2/3]

UInt64 LiteFX::Rendering::ICommandQueue::submit ( const SharedPtr< ICommandBuffer > & commandBuffer ) const

inline

Submits a single command buffer with shared ownership and inserts a fence to wait for it.

By calling this method, the queue takes shared ownership over the commandBuffer until the fence is passed. The reference will be released during a waitFor, if the awaited fence is inserted after the associated one.

Note that submitting a command buffer that is currently recording will implicitly close the command buffer.

Parameters

commandBuffer The command buffer to submit to the command queue.

Returns: The value of the fence, inserted after the command buffer.

See also: waitFor

◆ submit() [3/3]

UInt64 LiteFX::Rendering::ICommandQueue::submit ( Enumerable< SharedPtr< const ICommandBuffer > > commandBuffers ) const

inline

Submits a set of command buffers with shared ownership and inserts a fence to wait for them.

By calling this method, the queue takes shared ownership over the commandBuffers until the fence is passed. The reference will be released during a waitFor, if the awaited fence is inserted after the associated one.

Note that submitting a command buffer that is currently recording will implicitly close the command buffer.

Parameters

commandBuffers The command buffers to submit to the command queue.

Returns: The value of the fence, inserted after the command buffers.

See also: waitFor

◆ type()

virtual QueueType LiteFX::Rendering::ICommandQueue::type ( ) const

pure virtualnoexcept

Returns the type of the queue.

Returns: The type of the queue.

Implemented in LiteFX::Rendering::Backends::DirectX12Queue, and LiteFX::Rendering::Backends::VulkanQueue.

◆ waitFor() [1/2]

void LiteFX::Rendering::ICommandQueue::waitFor	(	const ICommandQueue &	queue,
		UInt64	fence ) const

inline

Lets the command queue wait for a certain fence value to complete on another queue.

This overload performs a GPU-side wait, i.e., the current command queue waits until queue has passed the fence value provided by the fence parameter. This overload does return immediately and does not block the CPU.

Parameters

queue	The queue to wait upon.
fence	The value of the fence to wait upon on the other queue.

◆ waitFor() [2/2]

virtual void LiteFX::Rendering::ICommandQueue::waitFor ( UInt64 fence ) const

pure virtual

Lets the CPU wait for a certain fence value to complete on the command queue.

This overload performs a CPU-side wait, i.e., the CPU blocks until the current queue has passed the fence value provided by the fence parameter.

Parameters

fence The value of the fence to wait for.

See also: submit

Implemented in LiteFX::Rendering::Backends::DirectX12Queue, and LiteFX::Rendering::Backends::VulkanQueue.

Member Data Documentation

◆ DEFAULT_DEBUG_COLOR

Vectors::ByteVector3 LiteFX::Rendering::ICommandQueue::DEFAULT_DEBUG_COLOR = { 128_b, 128_b, 128_b }

staticconstexpr

The default color value for a debug region or marker, if no other has been specified.

See also: beginDebugRegion, setDebugMarker

◆ submitted

Event<QueueSubmittedEventArgs> LiteFX::Rendering::ICommandQueue::submitted

mutable

Invoked, after one or more command buffers have been submitted to the queue.

◆ submitting

Event<QueueSubmittingEventArgs> LiteFX::Rendering::ICommandQueue::submitting

mutable

Invoked, when one or more command buffers are submitted to the queue.

Classes

Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ICommandQueue() [1/3]

◆ ICommandQueue() [2/3]

◆ ICommandQueue() [3/3]

◆ ~ICommandQueue()

Member Function Documentation

◆ beginDebugRegion()

◆ createCommandBuffer()

◆ currentFence()

◆ endDebugRegion()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ priority()

◆ releaseSharedState()

◆ setDebugMarker()

◆ submit() [1/3]

◆ submit() [2/3]

◆ submit() [3/3]

◆ type()

◆ waitFor() [1/2]

◆ waitFor() [2/2]

Member Data Documentation

◆ DEFAULT_DEBUG_COLOR

◆ submitted

◆ submitting