LLGL::CommandBuffer Class Reference

Command buffer interface used for storing and encoding GPU commands. More...

#include <CommandBuffer.h>

Inheritance diagram for LLGL::CommandBuffer:

Public Member Functions
virtual void	Begin ()=0
	Begins with the encoding (also referred to as "recording") of this command buffer.
virtual void	End ()=0
	Ends the encoding (also referred to as "recording") of this command buffer.
virtual void	Execute (CommandBuffer &secondaryCommandBuffer)=0
	Executes the specified secondary command buffer by inlining its commands into this command buffer.
virtual void	UpdateBuffer (Buffer &dstBuffer, std::uint64_t dstOffset, const void *data, std::uint64_t dataSize)=0
	Updates the data of the specified buffer during encoding the command buffer.
virtual void	CopyBuffer (Buffer &dstBuffer, std::uint64_t dstOffset, Buffer &srcBuffer, std::uint64_t srcOffset, std::uint64_t size)=0
	Encodes a buffer copy command for the specified buffer region.
virtual void	CopyBufferFromTexture (Buffer &dstBuffer, std::uint64_t dstOffset, Texture &srcTexture, const TextureRegion &srcRegion, std::uint32_t rowStride=0, std::uint32_t layerStride=0)=0
	Encodes a buffer copy command that blits data from a source texture.
virtual void	FillBuffer (Buffer &dstBuffer, std::uint64_t dstOffset, std::uint32_t value, std::uint64_t fillSize=LLGL_WHOLE_SIZE)=0
	Fills the destination buffer with copies of the specified 32-bit value.
virtual void	CopyTexture (Texture &dstTexture, const TextureLocation &dstLocation, Texture &srcTexture, const TextureLocation &srcLocation, const Extent3D &extent)=0
	Encodes a texture copy command for the specified texture regions.
virtual void	CopyTextureFromBuffer (Texture &dstTexture, const TextureRegion &dstRegion, Buffer &srcBuffer, std::uint64_t srcOffset, std::uint32_t rowStride=0, std::uint32_t layerStride=0)=0
	Encodes a texture copy command that blits data from a source buffer.
virtual void	CopyTextureFromFramebuffer (Texture &dstTexture, const TextureRegion &dstRegion, const Offset2D &srcOffset)=0
	Encodes a texture copy command that blits data from the current framebuffer.
virtual void	GenerateMips (Texture &texture)=0
	Generates all MIP-maps for the specified texture.
virtual void	GenerateMips (Texture &texture, const TextureSubresource &subresource)=0
	Generates a range of MIP-maps for the specified texture.
virtual void	SetViewport (const Viewport &viewport)=0
	Sets a single viewport.
virtual void	SetViewports (std::uint32_t numViewports, const Viewport *viewports)=0
	Sets an array of viewports.
virtual void	SetScissor (const Scissor &scissor)=0
	Sets a single scissor rectangle.
virtual void	SetScissors (std::uint32_t numScissors, const Scissor *scissors)=0
	Sets an array of scissor rectangles, but only if the scissor test was enabled in the previously set graphics pipeline (otherwise, this function has no effect).
virtual void	SetVertexBuffer (Buffer &buffer)=0
	Sets the specified vertex buffer for subsequent drawing operations.
virtual void	SetVertexBuffer (Buffer &buffer, std::uint32_t stride, std::uint64_t offset=0)=0
	Sets the specified vertex buffer for subsequent drawing operations with a new stride and optional base offset.
virtual void	SetVertexBuffers (std::uint32_t numBufferViews, const VertexBufferView *bufferViews)=0
	Sets the specified number of vertex buffers for subsequent drawing operations with optional strides and base offsets.
virtual void	SetVertexBufferArray (BufferArray &bufferArray)=0
	Sets the specified array of vertex buffers for subsequent drawing operations.
virtual void	SetIndexBuffer (Buffer &buffer)=0
	Sets the active index buffer for subsequent drawing operations.
virtual void	SetIndexBuffer (Buffer &buffer, const Format format, std::uint64_t offset=0)=0
	Sets the active index buffer for subsequent drawing operations with a dynamic format and optional buffer offset.
virtual void	SetResourceHeap (ResourceHeap &resourceHeap, std::uint32_t descriptorSet=0)=0
	Binds the specified resource heap to the respective pipeline.
virtual void	SetResource (std::uint32_t descriptor, Resource &resource)=0
	Binds the specified resource as root parameter to the respective pipeline.
virtual void	ResourceBarrier (std::uint32_t numBuffers, Buffer *const *buffers, std::uint32_t numTextures, Texture *const *textures)=0
	Inserts a resource memory barrier for the specified resources.
virtual void	BeginRenderPass (RenderTarget &renderTarget, const RenderPass *renderPass=nullptr, std::uint32_t numClearValues=0, const ClearValue *clearValues=nullptr, std::uint32_t swapBufferIndex=LLGL_CURRENT_SWAP_INDEX)=0
	Begins with a new render pass.
virtual void	EndRenderPass ()=0
	Ends the current render pass.
virtual void	Clear (long flags, const ClearValue &clearValue={})=0
	Clears the specified group of attachments of the active render target.
virtual void	ClearAttachments (std::uint32_t numAttachments, const AttachmentClear *attachments)=0
	Clears the specified attachments of the active render target.
virtual void	SetPipelineState (PipelineState &pipelineState)=0
	Sets the active graphics or compute pipeline state.
virtual void	SetBlendFactor (const float color[4])=0
	Sets the dynamic pipeline state for blending factors.
virtual void	SetStencilReference (std::uint32_t reference, const StencilFace stencilFace=StencilFace::FrontAndBack)=0
	Sets the dynamic pipeline state for stencil reference values.
virtual void	SetUniforms (std::uint32_t first, const void *data, std::uint16_t dataSize)=0
	Sets the value of a certain number of shader uniforms (aka. push constant/ shader constants) in the currently bound PSO.
virtual void	BeginQuery (QueryHeap &queryHeap, std::uint32_t query=0)=0
	Begins a query of the specified query heap.
virtual void	EndQuery (QueryHeap &queryHeap, std::uint32_t query=0)=0
	Ends the specified query.
virtual void	BeginRenderCondition (QueryHeap &queryHeap, std::uint32_t query=0, const RenderConditionMode mode=RenderConditionMode::Wait)=0
	Begins conditional rendering with the specified query object.
virtual void	EndRenderCondition ()=0
	Ends the current render condition.
virtual void	BeginStreamOutput (std::uint32_t numBuffers, Buffer *const *buffers)=0
	Begins a stream-output section for subsequent draw calls.
virtual void	EndStreamOutput ()=0
	Ends the current stream-output.
virtual void	Draw (std::uint32_t numVertices, std::uint32_t firstVertex)=0
	Draws the specified amount of primitives from the currently set vertex buffer.
virtual void	DrawIndexed (std::uint32_t numIndices, std::uint32_t firstIndex)=0
virtual void	DrawIndexed (std::uint32_t numIndices, std::uint32_t firstIndex, std::int32_t vertexOffset)=0
	Draws the specified amount of primitives from the currently set vertex- and index buffers.
virtual void	DrawInstanced (std::uint32_t numVertices, std::uint32_t firstVertex, std::uint32_t numInstances)=0
virtual void	DrawInstanced (std::uint32_t numVertices, std::uint32_t firstVertex, std::uint32_t numInstances, std::uint32_t firstInstance)=0
	Draws the specified amount of instances of primitives from the currently set vertex buffer.
virtual void	DrawIndexedInstanced (std::uint32_t numIndices, std::uint32_t numInstances, std::uint32_t firstIndex)=0
virtual void	DrawIndexedInstanced (std::uint32_t numIndices, std::uint32_t numInstances, std::uint32_t firstIndex, std::int32_t vertexOffset)=0
virtual void	DrawIndexedInstanced (std::uint32_t numIndices, std::uint32_t numInstances, std::uint32_t firstIndex, std::int32_t vertexOffset, std::uint32_t firstInstance)=0
	Draws the specified amount of instances of primitives from the currently set vertex- and index buffers.
