Use the command recorder to generate Kanzi graphics commands. More...

#include <kanzi/core.ui/graphics/command_recorder.hpp>

Classes
struct	BufferStats
	The statistics for a staging buffer. More...

Public Member Functions
void	addUniformBufferOffset (uint8_t setIndex, uint8_t bufferIndex, uint32_t offset)
	Adds a uniform buffer binding.

pair< gfx::BufferHandleGuard, uint32_t >	allocateStagingMemory (gfx::BufferUsageFlag usage, ConstByteSpan data)
	Allocates a region in staging memory.

void	beginFrame ()
	Begins a new frame and blocks if we have enough frames in flight already.

void	bindConstantData (ConstByteSpan data)
	Binds a constant buffer.

void	bindIndexBuffer (gfx::BufferHandleGuard indexBuffer, gfx::IndexBufferType indexType, uint32_t indexOffset)
	Binds the Kanzi graphics index buffer for use with all draw operations until the next popFramebuffer or bindRenderPipeline.

void	bindLineWidth (float lineWidth)
	Binds a line width.

void	bindRenderPipeline (gfx::RenderPipelineHandleGuard pipeline)
	Binds the Kanzi render pipeline object for use with all draw operations until the next popFramebuffer.

void	bindResourceSet (uint32_t slot, gfx::RenderResourceSetHandleGuard resourceSet)
	Binds the Kanzi graphics render resource set.

void	bindVertexBuffer (uint32_t slot, gfx::VertexBufferBinding binding)
	Binds the Kanzi graphics vertex buffer.

void	clearFramebuffer (span< const optional< ColorRGBA > > colors, optional< float > depth=nullopt, optional< unsigned int > stencil=nullopt)
	Clears the current framebuffer.

void	commandDraw (uint32_t elementCount, uint32_t indexOffset=0, uint32_t instanceCount=1, uint32_t instanceOffset=0, uint32_t vertexOffset=0)
	Generates a draw command.

void	commandIndirectDraw (gfx::BufferHandleGuard buffer, uint32_t drawCount, uint32_t drawStride, uint32_t offset=0)
	Generates an indirect draw command.

	CommandRecorder ()
	Constructor.

	CommandRecorder (CommandRecorder &&)=delete

	CommandRecorder (const CommandRecorder &)=delete

void	disableStatistics ()
	Disabled statistics tracking. Intended to be used by the RendererStatisticsScope class.

void	enableStatistics ()
	Enables statistics tracking. Intended to be used by the RendererStatisticsScope class.

gfx::CommandBufferHandleGuard	endFrame ()
	Ends the current frame and returns a Kanzi graphics command buffer that represents all recorded commands.

gfx::CommandBufferHandleGuard	flush ()
	Flushes the currently recorded commands and returns a Kanzi graphics command buffer that represents all recorded commands.

void	generateMipMaps (gfx::ImageHandleGuard image)
	Adds a generate mipmaps command to the current staging command buffer.

uint32_t	getCommandPageSize () const
	Gets the current size of each command buffer page.

size_t	getLatchGeneration () const
	Gets the current latch generation.

RenderPassArchetype *	getRenderPassArchetype ()
	Gets the current render pass archetype for the active framebuffer.

vector< BufferStats >	getStagingBufferStats ()
	Gets a list of statistics about staging buffers that are being used.

uint16_t	getUniformGeneration () const
	Gets the current uniform generation.

bool	hasFramebuffer () const
	Gets if the Command Recorder has an active framebuffer on the stack.

void	invalidate ()
	Invalidates all partially recorded command buffers and releases all Kanzi graphics handles.

void	invalidateFramebuffer ()
	Indicates that the existing contents of the framebuffer are not required to be loaded from memory.

void	latch ()
	Finalizes all contexts and moves all recorded commands to the list of latched command buffers.

CommandRecorder &	operator= (CommandRecorder &&)=delete

CommandRecorder &	operator= (const CommandRecorder &)=delete

void	popFramebuffer ()
	Pops the current framebuffer stack.

void	present (gfx::FrameBufferHandleGuard framebuffer)
	Adds a Present command to the current staging command buffer.

