ezGALCommandEncoder Class Reference

Public Member Functions
	ezGALCommandEncoder (ezGALDevice &ref_device, ezGALCommandEncoderCommonPlatformInterface &ref_commonImpl)
void	SetBindGroup (ezUInt32 uiBindGroup, const ezGALBindGroupCreationDescription &bindGroup)
	Sets a bind group to the given bind group index. Preferably, bindGroup should be created via ezBindGroupBuilder::CreateBindGroup.
void	SetBindGroup (ezUInt32 uiBindGroup, ezGALBindGroupHandle hBindGroup)
	Sets a bind group resource to the given bind group index. As there are two functions to set bind groups (this one and the overload for transient bind groups) the last call takes precedence if both functions are called for the same index. Resources in hBindGroup must be in the states required by their shader binding when the bind group is used by a draw or dispatch call.
void	SetPushConstants (ezArrayPtr< const ezUInt8 > data)
ezGALTimestampHandle	InsertTimestamp ()
ezGALOcclusionHandle	BeginOcclusionQuery (ezEnum< ezGALQueryType > type)
	Starts an occlusion query. This function must be called within a render scope and EndOcclusionQuery must be called within the same scope. Only one occlusion query can be active at any given time.
void	EndOcclusionQuery (ezGALOcclusionHandle hOcclusion)
	Ends an occlusion query. The given handle must afterwards be passed into the ezGALDevice::GetOcclusionQueryResult function, which needs to be repeated every frame until results are ready.
ezGALFenceHandle	InsertFence ()
void	CopyBuffer (ezGALBufferHandle hDest, ezGALBufferHandle hSource)
	hDest must be in ezGALResourceState::CopyDestination. hSource must be in ezGALResourceState::CopySource.
void	CopyBufferRegion (ezGALBufferHandle hDest, ezUInt32 uiDestOffset, ezGALBufferHandle hSource, ezUInt32 uiSourceOffset, ezUInt32 uiByteCount)
	hDest must be in ezGALResourceState::CopyDestination. hSource must be in ezGALResourceState::CopySource.
void	UpdateBuffer (ezGALBufferHandle hDest, ezUInt32 uiDestOffset, ezArrayPtr< const ezUInt8 > sourceData, ezGALUpdateMode::Enum updateMode=ezGALUpdateMode::TransientConstantBuffer)
	Updates a buffer region. TransientConstantBuffer is only allowed on transient constant buffers. AheadOfTime means the update happens before the encoder commands are executed. No state prerequisites are required.
void	CopyTexture (ezGALTextureHandle hDest, ezGALTextureHandle hSource)
	hDest must be in ezGALResourceState::CopyDestination. hSource must be in ezGALResourceState::CopySource.
void	CopyTextureRegion (ezGALTextureHandle hDest, const ezGALTextureSubresource &destinationSubResource, const ezVec3U32 &vDestinationPoint, ezGALTextureHandle hSource, const ezGALTextureSubresource &sourceSubResource, const ezBoundingBoxu32 &box)
	destinationSubResource of hDest must be in ezGALResourceState::CopyDestination. sourceSubResource of hSource must be in ezGALResourceState::CopySource.
void	UpdateTexture (ezGALTextureHandle hDest, const ezGALTextureSubresource &destinationSubResource, const ezBoundingBoxu32 &destinationBox, const ezGALSystemMemoryDescription &sourceData)
	Updates a texture region. Similar to UpdateBuffer with AheadOfTime. No state prerequisites are required.
void	ResolveTexture (ezGALTextureHandle hDest, const ezGALTextureSubresource &destinationSubResource, ezGALTextureHandle hSource, const ezGALTextureSubresource &sourceSubResource)
	destinationSubResource of hDest must be in ezGALResourceState::ResolveDestination. sourceSubResource of hSource must be in ezGALResourceState::ResolveSource.
void	ReadbackTexture (ezGALReadbackTextureHandle hDestination, ezGALTextureHandle hSource)
	hSource must be in ezGALResourceState::CopySource.
void	ReadbackBuffer (ezGALReadbackBufferHandle hDestination, ezGALBufferHandle hSource)
	hSource must be in ezGALResourceState::CopySource.