virtual void	DrawIndirect (Buffer &buffer, std::uint64_t offset)=0
	Draws an unknown amount of instances of primitives whose draw command arguments are taken from a buffer object.
virtual void	DrawIndirect (Buffer &buffer, std::uint64_t offset, std::uint32_t numCommands, std::uint32_t stride)=0
	Draws an unknown amount of instances of primitives whose draw command arguments are taken from a buffer object.
virtual void	DrawIndexedIndirect (Buffer &buffer, std::uint64_t offset)=0
	Draws an unknown amount of instances of primitives whose indexed draw command arguments are taken from a buffer object.
virtual void	DrawIndexedIndirect (Buffer &buffer, std::uint64_t offset, std::uint32_t numCommands, std::uint32_t stride)=0
	Draws an unknown amount of instances of primitives whose indexed draw command arguments are taken from a buffer object.
virtual void	DrawStreamOutput ()=0
	Performs an automatic draw command whose number of primitives is provided by a stream-output buffer that is bound as vertex buffer.
virtual void	Dispatch (std::uint32_t numWorkGroupsX, std::uint32_t numWorkGroupsY, std::uint32_t numWorkGroupsZ)=0
	Dispatches a compute command.
virtual void	DispatchIndirect (Buffer &buffer, std::uint64_t offset)=0
	Dispatches a compute command with an unknown amount of thread grounds.
virtual void	PushDebugGroup (const char *name)=0
	Pushes the specified name onto a stack of group strings that is used for debug reports.
virtual void	PopDebugGroup ()=0
virtual void	DoNativeCommand (const void *nativeCommand, std::size_t nativeCommandSize)=0
	Performs a native command that is backend specific.
virtual bool	GetNativeHandle (void *nativeHandle, std::size_t nativeHandleSize)=0
	Returns the native command buffer handle.
Public Member Functions inherited from LLGL::RenderSystemChild
virtual void	SetDebugName (const char *name)
	Sets the name of this class instance for debugging purposes.
Public Member Functions inherited from LLGL::Interface
virtual bool	IsInstanceOf (int id) const
	Returns true if this object is an instance of the specified interface.
Public Member Functions inherited from LLGL::NonCopyable
	NonCopyable (const NonCopyable &)=delete
NonCopyable &	operator= (const NonCopyable &)=delete
virtual	~NonCopyable ()=default

Protected Member Functions
	CommandBuffer ()=default
Protected Member Functions inherited from LLGL::NonCopyable
	NonCopyable ()=default

Detailed Description

Command buffer interface used for storing and encoding GPU commands.

Remarks

This is the main interface to encode graphics, compute, and blit commands to be submitted to the GPU. All states that can be changed with a setter function are not persistent across several encoding sections. Before any command can be encoded, the command buffer must be put into recording mode via the CommandBuffer::Begin function. And before the command buffer can be submitted to the command queue, it must be put out of recording mode via the CommandBuffer::End function.

In a multi-threaded environment, buffer and texture resources must not be encoded in more than one command buffer at a time. They can be used in more than one command buffer, but they cannot be encoded in parallel. That is because some backends might modify internal data of the resources to quickly organize them in caches.

See also

RenderSystem::CreateCommandBuffer

Constructor & Destructor Documentation

CommandBuffer()

LLGL::CommandBuffer::CommandBuffer ( )

protecteddefault

Member Function Documentation

Begin()

virtual void LLGL::CommandBuffer::Begin ( )

pure virtual

Begins with the encoding (also referred to as "recording") of this command buffer.

Remarks

All functions of the CommandBuffer interface must be used between a call to Begin and End. This function also resets all previously encoded commands.

See also

End

BeginQuery()

virtual void LLGL::CommandBuffer::BeginQuery ( QueryHeap & queryHeap, std::uint32_t query = 0 )

pure virtual

Begins a query of the specified query heap.

Parameters

[in]	queryHeap	Specifies the query heap.
[in]	query	Specifies the zero-based index of the query within the heap to begin with. By default 0. This must be in the half-open range [0, QueryHeapDescriptor::numQueries).

Remarks

The BeginQuery and EndQuery functions can be wrapped around any drawing and/or compute operation. This can be an occlusion query for instance, which determines how many fragments have passed the depth test. The result of a query can be retrieved by the command queue after this command buffer has been submitted.

See also

EndQuery

RenderSystem::CreateQueryHeap

CommandQueue::QueryResult

BeginRenderCondition()

virtual void LLGL::CommandBuffer::BeginRenderCondition ( QueryHeap & queryHeap, std::uint32_t query = 0, const RenderConditionMode mode = RenderConditionMode::Wait )

pure virtual

Begins conditional rendering with the specified query object.

Parameters

[in]	queryHeap	Specifies the query heap. This query heap must have been created with the renderCondition member set to true.
[in]	query	Specifies the zero-based index of the query within the heap which is to be used as render condition. By default 0. This must be in the half-open range [0, QueryHeapDescriptor::numQueries).
[in]	mode	Specifies the mode of the render condition.

Remarks

Here is a usage example:

myCmdBuffer->BeginQuery(*myOcclusionQuery);
// draw bounding box ...
myCmdBuffer->EndQuery(*myOcclusionQuery);
myCmdBuffer->BeginRenderCondition(*myOcclusionQuery, LLGL::RenderConditionMode::Wait);
// draw actual object ...
myCmdBuffer->EndRenderCondition();

See also

RenderSystem::CreateQueryHeap

QueryHeapDescriptor::renderCondition

BeginRenderPass()

virtual void LLGL::CommandBuffer::BeginRenderPass ( RenderTarget & renderTarget, const RenderPass * renderPass = nullptr, std::uint32_t numClearValues = 0, const ClearValue * clearValues = nullptr, std::uint32_t swapBufferIndex = LLGL_CURRENT_SWAP_INDEX )

pure virtual

Begins with a new render pass.

Parameters

[in]	renderTarget	Specifies the render target in which the subsequent draw operations will be stored. If this is a swap-chain and SwapChain::Present is called on such swap-chain before this command buffer is submitted to the command queue, use swapBufferIndex parameter to render into a specific swap buffer and then select the correct command buffer via SwapChain::GetCurrentSwapIndex when submitting to the command queue.
[in]	renderPass	Specifies an optional render pass object. If this is null, the default render pass for the specified render target will be used. This render pass object must be compatible with the render pass object the specified render target was created with. Note that the default render pass will ignore the previous framebuffer content (see AttachmentLoadOp::Undefined), i.e. such a render pass section should fill the entire framebuffer.
[in]	numClearValues	Specifies the number of clear values that are specified in the clearValues parameter. This should be greater than or equal to the number of render pass attachments whose load operation (i.e. AttachmentFormatDescriptor::loadOp) is set to AttachmentLoadOp::Clear. Otherwise, the following default values are used: (0, 0, 0, 0) for color, 1 for depth, 0 for stencil.
[in]	clearValues	Optional pointer to the array of clear values. If numClearValues is not zero, this must be a valid pointer to an array of at least numClearValues entries. Each entry in the array is used to clear the attachment whose load operation is set to AttachmentLoadOp::Clear, where the depth attachment (i.e. RenderPassDescriptor::depthAttachment) and the stencil attachment (i.e. RenderPassDescriptor::stencilAttachment) are combined and appear as the last entry.
[in]	swapBufferIndex	Optional index into what swap-chain buffer the render pass is meant to be rendered. If this is equal to LLGL_CURRENT_SWAP_INDEX, the current buffer in the swap-chain is used. Otherwise, this should be the current value returned from SwapChain::GetCurrentSwapIndex by the time this command buffer is submitted to the command queue. This parameter is ignored for regular render targets, i.e. if renderTarget is not a SwapChain.

Remarks

This function starts a new render pass section and must be ended with the EndRenderPass function. Render passes must not be interleaved, i.e. each render pass must end before a new render pass can begin.

