Interface for a command buffer. More...

#include <CommandBuffer.h>

Inheritance diagram for spark::render::ICommandBuffer:

Public Member Functions
virtual void	begin () const =0
	Sets the command buffer to recording state, allowing it to receive commands that should be transmitted to the CommandQueue.

virtual void	end () const =0
	Ends the recording of the command buffer.

virtual bool	isRecording () const noexcept=0
	Checks if the command buffer is recording.

virtual bool	isSecondary () const noexcept=0
	Checks if the command buffer is a secondary command buffer.

void	transfer (IBuffer &source, IBuffer &target, unsigned int source_element=0, unsigned int target_element=0, unsigned int elements=1) const
	Performs a buffer to buffer transfer from `source` to `target`.

void	transfer (std::shared_ptr< IBuffer > source, IBuffer &target, unsigned int source_element=0, unsigned int target_element=0, unsigned int elements=1) const
	Performs a buffer to buffer transfer from `source` to `target`.

void	transfer (IBuffer &source, IImage &target, unsigned int source_element=0, unsigned int first_subresource=0, unsigned int elements=1) const
	Performs a buffer to image transfer from `source` to `target`.

void	transfer (std::shared_ptr< IBuffer > source, IImage &target, unsigned int source_element=0, unsigned int first_subresource=0, unsigned int elements=1) const
	Performs a buffer to image transfer from `source` to `target`.

void	transfer (IImage &source, IImage &target, unsigned int source_subresource=0, unsigned int target_subresource=0, unsigned int subresources=1) const
	Performs an image to buffer transfer from `source` to `target`.

void	transfer (std::shared_ptr< IImage > source, IImage &target, unsigned int source_subresource=0, unsigned int target_subresource=0, unsigned int subresources=1) const
	Performs an image to buffer transfer from `source` to `target`.

void	transfer (IImage &source, IBuffer &target, unsigned int first_subresource=0, unsigned int target_element=0, unsigned int subresources=1) const
	Performs an image to buffer transfer from `source` to `target`.

void	transfer (std::shared_ptr< IImage > source, IBuffer &target, unsigned int first_subresource=0, unsigned int target_element=0, unsigned int subresources=1) const
	Performs an image to buffer transfer from `source` to `target`.

void	use (const IPipeline &pipeline) const noexcept
	Sets the `pipeline` to be used for subsequent draw calls.

void	bind (const IDescriptorSet &descriptor_set) const
	Binds the `descriptor_set` to the last pipeline used by the command buffer.

void	bind (const IDescriptorSet &descriptor_set, const IPipeline &pipeline) const noexcept
	Binds the `descriptor_set` to the `pipeline`.

void	bind (const IVertexBuffer &vertex_buffer) const noexcept
	Binds the `vertex_buffer` to the pipeline.

void	bind (const IIndexBuffer &index_buffer) const noexcept
	Binds the `index_buffer` to the pipeline.

void	draw (unsigned int vertices, unsigned int instances=1, unsigned int first_vertex=0, unsigned int first_instance=0) const noexcept
	Draw a number of vertices from the currently bound vertex buffer.

void	draw (const IVertexBuffer &vertex_buffer, unsigned int instances=1, unsigned int first_vertex=0, unsigned int first_instance=0) const noexcept
	Draw all vertices from the provided IVertexBuffer in `vertex_buffer`.

void	drawIndexed (unsigned int indices, unsigned int instances=1, unsigned int first_index=0, int vertex_offset=0, unsigned int first_instance=0) const noexcept
	Draws the currently bound vertex buffer with a set of indices from the currently bound index buffer.

void	drawIndexed (const IIndexBuffer &index_buffer, unsigned int instances=1, unsigned int first_index=0, int vertex_offset=0, unsigned int first_instance=0) const noexcept
	Draws the currently bound IVertexBuffer using the provided IIndexBuffer in `index_buffer`.

void	drawIndexed (const IVertexBuffer &vertex_buffer, const IIndexBuffer &index_buffer, unsigned int instances=1, unsigned int first_index=0, int vertex_offset=0, unsigned int first_instance=0) const noexcept
	Draws the currently bound IVertexBuffer using the provided IIndexBuffer in `index_buffer`.

virtual void	dispatch () const noexcept=0
	Executes a compute shader.

void	execute (std::shared_ptr< const ICommandBuffer > command_buffer) const
	Executes a secondary command buffer.

