CommandBuffer Struct Reference

A recorded sequence of GPU commands for a single frame. More...

#include <CommandBuffer.h>

Inheritance diagram for CommandBuffer:

Public Member Functions
bool	acquireSwapchainTexture (const CommandBuffer *self, SwapchainTexture *swapchain)
	Acquires the next swapchain texture for rendering.
ComputePass *	beginComputePass (CommandBuffer *self, const SDL_GPUStorageTextureReadWriteBinding *storageTextures, Uint32 numStorageTextures, const SDL_GPUStorageBufferReadWriteBinding *storageBuffers, Uint32 numStorageBuffers)
	Begins a compute pass and returns a retained ComputePass.
CopyPass *	beginCopyPass (CommandBuffer *self)
	Begins a copy pass and returns a retained CopyPass.
RenderPass *	beginRenderPass (CommandBuffer *self, const SDL_GPUColorTargetInfo *colorTargets, Uint32 numColorTargets, const SDL_GPUDepthStencilTargetInfo *depthStencil)
	Begins a render pass and returns a retained RenderPass.
RenderPass *	beginRenderPassWithFramebuffer (CommandBuffer *self, const Framebuffer *framebuffer, SDL_GPULoadOp loadOp, SDL_GPUStoreOp storeOp)
	Begins a render pass over all of framebuffer's color targets and its depth target (if any), using its own clear color(s) and clear depth when loadOp is SDL_GPU_LOADOP_CLEAR.
void	blitTexture (const CommandBuffer *self, const SDL_GPUBlitInfo *info)
	Blits a region of one texture to another.
bool	cancel (CommandBuffer *self)
	Cancels this command buffer without submitting it to the GPU.
void	generateMipmaps (const CommandBuffer *self, SDL_GPUTexture *texture)
	Records a mipmap generation command for the given texture.
CommandBuffer *	initWithCommandBuffer (CommandBuffer *self, const RenderDevice *device, SDL_GPUCommandBuffer *commands)
void	insertDebugLabel (const CommandBuffer *self, const char *text)
	Inserts an arbitrary debug label into the command stream.
void	popDebugGroup (const CommandBuffer *self)
	Ends the innermost active debug group.
void	pushComputeUniformData (const CommandBuffer *self, Uint32 slot, const void *data, Uint32 length)
	Pushes uniform data for the current compute shader.
void	pushDebugGroup (const CommandBuffer *self, const char *name)
	Begins a named debug group in the command stream.
void	pushFragmentUniformData (const CommandBuffer *self, Uint32 slot, const void *data, Uint32 length)
	Pushes uniform data for the current fragment shader.
void	pushVertexUniformData (const CommandBuffer *self, Uint32 slot, const void *data, Uint32 length)
	Pushes uniform data for the current vertex shader.
void	pushUniformData (const CommandBuffer *self, Uint32 slot, const void *data, Uint32 length)
	Pushes the same uniform data to slot for both the current vertex and fragment shaders.
bool	submit (CommandBuffer *self)
	Submits this command buffer to the GPU for execution.
Fence *	submitAndFence (CommandBuffer *self)
	Submits this command buffer and returns a Fence for GPU completion.
bool	waitAndAcquireSwapchainTexture (const CommandBuffer *self, SwapchainTexture *swapchain)
	Blocks until a swapchain texture is available, then acquires it.
Class *	_CommandBuffer (void)
	The CommandBuffer archetype.
CommandBuffer *	initWithCommandBuffer (CommandBuffer *self, const RenderDevice *device, *SDL_GPUCommandBuffer *commands)
	Initializes this CommandBuffer wrapping the given SDL command buffer.

Data Fields
Object	object
	The superclass.
SDL_GPUCommandBuffer *	commands
	The underlying SDL command buffer.
RenderDevice *	device
	The RenderDevice that this CommandBuffer belongs to.
ident	data
	User data.

Protected Attributes
CommandBufferInterface *	interface
	The interface.

Detailed Description

A recorded sequence of GPU commands for a single frame.

CommandBuffer is a lightweight wrapper around SDL_GPUCommandBuffer. Obtain one from RenderDevice::acquireCommandBuffer each frame. The three begin*Pass factory methods return the appropriate pass object; releasing the pass ends it, ready for the next pass or submission.

Submit or cancel the buffer with submit, submitAndFence, or cancel. Releasing a CommandBuffer without submitting or cancelling it is an error.