void	pushFramebuffer (const Framebuffer *framebuffer, optional< Rectangle< int > > viewport, optional< Rectangle< int > > scissor)
	Pushes a new frame to the framebuffer stack.

void	queueReleaseTemporaryCompositionTarget (TextureSharedPtr texture)
	Queues a composition target texture for release.

void	resolveMultisample (gfx::ImageHandleGuard multisampleImage, gfx::ImageHandleGuard resolveImage, gfx::ImageSubresource resolveImageSubresource={})
	Adds a resolve Multisample command to the current staging command buffer.

void	setCommandPageSize (uint32_t commandPageSize)
	Sets the size of the command buffer page.

void	setCompositionManager (CompositionManager *compositionManager)
	Sets the CompositionManager associated with the command recorder.

void	setUniformBufferSize (uint32_t uniformBufferSize)
	Sets the uniform buffer size.

void	updateBuffer (gfx::BufferHandleGuard destination, uint32_t offset, ConstByteSpan data)
	Updates the contents of a buffer using the current staging command buffer.

void	updateImage (gfx::ImageHandleGuard image, gfx::Format format, gfx::box3u32 region, gfx::ImageSubresource subResource, ConstByteSpan data)
	Updates the contents of an image using the current staging command buffer.

StagingBufferUpload	uploadUniformBuffer (ByteSpan data)
	Uploads uniform buffer data to the managed uniform buffer.

Static Public Attributes
static constexpr uint32_t	DefaultCommandPageSize
	The default size of a command page.

Detailed Description

Use the command recorder to generate Kanzi graphics commands.

The Command Recorder:

Reorders commands for different render targets to optimize performance.

Kanzi runs staging commands always before the currently bound render target. Kanzi runs render targets in the order that they are popped from the framebuffer stack.
Manages a staging buffer that you can use to store image or generic data in GPU-visible memory.

Kanzi generates the corresponding staging commands to copy the staging memory to the destination resource.
Manages a uniform buffer that Kanzi uses to store uniform data for each frame.

Upload each uniform buffer every frame. When using a render pipeline, you can use the offset.

Since: Kanzi 4.0.0

Constructor & Destructor Documentation

◆ CommandRecorder() [1/3]

kanzi::CommandRecorder::CommandRecorder ( )

explicit

Constructor.

◆ CommandRecorder() [2/3]

kanzi::CommandRecorder::CommandRecorder ( const CommandRecorder & )

delete

◆ CommandRecorder() [3/3]

kanzi::CommandRecorder::CommandRecorder ( CommandRecorder && )

delete

Member Function Documentation

◆ operator=() [1/2]

CommandRecorder & kanzi::CommandRecorder::operator= ( const CommandRecorder & )

delete

◆ operator=() [2/2]

CommandRecorder & kanzi::CommandRecorder::operator= ( CommandRecorder && )

delete

◆ invalidate()

void kanzi::CommandRecorder::invalidate ( )

Invalidates all partially recorded command buffers and releases all Kanzi graphics handles.

◆ getUniformGeneration()

uint16_t kanzi::CommandRecorder::getUniformGeneration ( ) const

inline

Gets the current uniform generation.

Kanzi increments the generation every frame. When a previous uniform upload has a different generation, reupload the data.

Returns: The uniform generation.

◆ uploadUniformBuffer()

StagingBufferUpload kanzi::CommandRecorder::uploadUniformBuffer ( ByteSpan data )

Uploads uniform buffer data to the managed uniform buffer.

Returns: Uniform upload information.

◆ getCommandPageSize()

uint32_t kanzi::CommandRecorder::getCommandPageSize ( ) const

inline

Gets the current size of each command buffer page.

Returns: The size of the command buffer page in bytes.

◆ getLatchGeneration()

size_t kanzi::CommandRecorder::getLatchGeneration ( ) const

inline

Gets the current latch generation.

Returns: The current latch generation.

◆ setCommandPageSize()

void kanzi::CommandRecorder::setCommandPageSize ( uint32_t commandPageSize )

inline

Sets the size of the command buffer page.