void	TextureBarrier (ezArrayPtr< const ezGALTextureBarrier > barriers)
void	TextureBarrier (ezGALTextureHandle hTexture, ezGALTextureRange range={}, ezBitflags< ezGALResourceState > stateBefore=ezGALResourceState::Default, ezBitflags< ezGALResourceState > stateAfter=ezGALResourceState::Default, ezBitflags< ezGALShaderStageFlags > stagesBefore=ezGALShaderStageFlags::Auto, ezBitflags< ezGALShaderStageFlags > stagesAfter=ezGALShaderStageFlags::Auto)
void	BufferBarrier (ezArrayPtr< const ezGALBufferBarrier > barriers)
void	BufferBarrier (ezGALBufferHandle hBuffer, ezBitflags< ezGALResourceState > stateBefore=ezGALResourceState::Default, ezBitflags< ezGALResourceState > stateAfter=ezGALResourceState::Default, ezBitflags< ezGALShaderStageFlags > stagesBefore=ezGALShaderStageFlags::Auto, ezBitflags< ezGALShaderStageFlags > stagesAfter=ezGALShaderStageFlags::Auto)
void	Flush ()
	Submits all pending work to the GPU. Call this if you want to wait for a fence or some other kind of GPU synchronization to take place to ensure the work is actually submitted to the GPU.
void	PushMarker (const char *szMarker)
void	PopMarker ()
void	InsertEventMarker (const char *szMarker)
void	BeginCompute (const char *szName="")
void	EndCompute ()
ezResult	Dispatch (ezUInt32 uiThreadGroupCountX, ezUInt32 uiThreadGroupCountY, ezUInt32 uiThreadGroupCountZ)
ezResult	DispatchIndirect (ezGALBufferHandle hIndirectArgumentBuffer, ezUInt32 uiArgumentOffsetInBytes)
	hIndirectArgumentBuffer must be in ezGALResourceState::DrawIndirect.
void	BeginRendering (const ezGALRenderingSetup &renderingSetup, const char *szName="")
	Color targets in renderingSetup must be in ezGALResourceState::RenderTarget. The depth target must be in ezGALResourceState::DepthStencilRead or ezGALResourceState::DepthStencilWrite depending on the render target view.
void	EndRendering ()
bool	IsInRenderingScope () const
void	Clear (const ezColor &clearColor, ezUInt32 uiRenderTargetClearMask=0xFFFFFFFFu, bool bClearDepth=true, bool bClearStencil=true, float fDepthClear=1.0f, ezUInt8 uiStencilClear=0x0u)
	Clears active rendertargets.
ezResult	Draw (ezUInt32 uiVertexCount, ezUInt32 uiStartVertex)
	Bound vertex buffers must be in ezGALResourceState::VertexBuffer.
ezResult	DrawIndexed (ezUInt32 uiIndexCount, ezUInt32 uiStartIndex)
	Bound vertex buffers must be in ezGALResourceState::VertexBuffer. The bound index buffer must be in ezGALResourceState::IndexBuffer.
ezResult	DrawIndexedInstanced (ezUInt32 uiIndexCountPerInstance, ezUInt32 uiInstanceCount, ezUInt32 uiStartIndex)
	Bound vertex buffers must be in ezGALResourceState::VertexBuffer. The bound index buffer must be in ezGALResourceState::IndexBuffer.
ezResult	DrawIndexedInstancedIndirect (ezGALBufferHandle hIndirectArgumentBuffer, ezUInt32 uiArgumentOffsetInBytes)
	Bound vertex buffers must be in ezGALResourceState::VertexBuffer. The bound index buffer must be in ezGALResourceState::IndexBuffer. hIndirectArgumentBuffer must be in ezGALResourceState::DrawIndirect.
ezResult	DrawInstanced (ezUInt32 uiVertexCountPerInstance, ezUInt32 uiInstanceCount, ezUInt32 uiStartVertex)
	Bound vertex buffers must be in ezGALResourceState::VertexBuffer.
ezResult	DrawInstancedIndirect (ezGALBufferHandle hIndirectArgumentBuffer, ezUInt32 uiArgumentOffsetInBytes)
	Bound vertex buffers must be in ezGALResourceState::VertexBuffer. hIndirectArgumentBuffer must be in ezGALResourceState::DrawIndirect.