void	execute (const std::vector< std::shared_ptr< const ICommandBuffer > > &command_buffers) const
	Executes a series of secondary command buffers/bundles.

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

virtual void	setViewport (const IViewport *viewport) const noexcept=0
	Sets the viewport to use for subsequent draw calls.

virtual void	setViewports (std::span< const IViewport * > viewports) const noexcept=0
	Sets the viewports to use for subsequent draw calls.

virtual void	setScissor (const IScissor *scissor) const noexcept=0
	Sets the scissor to use for subsequent draw calls.

virtual void	setScissors (std::span< const IScissor * > scissors) const noexcept=0
	Sets the scissors to use for subsequent draw calls.

virtual void	setBlendFactors (const math::Vector4< float > &blend_factors) const noexcept=0
	Sets the blend factors to use for subsequent draw calls.

virtual void	setStencilRef (unsigned int stencil_ref) const noexcept=0
	Sets the stencil reference value to use for subsequent draw calls.

virtual void	releaseSharedState () const =0
	Called by the parent command queue to signal that the command buffer should release it's shared state.

Detailed Description

Interface for a command buffer.

Member Function Documentation

◆ begin()

virtual void spark::render::ICommandBuffer::begin ( ) const

pure virtual

Sets the command buffer to recording state, allowing it to receive commands that should be transmitted to the CommandQueue.

Note: You should wait for the buffer to be executed before recording again.

Exceptions

spark::base::CommandBufferAlreadyRecordingException if the command buffer is already recording.

Implemented in spark::render::vk::VulkanCommandBuffer.

◆ bind() [1/4]

void spark::render::ICommandBuffer::bind ( const IDescriptorSet & descriptor_set ) const

inline

Binds the descriptor_set to the last pipeline used by the command buffer.

Parameters

descriptor_set The IDescriptorSet to bind.

Exceptions

base::BadArgumentException if the command buffer has not used a pipeline yet.

◆ bind() [2/4]

void spark::render::ICommandBuffer::bind	(	const IDescriptorSet &	descriptor_set,
		const IPipeline &	pipeline ) const

inlinenoexcept

Binds the descriptor_set to the pipeline.

Parameters

descriptor_set	The IDescriptorSet to bind.
pipeline	The IPipeline to bind the `descriptor_set` to.

◆ bind() [3/4]

void spark::render::ICommandBuffer::bind ( const IIndexBuffer & index_buffer ) const

inlinenoexcept

Binds the index_buffer to the pipeline.

Parameters

index_buffer The IIndexBuffer to bind to the pipeline.

Note: After binding the index buffer, the next call to ICommandBuffer::drawIndexed() will read data from the bound buffer until another index buffer is bound.

◆ bind() [4/4]

void spark::render::ICommandBuffer::bind ( const IVertexBuffer & vertex_buffer ) const

inlinenoexcept

Binds the vertex_buffer to the pipeline.

Parameters

vertex_buffer The IVertexBuffer to bind to the pipeline.

Note: After binding the vertex buffer, the next call to ICommandBuffer::draw() or ICommandBuffer::drawIndexed() will read vertex data from the bound buffer until another vertex buffer is bound.

◆ dispatch()

virtual void spark::render::ICommandBuffer::dispatch ( ) const

pure virtualnoexcept

Executes a compute shader.

Implemented in spark::render::vk::VulkanCommandBuffer.

◆ draw() [1/2]

void spark::render::ICommandBuffer::draw	(	const IVertexBuffer &	vertex_buffer,
		unsigned int	instances = 1,
		unsigned int	first_vertex = 0,
		unsigned int	first_instance = 0 ) const

inlinenoexcept

Draw all vertices from the provided IVertexBuffer in vertex_buffer.

Parameters

vertex_buffer	The IVertexBuffer to draw from.
instances	The number of instances to draw.
first_vertex	The index of the first vertex to start drawing from.
first_instance	The index of the first instance to draw.

◆ draw() [2/2]

void spark::render::ICommandBuffer::draw	(	unsigned int	vertices,
		unsigned int	instances = 1,
		unsigned int	first_vertex = 0,
		unsigned int	first_instance = 0 ) const

inlinenoexcept

Draw 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.
first_vertex	The index of the first vertex to draw.
first_instance	The index of the first instance to draw.

◆ drawIndexed() [1/3]

