The interface for a command buffer. More...

#include <rendering_api.hpp>

Inherited by LiteFX::Rendering::CommandBuffer< IDirectX12Buffer, IDirectX12VertexBuffer, IDirectX12IndexBuffer, IDirectX12Image, DirectX12Barrier, DirectX12PipelineState >, LiteFX::Rendering::CommandBuffer< IVulkanBuffer, IVulkanVertexBuffer, IVulkanIndexBuffer, IVulkanImage, VulkanBarrier, VulkanPipelineState >, and LiteFX::Rendering::CommandBuffer< TBuffer, TVertexBuffer, TIndexBuffer, TImage, TBarrier, TPipeline >.

Public Member Functions
virtual	~ICommandBuffer () noexcept=default

virtual void	begin () const =0
	Sets the command buffer into recording state, so that it can receive command that should be submitted to the parent CommandQueue. More...

virtual void	end () const =0
	Ends recording commands on the command buffer. More...

void	barrier (const IBarrier &barrier, const bool &invert=false) const noexcept
	Executes the transitions that have been added to barrier . More...

void	generateMipMaps (IImage &image) noexcept
	Uses the image at level 0 to generate mip-maps for the remaining levels. More...

void	transfer (const IBuffer &source, const IBuffer &target, const UInt32 &sourceElement=0, const UInt32 &targetElement=0, const UInt32 &elements=1) const
	Performs a buffer-to-buffer transfer from source to target . More...

void	transfer (const IBuffer &source, const IImage &target, const UInt32 &sourceElement=0, const UInt32 &firstSubresource=0, const UInt32 &elements=1) const
	Performs a buffer-to-image transfer from source to target . More...

void	transfer (const IImage &source, const IImage &target, const UInt32 &sourceSubresource=0, const UInt32 &targetSubresource=0, const UInt32 &subresources=1) const
	Performs an image-to-image transfer from source to target . More...

void	transfer (const IImage &source, const IBuffer &target, const UInt32 &firstSubresource=0, const UInt32 &targetElement=0, const UInt32 &subresources=1) const
	Performs an image-to-buffer transfer from source to target . More...

void	use (const IPipeline &pipeline) const noexcept
	Sets the active pipeline state. More...

void	bind (const IDescriptorSet &descriptorSet, const IPipeline &pipeline) const noexcept
	Binds the provided descriptor set to the provided pipeline. More...

void	bind (const IVertexBuffer &buffer) const noexcept
	Binds a vertex buffer to the pipeline. More...

void	bind (const IIndexBuffer &buffer) const noexcept
	Binds a index buffer to the pipeline. More...

virtual void	dispatch (const Vector3u &threadCount) const noexcept=0
	Executes a compute shader. More...

virtual void	draw (const UInt32 &vertices, const UInt32 &instances=1, const UInt32 &firstVertex=0, const UInt32 &firstInstance=0) const noexcept=0
	Draws a number of vertices from the currently bound vertex buffer. More...

virtual void	drawIndexed (const UInt32 &indices, const UInt32 &instances=1, const UInt32 &firstIndex=0, const Int32 &vertexOffset=0, const UInt32 &firstInstance=0) const noexcept=0
	Draws the currently bound vertex buffer with a set of indices from the currently bound index buffer. More...

void	pushConstants (const IPushConstantsLayout &layout, const void *const memory) const noexcept
	Pushes a block of memory into the push constants backing memory. More...

void	draw (const IVertexBuffer &vertexBuffer, const UInt32 &instances=1, const UInt32 &firstVertex=0, const UInt32 &firstInstance=0) const
	Draws all vertices from the vertex buffer provided in vertexBuffer . More...

void	drawIndexed (const IIndexBuffer &indexBuffer, const UInt32 &instances=1, const UInt32 &firstIndex=0, const Int32 &vertexOffset=0, const UInt32 &firstInstance=0) const
	Draws the currently bound vertex buffer using the index buffer provided in indexBuffer . More...

void	drawIndexed (const IVertexBuffer &vertexBuffer, const IIndexBuffer &indexBuffer, const UInt32 &instances=1, const UInt32 &firstIndex=0, const Int32 &vertexOffset=0, const UInt32 &firstInstance=0) const
	Draws the vertex buffer provided by vertexBuffer using the index buffer, provided by indexBuffer . More...

Detailed Description

The interface for a command buffer.

Constructor & Destructor Documentation

◆ ~ICommandBuffer()