This affects only newly created buffers. Larger buffers allow more complex rendering without needing to split a Kanzi graphics render pass, which can be inefficient. Smaller buffers reduce memory waste when not many commands are generated. The minimum supported size is 512 bytes.

Parameters

commandPageSize The size in bytes.

◆ setUniformBufferSize()

void kanzi::CommandRecorder::setUniformBufferSize ( uint32_t uniformBufferSize )

Sets the uniform buffer size.

The size must be large enough to store three frames worth of uniform data. If the buffer is too small, Kanzi creates a large enough buffer.

Parameters

uniformBufferSize The uniform buffer size in bytes.

◆ beginFrame()

void kanzi::CommandRecorder::beginFrame ( )

Begins a new frame and blocks if we have enough frames in flight already.

◆ endFrame()

gfx::CommandBufferHandleGuard kanzi::CommandRecorder::endFrame ( )

Ends the current frame and returns a Kanzi graphics command buffer that represents all recorded commands.

This also increments the uniform generation.

To call this function, the framebuffer stack must be empty.

Returns: The Kanzi graphics command buffer handle.

◆ flush()

gfx::CommandBufferHandleGuard kanzi::CommandRecorder::flush ( )

Flushes the currently recorded commands and returns a Kanzi graphics command buffer that represents all recorded commands.

You can call this function at any time. It cuts ongoing render targets in half and therefore results in less efficient commands.

This function is primarily provided for testing purposes.

Returns: The Kanzi graphics command buffer handle.

◆ latch()

void kanzi::CommandRecorder::latch ( )

Finalizes all contexts and moves all recorded commands to the list of latched command buffers.

This is used to ensure ordering of all commands before and after the latch. Usage in the middle of a frame may have significant performance impact.

◆ present()

void kanzi::CommandRecorder::present ( gfx::FrameBufferHandleGuard framebuffer )

Adds a Present command to the current staging command buffer.

Parameters

framebuffer The framebuffer to present. Must be a surface-type framebuffer.

◆ generateMipMaps()

void kanzi::CommandRecorder::generateMipMaps ( gfx::ImageHandleGuard image )

Adds a generate mipmaps command to the current staging command buffer.

Parameters

image The image handle.

◆ resolveMultisample()

void kanzi::CommandRecorder::resolveMultisample	(	gfx::ImageHandleGuard	multisampleImage,
		gfx::ImageHandleGuard	resolveImage,
		gfx::ImageSubresource	resolveImageSubresource = {} )

Adds a resolve Multisample command to the current staging command buffer.

Parameters

multisampleImage	The multisampled source image handle.
resolveImage	The destination resolve image handle.
resolveImageSubresource	The subresource of the destination resolve image.

◆ updateImage()

void kanzi::CommandRecorder::updateImage	(	gfx::ImageHandleGuard	image,
		gfx::Format	format,
		gfx::box3u32	region,
		gfx::ImageSubresource	subResource,
		ConstByteSpan	data )

Updates the contents of an image using the current staging command buffer.

Parameters

image	The destination image.
format	The image format.
region	The destination region to update.
subResource	The destination sub-resource to update.
data	The source bytes for the update.

◆ updateBuffer()

void kanzi::CommandRecorder::updateBuffer	(	gfx::BufferHandleGuard	destination,
		uint32_t	offset,
		ConstByteSpan	data )

Updates the contents of a buffer using the current staging command buffer.

Parameters

destination	The destination buffer.
offset	The offset into the destination buffer in bytes.
data	The source bytes for the update.

◆ allocateStagingMemory()

pair< gfx::BufferHandleGuard, uint32_t > kanzi::CommandRecorder::allocateStagingMemory	(	gfx::BufferUsageFlag	usage,
		ConstByteSpan	data )

Allocates a region in staging memory.

Allows direct usage of the staging buffer by rendering commands.

Parameters

usage	The usage flags needed by the staging buffer.
data	The source bytes for the update.

Returns: A pair that contains the staging buffer handle, and the offset within the staging buffer in bytes.

◆ pushFramebuffer()