void spark::render::ICommandBuffer::drawIndexed	(	const IIndexBuffer &	index_buffer,
		unsigned int	instances = 1,
		unsigned int	first_index = 0,
		int	vertex_offset = 0,
		unsigned int	first_instance = 0 ) const

inlinenoexcept

Draws the currently bound IVertexBuffer using the provided IIndexBuffer in index_buffer.

Parameters

index_buffer	The IIndexBuffer to draw with.
instances	The number of instances to draw.
first_index	The index of the first element of the `index_buffer` to start drawing from.
vertex_offset	The offset to add to each index to find the vertex to draw.
first_instance	The index of the first instance to draw.

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

◆ drawIndexed() [2/3]

void spark::render::ICommandBuffer::drawIndexed	(	const IVertexBuffer &	vertex_buffer,
		const IIndexBuffer &	index_buffer,
		unsigned int	instances = 1,
		unsigned int	first_index = 0,
		int	vertex_offset = 0,
		unsigned int	first_instance = 0 ) const

inlinenoexcept

Draws the currently bound IVertexBuffer using the provided IIndexBuffer in index_buffer.

Parameters

vertex_buffer	The IVertexBuffer to draw from.
index_buffer	The IIndexBuffer to draw with.
instances	The number of instances to draw.
first_index	The index of the first element of the `index_buffer` to start drawing from.
vertex_offset	The offset to add to each index to find the vertex to draw.
first_instance	The index of the first instance to draw.

◆ drawIndexed() [3/3]

void spark::render::ICommandBuffer::drawIndexed	(	unsigned int	indices,
		unsigned int	instances = 1,
		unsigned int	first_index = 0,
		int	vertex_offset = 0,
		unsigned int	first_instance = 0 ) const

inlinenoexcept

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.
first_index	The index of the first index to draw.
vertex_offset	The offset to add to each index to find the vertex to draw.
first_instance	The index of the first instance to draw.

◆ end()

virtual void spark::render::ICommandBuffer::end ( ) const

pure virtual

Ends the recording of the command buffer.

Note: You can call this method multiple times but it will do nothing after the first call.

Implemented in spark::render::vk::VulkanCommandBuffer.

◆ execute() [1/2]

void spark::render::ICommandBuffer::execute ( const std::vector< std::shared_ptr< const ICommandBuffer > > & command_buffers ) const

inline

Executes a series of secondary command buffers/bundles.

Parameters

command_buffers The std::vector of secondary command buffers to execute.

◆ execute() [2/2]

void spark::render::ICommandBuffer::execute ( std::shared_ptr< const ICommandBuffer > command_buffer ) const

inline

Executes a secondary command buffer.

Parameters

command_buffer The secondary command buffer to execute.

◆ isRecording()

virtual bool spark::render::ICommandBuffer::isRecording ( ) const

nodiscardpure virtualnoexcept

Checks if the command buffer is recording.

Returns: true if the command buffer is recording, false otherwise.

Implemented in spark::render::vk::VulkanCommandBuffer.

◆ isSecondary()

virtual bool spark::render::ICommandBuffer::isSecondary ( ) const

nodiscardpure virtualnoexcept

Checks if the command buffer is a secondary command buffer.

Returns: true if the command buffer is a secondary command buffer, false otherwise.

Implemented in spark::render::vk::VulkanCommandBuffer.

◆ pushConstants()

void spark::render::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 IPushConstantsLayout to update.
memory	A pointer to the source memory.

◆ releaseSharedState()

virtual void spark::render::ICommandBuffer::releaseSharedState ( ) const

pure virtual

Called by the parent command queue to signal that the command buffer should release it's shared state.

Implemented in spark::render::vk::VulkanCommandBuffer.

◆ setBlendFactors()

virtual void spark::render::ICommandBuffer::setBlendFactors ( const math::Vector4< float > & blend_factors ) const

pure virtualnoexcept

Sets the blend factors to use for subsequent draw calls.

Parameters

blend_factors The math::Vector4<float> containing the blend factors to use for subsequent draw calls.

Note: Blend factors are set for all render targets that use the blend modes ConstantColor, OneMinusConstantColor, ConstantAlpha or OneMinusConstantAlpha.

Implemented in spark::render::vk::VulkanCommandBuffer.

◆ setScissor()

virtual void spark::render::ICommandBuffer::setScissor ( const IScissor * scissor ) const

pure virtualnoexcept

Sets the scissor to use for subsequent draw calls.

Parameters

scissor The IScissor to use for subsequent draw calls.