The following example shows how to use a render pass to clear a render target with two color attachments and a depth-stencil attachment:

LLGL::ClearValue myClearValues[3];
 
// Set clear values for color attachments 0 and 1
myClearValues[0].color = { 1, 0, 0, 1 };
myClearValues[1].color = { 0, 1, 0, 1 };
 
// Set clear values for depth-stencil attachment
myClearValues[2].depth   = 1.0f;
myClearValues[2].stencil = 0;
 
// Begin render pass and clear render target
myCmdBuffer->BeginRenderPass(*myRenderTarget, *myRenderPass, 3, myClearValues);
{
    // Draw scene ...
}
myCmdBuffer->EndRenderPass();

The following commands must only be used inside a render pass section:

• Drawing commands (i.e. Draw, DrawInstanced, DrawIndexed, DrawIndexedInstanced, DrawIndirect and DrawIndexedIndirect).
• Clear attachment commands (i.e. Clear and ClearAttachments).
• Query block (i.e. BeginQuery and EndQuery).
• Conditional render block (i.e. BeginRenderCondition and EndRenderCondition).
• Stream-output block (i.e. BeginStreamOutput and EndStreamOutput).

The following commands must only be used outside a render pass section:

• Dispatch compute commands (i.e. Dispatch and DispatchIndirect).

The following commands can be used both inside and outside a render pass section but are recommended to be used only outside a render pass section to avoid potential performance penalties:

• Copy commands (i.e. UpdateBuffer, CopyBuffer*, and CopyTexture*).
• MIP-map generation commands (i.e. GenerateMips).

See also

RenderSystem::CreateRenderPass

RenderSystem::CreateRenderTarget

RenderTargetDescriptor::renderPass

AttachmentFormatDescriptor::loadOp

SwapChain::GetCurrentSwapIndex

EndRenderPass

BeginStreamOutput()

virtual void LLGL::CommandBuffer::BeginStreamOutput ( std::uint32_t numBuffers, Buffer *const * buffers )

pure virtual

Begins a stream-output section for subsequent draw calls.

Parameters

[in]	numBuffers	Specifies the number of stream-output buffers. This must be in the range [1, RenderingLimits::maxStreamOutputs].
[in]	buffers	Array to the stream-output buffers. This must be a valid pointer to an array of numBuffers buffer objects. Each of these buffers must have been created with the binding flag BindFlags::StreamOutputBuffer.

Remarks

This function starts a new stream output section and must be ended with the EndStreamOutput function. Stream outputs must not be interleaved, i.e. each stream output must end before a new stream output can begin.

This must only be called if a graphics pipeline is currently bound.

See also

EndStreamOutput

SetPipelineState

RenderingFeatures::hasStreamOutputs

RenderingLimits::maxStreamOutputs

Clear()

virtual void LLGL::CommandBuffer::Clear ( long flags, const ClearValue & clearValue = {} )

pure virtual

Clears the specified group of attachments of the active render target.

Parameters

[in]	flags	Specifies the clear buffer flags. This can be a bitwise OR combination of the ClearFlags enumeration entries. If this contains the ClearFlags::Color bit, all color attachments of the active render target are cleared with the color specified by clearValue.
[in]	clearValue	Specifies the value to which the attachments will be cleared.

Remarks

To specify the clear values for each buffer type, use the respective SetClear... function. To clear only a specific render-target color buffer, use the ClearAttachments function. Clearing a depth-stencil attachment while the active render target has no depth-stencil buffer is allowed but has no effect. For efficiency reasons, it is recommended to clear the render target attachments when a new render pass begins, i.e. the clear values of the BeginRenderPass function should be preferred over this function. For some render systems (e.g. Metal) this function forces the current render pass to stop and start again in order to clear the attachments.

See also

ClearFlags

ClearAttachments

BeginRenderPass

ClearAttachments()

virtual void LLGL::CommandBuffer::ClearAttachments ( std::uint32_t numAttachments, const AttachmentClear * attachments )

pure virtual

Clears the specified attachments of the active render target.

Parameters

[in]	numAttachments	Specifies the number of attachments to clear.
[in]	attachments	Pointer to the array of attachment clear commands. This must not be null!

Remarks

To clear all color buffers with the same value, use the Clear function. Clearing a depth-stencil attachment while the active render target has no depth-stencil buffer is allowed but has no effect. For efficiency reasons, it is recommended to clear the render target attachments when a new render pass begins, i.e. the clear values of the BeginRenderPass function should be preferred over this function. For some render systems (e.g. Metal) this function forces the current render pass to stop and start again in order to clear the attachments.

See also

Clear

BeginRenderPass

CopyBuffer()

virtual void LLGL::CommandBuffer::CopyBuffer ( Buffer & dstBuffer, std::uint64_t dstOffset, Buffer & srcBuffer, std::uint64_t srcOffset, std::uint64_t size )

pure virtual

Encodes a buffer copy command for the specified buffer region.

Parameters

[in,out]	dstBuffer	Specifies the destination buffer whose data is to be updated.
[in]	dstOffset	Specifies the destination offset (in bytes) at which the destination buffer is to be updated. This offset plus the size (i.e. dstOffset + size) must be less than or equal to the size of the destination buffer.
[in]	srcBuffer	Specifies the source buffer whose data is to be read from.
[in]	srcOffset	Specifies the source offset (in bytes) at which the source buffer is to be read from. This offset plus the size (i.e. srcOffset + size) must be less than or equal to the size of the source buffer.
[in]	size	Specifies the size of the buffer region to copy.

Remarks

For performance reasons, it is recommended to encode this command outside of a render pass. Otherwise, render pass interruptions might be inserted by LLGL.

CopyBufferFromTexture()

virtual void LLGL::CommandBuffer::CopyBufferFromTexture ( Buffer & dstBuffer, std::uint64_t dstOffset, Texture & srcTexture, const TextureRegion & srcRegion, std::uint32_t rowStride = 0, std::uint32_t layerStride = 0 )

pure virtual

Encodes a buffer copy command that blits data from a source texture.

Parameters

[in,out]	dstBuffer	Specifies the destination buffer whose data is to be updated. This buffer must have been created with the binding flag BindFlags::CopyDst.
[in]	dstOffset	Specifies the destination offset (in bytes) at which the source buffer is to be updated. This must be a multiple of 4.
[in]	srcTexture	Specifies the source texture whose data is to be read from. This texture must have been created with the binding flag BindFlags::CopySrc and its format must not be compressed (see FormatFlags::IsCompressed) or packed (see FormatFlags::IsPacked).
[in]	srcRegion	Specifies the source region where the texture is to be read from. Note that the numMipLevels attribute of this parameter must be 1.
[in]	rowStride	Specifies an optional stride (in bytes) per row in the destination buffer. By default 0.
[in]	layerStride	Specifies an optional stride (in bytes) per layer in the destination buffer. This must be a multiple of rowStride. If rowStride is zero, then layerStride must also be zero. By default 0.

Remarks

This is called "copy buffer from texture" instead of "copy texture to buffer" to be uniform with the notation buffer := texture, or memcpy(destination, source, size).

For performance reasons, it is recommended to encode this command outside of a render pass. Otherwise, render pass interruptions might be inserted by LLGL.

Further performance penalties can be introduced if rowStride is not aligned to the respective rendering API restrictions:

• Direct3D 12: rowStride should be a multiple of 256.
• Metal: rowStride should be less than or equal to 32767 multiplied by the source texture's format size.

If rowStride is 0, the source data is considered to be tightly packed for each array layer and the required alignment is managed automatically.

If rowStride is not 0, it must be greater than or equal to the size (in bytes) of each row in the texture region with respect to the texture's format.

The same rules of rowStride also apply to layerStride.

See also

CopyTextureFromBuffer

GetMemoryFootprint

Texture::GetSubresourceFootprint

CopyTexture()

virtual void LLGL::CommandBuffer::CopyTexture ( Texture & dstTexture, const TextureLocation & dstLocation, Texture & srcTexture, const TextureLocation & srcLocation, const Extent3D & extent )