virtual LiteFX::Rendering::ICommandBuffer::~ICommandBuffer ( )

virtualdefaultnoexcept

Member Function Documentation

◆ barrier()

void LiteFX::Rendering::ICommandBuffer::barrier	(	const IBarrier &	barrier,
		const bool &	invert = `false`
	)		const

inlinenoexcept

Executes the transitions that have been added to barrier .

Calling this method will also update the resource states of each resource within the barrier. However, the actual state of the resource does not change until the barrier is executed on the command queue. Keep this in mind when inserting multiple barriers from different threads or in different command buffers, which may not be executed in order. You might have to manually synchronize barrier execution.

Parameters

barrier	The barrier containing the transitions to perform.
invert	If set to `true`, the barrier will perform a transition back to the original resource states.

◆ begin()

virtual void LiteFX::Rendering::ICommandBuffer::begin ( ) const

pure virtual

Sets the command buffer into recording state, so that it can receive command that should be submitted to the parent CommandQueue.

Note that you have to wait for a command buffer to be executed on the parent CommandQueue before you can begin recording on it again.

Exceptions

RuntimeException Thrown, if the command buffer is already recording.

See also: end

Implemented in LiteFX::Rendering::Backends::DirectX12CommandBuffer, and LiteFX::Rendering::Backends::VulkanCommandBuffer.

◆ bind() [1/3]

void LiteFX::Rendering::ICommandBuffer::bind	(	const IDescriptorSet &	descriptorSet,
		const IPipeline &	pipeline
	)		const

inlinenoexcept

Binds the provided descriptor set to the provided pipeline.

Parameters

descriptorSet	The descriptor set to bind.
pipeline	The pipeline to bind the descriptor set to.

◆ bind() [2/3]

void LiteFX::Rendering::ICommandBuffer::bind ( const IIndexBuffer & buffer ) const

inlinenoexcept

Binds a index buffer to the pipeline.

After binding the index buffer, the next call to drawIndexed will read from it, until another index buffer is bound.

Parameters

buffer The index buffer to bind to the pipeline.

See also: IndexBuffer, drawIndexed

◆ bind() [3/3]

void LiteFX::Rendering::ICommandBuffer::bind ( const IVertexBuffer & buffer ) const

inlinenoexcept

Binds a vertex buffer to the pipeline.

After binding the vertex buffer, the next call to draw or drawIndexed will read from it, until another vertex buffer is bound.

Parameters

buffer The vertex buffer to bind to the pipeline.

See also: VertexBuffer, draw, drawIndexed

◆ dispatch()

virtual void LiteFX::Rendering::ICommandBuffer::dispatch ( const Vector3u & threadCount ) const

pure virtualnoexcept

Executes a compute shader.

Parameters

threadCount The number of thread groups per axis.

Implemented in LiteFX::Rendering::Backends::DirectX12CommandBuffer, and LiteFX::Rendering::Backends::VulkanCommandBuffer.

◆ draw() [1/2]

void LiteFX::Rendering::ICommandBuffer::draw	(	const IVertexBuffer &	vertexBuffer,
		const UInt32 &	instances = `1`,
		const UInt32 &	firstVertex = `0`,
		const UInt32 &	firstInstance = `0`
	)		const

inline

Draws all vertices from the vertex buffer provided in vertexBuffer .

This helper method binds the vertex buffer and issues a draw command for all vertices.

Parameters

vertexBuffer	The vertex buffer to draw from.
instances	The number of instances to draw.
firstVertex	The index of the first vertex to start drawing from.
firstInstance	The index of the first instance to draw.

◆ draw() [2/2]

virtual void LiteFX::Rendering::ICommandBuffer::draw	(	const UInt32 &	vertices,
		const UInt32 &	instances = `1`,
		const UInt32 &	firstVertex = `0`,
		const UInt32 &	firstInstance = `0`
	)		const

pure virtualnoexcept

Draws a number of vertices from the currently bound vertex buffer.

Parameters

vertices	The number of vertices to draw.
instances	The number of instances to draw.
firstVertex	The index of the first vertex to start drawing from.
firstInstance	The index of the first instance to draw.

Implemented in LiteFX::Rendering::Backends::DirectX12CommandBuffer, and LiteFX::Rendering::Backends::VulkanCommandBuffer.

◆ drawIndexed() [1/3]

void LiteFX::Rendering::ICommandBuffer::drawIndexed	(	const IIndexBuffer &	indexBuffer,
		const UInt32 &	instances = `1`,
		const UInt32 &	firstIndex = `0`,
		const Int32 &	vertexOffset = `0`,
		const UInt32 &	firstInstance = `0`
	)		const