Member Function Documentation

_CommandBuffer()

Class * _CommandBuffer

(

void

)

The CommandBuffer archetype.

Returns

The CommandBuffer Class.

acquireSwapchainTexture()

bool acquireSwapchainTexture	(	const CommandBuffer *	self,
		SwapchainTexture *	swapchain
	)

Acquires the next swapchain texture for rendering.

Returns false (without asserting) when the window is minimised, too many frames are in flight, or the swapchain is temporarily unavailable; SDL reports those cases as success with a NULL texture, which MUST NOT be passed back into SDL, so they are reported here as failure and swapchain is zeroed. The caller should skip presenting for that frame.

Parameters

self	The CommandBuffer.
swapchain	Output structure populated with the texture and dimensions, or zeroed.

Returns

True on success, false when the swapchain is unavailable this frame.

beginComputePass()

ComputePass * beginComputePass	(	CommandBuffer *	self,
		const SDL_GPUStorageTextureReadWriteBinding *	storageTextures,
		Uint32	numStorageTextures,
		const SDL_GPUStorageBufferReadWriteBinding *	storageBuffers,
		Uint32	numStorageBuffers
	)

Begins a compute pass and returns a retained ComputePass.

The returned ComputePass must be released when compute work is complete. Releasing it calls SDL_EndGPUComputePass automatically.

Parameters

self	The CommandBuffer.
storageTextures	Read-write storage texture bindings, or NULL.
numStorageTextures	Number of storage texture bindings.
storageBuffers	Read-write storage buffer bindings, or NULL.
numStorageBuffers	Number of storage buffer bindings.

Returns

A new ComputePass, retained. Must be released by the caller.

beginCopyPass()

CopyPass * beginCopyPass

(

CommandBuffer *

self

)

Begins a copy pass and returns a retained CopyPass.

The returned CopyPass must be released when all transfers are complete. Releasing it calls SDL_EndGPUCopyPass automatically.

Parameters

self	The CommandBuffer.

Returns

A new CopyPass, retained. Must be released by the caller.

beginRenderPass()

RenderPass * beginRenderPass	(	CommandBuffer *	self,
		const SDL_GPUColorTargetInfo *	colorTargets,
		Uint32	numColorTargets,
		const SDL_GPUDepthStencilTargetInfo *	depthStencil
	)

Begins a render pass and returns a retained RenderPass.

The returned RenderPass must be released when all draw calls are recorded. Releasing it calls SDL_EndGPURenderPass automatically.

Parameters

self	The CommandBuffer.
colorTargets	Array of color target infos.
numColorTargets	Number of color targets.
depthStencil	Depth-stencil target info, or NULL.

Returns

A new RenderPass, retained. Must be released by the caller.

beginRenderPassWithFramebuffer()

RenderPass * beginRenderPassWithFramebuffer	(	CommandBuffer *	self,
		const Framebuffer *	framebuffer,
		SDL_GPULoadOp	loadOp,
		SDL_GPUStoreOp	storeOp
	)

Begins a render pass over all of framebuffer's color targets and its depth target (if any), using its own clear color(s) and clear depth when loadOp is SDL_GPU_LOADOP_CLEAR.

Convenience for the common case of "render into this framebuffer" with a single load/store op shared by every target. For a mix of load ops across targets, per-target clear overrides, a query pool, or a subset of a framebuffer's targets (e.g. a depth-only pass), build the target infos yourself via Framebuffer::colorTargetInfo/depthTargetInfo and call beginRenderPass directly.

Parameters

self	The CommandBuffer.
framebuffer	The Framebuffer to render into.
loadOp	Load operation applied uniformly to every target.
storeOp	Store operation applied uniformly to every target.

Returns

A new RenderPass, retained. Must be released by the caller.

blitTexture()

void blitTexture	(	const CommandBuffer *	self,
		const SDL_GPUBlitInfo *	info
	)

Blits a region of one texture to another.

cancel()

bool cancel

(

CommandBuffer *

self

)

Cancels this command buffer without submitting it to the GPU.

Use this when swapchain acquisition fails or rendering must be skipped for a frame. The CommandBuffer must be released after cancel.

Parameters

self	The CommandBuffer.

Returns

True on success, false on error.

generateMipmaps()

void generateMipmaps	(	const CommandBuffer *	self,
		SDL_GPUTexture *	texture
	)