pure virtual

Encodes a texture copy command for the specified texture regions.

Parameters

[in,out]	dstTexture	Specifies the destination texture whose data is to be updated.
[in]	dstLocation	Specifies the destination location, including MIP-map level and offset. Its offset plus the extent (i.e. dstLocation.offset + extent) must be less than or equal to the size of the destination texture.
[in]	srcTexture	Specifies the source texture whose data is to be read from.
[in]	srcLocation	Specifies the source location, including MIP-map level and offset. Its offset plus the extent (i.e. srcLocation.offset + extent) must be less than or equal to the size of the source texture.
[in]	extent	Specifies the extent of the texture region to copy (see TextureDescriptor::extent). For this function, the extent also includes the array layers, i.e. y component for 1D arrays (TextureType::Texture1DArray), and z component for 2D and cube arrays (TextureType::Texture2DArray and TextureType::TextureCubeArray).

Remarks

For performance reasons, it is recommended to encode this command outside of a render pass. Otherwise, render pass interruptions might be inserted by LLGL.

CopyTextureFromBuffer()

virtual void LLGL::CommandBuffer::CopyTextureFromBuffer ( Texture & dstTexture, const TextureRegion & dstRegion, Buffer & srcBuffer, std::uint64_t srcOffset, std::uint32_t rowStride = 0, std::uint32_t layerStride = 0 )

pure virtual

Encodes a texture copy command that blits data from a source buffer.

Parameters

[in,out]	dstTexture	Specifies the destination texture whose data is to be updated. This texture must have been created with the binding flag BindFlags::CopyDst and its format must not be compressed (see FormatFlags::IsCompressed) or packed (see FormatFlags::IsPacked).
[in]	dstRegion	Specifies the destination region where the texture is to be updated. Note that the numMipLevels attribute of this parameter must be 1.
[in]	srcBuffer	Specifies the source buffer whose data is to be read from. This buffer must have been created with the binding flag BindFlags::CopySrc.
[in]	srcOffset	Specifies the source offset (in bytes) at which the source buffer is to be read from. This must be a multiple of 4.
[in]	rowStride	Specifies an optional stride (in bytes) per row in the source buffer. By default 0.
[in]	layerStride	Specifies an optional stride (in bytes) per layer in the source buffer. This must be a multiple of rowStride. If rowStride is zero, then layerStride must also be zero. By default 0.

Remarks

This is called "copy texture from buffer" instead of "copy buffer to texture" to be uniform with the notation texture := buffer, or memcpy(destination, source, size).

For performance reasons, it is recommended to encode this command outside of a render pass. Otherwise, render pass interruptions might be inserted by LLGL.

Further performance penalties can be introduced if rowStride is not aligned to the respective rendering API restrictions:

• Direct3D 12: rowStride should be a multiple of 256.
• Metal: rowStride should be less than or equal to 32767 multiplied by the destination texture's format size.

If rowStride is 0, the source data is considered to be tightly packed for each array layer and the required alignment is managed automatically.

If rowStride is not 0, it must be greater than or equal to the size (in bytes) of each row in the texture region with respect to the texture's format.

The same rules of rowStride also apply to layerStride.

See also

CopyBufferFromTexture

GetMemoryFootprint

Texture::GetSubresourceFootprint

CopyTextureFromFramebuffer()

virtual void LLGL::CommandBuffer::CopyTextureFromFramebuffer ( Texture & dstTexture, const TextureRegion & dstRegion, const Offset2D & srcOffset )

pure virtual

Encodes a texture copy command that blits data from the current framebuffer.

Parameters

[in,out]	dstTexture	Specifies the destination texture whose data is to be updated. This texture must have been created with the binding flag BindFlags::CopyDst and its format must not be compressed (see FormatFlags::IsCompressed) or packed (see FormatFlags::IsPacked). If the current framebuffer is multi-sampled, this texture can be either a multi-sampled texture with the same sample count as the current framebuffer or a single-sampled texture in which case the resource will be automatically resolved. If the current framebuffer is single-sampled, this texture must be single-sampled as well.
[in]	dstRegion	Specifies the destination region where the texture is to be updated. Note that the subresource.numMipLevels, subresource.numArrayLayers, and extent.depth attributes of this parameter must be 1.
[in]	srcOffset	Specifies the source offset at which the framebuffer is to be read from. If the source offset plus the destination dimension is larger the framebuffer's resolution, the behavior is undefined.

Remarks

This command must only be used inside a render pass.

For performance reasons, it is recommended to render a scene into a RenderTarget instead of copying the framebuffer into a texture. This command merely simplifies the process of capturing the framebuffer mid-scene without having to interrupt a render pass or creating an intermediate render target.

This function is only supported for SwapChain framebuffers, not for common render targets. This functionality might be added in the future.

Todo

Add support for common render targets.

See also

RenderTarget::GetResolution

Dispatch()

virtual void LLGL::CommandBuffer::Dispatch ( std::uint32_t numWorkGroupsX, std::uint32_t numWorkGroupsY, std::uint32_t numWorkGroupsZ )

pure virtual

Dispatches a compute command.

Parameters

[in]	numWorkGroupsX	Specifies the number of worker thread groups in the X-dimension.
[in]	numWorkGroupsY	Specifies the number of worker thread groups in the Y-dimension.
[in]	numWorkGroupsZ	Specifies the number of worker thread groups in the Z-dimension.

See also

SetPipelineState

RenderingLimits::maxComputeShaderWorkGroups

DispatchIndirect()

virtual void LLGL::CommandBuffer::DispatchIndirect ( Buffer & buffer, std::uint64_t offset )

pure virtual

Dispatches a compute command with an unknown amount of thread grounds.

Parameters

[in]	buffer	Specifies the buffer from which the dispatch command arguments are taken. This buffer must have been created with the BindFlags::IndirectBuffer binding flag.
[in]	offset	Specifies an offset within the argument buffer from which the arguments are to be taken. This offset must be a multiple of 4.

See also

DispatchIndirectArguments

DoNativeCommand()

virtual void LLGL::CommandBuffer::DoNativeCommand ( const void * nativeCommand, std::size_t nativeCommandSize )

pure virtual

Performs a native command that is backend specific.

Parameters

[out]	nativeCommand	Raw pointer to the backend specific structure to store the native command. Obtain the respective structure from #include <LLGL/Backend/BACKEND/NativeCommand.h> where BACKEND must be either Direct3D12, Direct3D11, Vulkan, Metal, or OpenGL.
[in]	nativeCommandSize	Specifies the size (in bytes) of the native command structure for robustness. This must be sizeof(STRUCT) where STRUCT is the respective backend specific structure such as LLGL::Metal::NativeCommand.

Remarks

This must only be used on an immediate command buffer, i.e. those that have been created with the CommandBufferFlags::ImmediateSubmit flag.

This can be used to work around several differences between the low-level graphics APIs, e.g. for internal buffer binding slots. Here is a usage example:

LLGL::Metal::NativeCommand myMetalCommand;
myMetalCommand.type                  = LLGL::Metal::NativeCommandType::TessFactorBuffer;
myMetalCommand.tessFactorBuffer.slot = 1;
myCmdBuffer->DoNativeCommand(&myMetalCommand, sizeof(myMetalCommand));

See also

Direct3D12::NativeCommand

Direct3D11::NativeCommand

Vulkan::NativeCommand

Metal::NativeCommand

OpenGL::NativeCommand

Draw()

virtual void LLGL::CommandBuffer::Draw ( std::uint32_t numVertices, std::uint32_t firstVertex )

pure virtual

Draws the specified amount of primitives from the currently set vertex buffer.

Parameters

[in]	numVertices	Specifies the number of vertices to generate.
[in]	firstVertex	Specifies the zero-based offset of the first vertex from the vertex buffer.

Note