inline

Draws the currently bound vertex buffer using the index buffer provided in indexBuffer .

This helper method binds the index buffer and issues a draw command for all indices.

Parameters

indexBuffer	The index buffer to draw with.
instances	The number of instances to draw.
firstIndex	The index of the first element of the index buffer to start drawing from.
vertexOffset	The offset added to each index to find the corresponding vertex.
firstInstance	The index of the first instance to draw.

◆ drawIndexed() [2/3]

void LiteFX::Rendering::ICommandBuffer::drawIndexed	(	const IVertexBuffer &	vertexBuffer,
		const IIndexBuffer &	indexBuffer,
		const UInt32 &	instances = `1`,
		const UInt32 &	firstIndex = `0`,
		const Int32 &	vertexOffset = `0`,
		const UInt32 &	firstInstance = `0`
	)		const

inline

Draws the vertex buffer provided by vertexBuffer using the index buffer, provided by indexBuffer .

This helper method binds the provided vertex and index buffers and issues a draw command for all indices.

Parameters

vertexBuffer	The vertex buffer to draw from.
indexBuffer	The index buffer to draw with.
instances	The number of instances to draw.
firstIndex	The index of the first element of the index buffer to start drawing from.
vertexOffset	The offset added to each index to find the corresponding vertex.
firstInstance	The index of the first instance to draw.

◆ drawIndexed() [3/3]

virtual void LiteFX::Rendering::ICommandBuffer::drawIndexed	(	const UInt32 &	indices,
		const UInt32 &	instances = `1`,
		const UInt32 &	firstIndex = `0`,
		const Int32 &	vertexOffset = `0`,
		const UInt32 &	firstInstance = `0`
	)		const

pure virtualnoexcept

Draws the currently bound vertex buffer with a set of indices from the currently bound index buffer.

Parameters

indices	The number of indices to draw.
instances	The number of instances to draw.
firstIndex	The index of the first element of the index buffer to start drawing from.
vertexOffset	The offset added to each index to find the corresponding vertex.
firstInstance	The index of the first instance to draw.

Implemented in LiteFX::Rendering::Backends::DirectX12CommandBuffer, and LiteFX::Rendering::Backends::VulkanCommandBuffer.

◆ end()

virtual void LiteFX::Rendering::ICommandBuffer::end ( ) const

pure virtual

Ends recording commands on the command buffer.

It is valid to call this method multiple times. If a command buffer is already closed, nothing will happen.

See also: begin

Implemented in LiteFX::Rendering::Backends::DirectX12CommandBuffer, and LiteFX::Rendering::Backends::VulkanCommandBuffer.

◆ generateMipMaps()

void LiteFX::Rendering::ICommandBuffer::generateMipMaps ( IImage & image )

inlinenoexcept

Uses the image at level 0 to generate mip-maps for the remaining levels.

It is strongly advised, not to generate mip maps at runtime. Instead, prefer using a format that supports pre-computed mip maps. If you have to, prefer computing mip maps in a pre-process.

Note that not all texture formats and sizes are supported for mip map generation and the result might not be satisfactory. For example, it is not possible to compute proper mip maps for pre-compressed formats. Textures should have power of two sizes in order to not appear under-sampled.

Note that generating mip maps might require the texture to be writable. You can transfer the texture into a non-writable resource afterwards to improve performance.

Parameters

commandBuffer The command buffer used to issue the transition and transfer operations.

◆ pushConstants()

void LiteFX::Rendering::ICommandBuffer::pushConstants	(	const IPushConstantsLayout &	layout,
		const void *const	memory
	)		const

inlinenoexcept

Pushes a block of memory into the push constants backing memory.

Parameters

layout	The layout of the push constants to update.
memory	A pointer to the source memory.

◆ transfer() [1/4]

void LiteFX::Rendering::ICommandBuffer::transfer	(	const IBuffer &	source,
		const IBuffer &	target,
		const UInt32 &	sourceElement = `0`,
		const UInt32 &	targetElement = `0`,
		const UInt32 &	elements = `1`
	)		const

inline

Performs a buffer-to-buffer transfer from source to target .

Parameters

source	The source buffer to transfer data from.
target	The target buffer to transfer data to.
sourceElement	The index of the first element in the source buffer to copy.
targetElement	The index of the first element in the target buffer to copy to.
elements	The number of elements to copy from the source buffer into the target buffer.