void	SetIndexBuffer (ezGALBufferHandle hIndexBuffer)
	hIndexBuffer must be invalidated or in ezGALResourceState::IndexBuffer.
void	SetVertexBuffer (ezUInt32 uiSlot, ezGALBufferHandle hVertexBuffer, ezUInt32 uiOffset=0)
	hVertexBuffer must be invalidated or in ezGALResourceState::VertexBuffer.
void	SetGraphicsPipeline (ezGALGraphicsPipelineHandle hGraphicsPipeline)
void	SetComputePipeline (ezGALComputePipelineHandle hComputePipeline)
void	SetViewport (const ezRectFloat &rect, float fMinDepth=0.0f, float fMaxDepth=1.0f)
void	SetScissorRect (const ezRectU32 &rect)
void	SetStencilReference (ezUInt8 uiStencilRefValue)
EZ_ALWAYS_INLINE ezGALDevice &	GetDevice ()
void	InvalidateState ()
const ezGALCommandEncoderStats &	GetStats () const
void	ResetStats ()

Static Public Attributes
static ezEvent< const ezTextureValidationError & >	s_TextureBarrierValidationFailed
	Fired when a texture barrier validation error is detected.
static ezEvent< const ezBufferValidationError & >	s_BufferBarrierValidationFailed
	Fired when a buffer barrier validation error is detected.

Protected Member Functions
void	GALStaticDeviceEventHandler (const ezGALDeviceEvent &e)
void	AssertRenderingThread ()
void	AssertOutsideRenderingScope ()

Friends
class	ezGALDevice
class	ezMemoryUtils

Member Function Documentation

BeginOcclusionQuery()

ezGALOcclusionHandle ezGALCommandEncoder::BeginOcclusionQuery

(

ezEnum< ezGALQueryType >

type

)

Starts an occlusion query. This function must be called within a render scope and EndOcclusionQuery must be called within the same scope. Only one occlusion query can be active at any given time.

Parameters

type	The type of the occlusion query.

Returns

A handle to be passed into EndOcclusionQuery.

See also

EndOcclusionQuery

BufferBarrier() [1/2]

void ezGALCommandEncoder::BufferBarrier

(

ezArrayPtr< const ezGALBufferBarrier >

barriers

)

Inserts resource barriers for buffer state transitions.

All barriers in a single call are batched into one API-level barrier command. Must be called outside of rendering and compute scopes. Each buffer must currently be in the barrier's m_StateBefore state.

BufferBarrier() [2/2]

void ezGALCommandEncoder::BufferBarrier	(	ezGALBufferHandle	hBuffer,
		ezBitflags< ezGALResourceState >	stateBefore = ezGALResourceState::Default,
		ezBitflags< ezGALResourceState >	stateAfter = ezGALResourceState::Default,
		ezBitflags< ezGALShaderStageFlags >	stagesBefore = ezGALShaderStageFlags::Auto,
		ezBitflags< ezGALShaderStageFlags >	stagesAfter = ezGALShaderStageFlags::Auto
	)

Inserts a single buffer barrier for a state transition. Must be called outside of rendering and compute scopes. hBuffer must currently be in stateBefore.

Clear()

void ezGALCommandEncoder::Clear	(	const ezColor &	clearColor,
		ezUInt32	uiRenderTargetClearMask = 0xFFFFFFFFu,
		bool	bClearDepth = true,
		bool	bClearStencil = true,
		float	fDepthClear = 1.0f,
		ezUInt8	uiStencilClear = 0x0u
	)

Clears active rendertargets.

Parameters

uiRenderTargetClearMask

Each bit represents a bound color target. If all bits are set, all bound color targets will be cleared.

EndOcclusionQuery()

void ezGALCommandEncoder::EndOcclusionQuery

(

ezGALOcclusionHandle

hOcclusion

)

Ends an occlusion query. The given handle must afterwards be passed into the ezGALDevice::GetOcclusionQueryResult function, which needs to be repeated every frame until results are ready.

Parameters

hOcclusion

Value returned by the previous call to BeginOcclusionQuery.

See also

ezGALDevice::GetOcclusionQueryResult

InsertFence()

ezGALFenceHandle ezGALCommandEncoder::InsertFence

(

)