The parameter firstVertex modifies the vertex ID within the shader pipeline differently for SV_VertexID in HLSL and gl_VertexID in GLSL (or gl_VertexIndex for Vulkan), due to rendering API differences. The system value SV_VertexID in HLSL will always start with zero, but the system value gl_VertexID in GLSL (or gl_VertexIndex for Vulkan) will start with the value of firstVertex.

DrawIndexed() [1/2]

virtual void LLGL::CommandBuffer::DrawIndexed ( std::uint32_t numIndices, std::uint32_t firstIndex )

pure virtual

See also

DrawIndexed(std::uint32_t, std::uint32_t, std::int32_t)

DrawIndexed() [2/2]

virtual void LLGL::CommandBuffer::DrawIndexed ( std::uint32_t numIndices, std::uint32_t firstIndex, std::int32_t vertexOffset )

pure virtual

Draws the specified amount of primitives from the currently set vertex- and index buffers.

Parameters

[in]	numIndices	Specifies the number of indices to generate.
[in]	firstIndex	Specifies the zero-based offset of the first index from the index buffer.
[in]	vertexOffset	Specifies the base vertex offset (positive or negative) which is added to each index from the index buffer.

Note

For the Metal renderer, the parameter vertexOffset is ignored when tessellation is enabled.

DrawIndexedIndirect() [1/2]

virtual void LLGL::CommandBuffer::DrawIndexedIndirect ( Buffer & buffer, std::uint64_t offset )

pure virtual

Draws an unknown amount of instances of primitives whose indexed draw command arguments are taken from a buffer object.

Parameters

[in]	buffer	Specifies the buffer from which the draw command arguments are taken. This buffer must have been created with the BindFlags::IndirectBuffer binding flag.
[in]	offset	Specifies an offset within the argument buffer from which the arguments are to be taken. This offset must be a multiple of 4.

See also

DrawIndexedIndirectArguments

DrawIndexedIndirect() [2/2]

virtual void LLGL::CommandBuffer::DrawIndexedIndirect ( Buffer & buffer, std::uint64_t offset, std::uint32_t numCommands, std::uint32_t stride )

pure virtual

Draws an unknown amount of instances of primitives whose indexed draw command arguments are taken from a buffer object.

Parameters

[in]	buffer	Specifies the buffer from which the draw command arguments are taken. This buffer must have been created with the BindFlags::IndirectBuffer binding flag.
[in]	offset	Specifies an offset within the argument buffer from which the arguments are to be taken. This offset must be a multiple of 4.
[in]	numCommands	Specifies the number of draw commands that are to be taken from the argument buffer.
[in]	stride	Specifies the stride (in bytes) between consecutive sets of arguments, which is commonly greater than or equal to sizeof(DrawIndexedIndirectArguments). This stride must be a multiple of 4.

Remarks

This is also known as a "multi draw command" which is only natively supported by OpenGL and Vulkan. For other rendering APIs, the recording of multiple draw commands is emulated with a simple loop, which is equivalent to the following example:

while (numCommands-- > 0)
{
    DrawIndexedIndirect(buffer, offset);
    offset += stride;
}

See also

DrawIndexedIndirectArguments

DrawIndexedInstanced() [1/3]

virtual void LLGL::CommandBuffer::DrawIndexedInstanced ( std::uint32_t numIndices, std::uint32_t numInstances, std::uint32_t firstIndex )

pure virtual

See also

DrawIndexedInstanced(std::uint32_t, std::uint32_t, std::uint32_t, std::int32_t, std::uint32_t)

DrawIndexedInstanced() [2/3]

virtual void LLGL::CommandBuffer::DrawIndexedInstanced ( std::uint32_t numIndices, std::uint32_t numInstances, std::uint32_t firstIndex, std::int32_t vertexOffset )

pure virtual

See also

DrawIndexedInstanced(std::uint32_t, std::uint32_t, std::uint32_t, std::int32_t, std::uint32_t)

DrawIndexedInstanced() [3/3]

virtual void LLGL::CommandBuffer::DrawIndexedInstanced ( std::uint32_t numIndices, std::uint32_t numInstances, std::uint32_t firstIndex, std::int32_t vertexOffset, std::uint32_t firstInstance )

pure virtual

Draws the specified amount of instances of primitives from the currently set vertex- and index buffers.

Parameters

[in]	numIndices	Specifies the number of indices to generate.
[in]	numInstances	Specifies the number of instances to generate.
[in]	firstIndex	Specifies the zero-based offset of the first index from the index buffer.
[in]	vertexOffset	Specifies the base vertex offset (positive or negative) which is added to each index from the index buffer.
[in]	firstInstance	Specifies the zero-based offset of the first instance.

Note

The parameter firstInstance modifies the instance ID within the shader pipeline differently for SV_InstanceID in HLSL and gl_InstanceID in GLSL (or gl_InstanceIndex for Vulkan), due to rendering API differences. The system value SV_InstanceID in HLSL will always start with zero, but the system value gl_InstanceID in GLSL (or gl_InstanceIndex for Vulkan) will start with the value of firstInstance.

For the Metal renderer, the parameter vertexOffset is ignored when tessellation is enabled.

See also

RenderingFeatures::hasInstancing

RenderingFeatures::hasOffsetInstancing

DrawIndirect() [1/2]

virtual void LLGL::CommandBuffer::DrawIndirect ( Buffer & buffer, std::uint64_t offset )

pure virtual

Draws an unknown amount of instances of primitives whose draw command arguments are taken from a buffer object.

Parameters

[in]	buffer	Specifies the buffer from which the draw command arguments are taken. This buffer must have been created with the BindFlags::IndirectBuffer binding flag.
[in]	offset	Specifies an offset within the argument buffer from which the arguments are to be taken. This offset must be a multiple of 4.

See also

DrawIndirectArguments

RenderingFeatures::hasIndirectDrawing

DrawIndirect() [2/2]

virtual void LLGL::CommandBuffer::DrawIndirect ( Buffer & buffer, std::uint64_t offset, std::uint32_t numCommands, std::uint32_t stride )

pure virtual

Draws an unknown amount of instances of primitives whose draw command arguments are taken from a buffer object.

Parameters

[in]	buffer	Specifies the buffer from which the draw command arguments are taken. This buffer must have been created with the BindFlags::IndirectBuffer binding flag.
[in]	offset	Specifies an offset within the argument buffer from which the arguments are to be taken. This offset must be a multiple of 4.
[in]	numCommands	Specifies the number of draw commands that are to be taken from the argument buffer.
[in]	stride	Specifies the stride (in bytes) between consecutive sets of arguments, which is commonly greater than or equal to sizeof(DrawIndirectArguments). This stride must be a multiple of 4.

Remarks

This is also known as a "multi draw command" which is only natively supported by OpenGL and Vulkan. For other rendering APIs, the recording of multiple draw commands is emulated with a simple loop, which is equivalent to the following example:

while (numCommands-- > 0)
{
    DrawIndirect(buffer, offset);
    offset += stride;
}

See also

DrawIndirectArguments

RenderingFeatures::hasIndirectDrawing

DrawInstanced() [1/2]

virtual void LLGL::CommandBuffer::DrawInstanced ( std::uint32_t numVertices, std::uint32_t firstVertex, std::uint32_t numInstances )

pure virtual

See also

DrawInstanced(std::uint32_t, std::uint32_t, std::uint32_t, std::uint32_t)

Todo

numInstances should be the second parameter to be consistent with DrawIndexedInstanced() function and with D3D API. This will inevitably be a breaking change.

DrawInstanced() [2/2]

virtual void LLGL::CommandBuffer::DrawInstanced ( std::uint32_t numVertices, std::uint32_t firstVertex, std::uint32_t numInstances, std::uint32_t firstInstance )

pure virtual

Draws the specified amount of instances of primitives from the currently set vertex buffer.

Parameters

[in]	numVertices	Specifies the number of vertices to generate.
[in]	firstVertex	Specifies the zero-based offset of the first vertex from the vertex buffer.
[in]	numInstances	Specifies the number of instances to generate.
[in]	firstInstance	Specifies the zero-based offset of the first instance.

