LiteFX 0.4.1.2025
Computer Graphics Engine
Loading...
Searching...
No Matches
LiteFX::Rendering::ICommandBuffer Class Referenceabstract

The interface for a command buffer. More...

#include <rendering_api.hpp>

Inherits LiteFX::SharedObject.

Inherited by LiteFX::Rendering::CommandBuffer< DirectX12CommandBuffer, IDirectX12Buffer, IDirectX12VertexBuffer, IDirectX12IndexBuffer, IDirectX12Image, DirectX12Barrier, DirectX12PipelineState, DirectX12BottomLevelAccelerationStructure, DirectX12TopLevelAccelerationStructure >, LiteFX::Rendering::CommandBuffer< VulkanCommandBuffer, IVulkanBuffer, IVulkanVertexBuffer, IVulkanIndexBuffer, IVulkanImage, VulkanBarrier, VulkanPipelineState, VulkanBottomLevelAccelerationStructure, VulkanTopLevelAccelerationStructure >, and LiteFX::Rendering::CommandBuffer< TCommandBuffer, TBuffer, TVertexBuffer, TIndexBuffer, TImage, TBarrier, TPipeline, TBLAS, TTLAS >.

Public Member Functions

 ~ICommandBuffer () noexcept override=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.
 
virtual void end () const =0
 Ends recording commands on the command buffer.
 
virtual bool isSecondary () const noexcept=0
 Returns true, if the command buffer is a secondary command buffer, or false otherwise.
 
virtual void track (SharedPtr< const IBuffer > buffer) const =0
 Sets up tracking for a buffer, so that it will not be destroyed until the command buffer has been executed.
 
virtual void track (SharedPtr< const IImage > image) const =0
 Sets up tracking for an image, so that it will not be destroyed until the command buffer has been executed.
 
virtual void track (SharedPtr< const ISampler > sampler) const =0
 Sets up tracking for a sampler state, so that it will not be destroyed until the command buffer has been executed.
 
SharedPtr< const ICommandQueuequeue () const noexcept
 Gets a pointer to the command queue that this command buffer was allocated from or nullptr, if the queue has already been released.
 
UniquePtr< IBarriermakeBarrier (PipelineStage syncBefore, PipelineStage syncAfter) const
 Creates a new barrier instance.
 
void barrier (const IBarrier &barrier) const noexcept
 Executes the transitions that have been added to barrier .
 
void transfer (const IBuffer &source, const IBuffer &target, UInt32 sourceElement=0, UInt32 targetElement=0, UInt32 elements=1) const
 Performs a buffer-to-buffer transfer from source to target .
 
void transfer (const SharedPtr< const IBuffer > &source, const IBuffer &target, UInt32 sourceElement=0, UInt32 targetElement=0, UInt32 elements=1) const
 Performs a buffer-to-buffer transfer from source to target .
 
void transfer (const void *const data, size_t size, const IBuffer &target, UInt32 targetElement=0, UInt32 elements=1) const
 Performs a buffer-to-buffer transfer from a temporary buffer into target .
 
void transfer (Span< const void *const > data, size_t elementSize, const IBuffer &target, UInt32 targetElement=0) const
 Performs a buffer-to-buffer transfer from a temporary buffer into target .
 
void transfer (const IBuffer &source, const IImage &target, UInt32 sourceElement=0, UInt32 firstSubresource=0, UInt32 elements=1) const
 Performs a buffer-to-image transfer from source to target .
 
void transfer (const SharedPtr< const IBuffer > &source, const IImage &target, UInt32 sourceElement=0, UInt32 firstSubresource=0, UInt32 elements=1) const
 Performs a buffer-to-image transfer from source to target .
 
void transfer (const void *const data, size_t size, const IImage &target, UInt32 subresource=0) const
 Performs a buffer-to-buffer transfer from a temporary buffer into target .
 
void transfer (Span< const void *const > data, size_t elementSize, const IImage &target, UInt32 firstSubresource=0, UInt32 elements=1) const
 Performs a buffer-to-buffer transfer from a temporary buffer into target .
 
void transfer (const IImage &source, const IImage &target, UInt32 sourceSubresource=0, UInt32 targetSubresource=0, UInt32 subresources=1) const
 Performs an image-to-image transfer from source to target .
 
void transfer (const SharedPtr< const IImage > &source, const IImage &target, UInt32 sourceSubresource=0, UInt32 targetSubresource=0, UInt32 subresources=1) const
 Performs an image-to-image transfer from source to target .
 
void transfer (const IImage &source, const IBuffer &target, UInt32 firstSubresource=0, UInt32 targetElement=0, UInt32 subresources=1) const
 Performs an image-to-buffer transfer from source to target .
 
void transfer (const SharedPtr< const IImage > &source, const IBuffer &target, UInt32 firstSubresource=0, UInt32 targetElement=0, UInt32 subresources=1) const
 Performs an image-to-buffer transfer from source to target .
 
void use (const IPipeline &pipeline) const noexcept
 Sets the active pipeline state.
 
void bind (const IDescriptorSet &descriptorSet) const
 Binds the provided descriptor to the last pipeline that was used by the command buffer.
 
template<typename TSelf , typename T >
requires std::derived_from<T, IDescriptorSet>
void bind (this const TSelf &self, std::initializer_list< const T * > descriptorSets)
 Binds an arbitrary input range of descriptor sets to the last pipeline that was used by the command buffer.
 
template<typename TSelf >
requires std::derived_from<std::remove_cv_t<std::remove_pointer_t<std::iter_value_t<std::ranges::iterator_t<std::remove_cv_t<std::remove_reference_t<decltype(descriptorSets)>>>>>>, IDescriptorSet>
void bind (this const TSelf &self, std::ranges::input_range auto &&descriptorSets)
 Binds an arbitrary input range of descriptor sets to the last pipeline that was used by the command buffer.
 
void bind (Span< const IDescriptorSet * > descriptorSets) const
 Binds an arbitrary input range of descriptor sets to the last pipeline that was used by the command buffer.
 
void bind (const IDescriptorSet &descriptorSet, const IPipeline &pipeline) const
 Binds the provided descriptor set to the provided pipeline.
 
template<typename TSelf , typename T >
void bind (this const TSelf &self, std::initializer_list< const T * > descriptorSets, const typename TSelf::pipeline_type &pipeline)
 Binds an arbitrary input range of descriptor sets to the last pipeline that was used by the command buffer.
 