Exceptions

ArgumentOutOfRangeException Thrown, if the number of either the source buffer or the target buffer has not enough elements for the specified elements parameter.

◆ transfer() [2/4]

void LiteFX::Rendering::ICommandBuffer::transfer	(	const IBuffer &	source,
		const IImage &	target,
		const UInt32 &	sourceElement = `0`,
		const UInt32 &	firstSubresource = `0`,
		const UInt32 &	elements = `1`
	)		const

inline

Performs a buffer-to-image transfer from source to target .

The subresource parameter describes the index of the first sub-resource to copy. Each element gets copied into the subsequent sub-resource, where resources are counted in the following order:

Level Contains the mip-map levels.
Layer Contains the array slices.
Plane Contains planes for multi-planar formats.

E.g., if 6 elements should be copied to an image with 3 mip-map levels and 3 layers, the elements 0-2 contain the mip-map levels of the first layer, while elements 3-5 contain the three mip-map levels of the second layer. The third layer would not receive any data in this example. If the image format has multiple planes, this procedure would be repeated for each plane, however one buffer element only maps to one sub-resource.

Parameters

source	The source buffer to transfer data from.
target	The target image to transfer data to.
sourceElement	The index of the first element in the source buffer to copy.
firstSubresource	The index of the first sub-resource of the target image to receive data.
elements	The number of elements to copy from the source buffer into the target image sub-resources.

Exceptions

ArgumentOutOfRangeException Thrown, if the number of either the source buffer or the target buffer has not enough elements for the specified elements parameter.

◆ transfer() [3/4]

void LiteFX::Rendering::ICommandBuffer::transfer	(	const IImage &	source,
		const IBuffer &	target,
		const UInt32 &	firstSubresource = `0`,
		const UInt32 &	targetElement = `0`,
		const UInt32 &	subresources = `1`
	)		const

inline

Performs an image-to-buffer transfer from source to target .

The firstSubresource parameter describes the index of the first sub-resource to copy. Each element gets copied into the subsequent sub-resource, where resources are counted in the following order:

Level Contains the mip-map levels.
Layer Contains the array slices.
Plane Contains planes for multi-planar formats.

E.g., if 6 elements should be copied to an image with 3 mip-map levels and 3 layers, the elements 0-2 contain the mip-map levels of the first layer, while elements 3-5 contain the three mip-map levels of the second layer. The third layer would not receive any data in this example. If the image format has multiple planes, this procedure would be repeated for each plane, however one buffer element only maps to one sub-resource.

Parameters

source	The source image to transfer data from.
target	The target buffer to transfer data to.
firstSubresource	The index of the first sub-resource to copy from the source image.
targetElement	The index of the first target element to receive data.
subresources	The number of sub-resources to copy.

Exceptions

ArgumentOutOfRangeException Thrown, if the number of either the source buffer or the target buffer has not enough elements for the specified elements parameter.

◆ transfer() [4/4]

void LiteFX::Rendering::ICommandBuffer::transfer	(	const IImage &	source,
		const IImage &	target,
		const UInt32 &	sourceSubresource = `0`,
		const UInt32 &	targetSubresource = `0`,
		const UInt32 &	subresources = `1`
	)		const

inline

Performs an image-to-image transfer from source to target .

Parameters

source	The source image to transfer data from.
target	The target image to transfer data to.
sourceSubresource	The index of the first sub-resource to copy from the source image.
targetSubresource	The image of the first sub-resource in the target image to receive data.
subresources	The number of sub-resources to copy between the images.

Exceptions

ArgumentOutOfRangeException Thrown, if the number of either the source buffer or the target buffer has not enough elements for the specified elements parameter.

◆ use()

void LiteFX::Rendering::ICommandBuffer::use ( const IPipeline & pipeline ) const

inlinenoexcept

Sets the active pipeline state.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~ICommandBuffer()

Member Function Documentation

◆ barrier()

◆ begin()

◆ bind() [1/3]

◆ bind() [2/3]

◆ bind() [3/3]

◆ dispatch()

◆ draw() [1/2]

◆ draw() [2/2]

◆ drawIndexed() [1/3]

◆ drawIndexed() [2/3]

◆ drawIndexed() [3/3]

◆ end()

◆ generateMipMaps()

◆ pushConstants()

◆ transfer() [1/4]

◆ transfer() [2/4]

◆ transfer() [3/4]

◆ transfer() [4/4]

◆ use()