Implemented in spark::render::vk::VulkanCommandBuffer.

◆ setScissors()

virtual void spark::render::ICommandBuffer::setScissors ( std::span< const IScissor * > scissors ) const

pure virtualnoexcept

Sets the scissors to use for subsequent draw calls.

Parameters

scissors A std::span of IScissor to use for subsequent draw calls.

Implemented in spark::render::vk::VulkanCommandBuffer.

◆ setStencilRef()

virtual void spark::render::ICommandBuffer::setStencilRef ( unsigned int stencil_ref ) const

pure virtualnoexcept

Sets the stencil reference value to use for subsequent draw calls.

Parameters

stencil_ref The stencil reference value to use for subsequent draw calls.

◆ setViewport()

virtual void spark::render::ICommandBuffer::setViewport ( const IViewport * viewport ) const

pure virtualnoexcept

Sets the viewport to use for subsequent draw calls.

Parameters

viewport The IViewport to use for subsequent draw calls.

Implemented in spark::render::vk::VulkanCommandBuffer.

◆ setViewports()

virtual void spark::render::ICommandBuffer::setViewports ( std::span< const IViewport * > viewports ) const

pure virtualnoexcept

Sets the viewports to use for subsequent draw calls.

Parameters

viewports The std::span of IViewport to use for subsequent draw calls.

Implemented in spark::render::vk::VulkanCommandBuffer.

◆ transfer() [1/8]

