donner::gpu::CommandEncoder Class Reference

Records and validates GPU commands for one command buffer. More...

#include "donner/gpu/CommandEncoder.h"

Public Member Functions
	CommandEncoder (const CommandEncoder &)=delete
CommandEncoder &	operator= (const CommandEncoder &)=delete
	CommandEncoder (CommandEncoder &&)=delete
CommandEncoder &	operator= (CommandEncoder &&)=delete
	~CommandEncoder ()=default
	Destructor. Discards recorded commands unless finish transferred them.
Result< RenderPassEncoder * >	beginRenderPass (const RenderPassDescriptor &descriptor)
	Begins a render pass and returns its pass encoder.
Result< ComputePassEncoder * >	beginComputePass (const ComputePassDescriptor &descriptor)
	Begins a compute pass and returns its pass encoder.
Status	copyTextureToBuffer (const TexelCopyTextureInfo &source, const Buffer &destination, const TexelCopyBufferLayout &destinationLayout, const Extent2d &copySize)
	Records a texture-to-buffer copy (readback staging).
Status	copyTextureToTexture (const Texture &source, const Texture &destination, const Extent2d &copySize, const Origin2d &sourceOrigin={}, const Origin2d &destinationOrigin={})
	Records a texture-to-texture copy of a copySize rectangle, read from sourceOrigin and written at destinationOrigin.
Result< CommandBuffer >	finish ()
	Finishes recording and registers the command buffer with the device.

Friends
class	Device
class	RenderPassEncoder
class	ComputePassEncoder

Detailed Description

Records and validates GPU commands for one command buffer.

The encoder is a fail-closed state machine: every operation validates handle liveness, device identity, usage flags, bounds, and pass state before recording. The first error latches and poisons the encoder - every subsequent operation, including finish, returns that first error - so a failure cannot be silently skipped and the root cause is always the reported error. Obtain encoders via Device::createCommandEncoder; the encoder must not outlive its device.

Commands record full (slot, generation) resource identities, and Device::submit re-validates every one, so destroying a resource between recording and submission fails closed at submit.

Member Function Documentation

beginComputePass()

Result< ComputePassEncoder * > donner::gpu::CommandEncoder::beginComputePass

(

const ComputePassDescriptor &

descriptor

)

Begins a compute pass and returns its pass encoder.

Fails with GpuErrorType::InvalidState if a pass is already active.

The returned pointer is owned by this encoder and remains valid until the encoder is destroyed.

Parameters

descriptor

Validated compute pass descriptor.

beginRenderPass()

Result< RenderPassEncoder * > donner::gpu::CommandEncoder::beginRenderPass

(

const RenderPassDescriptor &

descriptor

)

Begins a render pass and returns its pass encoder.

Fails with GpuErrorType::InvalidState if a pass is already active. Attachment views must be live, share one extent, and their textures need TextureUsage::RenderAttachment.

The returned pointer is owned by this encoder and remains valid until the encoder is destroyed.

Parameters

descriptor

Validated render pass descriptor.

copyTextureToBuffer()

Status donner::gpu::CommandEncoder::copyTextureToBuffer	(	const TexelCopyTextureInfo &	source,
		const Buffer &	destination,
		const TexelCopyBufferLayout &	destinationLayout,
		const Extent2d &	copySize )

Records a texture-to-buffer copy (readback staging).

Not allowed inside a render pass. destinationLayout must be 256-aligned and cover copySize, copySize must fit in the source texture, and the described rows must fit in destination (checked arithmetic).

Parameters

source	Source texture; needs TextureUsage::CopySrc.
destination	Destination buffer; needs BufferUsage::CopyDst.
destinationLayout	Row layout in the destination buffer.
copySize	Copy extent in texels.

copyTextureToTexture()

Status donner::gpu::CommandEncoder::copyTextureToTexture	(	const Texture &	source,
		const Texture &	destination,
		const Extent2d &	copySize,
		const Origin2d &	sourceOrigin = {},
		const Origin2d &	destinationOrigin = {} )

Records a texture-to-texture copy of a copySize rectangle, read from sourceOrigin and written at destinationOrigin.

Both origins default to texel (0, 0), which is the whole-rect copy convention this operation had before sub-rectangle copies existed, so an existing call keeps its meaning.

Not allowed inside a pass. Both textures must be live handles of this device and share one TextureFormat, source needs TextureUsage::CopySrc, destination needs TextureUsage::CopyDst, copySize must be nonzero, and each origin plus copySize must fit inside its texture's extent.

Parameters

source	Source texture; needs TextureUsage::CopySrc.
destination	Destination texture; needs TextureUsage::CopyDst.
copySize	Copy extent in texels.
sourceOrigin	Top-left texel of the source rectangle.
destinationOrigin	Top-left texel of the destination rectangle.

finish()

Result< CommandBuffer > donner::gpu::CommandEncoder::finish

(

)

Finishes recording and registers the command buffer with the device.

Fails with the first recorded error if any operation failed, or with GpuErrorType::InvalidState if a pass is still active or the encoder already finished.

---

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

• donner/gpu/CommandEncoder.h