template<typename TSelf >
requires std::derived_from<std::remove_cv_t<std::remove_pointer_t<std::iter_value_t<std::ranges::iterator_t<std::remove_cv_t<std::remove_reference_t<decltype(descriptorSets)>>>>>>, IDescriptorSet>
void bind (this const TSelf &self, std::ranges::input_range auto &&descriptorSets, const typename TSelf::pipeline_type &pipeline)
 Binds an arbitrary input range of descriptor sets to the provided pipeline.
 
void bind (Span< const IDescriptorSet * > descriptorSets, const IPipeline &pipeline) const
 Binds an arbitrary input range of descriptor sets to the provided pipeline.
 
void bind (const IVertexBuffer &buffer) const
 Binds a vertex buffer to the pipeline.
 
void bind (const IIndexBuffer &buffer) const
 Binds a index buffer to the pipeline.
 
virtual void dispatch (const Vector3u &threadGroupCount) const noexcept=0
 Executes a compute shader.
 
void dispatch (UInt32 x, UInt32 y, UInt32 z) const noexcept
 Executes a compute shader.
 
void dispatchIndirect (const IBuffer &batchBuffer, UInt32 batchCount, UInt64 offset=0) const noexcept
 Executes a set of indirect dispatches.
 
virtual void dispatchMesh (const Vector3u &threadGroupCount) const noexcept=0
 Executes a mesh shader pipeline.
 
void dispatchMesh (UInt32 x, UInt32 y, UInt32 z) const noexcept
 Executes a mesh shader pipeline.
 
void dispatchMeshIndirect (const IBuffer &batchBuffer, UInt32 batchCount, UInt64 offset=0) const noexcept
 Executes a set of indirect mesh shader dispatches.
 
void dispatchMeshIndirect (const IBuffer &batchBuffer, const IBuffer &countBuffer, UInt64 offset=0, UInt64 countOffset=0, UInt32 maxBatches=std::numeric_limits< UInt32 >::max()) const noexcept
 Executes a set of indirect mesh shader dispatches.
 
void traceRays (UInt32 width, UInt32 height, UInt32 depth, const ShaderBindingTableOffsets &offsets, const IBuffer &rayGenerationShaderBindingTable, const IBuffer *missShaderBindingTable=nullptr, const IBuffer *hitShaderBindingTable=nullptr, const IBuffer *callableShaderBindingTable=nullptr) const noexcept
 Executes a query on a ray-tracing pipeline.
 
void traceRays (const Vector3u &dimensions, const ShaderBindingTableOffsets &offsets, const IBuffer &rayGenerationShaderBindingTable, const IBuffer *missShaderBindingTable=nullptr, const IBuffer *hitShaderBindingTable=nullptr, const IBuffer *callableShaderBindingTable=nullptr) const noexcept
 Executes a query on a ray-tracing pipeline.
 
virtual void draw (UInt32 vertices, UInt32 instances=1, UInt32 firstVertex=0, UInt32 firstInstance=0) const noexcept=0
 Draws a number of vertices from the currently bound vertex buffer.
 
void draw (const IVertexBuffer &vertexBuffer, UInt32 instances=1, UInt32 firstVertex=0, UInt32 firstInstance=0) const
 Draws all vertices from the vertex buffer provided in vertexBuffer .
 
void drawIndirect (const IBuffer &batchBuffer, UInt32 batchCount, UInt64 offset=0) const noexcept
 Executes a set of indirect non-indexed draw calls.
 
void drawIndirect (const IBuffer &batchBuffer, const IBuffer &countBuffer, UInt64 offset=0, UInt64 countOffset=0, UInt32 maxBatches=std::numeric_limits< UInt32 >::max()) const noexcept
 Executes a set of indirect non-indexed draw calls.
 
virtual void drawIndexed (UInt32 indices, UInt32 instances=1, UInt32 firstIndex=0, Int32 vertexOffset=0, UInt32 firstInstance=0) const noexcept=0
 Draws the currently bound vertex buffer with a set of indices from the currently bound index buffer.
 
void drawIndexed (const IIndexBuffer &indexBuffer, UInt32 instances=1, UInt32 firstIndex=0, Int32 vertexOffset=0, UInt32 firstInstance=0) const
 Draws the currently bound vertex buffer using the index buffer provided in indexBuffer .
 
void drawIndexed (const IVertexBuffer &vertexBuffer, const IIndexBuffer &indexBuffer, UInt32 instances=1, UInt32 firstIndex=0, Int32 vertexOffset=0, UInt32 firstInstance=0) const
 Draws the vertex buffer provided by vertexBuffer using the index buffer, provided by indexBuffer .
 
void drawIndexedIndirect (const IBuffer &batchBuffer, UInt32 batchCount, UInt64 offset=0) const noexcept
 Executes a set of indirect indexed draw calls.
 
void drawIndexedIndirect (const IBuffer &batchBuffer, const IBuffer &countBuffer, UInt64 offset=0, UInt64 countOffset=0, UInt32 maxBatches=std::numeric_limits< UInt32 >::max()) const noexcept
 Executes a set of indirect indexed draw calls.
 
void pushConstants (const IPushConstantsLayout &layout, const void *const memory) const
 Pushes a block of memory into the push constants backing memory.
 
virtual void setViewports (Span< const IViewport * > viewports) const =0
 Sets the viewports used for the subsequent draw calls.
 
virtual void setViewports (const IViewport *viewport) const =0
 Sets the viewport used for the subsequent draw calls.
 
virtual void setScissors (Span< const IScissor * > scissors) const =0
 Sets the scissor rectangles used for the subsequent draw calls.
 
virtual void setScissors (const IScissor *scissor) const =0
 Sets the scissor rectangle used for the subsequent draw calls.
 
virtual void setBlendFactors (const Vector4f &blendFactors) const noexcept=0
 Sets the blend factors for the subsequent draw calls.
 
virtual void setStencilRef (UInt32 stencilRef) const noexcept=0
 Sets the stencil reference for the subsequent draw calls.
 
virtual UInt64 submit () const =0
 Submits the command buffer to parent command.
 
virtual void writeTimingEvent (const SharedPtr< const TimingEvent > &timingEvent) const =0
 Writes the current GPU time stamp value for the timing event.
 
void execute (const SharedPtr< const ICommandBuffer > &commandBuffer) const
 Executes a secondary command buffer/bundle.
 
void execute (Enumerable< SharedPtr< const ICommandBuffer > > commandBuffers) const
 Executes a series of secondary command buffers/bundles.
 
void buildAccelerationStructure (IBottomLevelAccelerationStructure &blas, const SharedPtr< const IBuffer > &scratchBuffer, const IBuffer &buffer, UInt64 offset=0) const
 Builds a bottom-level acceleration structure.
 