Inserts a fence. You need to flush commands to the GPU in order to be able to wait for a fence by either ending a frame or calling ezCommandEncoder::Flush explicitly.

Returns

A handle to be passed into ezGALDevice::GetFenceResult.

See also

ezGALDevice::GetFenceResult

InsertTimestamp()

ezGALTimestampHandle ezGALCommandEncoder::InsertTimestamp

(

)

Inserts a timestamp.

Returns

A handle to be passed into ezGALDevice::GetTimestampResult.

SetBindGroup() [1/2]

void ezGALCommandEncoder::SetBindGroup	(	ezUInt32	uiBindGroup,
		const ezGALBindGroupCreationDescription &	bindGroup
	)

Sets a bind group to the given bind group index. Preferably, bindGroup should be created via ezBindGroupBuilder::CreateBindGroup.

This function binds a collection of resources (buffers, textures, samplers) to a specific bind group index. In debug builds, it performs extensive validation of each ezGALBindGroupItem against the layout's ezShaderResourceBinding to ensure:

General Validation:

• Bind group layout matches the number of provided items
• All resource handles are valid (non-null)

Buffer Validation:

• Buffer handles are valid and match expected binding types
• Constant buffers: No texel format override, zero offset, full buffer size
• Structured/Texel/ByteAddress buffers: Proper usage flags, correct element alignment
• Buffer ranges: Offset/size alignment with element boundaries, bounds checking
• Access permissions: SRV/UAV flags match buffer usage flags

Texture Validation:

• Texture handles are valid with proper view format compatibility
• Array slice counts match binding requirements (e.g. 1 for non-arrays, multiple of 6 for cubes)
• MSAA sample counts match between texture and binding
• Access permissions: SRV/UAV flags match texture capabilities
• Texture ranges: Mip levels and array slices within bounds
• Make sure no proxy texture is present

Resource State Validation:

• Constant buffer bindings must be in ezGALResourceState::ConstantBuffer
• SRV texture and buffer bindings must be in ezGALResourceState::ShaderResource, except depth textures which must be in ezGALResourceState::DepthStencilRead
• UAV texture and buffer bindings must be in ezGALResourceState::UnorderedAccess

Parameters

uiBindGroup	The bind group set index to set
bindGroup	Description containing the layout and resource items to bind

SetBindGroup() [2/2]

void ezGALCommandEncoder::SetBindGroup	(	ezUInt32	uiBindGroup,
		ezGALBindGroupHandle	hBindGroup
	)

Sets a bind group resource to the given bind group index. As there are two functions to set bind groups (this one and the overload for transient bind groups) the last call takes precedence if both functions are called for the same index. Resources in hBindGroup must be in the states required by their shader binding when the bind group is used by a draw or dispatch call.

Parameters

uiBindGroup	The bind group set index to set
hBindGroup	Handle to the bind group that is to be used.

TextureBarrier() [1/2]

void ezGALCommandEncoder::TextureBarrier

(

ezArrayPtr< const ezGALTextureBarrier >

barriers

)

Inserts resource barriers for texture state transitions.

All barriers in a single call are batched into one API-level barrier command. Must be called outside of rendering and compute scopes. Each texture must currently be in the barrier's m_StateBefore state.

TextureBarrier() [2/2]

void ezGALCommandEncoder::TextureBarrier	(	ezGALTextureHandle	hTexture,
		ezGALTextureRange	range = {},
		ezBitflags< ezGALResourceState >	stateBefore = ezGALResourceState::Default,
		ezBitflags< ezGALResourceState >	stateAfter = ezGALResourceState::Default,
		ezBitflags< ezGALShaderStageFlags >	stagesBefore = ezGALShaderStageFlags::Auto,
		ezBitflags< ezGALShaderStageFlags >	stagesAfter = ezGALShaderStageFlags::Auto
	)

Inserts a single texture barrier for a layout/state transition. Must be called outside of rendering and compute scopes. hTexture must currently be in stateBefore.

---

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

• /home/runner/work/ezEngine/ezEngine/Code/Engine/RendererFoundation/CommandEncoder/CommandEncoder.h
• /home/runner/work/ezEngine/ezEngine/Code/Engine/RendererFoundation/CommandEncoder/Implementation/CommandEncoder.cpp