Note

The parameter firstVertex modifies the vertex ID within the shader pipeline differently for SV_VertexID in HLSL and gl_VertexID in GLSL (or gl_VertexIndex for Vulkan), due to rendering API differences. The system value SV_VertexID in HLSL will always start with zero, but the system value gl_VertexID in GLSL (or gl_VertexIndex for Vulkan) will start with the value of firstVertex. The same holds true for the parameter firstInstance and the system values SV_InstanceID in HLSL and gl_InstanceID in GLSL (or gl_InstanceIndex for Vulkan).

See also

RenderingFeatures::hasInstancing

RenderingFeatures::hasOffsetInstancing

Todo

numInstances should be the second parameter to be consistent with DrawIndexedInstanced() function and with D3D API. This will inevitably be a breaking change.

DrawStreamOutput()

virtual void LLGL::CommandBuffer::DrawStreamOutput ( )

pure virtual

Performs an automatic draw command whose number of primitives is provided by a stream-output buffer that is bound as vertex buffer.

Remarks

This command only supports a single vertex buffer in the input assembler stage and it must have been created with the BindFlags::VertexBuffer and BindFlags::StreamOutputBuffer binding flags.

This can be used to pre-transform vertices and render the output later on or multiple times.

See also

RenderingFeatures::hasStreamOutputs

SetVertexBuffer

End()

virtual void LLGL::CommandBuffer::End ( )

pure virtual

Ends the encoding (also referred to as "recording") of this command buffer.

Remarks

After this call, the command buffer can be submitted to the CommandQueue or executed by a primary command buffer.

See also

Begin

Execute

CommandQueue::Submit(CommandBuffer&)

EndQuery()

virtual void LLGL::CommandBuffer::EndQuery ( QueryHeap & queryHeap, std::uint32_t query = 0 )

pure virtual

Ends the specified query.

See also

BeginQuery

EndRenderCondition()

virtual void LLGL::CommandBuffer::EndRenderCondition ( )

pure virtual

Ends the current render condition.

See also

BeginRenderCondition

EndRenderPass()

virtual void LLGL::CommandBuffer::EndRenderPass ( )

pure virtual

Ends the current render pass.

See also

BeginRenderPass

EndStreamOutput()

virtual void LLGL::CommandBuffer::EndStreamOutput ( )

pure virtual

Ends the current stream-output.

See also

BeginStreamOutput

Execute()

virtual void LLGL::CommandBuffer::Execute ( CommandBuffer & secondaryCommandBuffer )

pure virtual

Executes the specified secondary command buffer by inlining its commands into this command buffer.

Parameters

[in]

secondaryCommandBuffer

Specifies the secondary command buffer which is meant to be inlined. This command buffer must have been created with the CommandBufferFlags::Secondary flag and its must also have finished encoding.

Remarks

This function can only be used by primary command buffers, i.e. command buffers that have not been created with the flag CommandBufferFlags::Secondary.

Once this command buffer is submitted for execution to one or more primary command buffers, it must not be updated unless all of such primary command buffers are also updated before their next submission to the command queue.

See also

CommandBufferFlags

Todo

Incomplete for: D3D12, Vulkan, Metal.

FillBuffer()

virtual void LLGL::CommandBuffer::FillBuffer ( Buffer & dstBuffer, std::uint64_t dstOffset, std::uint32_t value, std::uint64_t fillSize = LLGL_WHOLE_SIZE )

pure virtual

Fills the destination buffer with copies of the specified 32-bit value.

Parameters

[in,out]	dstBuffer	Specifies the destination buffer whose data is to be updated. This buffer must have been created with the binding flag BindFlags::CopyDst. This command works with all kinds of buffers, but for performance reasons it is recommended to create this buffer with the binding flag BindFlags::Storage. Otherwise, an intermediate buffer might be created and copied by LLGL.
[in]	dstOffset	Specifies the destination offset (in bytes) at which the destination buffer is to be updated.
[in]	value	Specifies the 32-bit value to fill the buffer with.
[in]	fillSize	Specifies the fill size (in bytes) of the buffer region. This must be a multiple of 4. By default LLGL_WHOLE_SIZE. If this is equal to LLGL_WHOLE_SIZE, dstOffset is ignored and the entire buffer will be filled.

Remarks

For performance reasons, it is recommended to encode this command outside of a render pass. Otherwise, render pass interruptions might be inserted by LLGL.

GenerateMips() [1/2]

virtual void LLGL::CommandBuffer::GenerateMips ( Texture & texture )

pure virtual

Generates all MIP-maps for the specified texture.

Parameters

[in,out]

texture

Specifies the texture whose MIP-maps are to be generated. This texture must have been created with the binding flags BindFlags::Sampled and BindFlags::ColorAttachment.

Remarks

For performance reasons, it is recommended to encode this command outside of a render pass. Otherwise, render pass interruptions might be inserted by LLGL.

See also

GenerateMips(Texture&, const TextureSubresource&)

GenerateMips() [2/2]

virtual void LLGL::CommandBuffer::GenerateMips ( Texture & texture, const TextureSubresource & subresource )

pure virtual

Generates a range of MIP-maps for the specified texture.

Parameters

[in,out]	texture	Specifies the texture whose MIP-maps are to be generated. This texture must have been created with the binding flags BindFlags::Sampled and BindFlags::ColorAttachment.
[in]	subresource	Specifies the texture subresource, i.e. the range of MIP-maps that are to be updated.

Remarks

For performance reasons, it is recommended to encode this command outside of a render pass. Otherwise, render pass interruptions might be inserted by LLGL.

This function guarantees to generate only the MIP-maps in the specified range (specified by subresource). However, this function may introduce a performance penalty compared to generating the full MIP chain if texture views are not natively supported by the backend. It is therefore recommended to use this function only if the range of MIP-maps is significantly smaller than the entire MIP chain, e.g. only a single slice of a large 2D array texture, and use the primary GenerateMips function otherwise.

See also

GenerateMips(Texture&)

RenderingFeatures::hasTextureViews

GetNativeHandle()

virtual bool LLGL::CommandBuffer::GetNativeHandle ( void * nativeHandle, std::size_t nativeHandleSize )

pure virtual

Returns the native command buffer handle.

Parameters

[out]	nativeHandle	Raw pointer to the backend specific structure to store the native handle. Obtain the respective structure from #include <LLGL/Backend/BACKEND/NativeHandle.h> where BACKEND must be either Direct3D12, Direct3D11, Vulkan, or Metal. OpenGL does not have a native handle as it uses the current platform specific GL context.
[in]	nativeHandleSize	Specifies the size (in bytes) of the native handle structure for robustness. This must be sizeof(STRUCT) where STRUCT is the respective backend specific structure such as LLGL::Direct3D12::CommandBufferNativeHandle.

Returns

True if the native handle was successfully retrieved. Otherwise, nativeHandleSize specifies an incompatible structure size.

Remarks

This must only be used on an immediate command buffer, i.e. those that have been created with the CommandBufferFlags::ImmediateSubmit flag.

For the Direct3D backends, all retrieved COM pointers will be incremented and the user is responsible for releasing those pointers, i.e. a call to IUnknown::Release is required to each of the objects returned by this function.

For the Metal backend, all retrieved NSObject instances will have their retain counter incremented and the user is responsible for releasing those objects, i.e. a call to -(oneway void)release is required to each of the objects returned by this function.

For backends that do not support this function, the return value is false unless nativeHandle is null or nativeHandleSize is 0.

Example for obtaining the native handle of a Direct3D12 render system:

#include <LLGL/Backend/Direct3D12/NativeHandle.h>
//...
LLGL::Direct3D12::CommandBufferNativeHandle d3dNativeHandle;
myCmdBuffer->GetNativeHandle(&d3dNativeHandle, sizeof(d3dNativeHandle));
ID3D12GraphicsCommandList* d3dCommandList = d3dNativeHandle.commandList;
...
d3dCommandList->Release();

Note

Only supported with: Direct3D 12, Direct3D 11, Vulkan, Metal.

