Skip to content

TSdlGpuCommandBuffer

A command buffer.

Most state is managed via command buffers. When setting state using a command buffer, that state is local to the command buffer.

Commands only begin execution on the GPU once Submit is called. Once the command buffer is submitted, it is no longer valid to use it.

Command buffers are executed in submission order. If you submit command buffer A and then command buffer B all commands in A will begin executing before any command in B begins executing.

In multi-threading scenarios, you should only access a command buffer on the thread you acquired it from.

Definition

Unit: Neslib.Sdl3.Gpu

type TSdlGpuCommandBuffer = record ... end;

See Also

Operators

Name Description
Equal(TSdlGpuCommandBuffer, TSdlGpuCommandBuffer) Used to compare against another TSdlGpuCommandBuffer.
Equal(TSdlGpuCommandBuffer, Pointer) Used to compare against nil.
Implicit Used to set the value to nil.
NotEqual(TSdlGpuCommandBuffer, TSdlGpuCommandBuffer) Used to compare against another TSdlGpuCommandBuffer.
NotEqual(TSdlGpuCommandBuffer, Pointer) Used to compare against nil.

Methods

Name Description
AcquireSwapchainTexture Acquire a texture to use in presentation.
BeginComputePass Begins a compute pass on a command buffer.
BeginCopyPass Begins a copy pass on a command buffer.
BeginRenderPass(TArray<TSdlGpuColorTargetInfo>, TSdlGpuDepthStencilTargetInfo) Begins a render pass on a command buffer.
BeginRenderPass(TArray<TSdlGpuColorTargetInfo>) Begins a render pass on a command buffer.
Blit Blits from a source texture region to a destination texture region.
Cancel Cancels the command buffer.
GenerateMipmaps Generates mipmaps for the given texture.
InsertDebugLabel Inserts an arbitrary string label into the command buffer callstream.
PopDebugGroup Ends the most-recently pushed debug group.
PushComputeUniformData(Integer, Pointer, Integer) Pushes data to a uniform slot on the command buffer.
PushComputeUniformData(Integer, TBytes) Pushes data to a uniform slot on the command buffer.
PushDebugGroup Begins a debug group with an arbitary name.
PushFragmentUniformData(Integer, Pointer, Integer) Pushes data to a fragment uniform slot on the command buffer.
PushFragmentUniformData(Integer, TBytes) Pushes data to a fragment uniform slot on the command buffer.
PushVertexUniformData(Integer, Pointer, Integer) Pushes data to a vertex uniform slot on the command buffer.
PushVertexUniformData(Integer, TBytes) Pushes data to a vertex uniform slot on the command buffer.
Submit Submits the command buffer so its commands can be processed on the GPU.
SubmitAndAcquireFence Submits the command buffer so its commands can be processed on the GPU, and acquires a fence associated with the command buffer.
WaitAndAcquireSwapchainTexture Blocks the thread until a swapchain texture is available to be acquired, and then acquires it.

Operator Descriptions

Equal(TSdlGpuCommandBuffer, TSdlGpuCommandBuffer)

Used to compare against another TSdlGpuCommandBuffer.

class operator Equal(const ALeft, ARight: TSdlGpuCommandBuffer): Boolean; inline; static

Parameters

ALeft: TSdlGpuCommandBuffer

ARight: TSdlGpuCommandBuffer

Returns

Boolean

Equal(TSdlGpuCommandBuffer, Pointer)

Used to compare against nil.