void buildAccelerationStructure (ITopLevelAccelerationStructure &tlas, const SharedPtr< const IBuffer > &scratchBuffer, const IBuffer &buffer, UInt64 offset=0) const
 Builds a top-level acceleration structure.
 
void updateAccelerationStructure (IBottomLevelAccelerationStructure &blas, const SharedPtr< const IBuffer > &scratchBuffer, const IBuffer &buffer, UInt64 offset=0) const
 Updates a bottom-level acceleration structure.
 
void updateAccelerationStructure (ITopLevelAccelerationStructure &tlas, const SharedPtr< const IBuffer > &scratchBuffer, const IBuffer &buffer, UInt64 offset=0) const
 Updates a top-level acceleration structure.
 
void copyAccelerationStructure (const IBottomLevelAccelerationStructure &from, const IBottomLevelAccelerationStructure &to, bool compress=false) const noexcept
 Copies the acceleration structure from into the acceleration structure to .
 
void copyAccelerationStructure (const ITopLevelAccelerationStructure &from, const ITopLevelAccelerationStructure &to, bool compress=false) const noexcept
 Copies the acceleration structure from into the acceleration structure to .
 
- 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.
 

Protected Member Functions

 ICommandBuffer () noexcept=default
 
 ICommandBuffer (ICommandBuffer &&) noexcept=default
 
 ICommandBuffer (const ICommandBuffer &)=default
 
ICommandBufferoperator= (const ICommandBuffer &)=default
 
ICommandBufferoperator= (ICommandBuffer &&) noexcept=default
 
virtual void releaseSharedState () const =0
 Called by the parent command queue to signal that the command buffer should release it's shared state.
 
- Protected Member Functions inherited from LiteFX::SharedObject
 SharedObject () noexcept=default
 Initializes a new shared object.
 
 SharedObject (SharedObject &&) noexcept=default
 
 SharedObject (const SharedObject &)=default
 
SharedObjectoperator= (SharedObject &&) noexcept=default
 
SharedObjectoperator= (const SharedObject &)=default
 

Friends

class ICommandQueue
 

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 buffer.

Constructor & Destructor Documentation

◆ ICommandBuffer() [1/3]

LiteFX::Rendering::ICommandBuffer::ICommandBuffer ( )
protecteddefaultnoexcept

◆ ICommandBuffer() [2/3]

LiteFX::Rendering::ICommandBuffer::ICommandBuffer ( ICommandBuffer && )
protecteddefaultnoexcept

◆ ICommandBuffer() [3/3]

LiteFX::Rendering::ICommandBuffer::ICommandBuffer ( const ICommandBuffer & )
protecteddefault

◆ ~ICommandBuffer()

LiteFX::Rendering::ICommandBuffer::~ICommandBuffer ( )
overridedefaultnoexcept

Member Function Documentation

◆ barrier()

void LiteFX::Rendering::ICommandBuffer::barrier ( const IBarrier & barrier) 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
barrierThe barrier containing the transitions to perform.

◆ 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
RuntimeExceptionThrown, if the command buffer is already recording.
See also
end

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

◆ bind() [1/10]

void LiteFX::Rendering::ICommandBuffer::bind ( const IDescriptorSet & descriptorSet) const
inline

Binds the provided descriptor to the last pipeline that was used by the command buffer.

Parameters
descriptorSetThe descriptor set to bind.
Exceptions
RuntimeExceptionThrown, if no pipeline has been used before attempting to bind the descriptor set.
See also
use

◆ bind() [2/10]

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

Binds the provided descriptor set to the provided pipeline.

Parameters
descriptorSetThe descriptor set to bind.
pipelineThe pipeline to bind the descriptor set to.

◆ bind() [3/10]

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

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
bufferThe index buffer to bind to the pipeline.
See also
IndexBuffer, drawIndexed

◆ bind() [4/10]

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

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
bufferThe vertex buffer to bind to the pipeline.
See also
VertexBuffer, draw, drawIndexed

◆ bind() [5/10]

void LiteFX::Rendering::ICommandBuffer::bind ( Span< const IDescriptorSet * > descriptorSets) const
inline

Binds an arbitrary input range of descriptor sets to the last pipeline that was used by the command buffer.

Note that if an element of descriptorSets is nullptr, it will be ignored.

Parameters
descriptorSetsThe pointers to the descriptor sets to bind.

◆ bind() [6/10]

void LiteFX::Rendering::ICommandBuffer::bind ( Span< const IDescriptorSet * > descriptorSets,
const IPipeline & pipeline ) const
inline

Binds an arbitrary input range of descriptor sets to the provided pipeline.

Note that if an element of descriptorSets is nullptr, it will be ignored.

Parameters
descriptorSetsThe pointers to the descriptor sets to bind.
pipelineThe pipeline to bind the descriptor set to.

◆ bind() [7/10]

template<typename TSelf , typename T >
requires std::derived_from<T, IDescriptorSet>
void LiteFX::Rendering::ICommandBuffer::bind ( this const TSelf & self,
std::initializer_list< const T * > descriptorSets )
inline

Binds an arbitrary input range of descriptor sets to the last pipeline that was used by the command buffer.

Note that if an element of descriptorSets is nullptr, it will be ignored.

Template Parameters
TThe type of the descriptor sets.
Parameters
descriptorSetsThe pointers to the descriptor sets to bind.
Exceptions
RuntimeExceptionThrown, if no pipeline has been used before attempting to bind the descriptor set.

◆ bind() [8/10]

template<typename TSelf , typename T >
void LiteFX::Rendering::ICommandBuffer::bind ( this const TSelf & self,
std::initializer_list< const T * > descriptorSets,
const typename TSelf::pipeline_type & pipeline )
inline

Binds an arbitrary input range of descriptor sets to the last pipeline that was used by the command buffer.

Note that if an element of descriptorSets is nullptr, it will be ignored.

Template Parameters
TThe type of the descriptor sets.
Parameters
descriptorSetsThe pointers to the descriptor sets to bind.
pipelineThe pipeline to bind the descriptor set to.
Exceptions
RuntimeExceptionThrown, if no pipeline has been used before attempting to bind the descriptor set.

◆ bind() [9/10]

template<typename TSelf >
requires std::derived_from<std::remove_cv_t<std::remove_pointer_t<std::iter_value_t<std::ranges::iterator_t<std::remove_cv_t<std::remove_reference_t<decltype(descriptorSets)>>>>>>, IDescriptorSet>
void LiteFX::Rendering::ICommandBuffer::bind ( this const TSelf & self,
std::ranges::input_range auto && descriptorSets )
inline