void kanzi::CommandRecorder::pushFramebuffer	(	const Framebuffer *	framebuffer,
		optional< Rectangle< int > >	viewport,
		optional< Rectangle< int > >	scissor )

Pushes a new frame to the framebuffer stack.

Each frame represents a new binding scope. Each pushFramebuffer must have a corresponding call to popFramebuffer.

Parameters

framebuffer	The framebuffer pointer. If set to nullptr, the framebuffer of the previous top of the stack is used.
viewport	The optional viewport. If not provided, the entire framebuffer used.
scissor	The optional scissor. If not provided, the entire framebuffer used.

◆ popFramebuffer()

void kanzi::CommandRecorder::popFramebuffer ( )

Pops the current framebuffer stack.

◆ getRenderPassArchetype()

RenderPassArchetype * kanzi::CommandRecorder::getRenderPassArchetype ( )

Gets the current render pass archetype for the active framebuffer.

This archetype is used to get a compatible Kanzi graphics render pass.

◆ hasFramebuffer()

bool kanzi::CommandRecorder::hasFramebuffer ( ) const

Gets if the Command Recorder has an active framebuffer on the stack.

Returns: If a framebuffer is active, true, otherwise false.

◆ clearFramebuffer()

void kanzi::CommandRecorder::clearFramebuffer	(	span< const optional< ColorRGBA > >	colors,
		optional< float >	depth = nullopt,
		optional< unsigned int >	stencil = nullopt )

Clears the current framebuffer.

Parameters

colors	The span of colors to use to clear each color attachment.
depth	The optional depth clear value. If the value is not provided, the depth is not cleared.
stencil	The optional stencil clear value. If the value is not provided, the stencil is not cleared.

◆ invalidateFramebuffer()

void kanzi::CommandRecorder::invalidateFramebuffer ( )

Indicates that the existing contents of the framebuffer are not required to be loaded from memory.

This must be the first recorder operation performed after a pushFrameBuffer.

◆ bindRenderPipeline()

void kanzi::CommandRecorder::bindRenderPipeline ( gfx::RenderPipelineHandleGuard pipeline )

Binds the Kanzi render pipeline object for use with all draw operations until the next popFramebuffer.

Parameters

pipeline The render pipeline handle.

◆ bindIndexBuffer()

void kanzi::CommandRecorder::bindIndexBuffer	(	gfx::BufferHandleGuard	indexBuffer,
		gfx::IndexBufferType	indexType,
		uint32_t	indexOffset )

Binds the Kanzi graphics index buffer for use with all draw operations until the next popFramebuffer or bindRenderPipeline.

Parameters

indexBuffer	The index buffer handle.
indexType	The index type.
indexOffset	The offset in bytes within the index buffer that contains the index data.

◆ bindResourceSet()

void kanzi::CommandRecorder::bindResourceSet	(	uint32_t	slot,
		gfx::RenderResourceSetHandleGuard	resourceSet )

Binds the Kanzi graphics render resource set.

The resource set remains bound until the next popFramebuffer or bindRenderPipeline.

Parameters

slot	The binding slot.
resourceSet	The render resource set.

◆ bindVertexBuffer()

void kanzi::CommandRecorder::bindVertexBuffer	(	uint32_t	slot,
		gfx::VertexBufferBinding	binding )

Binds the Kanzi graphics vertex buffer.

The vertex buffer remains bound until the next popFramebuffer or bindRenderPipeline.

Parameters

slot	The binding slot.
binding	The vertex buffer binding.

◆ bindConstantData()

void kanzi::CommandRecorder::bindConstantData ( ConstByteSpan data )

Binds a constant buffer.

The constant buffer remains bound until the next popFramebuffer or bindRenderPipeline.

Parameters

data	The constant data. Up to gfx::limits::ConstantDataSize bytes are used.

◆ bindLineWidth()

void kanzi::CommandRecorder::bindLineWidth ( float lineWidth )

Binds a line width.

Parameters

lineWidth The line width.

◆ addUniformBufferOffset()

void kanzi::CommandRecorder::addUniformBufferOffset	(	uint8_t	setIndex,
		uint8_t	bufferIndex,
		uint32_t	offset )