Records a mipmap generation command for the given texture.

initWithCommandBuffer() [1/2]

CommandBuffer * initWithCommandBuffer	(	CommandBuffer *	self,
		const RenderDevice *	device,
		*SDL_GPUCommandBuffer *	commands
	)

Initializes this CommandBuffer wrapping the given SDL command buffer.

Parameters

self	The CommandBuffer.
device	The RenderDevice that created this CommandBuffer.
commands	The SDL command buffer to wrap. Must not be NULL.

Returns

The initialized CommandBuffer, or NULL on failure.

initWithCommandBuffer() [2/2]

CommandBuffer * initWithCommandBuffer	(	CommandBuffer *	self,
		const RenderDevice *	device,
		SDL_GPUCommandBuffer *	commands
	)

insertDebugLabel()

void insertDebugLabel	(	const CommandBuffer *	self,
		const char *	text
	)

Inserts an arbitrary debug label into the command stream.

popDebugGroup()

void popDebugGroup

(

const CommandBuffer *

self

)

Ends the innermost active debug group.

pushComputeUniformData()

void pushComputeUniformData	(	const CommandBuffer *	self,
		Uint32	slot,
		const void *	data,
		Uint32	length
	)

Pushes uniform data for the current compute shader.

pushDebugGroup()

void pushDebugGroup	(	const CommandBuffer *	self,
		const char *	name
	)

Begins a named debug group in the command stream.

pushFragmentUniformData()

void pushFragmentUniformData	(	const CommandBuffer *	self,
		Uint32	slot,
		const void *	data,
		Uint32	length
	)

Pushes uniform data for the current fragment shader.

pushUniformData()

void pushUniformData	(	const CommandBuffer *	self,
		Uint32	slot,
		const void *	data,
		Uint32	length
	)

Pushes the same uniform data to slot for both the current vertex and fragment shaders.

Convenience for the common case of a uniform block (e.g. globals, a material block) declared at the same binding in both stages. Equivalent to calling pushVertexUniformData and pushFragmentUniformData with the same arguments.

Parameters

self	The CommandBuffer.
slot	The uniform buffer slot, matching both shaders' declarations.
data	The uniform data to push.
length	The length of data in bytes.

pushVertexUniformData()

void pushVertexUniformData	(	const CommandBuffer *	self,
		Uint32	slot,
		const void *	data,
		Uint32	length
	)

Pushes uniform data for the current vertex shader.

submit()

bool submit

(

CommandBuffer *

self

)

Submits this command buffer to the GPU for execution.

All passes must be released before submitting. The CommandBuffer must be released after submission.

Parameters

self	The CommandBuffer.

Returns

True on success, false on error.

submitAndFence()

Fence * submitAndFence

(

CommandBuffer *

self

)

Submits this command buffer and returns a Fence for GPU completion.

The returned Fence is retained; release it when no longer needed.

Parameters

self	The CommandBuffer.

Returns

A new, retained Fence, or NULL on error.

waitAndAcquireSwapchainTexture()

bool waitAndAcquireSwapchainTexture	(	const CommandBuffer *	self,
		SwapchainTexture *	swapchain
	)

Blocks until a swapchain texture is available, then acquires it.

Prefer acquireSwapchainTexture unless you must guarantee a texture this frame (e.g. during resize). Blocking bounds how many frames may be in flight, but a drawable is still not guaranteed: as with acquireSwapchainTexture, an unavailable swapchain is reported as false with swapchain zeroed.

Call this as late in the frame as possible. The acquired drawable is held until this CommandBuffer is submitted, and holding it across a frame's CPU work starves the drawable pool.

Parameters

self	The CommandBuffer.
swapchain	Output structure populated with the texture and dimensions, or zeroed.

Returns

True on success, false when the swapchain is unavailable this frame.

Field Documentation

commands

SDL_GPUCommandBuffer* CommandBuffer::commands

The underlying SDL command buffer.

data

ident CommandBuffer::data

User data.

device

RenderDevice* CommandBuffer::device

The RenderDevice that this CommandBuffer belongs to.

interface

CommandBufferInterface* CommandBuffer::interface

protected

The interface.

object

Object CommandBuffer::object

The superclass.

---

The documentation for this struct was generated from the following files:

• Sources/ObjectivelyGPU/CommandBuffer.h
• Sources/ObjectivelyGPU/CommandBuffer.c