Binds an arbitrary input range of descriptor sets to the last pipeline that was used by the command buffer.

Note that if an element of descriptorSets is nullptr, it will be ignored.

Parameters
descriptorSetsThe pointers to the descriptor sets to bind.
Exceptions
RuntimeExceptionThrown, if no pipeline has been used before attempting to bind the descriptor set.

◆ bind() [10/10]

template<typename TSelf >
requires std::derived_from<std::remove_cv_t<std::remove_pointer_t<std::iter_value_t<std::ranges::iterator_t<std::remove_cv_t<std::remove_reference_t<decltype(descriptorSets)>>>>>>, IDescriptorSet>
void LiteFX::Rendering::ICommandBuffer::bind ( this const TSelf & self,
std::ranges::input_range auto && descriptorSets,
const typename TSelf::pipeline_type & pipeline )
inline

Binds an arbitrary input range of descriptor sets to the provided pipeline.

Note that if an element of descriptorSets is nullptr, it will be ignored.

Parameters
descriptorSetsThe pointers to the descriptor sets to bind.
pipelineThe pipeline to bind the descriptor set to.

◆ buildAccelerationStructure() [1/2]

void LiteFX::Rendering::ICommandBuffer::buildAccelerationStructure ( IBottomLevelAccelerationStructure & blas,
const SharedPtr< const IBuffer > & scratchBuffer,
const IBuffer & buffer,
UInt64 offset = 0 ) const
inline

Builds a bottom-level acceleration structure.

This method is only supported if the GraphicsDeviceFeature::RayTracing feature is enabled.

Parameters
blasThe bottom-level acceleration structure to build.
scratchBufferThe scratch buffer to use for building the acceleration structure.
bufferThe buffer that contains the acceleration structure after the build.
offsetThe offset into buffer at which the acceleration structure gets stored after the build.
Exceptions
ArgumentNotInitializedExceptionThrown, if the provided scratchBuffer is not initialized.
See also
IAccelerationStructure::build

◆ buildAccelerationStructure() [2/2]

void LiteFX::Rendering::ICommandBuffer::buildAccelerationStructure ( ITopLevelAccelerationStructure & tlas,
const SharedPtr< const IBuffer > & scratchBuffer,
const IBuffer & buffer,
UInt64 offset = 0 ) const
inline

Builds a top-level acceleration structure.

This method is only supported if the GraphicsDeviceFeature::RayTracing feature is enabled.

Parameters
tlasThe top-level acceleration structure to build.
scratchBufferThe scratch buffer to use for building the acceleration structure.
bufferThe buffer that contains the acceleration structure after the build.
offsetThe offset into buffer at which the acceleration structure gets stored after the build.
Exceptions
ArgumentNotInitializedExceptionThrown, if the provided scratchBuffer is not initialized.
See also
IAccelerationStructure::build

◆ copyAccelerationStructure() [1/2]

void LiteFX::Rendering::ICommandBuffer::copyAccelerationStructure ( const IBottomLevelAccelerationStructure & from,
const IBottomLevelAccelerationStructure & to,
bool compress = false ) const
inlinenoexcept

Copies the acceleration structure from into the acceleration structure to .

Prefer calling IBottomLevelAccelerationStructure::copy over directly issuing copy commands on a command buffer, as this will make sure that the destination buffer will be properly allocated and contains enough memory to store the copy. Only issue copies on the command buffer directly, if you want to retain the destination buffer and know for certain, that it contains a sufficient amount of memory.

This method is only supported if the GraphicsDeviceFeature::RayTracing feature is enabled.

Parameters
fromThe source acceleration structure to copy from.
toThe destination acceleration structure to copy to.
compressIf set to true, the acceleration structure will be compressed.

◆ copyAccelerationStructure() [2/2]

void LiteFX::Rendering::ICommandBuffer::copyAccelerationStructure ( const ITopLevelAccelerationStructure & from,
const ITopLevelAccelerationStructure & to,
bool compress = false ) const
inlinenoexcept

Copies the acceleration structure from into the acceleration structure to .

Prefer calling ITopLevelAccelerationStructure::copy over directly issuing copy commands on a command buffer, as this will make sure that the destination buffer will be properly allocated and contains enough memory to store the copy. Only issue copies on the command buffer directly, if you want to retain the destination buffer and know for certain, that it contains a sufficient amount of memory.

This method is only supported if the GraphicsDeviceFeature::RayTracing feature is enabled.

Parameters
fromThe source acceleration structure to copy from.
toThe destination acceleration structure to copy to.
compressIf set to true, the acceleration structure will be compressed.

◆ dispatch() [1/2]

◆ dispatch() [2/2]

void LiteFX::Rendering::ICommandBuffer::dispatch ( UInt32 x,
UInt32 y,
UInt32 z ) const
inlinenoexcept

Executes a compute shader.

Parameters
xThe number of thread groups along the x dimension.
yThe number of thread groups along the y dimension.
zThe number of thread groups along the z dimension.

◆ dispatchIndirect()

void LiteFX::Rendering::ICommandBuffer::dispatchIndirect ( const IBuffer & batchBuffer,
UInt32 batchCount,
UInt64 offset = 0 ) const
inlinenoexcept

Executes a set of indirect dispatches.

Parameters
batchBufferThe buffer that contains the batches.
batchCountThe number of batches in the buffer to execute.
offsetThe offset (in bytes) to the first batch in the batchBuffer .
See also
dispatch

◆ dispatchMesh() [1/2]

◆ dispatchMesh() [2/2]

void LiteFX::Rendering::ICommandBuffer::dispatchMesh ( UInt32 x,
UInt32 y,
UInt32 z ) const
inlinenoexcept

Executes a mesh shader pipeline.

This method is only supported if the GraphicsDeviceFeature::MeshShaders feature is enabled.

Parameters
xThe number of thread groups along the x dimension.
yThe number of thread groups along the y dimension.
zThe number of thread groups along the z dimension.

◆ dispatchMeshIndirect() [1/2]

void LiteFX::Rendering::ICommandBuffer::dispatchMeshIndirect ( const IBuffer & batchBuffer,
const IBuffer & countBuffer,
UInt64 offset = 0,
UInt64 countOffset = 0,
UInt32 maxBatches = std::numeric_limits<UInt32>::max() ) const
inlinenoexcept

Executes a set of indirect mesh shader dispatches.