void spark::render::ICommandBuffer::transfer	(	IBuffer &	source,
		IBuffer &	target,
		unsigned int	source_element = 0,
		unsigned int	target_element = 0,
		unsigned int	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.
source_element	The index of the first element to transfer from the source buffer.
target_element	The index of the first element to transfer to the target buffer.
elements	The number of elements to transfer.

Exceptions

spark::base::ArgumentOutOfRangeException if the number of either the source or target buffers has not enough elements for the specified elements parameter.

◆ transfer() [2/8]

void spark::render::ICommandBuffer::transfer	(	IBuffer &	source,
		IImage &	target,
		unsigned int	source_element = 0,
		unsigned int	first_subresource = 0,
		unsigned int	elements = 1 ) const

inline

Performs a buffer to image transfer from source to target.

Parameters

source	The source buffer to transfer data from.
target	The target image to transfer data to.
source_element	The index of the first element to transfer from the source buffer.
first_subresource	The index of the first subresource of the target image to transfer data to.
elements	The number of elements to transfer from the source buffer to the target image subresources.

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

Level (mipmaps)
Layer (array slice)
Plane (for multi-planar formats)

Exceptions

spark::base::ArgumentOutOfRangeException if the number of either the source buffer or the target image has not enough elements for the specified elements parameter.

◆ transfer() [3/8]

void spark::render::ICommandBuffer::transfer	(	IImage &	source,
		IBuffer &	target,
		unsigned int	first_subresource = 0,
		unsigned int	target_element = 0,
		unsigned int	subresources = 1 ) const

inline

Performs an image to buffer transfer from source to target.

Parameters

source	The source image to transfer data from.
target	The target buffer to transfer data to.
first_subresource	The index of the first subresource of the source image to transfer data from.
target_element	The index of the first element to transfer to the target buffer.
subresources	The number of subresources to transfer from the source image to the target buffer.

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

Level (mipmaps)
Layer (array slice)
Plane (for multi-planar formats)

So, 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.

Note: You have to manually ensure that source and target buffers are in the proper state for transfer operations.

Exceptions

spark::base::ArgumentOutOfRangeException if the number of either the source image or the target buffer has not enough elements for the specified subresources parameter.

◆ transfer() [4/8]

void spark::render::ICommandBuffer::transfer	(	IImage &	source,
		IImage &	target,
		unsigned int	source_subresource = 0,
		unsigned int	target_subresource = 0,
		unsigned int	subresources = 1 ) const

inline

Performs an image to buffer transfer from source to target.

Parameters

source	The source image to transfer data from.
target	The target buffer to transfer data to.
source_subresource	The index of the first subresource of the source image to transfer data from.
target_subresource	The index of the first element to transfer to the target buffer.
subresources	The number of subresources to transfer from the source image to the target buffer.

Note: You have to manually ensure that source and target buffers are in the proper state for transfer operations.

Exceptions

spark::base::ArgumentOutOfRangeException if the number of either the source image or the target buffer has not enough elements for the specified subresources parameter.

◆ transfer() [5/8]

void spark::render::ICommandBuffer::transfer	(	std::shared_ptr< IBuffer >	source,
		IBuffer &	target,
		unsigned int	source_element = 0,
		unsigned int	target_element = 0,
		unsigned int	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.
source_element	The index of the first element to transfer from the source buffer.
target_element	The index of the first element to transfer to the target buffer.
elements	The number of elements to transfer.

Exceptions

spark::base::ArgumentOutOfRangeException if the number of either the source or target buffers has not enough elements for the specified elements parameter.

◆ transfer() [6/8]

void spark::render::ICommandBuffer::transfer	(	std::shared_ptr< IBuffer >	source,
		IImage &	target,
		unsigned int	source_element = 0,
		unsigned int	first_subresource = 0,
		unsigned int	elements = 1 ) const

inline

Performs a buffer to image transfer from source to target.

Parameters

source	The source buffer to transfer data from.
target	The target image to transfer data to.
source_element	The index of the first element to transfer from the source buffer.
first_subresource	The index of the first subresource of the target image to transfer data to.
elements	The number of elements to transfer from the source buffer to the target image subresources.

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

Level (mipmaps)
Layer (array slice)
Plane (for multi-planar formats)

Exceptions

spark::base::ArgumentOutOfRangeException if the number of either the source buffer or the target image has not enough elements for the specified elements parameter.

◆ transfer() [7/8]

void spark::render::ICommandBuffer::transfer	(	std::shared_ptr< IImage >	source,
		IBuffer &	target,
		unsigned int	first_subresource = 0,
		unsigned int	target_element = 0,
		unsigned int	subresources = 1 ) const

inline

Performs an image to buffer transfer from source to target.

Parameters

source	The source image to transfer data from.
target	The target buffer to transfer data to.
first_subresource	The index of the first subresource of the source image to transfer data from.
target_element	The index of the first element to transfer to the target buffer.
subresources	The number of subresources to transfer from the source image to the target buffer.

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

Level (mipmaps)
Layer (array slice)
Plane (for multi-planar formats)

So, 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.

Note: You have to manually ensure that source and target buffers are in the proper state for transfer operations.

Exceptions

spark::base::ArgumentOutOfRangeException if the number of either the source image or the target buffer has not enough elements for the specified subresources parameter.

◆ transfer() [8/8]

void spark::render::ICommandBuffer::transfer	(	std::shared_ptr< IImage >	source,
		IImage &	target,
		unsigned int	source_subresource = 0,
		unsigned int	target_subresource = 0,
		unsigned int	subresources = 1 ) const

inline

Performs an image to buffer transfer from source to target.

Parameters

source	The source image to transfer data from.
target	The target buffer to transfer data to.
source_subresource	The index of the first subresource of the source image to transfer data from.
target_subresource	The index of the first element to transfer to the target buffer.
subresources	The number of subresources to transfer from the source image to the target buffer.

Note: You have to manually ensure that source and target buffers are in the proper state for transfer operations.

Exceptions

spark::base::ArgumentOutOfRangeException if the number of either the source image or the target buffer has not enough elements for the specified subresources parameter.

◆ use()

void spark::render::ICommandBuffer::use ( const IPipeline & pipeline ) const

inlinenoexcept

Sets the pipeline to be used for subsequent draw calls.

Parameters

pipeline A IPipeline object to use for subsequent draw calls.

Public Member Functions

Detailed Description

Member Function Documentation

◆ begin()

◆ bind() [1/4]

◆ bind() [2/4]

◆ bind() [3/4]

◆ bind() [4/4]

◆ dispatch()

◆ draw() [1/2]

◆ draw() [2/2]

◆ drawIndexed() [1/3]

◆ drawIndexed() [2/3]

◆ drawIndexed() [3/3]

◆ end()

◆ execute() [1/2]

◆ execute() [2/2]

◆ isRecording()

◆ isSecondary()

◆ pushConstants()

◆ releaseSharedState()

◆ setBlendFactors()

◆ setScissor()

◆ setScissors()

◆ setStencilRef()

◆ setViewport()

◆ setViewports()

◆ transfer() [1/8]

◆ transfer() [2/8]

◆ transfer() [3/8]

◆ transfer() [4/8]

◆ transfer() [5/8]

◆ transfer() [6/8]

◆ transfer() [7/8]

◆ transfer() [8/8]

◆ use()