Adds a uniform buffer binding.

The uniform binding remains bound until the next popFramebuffer or bindRenderPipeline.

Parameters

setIndex	The resource set index.
bufferIndex	The buffer index as specified in the shader reflection information.
offset	The uniform buffer offset.

◆ commandDraw()

void kanzi::CommandRecorder::commandDraw	(	uint32_t	elementCount,
		uint32_t	indexOffset = 0,
		uint32_t	instanceCount = 1,
		uint32_t	instanceOffset = 0,
		uint32_t	vertexOffset = 0 )

Generates a draw command.

Uses all previously bound states.

Parameters

elementCount	The number of indices or vertices to draw.
indexOffset	The index offset within the index buffer.
instanceCount	The instance count.
instanceOffset	The instance offset.
vertexOffset	The vertex offset.

◆ commandIndirectDraw()

void kanzi::CommandRecorder::commandIndirectDraw	(	gfx::BufferHandleGuard	buffer,
		uint32_t	drawCount,
		uint32_t	drawStride,
		uint32_t	offset = 0 )

Generates an indirect draw command.

Uses all previously bound states.

Parameters

buffer	The kanzi graphics buffer that contains the draw information.
drawCount	The number of draws within the buffer.
drawStride	The stride between each draw in the buffer.
offset	The offset in bytes of the draw information in the buffer.

◆ setCompositionManager()

void kanzi::CommandRecorder::setCompositionManager ( CompositionManager * compositionManager )

Sets the CompositionManager associated with the command recorder.

◆ queueReleaseTemporaryCompositionTarget()

void kanzi::CommandRecorder::queueReleaseTemporaryCompositionTarget ( TextureSharedPtr texture )

Queues a composition target texture for release.

The command recorder will trigger the actual release from the composition manager when it can be safely reused without command reordering affecting the previously rendered contents.

Parameters

texture The composition target texture.

◆ getStagingBufferStats()

vector< BufferStats > kanzi::CommandRecorder::getStagingBufferStats ( )

Gets a list of statistics about staging buffers that are being used.

Statistics include bytes used and total bytes.

Returns: A vector of buffer statistics.

◆ enableStatistics()

void kanzi::CommandRecorder::enableStatistics ( )

Enables statistics tracking. Intended to be used by the RendererStatisticsScope class.

◆ disableStatistics()

void kanzi::CommandRecorder::disableStatistics ( )

Disabled statistics tracking. Intended to be used by the RendererStatisticsScope class.

Member Data Documentation

◆ DefaultCommandPageSize

constexpr uint32_t kanzi::CommandRecorder::DefaultCommandPageSize

staticconstexpr

The default size of a command page.

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

kanzi/core.ui/graphics/command_recorder.hpp

Classes

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ CommandRecorder() [1/3]

◆ CommandRecorder() [2/3]

◆ CommandRecorder() [3/3]

Member Function Documentation

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ invalidate()

◆ getUniformGeneration()

◆ uploadUniformBuffer()

◆ getCommandPageSize()

◆ getLatchGeneration()

◆ setCommandPageSize()

◆ setUniformBufferSize()

◆ beginFrame()

◆ endFrame()

◆ flush()

◆ latch()

◆ present()

◆ generateMipMaps()

◆ resolveMultisample()

◆ updateImage()

◆ updateBuffer()

◆ allocateStagingMemory()

◆ pushFramebuffer()

◆ popFramebuffer()

◆ getRenderPassArchetype()

◆ hasFramebuffer()

◆ clearFramebuffer()

◆ invalidateFramebuffer()

◆ bindRenderPipeline()

◆ bindIndexBuffer()

◆ bindResourceSet()

◆ bindVertexBuffer()

◆ bindConstantData()

◆ bindLineWidth()

◆ addUniformBufferOffset()

◆ commandDraw()

◆ commandIndirectDraw()

◆ setCompositionManager()

◆ queueReleaseTemporaryCompositionTarget()

◆ getStagingBufferStats()

◆ enableStatistics()

◆ disableStatistics()

Member Data Documentation

◆ DefaultCommandPageSize