Parameters
batchBufferThe buffer that contains the batches.
countBufferThe buffer that contains the number of batches to execute.
offsetThe offset (in bytes) to the first batch in the batchBuffer .
countOffsetThe offset (in bytes) to the number of batches in the countBuffer .
maxBatchesThe maximum number of batches executed, even if there are more batches in countBuffer .
See also
dispatch

◆ dispatchMeshIndirect() [2/2]

void LiteFX::Rendering::ICommandBuffer::dispatchMeshIndirect ( const IBuffer & batchBuffer,
UInt32 batchCount,
UInt64 offset = 0 ) const
inlinenoexcept

Executes a set of indirect mesh shader dispatches.

Parameters
batchBufferThe buffer that contains the batches.
batchCountThe number of batches in the buffer to execute.
offsetThe offset (in bytes) to the first batch in the batchBuffer .
See also
dispatchMesh

◆ draw() [1/2]

void LiteFX::Rendering::ICommandBuffer::draw ( const IVertexBuffer & vertexBuffer,
UInt32 instances = 1,
UInt32 firstVertex = 0,
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
vertexBufferThe vertex buffer to draw from.
instancesThe number of instances to draw.
firstVertexThe index of the first vertex to start drawing from.
firstInstanceThe index of the first instance to draw.

◆ draw() [2/2]

◆ drawIndexed() [1/3]

void LiteFX::Rendering::ICommandBuffer::drawIndexed ( const IIndexBuffer & indexBuffer,
UInt32 instances = 1,
UInt32 firstIndex = 0,
Int32 vertexOffset = 0,
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
indexBufferThe index buffer to draw with.
instancesThe number of instances to draw.
firstIndexThe index of the first element of the index buffer to start drawing from.
vertexOffsetThe offset added to each index to find the corresponding vertex.
firstInstanceThe index of the first instance to draw.

◆ drawIndexed() [2/3]

void LiteFX::Rendering::ICommandBuffer::drawIndexed ( const IVertexBuffer & vertexBuffer,
const IIndexBuffer & indexBuffer,
UInt32 instances = 1,
UInt32 firstIndex = 0,
Int32 vertexOffset = 0,
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
vertexBufferThe vertex buffer to draw from.
indexBufferThe index buffer to draw with.
instancesThe number of instances to draw.
firstIndexThe index of the first element of the index buffer to start drawing from.
vertexOffsetThe offset added to each index to find the corresponding vertex.
firstInstanceThe index of the first instance to draw.

◆ drawIndexed() [3/3]

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

◆ drawIndexedIndirect() [1/2]

void LiteFX::Rendering::ICommandBuffer::drawIndexedIndirect ( const IBuffer & batchBuffer,
const IBuffer & countBuffer,
UInt64 offset = 0,
UInt64 countOffset = 0,
UInt32 maxBatches = std::numeric_limits<UInt32>::max() ) const
inlinenoexcept

Executes a set of indirect indexed draw calls.

Parameters
batchBufferThe buffer that contains the batches.
countBufferThe buffer that contains the number of batches to execute.
offsetThe offset (in bytes) to the first batch in the batchBuffer .
countOffsetThe offset (in bytes) to the number of batches in the countBuffer .
maxBatchesThe maximum number of batches executed, even if there are more batches in countBuffer .
See also
drawIndexed

◆ drawIndexedIndirect() [2/2]

void LiteFX::Rendering::ICommandBuffer::drawIndexedIndirect ( const IBuffer & batchBuffer,
UInt32 batchCount,
UInt64 offset = 0 ) const
inlinenoexcept

Executes a set of indirect indexed draw calls.

Parameters
batchBufferThe buffer that contains the batches.
batchCountThe number of batches in the buffer to execute.
offsetThe offset (in bytes) to the first batch in the batchBuffer .
See also
drawIndexed

◆ drawIndirect() [1/2]

void LiteFX::Rendering::ICommandBuffer::drawIndirect ( const IBuffer & batchBuffer,
const IBuffer & countBuffer,
UInt64 offset = 0,
UInt64 countOffset = 0,
UInt32 maxBatches = std::numeric_limits<UInt32>::max() ) const
inlinenoexcept

Executes a set of indirect non-indexed draw calls.

Parameters
batchBufferThe buffer that contains the batches.
countBufferThe buffer that contains the number of batches to execute.
offsetThe offset (in bytes) to the first batch in the batchBuffer .
countOffsetThe offset (in bytes) to the number of batches in the countBuffer .
maxBatchesThe maximum number of batches executed, even if there are more batches in countBuffer .
See also
draw

◆ drawIndirect() [2/2]

void LiteFX::Rendering::ICommandBuffer::drawIndirect ( const IBuffer & batchBuffer,
UInt32 batchCount,
UInt64 offset = 0 ) const
inlinenoexcept

Executes a set of indirect non-indexed draw calls.

Parameters
batchBufferThe buffer that contains the batches.
batchCountThe number of batches in the buffer to execute.
offsetThe offset (in bytes) to the first batch in the batchBuffer .
See also
draw

◆ 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.

◆ execute() [1/2]

void LiteFX::Rendering::ICommandBuffer::execute ( const SharedPtr< const ICommandBuffer > & commandBuffer) const
inline

Executes a secondary command buffer/bundle.

Parameters
commandBufferThe secondary command buffer/bundle to execute.

◆ execute() [2/2]

void LiteFX::Rendering::ICommandBuffer::execute ( Enumerable< SharedPtr< const ICommandBuffer > > commandBuffers) const
inline

Executes a series of secondary command buffers/bundles.

Parameters
commandBuffersThe command buffers to execute.

◆ isSecondary()

virtual bool LiteFX::Rendering::ICommandBuffer::isSecondary ( ) const
pure virtualnoexcept

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

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

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

◆ makeBarrier()

UniquePtr< IBarrier > LiteFX::Rendering::ICommandBuffer::makeBarrier ( PipelineStage syncBefore,
PipelineStage syncAfter ) const
inlinenodiscard

Creates a new barrier instance.

Parameters
syncBeforeThe pipeline stage(s) all previous commands have to finish before the barrier is executed.
syncAfterThe pipeline stage(s) all subsequent commands are blocked at until the barrier is executed.
Returns
The instance of the barrier.

◆ operator=() [1/2]

ICommandBuffer & LiteFX::Rendering::ICommandBuffer::operator= ( const ICommandBuffer & )
protecteddefault

◆ operator=() [2/2]

ICommandBuffer & LiteFX::Rendering::ICommandBuffer::operator= ( ICommandBuffer && )
protecteddefaultnoexcept

◆ pushConstants()

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

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

Parameters
layoutThe layout of the push constants to update.
memoryA pointer to the source memory.

◆ queue()

SharedPtr< const ICommandQueue > LiteFX::Rendering::ICommandBuffer::queue ( ) const
inlinenoexcept

Gets a pointer to the command queue that this command buffer was allocated from or nullptr, if the queue has already been released.

Returns
A reference to the command queue that this command buffer was allocated from.

◆ releaseSharedState()

virtual void LiteFX::Rendering::ICommandBuffer::releaseSharedState ( ) const
protectedpure virtual

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

◆ setBlendFactors()

virtual void LiteFX::Rendering::ICommandBuffer::setBlendFactors ( const Vector4f & blendFactors) const
pure virtualnoexcept

Sets the blend factors for the subsequent draw calls.

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

Parameters
blendFactorsThe blend factors for the subsequent draw calls.

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

◆ setScissors() [1/2]

virtual void LiteFX::Rendering::ICommandBuffer::setScissors ( const IScissor * scissor) const
pure virtual

Sets the scissor rectangle used for the subsequent draw calls.

Parameters
scissorsThe scissor rectangle used for the subsequent draw calls.

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

◆ setScissors() [2/2]

virtual void LiteFX::Rendering::ICommandBuffer::setScissors ( Span< const IScissor * > scissors) const
pure virtual

Sets the scissor rectangles used for the subsequent draw calls.

Parameters
scissorsThe scissor rectangles used for the subsequent draw calls.

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

◆ setStencilRef()

virtual void LiteFX::Rendering::ICommandBuffer::setStencilRef ( UInt32 stencilRef) const
pure virtualnoexcept

Sets the stencil reference for the subsequent draw calls.

Parameters
stencilRefThe stencil reference for the subsequent draw calls.

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

◆ setViewports() [1/2]

virtual void LiteFX::Rendering::ICommandBuffer::setViewports ( const IViewport * viewport) const
pure virtual

Sets the viewport used for the subsequent draw calls.

Parameters
viewportThe viewport used for the subsequent draw calls.

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

◆ setViewports() [2/2]

virtual void LiteFX::Rendering::ICommandBuffer::setViewports ( Span< const IViewport * > viewports) const
pure virtual

Sets the viewports used for the subsequent draw calls.

Parameters
viewportsThe viewports used for the subsequent draw calls.

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

◆ submit()

virtual UInt64 LiteFX::Rendering::ICommandBuffer::submit ( ) const
pure virtual

Submits the command buffer to parent command.

Exceptions
RuntimeExceptionThrown, if the command buffer is a secondary command buffer.

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

◆ traceRays() [1/2]

void LiteFX::Rendering::ICommandBuffer::traceRays ( const Vector3u & dimensions,
const ShaderBindingTableOffsets & offsets,
const IBuffer & rayGenerationShaderBindingTable,
const IBuffer * missShaderBindingTable = nullptr,
const IBuffer * hitShaderBindingTable = nullptr,
const IBuffer * callableShaderBindingTable = nullptr ) const
inlinenoexcept

Executes a query on a ray-tracing pipeline.

This method is only supported if the GraphicsDeviceFeature::RayTracing feature is enabled.

Parameters
dimensionsThe dimensions of the ray-tracing query.
offsetsThe offsets, sizes and strides for each shader binding table.
rayGenerationShaderBindingTableThe shader binding table that contains the ray generation shader.
missShaderBindingTableThe shader binding table that contains the miss shaders.
hitShaderBindingTableThe shader binding table that contains the hit shaders.
callableShaderBindingTableThe shader binding table that contains the callable shaders.

◆ traceRays() [2/2]

void LiteFX::Rendering::ICommandBuffer::traceRays ( UInt32 width,
UInt32 height,
UInt32 depth,
const ShaderBindingTableOffsets & offsets,
const IBuffer & rayGenerationShaderBindingTable,
const IBuffer * missShaderBindingTable = nullptr,
const IBuffer * hitShaderBindingTable = nullptr,
const IBuffer * callableShaderBindingTable = nullptr ) const
inlinenoexcept

Executes a query on a ray-tracing pipeline.

This method is only supported if the GraphicsDeviceFeature::RayTracing feature is enabled.

Parameters
widthThe width of the ray-tracing query.
heightThe height of the ray-tracing query.
depthThe depth of the ray-tracing query.
offsetsThe offsets, sizes and strides for each shader binding table.
rayGenerationShaderBindingTableThe shader binding table that contains the ray generation shader.
missShaderBindingTableThe shader binding table that contains the miss shaders.
hitShaderBindingTableThe shader binding table that contains the hit shaders.
callableShaderBindingTableThe shader binding table that contains the callable shaders.

◆ track() [1/3]

virtual void LiteFX::Rendering::ICommandBuffer::track ( SharedPtr< const IBuffer > buffer) const
pure virtual

Sets up tracking for a buffer, so that it will not be destroyed until the command buffer has been executed.

When working with resources, often times you only need them for a single execution cycle of a command buffer. Having to manually check if the command buffer has been executed (by waiting for it's submission fence on the target queue) and releasing the resource afterwards can be difficult and intricate. Resource tracking allows the command buffer to store a reference of a resource and releasing it at some point after the command buffer has been executed automatically. Note that this does not automatically destroy the resource, which only happens if all references to it are released. However, if the only reference left is the one that is tracked by the command buffer, this process also destroys the resource.

Resources can only be tracked, if the command buffer is currently recording. The command buffer will not track uninitialized resources, i.e., a submitted nullptr will be discarded.

Parameters
bufferThe buffer to track.
Exceptions
RuntimeExceptionThrown, if the command buffer is not currently recording.
See also
track(SharedPtr&le;const IImage&ge;), track(SharedPtr&le;const ISampler&ge;)

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

◆ track() [2/3]

virtual void LiteFX::Rendering::ICommandBuffer::track ( SharedPtr< const IImage > image) const
pure virtual

Sets up tracking for an image, so that it will not be destroyed until the command buffer has been executed.

Parameters
imageThe image to track.
Exceptions
RuntimeExceptionThrown, if the command buffer is not currently recording.
See also
track(SharedPtr&le;const IBuffer&ge;)

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

◆ track() [3/3]

virtual void LiteFX::Rendering::ICommandBuffer::track ( SharedPtr< const ISampler > sampler) const
pure virtual

Sets up tracking for a sampler state, so that it will not be destroyed until the command buffer has been executed.

Parameters
samplerThe sampler to track.
Exceptions
RuntimeExceptionThrown, if the command buffer is not currently recording.
See also
track(SharedPtr&le;const IBuffer&ge;)

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

◆ transfer() [1/12]

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

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

Note that you have to manually ensure that source and target are in the proper state for transfer operations. You might have to use a IBarrier before starting the transfer.

Parameters
sourceThe source buffer to transfer data from.
targetThe target buffer to transfer data to.
sourceElementThe index of the first element in the source buffer to copy.
targetElementThe index of the first element in the target buffer to copy to.
elementsThe number of elements to copy from the source buffer into the target buffer.
Exceptions
ArgumentOutOfRangeExceptionThrown, if the number of either the source buffer or the target buffer has not enough elements for the specified elements parameter.
See also
IBarrier

◆ transfer() [2/12]

void LiteFX::Rendering::ICommandBuffer::transfer ( const IBuffer & source,
const IImage & target,
UInt32 sourceElement = 0,
UInt32 firstSubresource = 0,
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.

Note that you have to manually ensure that source and target are in the proper state for transfer operations. You might have to use a IBarrier before starting the transfer.

Parameters
sourceThe source buffer to transfer data from.
targetThe target image to transfer data to.
sourceElementThe index of the first element in the source buffer to copy.
firstSubresourceThe index of the first sub-resource of the target image to receive data.
elementsThe number of elements to copy from the source buffer into the target image sub-resources.
Exceptions
ArgumentOutOfRangeExceptionThrown, if the number of either the source buffer or the target buffer has not enough elements for the specified elements parameter.

◆ transfer() [3/12]

void LiteFX::Rendering::ICommandBuffer::transfer ( const IImage & source,
const IBuffer & target,
UInt32 firstSubresource = 0,
UInt32 targetElement = 0,
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.

Note that you have to manually ensure that source and target are in the proper state for transfer operations. You might have to use a IBarrier before starting the transfer.

Parameters
sourceThe source image to transfer data from.
targetThe target buffer to transfer data to.
firstSubresourceThe index of the first sub-resource to copy from the source image.
targetElementThe index of the first target element to receive data.
subresourcesThe number of sub-resources to copy.
Exceptions
ArgumentOutOfRangeExceptionThrown, if the number of either the source buffer or the target buffer has not enough elements for the specified elements parameter.

◆ transfer() [4/12]

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

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

Note that you have to manually ensure that source and target are in the proper state for transfer operations. You might have to use a IBarrier before starting the transfer.

Parameters
sourceThe source image to transfer data from.
targetThe target image to transfer data to.
sourceSubresourceThe index of the first sub-resource to copy from the source image.
targetSubresourceThe image of the first sub-resource in the target image to receive data.
subresourcesThe number of sub-resources to copy between the images.
Exceptions
ArgumentOutOfRangeExceptionThrown, if the number of either the source buffer or the target buffer has not enough elements for the specified elements parameter.

◆ transfer() [5/12]

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

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

This method takes shared ownership over source , which means that a reference is hold until the parent command queue finished using the command buffer. At this point, the command queue calls releaseSharedState to release all shared references. Note that this is a relaxed constraint. It is only guaranteed, that the queue calls this method at some point after the command buffer has been executed.

Sharing ownership is helpful in situations where you only have a temporary buffer that you do not want to manually keep track of. For example, it makes sense to create a temporary staging buffer and delete it, if the remote resource has been initialized. In such a case, the command buffer can take ownership over the resource to release it after it has been executed.

Note that you have to manually ensure that source and target are in the proper state for transfer operations. You might have to use a IBarrier before starting the transfer.

Parameters
sourceThe source buffer to transfer data from.
targetThe target buffer to transfer data to.
sourceElementThe index of the first element in the source buffer to copy.
targetElementThe index of the first element in the target buffer to copy to.
elementsThe number of elements to copy from the source buffer into the target buffer.
Exceptions
ArgumentOutOfRangeExceptionThrown, if the number of either the source buffer or the target buffer has not enough elements for the specified elements parameter.

◆ transfer() [6/12]

void LiteFX::Rendering::ICommandBuffer::transfer ( const SharedPtr< const IBuffer > & source,
const IImage & target,
UInt32 sourceElement = 0,
UInt32 firstSubresource = 0,
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.

This method takes shared ownership over source , which means that a reference is hold until the parent command queue finished using the command buffer. At this point, the command queue calls releaseSharedState to release all shared references. Note that this is a relaxed constraint. It is only guaranteed, that the queue calls this method at some point after the command buffer has been executed.

Sharing ownership is helpful in situations where you only have a temporary buffer that you do not want to manually keep track of. For example, it makes sense to create a temporary staging buffer and delete it, if the remote resource has been initialized. In such a case, the command buffer can take ownership over the resource to release it after it has been executed.

Note that you have to manually ensure that source and target are in the proper state for transfer operations. You might have to use a IBarrier before starting the transfer.

Parameters
sourceThe source buffer to transfer data from.
targetThe target image to transfer data to.
sourceElementThe index of the first element in the source buffer to copy.
firstSubresourceThe index of the first sub-resource of the target image to receive data.
elementsThe number of elements to copy from the source buffer into the target image sub-resources.
Exceptions
ArgumentOutOfRangeExceptionThrown, if the number of either the source buffer or the target buffer has not enough elements for the specified elements parameter.

◆ transfer() [7/12]

void LiteFX::Rendering::ICommandBuffer::transfer ( const SharedPtr< const IImage > & source,
const IBuffer & target,
UInt32 firstSubresource = 0,
UInt32 targetElement = 0,
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.

This method takes shared ownership over source , which means that a reference is hold until the parent command queue finished using the command buffer. At this point, the command queue calls releaseSharedState to release all shared references. Note that this is a relaxed constraint. It is only guaranteed, that the queue calls this method at some point after the command buffer has been executed.

Sharing ownership is helpful in situations where you only have a temporary buffer that you do not want to manually keep track of. For example, it makes sense to create a temporary staging buffer and delete it, if the remote resource has been initialized. In such a case, the command buffer can take ownership over the resource to release it after it has been executed.

Note that you have to manually ensure that source and target are in the proper state for transfer operations. You might have to use a IBarrier before starting the transfer.

Parameters
sourceThe source image to transfer data from.
targetThe target buffer to transfer data to.
firstSubresourceThe index of the first sub-resource to copy from the source image.
targetElementThe index of the first target element to receive data.
subresourcesThe number of sub-resources to copy.
Exceptions
ArgumentOutOfRangeExceptionThrown, if the number of either the source buffer or the target buffer has not enough elements for the specified elements parameter.

◆ transfer() [8/12]

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

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

This method takes shared ownership over source , which means that a reference is hold until the parent command queue finished using the command buffer. At this point, the command queue calls releaseSharedState to release all shared references. Note that this is a relaxed constraint. It is only guaranteed, that the queue calls this method at some point after the command buffer has been executed.

Sharing ownership is helpful in situations where you only have a temporary buffer that you do not want to manually keep track of. For example, it makes sense to create a temporary staging buffer and delete it, if the remote resource has been initialized. In such a case, the command buffer can take ownership over the resource to release it after it has been executed.

Note that you have to manually ensure that source and target are in the proper state for transfer operations. You might have to use a IBarrier before starting the transfer.

Parameters
sourceThe source image to transfer data from.
targetThe target image to transfer data to.
sourceSubresourceThe index of the first sub-resource to copy from the source image.
targetSubresourceThe image of the first sub-resource in the target image to receive data.
subresourcesThe number of sub-resources to copy between the images.
Exceptions
ArgumentOutOfRangeExceptionThrown, if the number of either the source buffer or the target buffer has not enough elements for the specified elements parameter.

◆ transfer() [9/12]

void LiteFX::Rendering::ICommandBuffer::transfer ( const void *const data,
size_t size,
const IBuffer & target,
UInt32 targetElement = 0,
UInt32 elements = 1 ) const
inline

Performs a buffer-to-buffer transfer from a temporary buffer into target .

This method creates a temporary buffer and maps data into it, before transferring it into target . A reference of the temporary buffer is stored until the parent command queue finished using the command buffer. At this point, the command queue calls releaseSharedState to release all shared references. Note that this is a relaxed constraint. It is only guaranteed, that the queue calls this method at some point after the command buffer has been executed.

Parameters
dataThe address that marks the beginning of the data to map.
sizeThe number of bytes to map.
targetThe target buffer to transfer data to.
targetElementThe array element to map the data to.
elementsThe number of elements to copy.

◆ transfer() [10/12]

void LiteFX::Rendering::ICommandBuffer::transfer ( const void *const data,
size_t size,
const IImage & target,
UInt32 subresource = 0 ) const
inline

Performs a buffer-to-buffer transfer from a temporary buffer into target .

This method creates a temporary buffer and maps data into it, before transferring it into target . A reference of the temporary buffer is stored until the parent command queue finished using the command buffer. At this point, the command queue calls releaseSharedState to release all shared references. Note that this is a relaxed constraint. It is only guaranteed, that the queue calls this method at some point after the command buffer has been executed.

Parameters
dataThe address that marks the beginning of the data to map.
sizeThe number of bytes to map.
targetThe target buffer to transfer data to.
firstSubresourceThe index of the first sub-resource of the target image to receive data.
elementsThe number of elements to copy from the source buffer into the target image sub-resources.

◆ transfer() [11/12]

void LiteFX::Rendering::ICommandBuffer::transfer ( Span< const void *const > data,
size_t elementSize,
const IBuffer & target,
UInt32 targetElement = 0 ) const
inline

Performs a buffer-to-buffer transfer from a temporary buffer into target .

This method creates a temporary buffer and maps data into it, before transferring it into target . A reference of the temporary buffer is stored until the parent command queue finished using the command buffer. At this point, the command queue calls releaseSharedState to release all shared references. Note that this is a relaxed constraint. It is only guaranteed, that the queue calls this method at some point after the command buffer has been executed.

Parameters
dataThe addresses that mark the beginning of the element data to map.
elementSizeThe number of bytes to map for each element.
targetThe target buffer to transfer data to.
targetElementThe first array element to transfer the data to.

◆ transfer() [12/12]

void LiteFX::Rendering::ICommandBuffer::transfer ( Span< const void *const > data,
size_t elementSize,
const IImage & target,
UInt32 firstSubresource = 0,
UInt32 elements = 1 ) const
inline

Performs a buffer-to-buffer transfer from a temporary buffer into target .

This method creates a temporary buffer and maps data into it, before transferring it into target . A reference of the temporary buffer is stored until the parent command queue finished using the command buffer. At this point, the command queue calls releaseSharedState to release all shared references. Note that this is a relaxed constraint. It is only guaranteed, that the queue calls this method at some point after the command buffer has been executed.

Parameters
dataThe addresses that mark the beginning of the element data to map.
elementSizeThe number of bytes to map for each element.
targetThe target buffer to transfer data to.
firstSubresourceThe index of the first sub-resource of the target image to receive data.
elementsThe number of elements to copy from the source buffer into the target image sub-resources.

◆ updateAccelerationStructure() [1/2]

void LiteFX::Rendering::ICommandBuffer::updateAccelerationStructure ( IBottomLevelAccelerationStructure & blas,
const SharedPtr< const IBuffer > & scratchBuffer,
const IBuffer & buffer,
UInt64 offset = 0 ) const
inline

Updates a bottom-level acceleration structure.

This method is only supported if the GraphicsDeviceFeature::RayTracing feature is enabled.

Parameters
blasThe bottom-level acceleration structure to build.
scratchBufferThe scratch buffer to use for building the acceleration structure.
bufferThe buffer that contains the acceleration structure after the build.
offsetThe offset into buffer at which the acceleration structure gets stored after the build.
Exceptions
ArgumentNotInitializedExceptionThrown, if the provided scratchBuffer is not initialized.
See also
IAccelerationStructure::build

◆ updateAccelerationStructure() [2/2]

void LiteFX::Rendering::ICommandBuffer::updateAccelerationStructure ( ITopLevelAccelerationStructure & tlas,
const SharedPtr< const IBuffer > & scratchBuffer,
const IBuffer & buffer,
UInt64 offset = 0 ) const
inline

Updates a top-level acceleration structure.

This method is only supported if the GraphicsDeviceFeature::RayTracing feature is enabled.

Parameters
tlasThe top-level acceleration structure to build.
scratchBufferThe scratch buffer to use for building the acceleration structure.
bufferThe buffer that contains the acceleration structure after the build.
offsetThe offset into buffer at which the acceleration structure gets stored after the build.
Exceptions
ArgumentNotInitializedExceptionThrown, if the provided scratchBuffer is not initialized.
See also
IAccelerationStructure::build

◆ use()

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

Sets the active pipeline state.

◆ writeTimingEvent()

virtual void LiteFX::Rendering::ICommandBuffer::writeTimingEvent ( const SharedPtr< const TimingEvent > & timingEvent) const
pure virtual

Writes the current GPU time stamp value for the timing event.

Parameters
timingEventThe timing event for which the time stamp is written.

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

Friends And Related Symbol Documentation

◆ ICommandQueue

friend class ICommandQueue
friend