See also

Direct3D12::CommandBufferNativeHandle

Direct3D11::CommandBufferNativeHandle

Vulkan::CommandBufferNativeHandle

Metal::CommandBufferNativeHandle

PopDebugGroup()

virtual void LLGL::CommandBuffer::PopDebugGroup ( )

pure virtual

See also

PushDebugGroup

PushDebugGroup()

virtual void LLGL::CommandBuffer::PushDebugGroup ( const char * name )

pure virtual

Pushes the specified name onto a stack of group strings that is used for debug reports.

Parameters

[in]

name

Pointer to a null terminated string that specifies the name. This must not be null!

Remarks

Here is a usage example:

myCmdBuffer->PushDebugGroup("Shadow Map Pass");
myCmdBuffer->BeginRenderPass(...);
// render shadow map ...
myCmdBuffer->EndRenderPass();
myCmdBuffer->PopDebugGroup();
 
myCmdBuffer->PushDebugGroup("Final Scene Pass");
myCmdBuffer->BeginRenderPass(...);
// render final scene ...
myCmdBuffer->EndRenderPass();
myCmdBuffer->PopDebugGroup();

Note

Only supported in debug mode or when the debug layer is enabled. Otherwise, the function has no effect.

See also

PopDebugGroup

RenderSystemChild::SetDebugName

ResourceBarrier()

virtual void LLGL::CommandBuffer::ResourceBarrier ( std::uint32_t numBuffers, Buffer *const * buffers, std::uint32_t numTextures, Texture *const * textures )

pure virtual

Inserts a resource memory barrier for the specified resources.

Parameters

[in]	numBuffers	Specifies the number of buffer resources.
[in]	buffers	Array to the buffer resources. This must be a valid pointer to an array of numBuffers Buffer objects. Null pointers within this array are silently ignored. Each resource that is non-null must have been created with the binding flag BindFlags::Storage.
[in]	numTextures	Specifies the number of texture resources.
[in]	textures	Array to the texture resources. This must be a valid pointer to an array of numTexture Texture objects. Null pointers within this array are silently ignored. Each resource that is non-null must have been created with the binding flag BindFlags::Storage.

Remarks

Explicit memory barriers are an alternative to pipeline layout barrier flags and can be used to fine-tune barriers when draw, compute, or blit commands potentially access memory that was written to by previous shader innvocations. They are not necessary if memory access between shader invocations is guaranteed to not overlap. For example, one invocation writes the first half of a buffer and another invocation writes the second half.

Here is a code example how to use them:

// Read 32 values from storageBufferA and write results to storageBufferB
cmdBuffer->SetResource(0, *storageBufferA);
cmdBuffer->SetResource(1, *storageBufferB);
cmdBuffer->Dispatch(32, 1, 1);
 
// Ensure all writes to storageBufferB are complete before next wave of compute kernels
cmdBuffer->ResourceBarrier(1, &storageBufferB, 0, nullptr);
 
// Now read previous results from storageBufferB and write new results to storageBufferA
// With the resource barrier, it is guaranteed that all results are available before
// any compute kernel will read from that buffer.
cmdBuffer->SetResource(0, *storageBufferB);
cmdBuffer->SetResource(1, *storageBufferA);
cmdBuffer->Dispatch(32, 1, 1);

See also

PipelineLayoutDescriptor::barrierFlags

Note

Only supported with: Direct3D 12, Direct3D 11, OpenGL.

Todo

Added support for Vulkan and Metal.

SetBlendFactor()

virtual void LLGL::CommandBuffer::SetBlendFactor ( const float color[4] )

pure virtual

Sets the dynamic pipeline state for blending factors.

Parameters

[in]

color

Specifies the blending factors for each color component as an array of four floating-point numbers. The default value is (1, 1, 1, 1).

Remarks

This is only used for the following blending operations:

• BlendOp::BlendFactor
• BlendOp::InvBlendFactor

This must only be used if the currently bound graphics pipeline state was created with blendFactorDynamic set to true. Otherwise, the behavior is undefined.

See also

BlendDescriptor::blendFactorDynamic

SetIndexBuffer() [1/2]

virtual void LLGL::CommandBuffer::SetIndexBuffer ( Buffer & buffer )

pure virtual

Sets the active index buffer for subsequent drawing operations.

Parameters

[in]

buffer

Specifies the index buffer to set. This buffer must have been created with the binding flag BindFlags::IndexBuffer and its content must not be uninitialized. For this version of SetIndexBuffer, the index buffer must also be created with indexFormat set to either Format::R16UInt or Format::R32UInt.

Remarks

An index buffer is only required for any DrawIndexed or DrawIndexedInstanced draw call.

See also

RenderSystem::CreateBuffer

RenderSystem::WriteBuffer

DrawIndexed

DrawIndexedInstanced

BufferDescriptor::format

SetIndexBuffer() [2/2]

virtual void LLGL::CommandBuffer::SetIndexBuffer ( Buffer & buffer, const Format format, std::uint64_t offset = 0 )

pure virtual

Sets the active index buffer for subsequent drawing operations with a dynamic format and optional buffer offset.

Parameters

[in]	buffer	Specifies the index buffer to set. This buffer must have been created with the binding flag BindFlags::IndexBuffer and its content must not be uninitialized.
[in]	format	Specifies the format of each index in the buffer. This must be either Format::R16UInt or Format::R32UInt.
[in]	offset	Specifies an optional offset (in bytes) where to start reading the index buffer. By default 0. This has the same effect as setting the firstIndex argument in any DrawIndexed or DrawIndexedInstanced function, except that this offset is byte aligned.

Remarks

The alternative version of this function uses merely the index format that was specified when the buffer was created.

See also

BufferDescriptor::format

SetIndexBuffer(Buffer&)

SetPipelineState()

virtual void LLGL::CommandBuffer::SetPipelineState ( PipelineState & pipelineState )

pure virtual

Sets the active graphics or compute pipeline state.

Parameters

[in]

pipelineState

Specifies the pipeline state which is to be bound for subsequent draw or compute commands.

Remarks

A graphics pipeline state will set all blending-, rasterizer-, depth-, stencil-, and shader states. A valid graphics pipeline state must always be set before any drawing operation can be performed, and a graphics pipeline state can be set inside and outside a render pass section.

A compute pipeline state will set shader states for dispatch compute commands. A valid compute pipeline state must always be set before any dispatch compute operation cam ne performed, and a compute pipeline state must be set outside a render pass section.

// Set compute pipeline state and perform compute commands
myCmdBuffer->SetPipelineState(*myComputePipeline);
myCmdBuffer->Dispatch(...);
 
// Start render pass section
myCmdBuffer->BeginRenderPass(...);
{
    // Set graphics pipeline state and perform drawing operations
    myCmdBuffer->SetPipelineState(*myGraphicsPipeline);
    myCmdBuffer->Draw(...);
}
myCmdBuffer->EndRenderPass();

See also

RenderSystem::CreatePipelineState

SetResource()

virtual void LLGL::CommandBuffer::SetResource ( std::uint32_t descriptor, Resource & resource )

pure virtual

Binds the specified resource as root parameter to the respective pipeline.

Parameters

[in]	descriptor	Specifies the zero-based index of the descriptor in the currently bound pipeline layout. This must be in the half-open range [0, PipelineLayout::GetNumBindings).
[in]	resource	Specifies the resource that is to be bound to the shader pipeline.

See also

PipelineLayoutDescriptor::bindings

SetResourceHeap()

virtual void LLGL::CommandBuffer::SetResourceHeap ( ResourceHeap & resourceHeap, std::uint32_t descriptorSet = 0 )

pure virtual

Binds the specified resource heap to the respective pipeline.

Parameters

[in]	resourceHeap	Specifies the resource heap that contains all shader resources that will be bound to the shader pipeline.
[in]	descriptorSet	Specifies the zero-based index of the set of resource descriptors. This must be in the half-open range [0, ResourceHeap::GetNumDescriptorSets). By default 0.