class operator Equal(const ALeft: TSdlGpuCommandBuffer; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlGpuCommandBuffer

ARight: Pointer

Returns

Boolean

Implicit(Pointer)

Used to set the value to nil.

class operator Implicit(const AValue: Pointer): TSdlGpuCommandBuffer; inline; static

Parameters

AValue: Pointer

Returns

TSdlGpuCommandBuffer

NotEqual(TSdlGpuCommandBuffer, TSdlGpuCommandBuffer)

Used to compare against another TSdlGpuCommandBuffer.

class operator NotEqual(const ALeft, ARight: TSdlGpuCommandBuffer): Boolean; inline; static

Parameters

ALeft: TSdlGpuCommandBuffer

ARight: TSdlGpuCommandBuffer

Returns

Boolean

NotEqual(TSdlGpuCommandBuffer, Pointer)

Used to compare against nil.

class operator NotEqual(const ALeft: TSdlGpuCommandBuffer; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlGpuCommandBuffer

ARight: Pointer

Returns

Boolean

Method Descriptions

AcquireSwapchainTexture(TSdlWindow, TSdlGpuTexture, Integer, Integer)

Acquire a texture to use in presentation.

When a swapchain texture is acquired on a command buffer, it will automatically be submitted for presentation when the command buffer is submitted. The swapchain texture should only be referenced by the command buffer used to acquire it.

This method will fill the swapchain texture handle with nil if too many frames are in flight. This is not an error.

If you use this method, it is possible to create a situation where many command buffers are allocated while the rendering context waits for the GPU to catch up, which will cause memory usage to grow. You should use WaitAndAcquireSwapchainTexture unless you know what you are doing with timing.

The swapchain texture is managed by the implementation and must not be freed by the user. You MUST NOT call this method from any thread other than the one that created the window.

procedure AcquireSwapchainTexture(const AWindow: TSdlWindow; out ASwapchainTexture: TSdlGpuTexture; out ASwapchainTextureWidth, ASwapchainTextureHeight: Integer); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AWindow: TSdlWindow : A window that has been claimed.

ASwapchainTexture: TSdlGpuTexture : Will be set to a swapchain texture.

ASwapchainTextureWidth: Integer : Will be set to the swapchain texture width.

ASwapchainTextureHeight: Integer : Will be set to the swapchain texture height.

See Also

Remarks

This method should only be called from the thread that created the window.

BeginComputePass(TArray<TSdlGpuStorageTextureReadWriteBinding>, TArray<TSdlGpuStorageBufferReadWriteBinding>)

Begins a compute pass on a command buffer.

A compute pass is defined by a set of texture subresources and buffers that may be written to by compute pipelines. These textures and buffers must have been created with TSdlGpuTextureUsage.ComputeStorageWrite or TSdlGpuTextureUsage.ComputeStorageSimultaneousReadWrite. If you do not create a texture with TSdlGpuTextureUsage.ComputeStorageSimultaneousReadWrite, you must not read from the texture in the compute pass. All operations related to compute pipelines must take place inside of a compute pass. You must not begin another compute pass, or a render pass or copy pass before ending the compute pass.

A VERY IMPORTANT NOTE - Reads and writes in compute passes are NOT implicitly synchronized. This means you may cause data races by both reading and writing a resource region in a compute pass, or by writing multiple times to a resource region. If your compute work depends on reading the completed output from a previous dispatch, you MUST end the current compute pass and begin a new one before you can safely access the data. Otherwise you will receive unexpected results. Reading and writing a texture in the same compute pass is only supported by specific texture formats. Make sure you check the format support!

function BeginComputePass(const AStorageTextureBindings, AStorageBufferBindings: TArray<TSdlGpuStorageBufferReadWriteBinding>): TSdlGpuComputePass; inline

Parameters

AStorageTextureBindings: TArray<TSdlGpuStorageTextureReadWriteBinding> : An array of writeable storage texture binding records.

AStorageBufferBindings: TArray<TSdlGpuStorageBufferReadWriteBinding> : An array of writeable storage buffer binding records.

Returns

TSdlGpuComputePass: A compute pass.

See Also

BeginCopyPass

Begins a copy pass on a command buffer.

All operations related to copying to or from buffers or textures take place inside a copy pass. You must not begin another copy pass, or a render pass or compute pass before ending the copy pass.

function BeginCopyPass: TSdlGpuCopyPass; inline

Returns

TSdlGpuCopyPass: A copy pass.

BeginRenderPass(TArray<TSdlGpuColorTargetInfo>, TSdlGpuDepthStencilTargetInfo)

Begins a render pass on a command buffer.

A render pass consists of a set of texture subresources (or depth slices in the 3D texture case) which will be rendered to during the render pass, along with corresponding clear values and load/store operations. All operations related to graphics pipelines must take place inside of a render pass. A default viewport and scissor state are automatically set when this is called. You cannot begin another render pass, or begin a compute pass or copy pass until you have ended the render pass.

function BeginRenderPass(const AColorTargetInfos: TArray<TSdlGpuColorTargetInfo>; const ADepthStencilTargetInfo: TSdlGpuDepthStencilTargetInfo): TSdlGpuRenderPass; overload; inline

Parameters

AColorTargetInfos: TArray<TSdlGpuColorTargetInfo> : An array of texture subresources with corresponding clear values and load/store ops.

ADepthStencilTargetInfo: TSdlGpuDepthStencilTargetInfo : Texture subresource with corresponding clear value and load/store ops, may be nil.

Returns

TSdlGpuRenderPass: A render pass.

See Also

BeginRenderPass(TArray<TSdlGpuColorTargetInfo>)

Begins a render pass on a command buffer.

A render pass consists of a set of texture subresources (or depth slices in the 3D texture case) which will be rendered to during the render pass, along with corresponding clear values and load/store operations. All operations related to graphics pipelines must take place inside of a render pass. A default viewport and scissor state are automatically set when this is called. You cannot begin another render pass, or begin a compute pass or copy pass until you have ended the render pass.

function BeginRenderPass(const AColorTargetInfos: TArray<TSdlGpuColorTargetInfo>): TSdlGpuRenderPass; overload; inline

Parameters

AColorTargetInfos: TArray<TSdlGpuColorTargetInfo> : An array of texture subresources with corresponding clear values and load/store ops.

Returns

TSdlGpuRenderPass: A render pass.

See Also

Blit(TSdlGpuBlitInfo)

Blits from a source texture region to a destination texture region.

This function must not be called inside of any pass.

procedure Blit(const AInfo: TSdlGpuBlitInfo); inline

Parameters

AInfo: TSdlGpuBlitInfo : The blit info struct containing the blit parameters.

Cancel

Cancels the command buffer.

None of the enqueued commands are executed.

It is an error to call this method after a swapchain texture has been acquired.

This must be called from the thread the command buffer was acquired on.

You must not reference the command buffer after calling this method.

procedure Cancel; inline

Exceptions

ESdlError: Raised on failure.

See Also

GenerateMipmaps(TSdlGpuTexture)

Generates mipmaps for the given texture.

This function must not be called inside of any pass.

procedure GenerateMipmaps(const ATexture: TSdlGpuTexture); inline

Parameters

ATexture: TSdlGpuTexture : A texture with more than 1 mip level.

InsertDebugLabel(String)

Inserts an arbitrary string label into the command buffer callstream.

Useful for debugging.

procedure InsertDebugLabel(const AText: String); inline

Parameters

AText: String : A string constant to insert as the label.

PopDebugGroup

Ends the most-recently pushed debug group.

procedure PopDebugGroup; inline

See Also

PushComputeUniformData(Integer, Pointer, Integer)

Pushes data to a uniform slot on the command buffer.

Subsequent draw calls will use this uniform data.

The data being pushed must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.

procedure PushComputeUniformData(const ASlotIndex: Integer; const AData: Pointer; const ASize: Integer); overload; inline

Parameters

ASlotIndex: Integer : The uniform slot to push data to.

AData: Pointer : Pointer to client data to write.

ASize: Integer : Size of the data to write.

PushComputeUniformData(Integer, TBytes)

Pushes data to a uniform slot on the command buffer.

Subsequent draw calls will use this uniform data.

The data being pushed must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.

procedure PushComputeUniformData(const ASlotIndex: Integer; const AData: TBytes); overload; inline

Parameters

ASlotIndex: Integer : The uniform slot to push data to.

AData: TBytes : Client data to write.

PushDebugGroup(String)

Begins a debug group with an arbitary name.

Used for denoting groups of calls when viewing the command buffer callstream in a graphics debugging tool.

Each call to PushDebugGroup must have a corresponding call to PopDebugGroup.

On some backends (e.g. Metal), pushing a debug group during a render/blit/compute pass will create a group that is scoped to the native pass rather than the command buffer. For best results, if you push a debug group during a pass, always pop it in the same pass.

procedure PushDebugGroup(const AName: String); inline

Parameters

AName: String : A string constant that names the group.

See Also

PushFragmentUniformData(Integer, Pointer, Integer)

Pushes data to a fragment uniform slot on the command buffer.

Subsequent draw calls will use this uniform data.

The data being pushed must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.

procedure PushFragmentUniformData(const ASlotIndex: Integer; const AData: Pointer; const ASize: Integer); overload; inline

Parameters

ASlotIndex: Integer : The fragment uniform slot to push data to.

AData: Pointer : Pointer to client data to write.

ASize: Integer : Size of the data to write.

PushFragmentUniformData(Integer, TBytes)

Pushes data to a fragment uniform slot on the command buffer.

Subsequent draw calls will use this uniform data.

The data being pushed must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.

procedure PushFragmentUniformData(const ASlotIndex: Integer; const AData: TBytes); overload; inline

Parameters

ASlotIndex: Integer : The fragment uniform slot to push data to.

AData: TBytes : Client data to write.

PushVertexUniformData(Integer, Pointer, Integer)

Pushes data to a vertex uniform slot on the command buffer.

Subsequent draw calls will use this uniform data.

The data being pushed must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.

procedure PushVertexUniformData(const ASlotIndex: Integer; const AData: Pointer; const ASize: Integer); overload; inline

Parameters

ASlotIndex: Integer : The vertex uniform slot to push data to.

AData: Pointer : Pointer to client data to write.

ASize: Integer : Size of the data to write.

PushVertexUniformData(Integer, TBytes)

Pushes data to a vertex uniform slot on the command buffer.

Subsequent draw calls will use this uniform data.

The data being pushed must respect std140 layout conventions. In practical terms this means you must ensure that vec3 and vec4 fields are 16-byte aligned.

procedure PushVertexUniformData(const ASlotIndex: Integer; const AData: TBytes); overload; inline

Parameters

ASlotIndex: Integer : The vertex uniform slot to push data to.

AData: TBytes : Client data to write.

Submit

Submits the command buffer so its commands can be processed on the GPU.

It is invalid to use the command buffer after this is called.

This must be called from the thread the command buffer was acquired on.

All commands in the submission are guaranteed to begin executing before any command in a subsequent submission begins executing.

procedure Submit; inline

Exceptions

ESdlError: Raised on failure.

See Also

SubmitAndAcquireFence

Submits the command buffer so its commands can be processed on the GPU, and acquires a fence associated with the command buffer.

You must release this fence when it is no longer needed or it will cause a leak. It is invalid to use the command buffer after this is called.

This must be called from the thread the command buffer was acquired on.

All commands in the submission are guaranteed to begin executing before any command in a subsequent submission begins executing.

function SubmitAndAcquireFence: TSdlGpuFence; inline

Exceptions

ESdlError: Raised on failure.

Returns

TSdlGpuFence: A fence associated with the command buffer.

See Also

WaitAndAcquireSwapchainTexture(TSdlWindow, TSdlGpuTexture, Integer, Integer)

Blocks the thread until a swapchain texture is available to be acquired, and then acquires it.

When a swapchain texture is acquired on a command buffer, it will automatically be submitted for presentation when the command buffer is submitted. The swapchain texture should only be referenced by the command buffer used to acquire it. It is an error to call Cancel after a swapchain texture is acquired.

This method can fill the swapchain texture handle with nil in certain cases, for example if the window is minimized. This is not an error. You should always make sure to check whether the pointer is nil before actually using it.

The swapchain texture is managed by the implementation and must not be freed by the user. You MUST NOT call this method from any thread other than the one that created the window.

The swapchain texture is write-only and cannot be used as a sampler or for another reading operation.

procedure WaitAndAcquireSwapchainTexture(const AWindow: TSdlWindow; out ASwapchainTexture: TSdlGpuTexture; out ASwapchainTextureWidth, ASwapchainTextureHeight: Integer); inline

Exceptions

ESdlError: Raised on failure.

Parameters

AWindow: TSdlWindow : A window that has been claimed.

ASwapchainTexture: TSdlGpuTexture : Is set to a swapchain texture.

ASwapchainTextureWidth: Integer : Is set to the swapchain texture width.

ASwapchainTextureHeight: Integer : Is set to the swapchain texture height.

See Also

Remarks

This method should only be called from the thread that created the window.