Remarks

Any previous heap resource bindings are invalid after this call.

See also

ResourceHeap::GetNumDescriptorSets

PipelineLayoutDescriptor::heapBindings

SetScissor()

virtual void LLGL::CommandBuffer::SetScissor ( const Scissor & scissor )

pure virtual

Sets a single scissor rectangle.

Remarks

Similar to SetScissors but only a single scissor rectangle is set.

This must only be used if the currently bound graphics pipeline state was created with scissors being empty. Otherwise, the behavior is undefined.

See also

SetScissors

GraphicsPipelineDescriptor::scissors

SetScissors()

virtual void LLGL::CommandBuffer::SetScissors ( std::uint32_t numScissors, const Scissor * scissors )

pure virtual

Sets an array of scissor rectangles, but only if the scissor test was enabled in the previously set graphics pipeline (otherwise, this function has no effect).

Parameters

[in]	numScissors	Specifies the number of scissor rectangles to set.
[in]	scissors	Pointer to the array of scissor rectangles. This must not be null!

Remarks

This must only be used if the currently bound graphics pipeline state was created with scissors being empty. Otherwise, the behavior is undefined.

See also

GraphicsPipelineDescriptor::scissors

RasterizerDescriptor::scissorTestEnabled

SetStencilReference()

virtual void LLGL::CommandBuffer::SetStencilReference ( std::uint32_t reference, const StencilFace stencilFace = StencilFace::FrontAndBack )

pure virtual

Sets the dynamic pipeline state for stencil reference values.

Parameters

[in]	reference	Specifies the reference value.
[in]	stencilFace	Specifies the faces that will be affected by this reference value. For Direct3D renderers, this must be StencilFace::FrontAndBack, which is the default value.

Remarks

This must only be used if the currently bound graphics pipeline state was created with referenceDynamic set to true. Otherwise, the behavior is undefined.

See also

StencilDescriptor::referenceDynamic

SetUniforms()

virtual void LLGL::CommandBuffer::SetUniforms ( std::uint32_t first, const void * data, std::uint16_t dataSize )

pure virtual

Sets the value of a certain number of shader uniforms (aka. push constant/ shader constants) in the currently bound PSO.

Parameters

[in]	first	Specifies the zero-based index of the first uniform that are to be updated. This must be in the half-open range [0, PipelineLayout::GetNumUniforms). The number of uniforms that are to be updated is determined by the size of the data. See dataSize parameter for more details.
[in]	data	Raw pointer to the data that is to be copied to the uniform.
[in]	dataSize	Specifies the size (in bytes) of the input buffer data. This must be a multiple of 4 since 32-bits are the smallest granularity to update shader uniforms. This parameter also determines the number of uniforms that are to be updated.

Remarks

This function must only be called after a pipeline state object (PSO) has been bound.

See also

PipelineLayoutDescriptor::uniforms

SetPipelineState

SetVertexBuffer() [1/2]

virtual void LLGL::CommandBuffer::SetVertexBuffer ( Buffer & buffer )

pure virtual

Sets the specified vertex buffer for subsequent drawing operations.

Parameters

[in]

buffer

Specifies the vertex buffer to set. This buffer must have been created with the binding flag BindFlags::VertexBuffer and its content must not be uninitialized.

See also

RenderSystem::CreateBuffer

RenderSystem::WriteBuffer

SetVertexBuffers

SetVertexBufferArray

SetVertexBuffer() [2/2]

virtual void LLGL::CommandBuffer::SetVertexBuffer ( Buffer & buffer, std::uint32_t stride, std::uint64_t offset = 0 )

pure virtual

Sets the specified vertex buffer for subsequent drawing operations with a new stride and optional base offset.

Parameters

[in]	buffer	Specifies the vertex buffer to set. This buffer must have been created with the binding flag BindFlags::VertexBuffer and its content must not be uninitialized.
[in]	stride	Specifies the stride (in bytes) between vertices. This must either be zero or equal to the stride of all vertex attributes that reference this buffer slot (0) described in the graphics PSO that is used in subsequent draw commands. If this is zero, the stride is implied by the stride this buffer was created with, which in turn must not be zero and is also subject to the same constraint of the PSO's input layout.
[in]	offset	Specifies an optional base offset (in bytes) where to start reading the vertex buffer. By default 0.

Remarks

Use this function either when the specified vertex buffer was not created with a default stride or the graphics PSO for subsequent draw commands has a vertex input layout with a stride different from the buffer's default stride.

Having to specify the same stride as used in the graphics PSO seems redundant, but it's a compromise of keeping the API lightweight and backend agnostic.

D3D defines the strides with their vertex buffers while Vulkan and Metal tie them to the graphics PSO. Letting LLGL track those states adds costs that can be avoided.

See also

BufferDescriptor::stride

SetVertexBufferArray()

virtual void LLGL::CommandBuffer::SetVertexBufferArray ( BufferArray & bufferArray )

pure virtual

Sets the specified array of vertex buffers for subsequent drawing operations.

Parameters

[in]

bufferArray

Specifies the vertex buffer array to set.

Remarks

This serves as minor performance optimization over SetVertexBuffers since the BufferArray interface allows backends to pre-allocate their internal representation for their native resources, strides, and offsets.

See also

RenderSystem::CreateBufferArray

SetVertexBuffers

SetVertexBuffers()

virtual void LLGL::CommandBuffer::SetVertexBuffers ( std::uint32_t numBufferViews, const VertexBufferView * bufferViews )

pure virtual

Sets the specified number of vertex buffers for subsequent drawing operations with optional strides and base offsets.

Parameters

[in]	numBufferViews	Specifies the number of vertex buffers to bind. This must not exceed the limit of vertex buffers the render system supports.
[in]	bufferViews	Pointer to an array of vertex buffer views. This must not be null and must point to an array with at least numBufferViews elements.

Remarks

This is a more convenient alternative to binding multiple vertex buffer slots 'on the fly' compared to binding via a BufferArray that needs to be pre-allocated.

See also

RenderingLimits::maxVertexBufferInputs

SetViewport()

virtual void LLGL::CommandBuffer::SetViewport ( const Viewport & viewport )

pure virtual

Sets a single viewport.

Remarks

Similar to SetViewports but only a single viewport is set.

This must only be used if the currently bound graphics pipeline state was created with viewports being empty. Otherwise, the behavior is undefined.

See also

SetViewports

GraphicsPipelineDescriptor::viewports

SetViewports()

virtual void LLGL::CommandBuffer::SetViewports ( std::uint32_t numViewports, const Viewport * viewports )

pure virtual

Sets an array of viewports.

Parameters

[in]	numViewports	Specifies the number of viewports to set. Most render system have a limit of 16 viewports.
[in]	viewports	Pointer to the array of viewports. This must not be null!

Remarks

This must only be used if the currently bound graphics pipeline state was created with viewports being empty. Otherwise, the behavior is undefined.

See also

GraphicsPipelineDescriptor::viewports

RenderingLimits::maxViewports

UpdateBuffer()

virtual void LLGL::CommandBuffer::UpdateBuffer ( Buffer & dstBuffer, std::uint64_t dstOffset, const void * data, std::uint64_t dataSize )

pure virtual

Updates the data of the specified buffer during encoding the command buffer.

Parameters

[in]	dstBuffer	Specifies the destination buffer whose data is to be updated.
[in]	dstOffset	Specifies the destination offset (in bytes) at which the buffer is to be updated. This offset plus the data block size (i.e. dstOffset + dataSize) must be less than or equal to the size of the buffer.
[in]	data	Raw pointer to the data with which the buffer is to be updated. This must not be null!
[in]	dataSize	Specifies the size (in bytes) of the data block which is to be updated.

Remarks

To update buffers without a command buffer, use RenderSystem::WriteBuffer. For performance reasons, it is recommended to encode this command outside of a render pass. Otherwise, render pass interruptions might be inserted by LLGL.

---

The documentation for this class was generated from the following file:

• CommandBuffer.h