Composition manager. More...

#include <kanzi/core.ui/graphics2d/composition_manager.hpp>

Classes
struct	LRUTracker
	Least Recently Used wrapper for different resource types. More...

class	Request
	Composition request class. More...

struct	ReuseParameters
	Reuse and pruning parameters for unused composition targets. More...

Public Types
using	AvailableTextureContainer
	Storage type for available textures.

using	AvailableTextureSpan
	Span type for available textures.

using	UsedTextureSpan
	Span type for used textures.

Public Member Functions
TextureSharedPtr	acquireTemporaryCompositionTarget (const CompositionContentRequirements &requirements)
	Requests a temporary composition target.

virtual TextureSharedPtr	acquireTemporaryCompositionTarget (const Request &compositionReq)
	Requests a temporary composition target.

TextureSharedPtr	acquireTemporaryCompositionTarget (size_t width, size_t height, bool alpha, bool depth, bool stencil, Sampler::MipmapMode mipmapMode, size_t numSamples)
	Requests a composition target.

TextureSharedPtr	acquireTemporaryCompositionTarget (size_t width, size_t height, GraphicsFormat colorFormat, GraphicsFormat depthStencilFormat, Sampler::MipmapMode mipmapMode, size_t numSamples)
	Requests a composition target.

void	clear ()
	Removes all allocated temporary composition targets.

	CompositionManager (Domain *domain)
	Constructor.

virtual TextureSharedPtr	createPersistentCompositionTarget (const Request &compositionReq)
	Creates a persistent composition target.

TextureSharedPtr	createPersistentCompositionTarget (size_t width, size_t height, bool alpha, bool depth, bool stencil)
	Creates a persistent composition target.

TextureSharedPtr	findClosestTexture (const CompositionManager::Request &compositionReq)
	Finds the color texture, which most closely matches a given composition requirement, and marks it used.

AvailableTextureSpan	getAvailableTextures () const
	Gets a span over the available textures.

GraphicsFormat	getColorFormat (bool alpha) const
	Gets color texture format format depending on alpha requirement.

GraphicsFormat	getDepthRenderbufferFormat () const
	Gets depth renderbuffer format.

GraphicsFormat	getDepthStencilFormat (bool depth, bool stencil) const
	Gets the depth or stencil renderbuffer format depending on requirements.

GraphicsFormat	getDepthStencilRenderbufferFormat () const
	Gets depth + stencil format.

GraphicsFormat	getDepthTextureFormat () const
	Gets format for depth textures.

ReuseParameters	getReuseParameters () const
	Gets the reuse and pruning parameters for unused composition targets.

GraphicsFormat	getStencilRenderbufferFormat () const
	Gets stencil renderbuffer format.

size_t	getUnusedTargetCount () const
	Gets the numbers of unused composition targets for statistics and test purposes.

UsedTextureSpan	getUsedTextures () const
	Gets a span over the textures that are in use.

void	initialize (Renderer &renderer)
	Initializes the composition manager.

void	pruneUnusedTargets ()
	Prunes unused composition targets from free lists.

void	releasePendingTemporaryCompositionTarget (span< TextureSharedPtr > textures)
	Releases the textures that have been pending release.

virtual void	releaseTemporaryCompositionTarget (const TextureSharedPtr &texture)
	Releases an composition target acquired earlier.

void	setReuseParameters (const ReuseParameters &reuseParameters)
	Sets the reuse and pruning parameters for unused composition targets.

virtual	~CompositionManager ()=default
	Destructor.

Static Public Member Functions
static bool	compositionTargetMatches (const Texture &target, const Request &compositionReq)
	Checks if a given composition target texture is an acceptable match for given requirements.

static bool	compositionTargetMatches (const Texture &target, const Request &compositionReq, float downScaleLimit)
	Checks if a given composition target is an acceptable match for given requirements.

Protected Member Functions
TextureSharedPtr	createCompositionTargetInternal (const CompositionManager::Request &compositionReq) const
	Internal creation of the composition target.

template<typename TargetType >
size_t	getTargetMatchLevel (const Request &request, const TargetType &target) const
	Calculates a match score between requested size and target size.

size_t	getTextureMatchLevel (const Texture &texture, const Request &compositionReq) const
	Gets texture match level for given requirements.

Static Protected Member Functions
static bool	compositionTargetMatchesOmitSize (const Texture &target, const Request &compositionReq)
	Checks if a given composition target texture is an acceptable match for given requirements.

Protected Attributes
GraphicsFormat	m_alphaColorTextureFormat
	Alpha color graphics format.

AvailableTextureContainer	m_availableTextures
	Temporary composition target textures available.

GraphicsFormat	m_depthRenderbufferFormat
	Depth format for renderbuffers.

GraphicsFormat	m_depthStencilRenderbufferFormat
	Depth + stencil format for renderbuffers.

GraphicsFormat	m_depthTextureFormat
	Depth format for depth textures.

Domain *	m_domain
	Owning domain.

uint64_t	m_frameNumber
	Current frame number used for freeing unused resources.

GraphicsFormat	m_opaqueColorTextureFormat
	Opaque color graphics format.

vector< TextureSharedPtr >	m_pendingReleaseTextures
	Composition target textures currently pending release.

ReuseParameters	m_reuseParameters
	Parameters for reuse and pruning of unused render targets.

GraphicsFormat	m_stencilRenderbufferFormat
	Stencil format for renderbuffers.

vector< TextureSharedPtr >	m_usedTextures
	Composition target textures currently in use.

Detailed Description

Composition manager.

Used for storing and managing composition targets and keeping track of their use. The rationale is to minimize memory used by composition targets.

Since: Kanzi 4.0.0 removed CompositionManager::Target class.; Kanzi 4.0.0 removed findClosestColorRenderbuffer, findClosestDepthTexture, findClosestTexture, markColorRenderbufferUnused, markDepthTextureUnused and markTextureUnused functions.; Kanzi 4.0.0 removed m_availableColorRenderBuffers, m_availableDepthTextures, m_implicitMultisample, m_usedColorRenderBuffers and m_usedDepthTextures fields.; Kanzi 4.0.0 removed superfluous acquireTemporaryCompositionTarget function variants.; Kanzi 4.0.0 removed superfluous createPersistentCompositionTarget function variants.; Kanzi 4.0.0 removed superfluous compositionTargetMatches function variants.

Member Typedef Documentation

◆ AvailableTextureContainer

using kanzi::CompositionManager::AvailableTextureContainer

Storage type for available textures.

Since: Kanzi 3.9.6

◆ AvailableTextureSpan

using kanzi::CompositionManager::AvailableTextureSpan

Span type for available textures.

Since: Kanzi 3.9.6

◆ UsedTextureSpan

using kanzi::CompositionManager::UsedTextureSpan

Span type for used textures.

Since: Kanzi 3.9.6

Constructor & Destructor Documentation

◆ CompositionManager()

kanzi::CompositionManager::CompositionManager ( Domain * domain )

inlineexplicit

Constructor.

Parameters

domain The domain owning this composition manager.

Since: Kanzi 4.0.0 replaced resourceManager parameter with domain.

◆ ~CompositionManager()

virtual kanzi::CompositionManager::~CompositionManager ( )

virtualdefault

Destructor.

Member Function Documentation

◆ initialize()

void kanzi::CompositionManager::initialize ( Renderer & renderer )

Initializes the composition manager.

Should be run after Renderer is initialized.

Parameters

renderer Renderer to retrieve information about supported composition types from.

◆ clear()

void kanzi::CompositionManager::clear ( )

Removes all allocated temporary composition targets.

◆ pruneUnusedTargets()

void kanzi::CompositionManager::pruneUnusedTargets ( )

Prunes unused composition targets from free lists.

Since: Kanzi 3.9.5

◆ acquireTemporaryCompositionTarget() [1/4]

virtual TextureSharedPtr kanzi::CompositionManager::acquireTemporaryCompositionTarget ( const Request & compositionReq )

virtual

Requests a temporary composition target.

Keep in mind that you must release the composition target using releaseTemporaryCompositionTarget().

Parameters

compositionReq Request details.

Returns: Composition target that fulfills the requirements.

◆ acquireTemporaryCompositionTarget() [2/4]

TextureSharedPtr kanzi::CompositionManager::acquireTemporaryCompositionTarget	(	size_t	width,
		size_t	height,
		GraphicsFormat	colorFormat,
		GraphicsFormat	depthStencilFormat,
		Sampler::MipmapMode	mipmapMode,
		size_t	numSamples )

inline

Requests a composition target.

Keep in mind that you must release the composition target using releaseTemporaryCompositionTarget().

Parameters

width	Requested width.
height	Requested height.
colorFormat	Color buffer format.
depthStencilFormat	Depth and/or stencil buffer format.
mipmapMode	Requested mipmap mode.
numSamples	Requested number of samples.

Returns: Framebuffer that fulfills the requirements.

Since: Kanzi 3.9.7; Kanzi 4.0.0 changed the type of width, height and numSamples parameters to size_t.; Kanzi 4.0.0 added the mipmapMode parameter.

◆ acquireTemporaryCompositionTarget() [3/4]

TextureSharedPtr kanzi::CompositionManager::acquireTemporaryCompositionTarget	(	size_t	width,
		size_t	height,
		bool	alpha,
		bool	depth,
		bool	stencil,
		Sampler::MipmapMode	mipmapMode,
		size_t	numSamples )

inline

Requests a composition target.

Keep in mind that you must release the composition target using releaseTemporaryCompositionTarget().

Parameters

width	Requested width.
height	Requested height.
alpha	Whether to request the alpha channel.
depth	Whether to request the depth buffer.
stencil	Whether to request the stencil buffer.
mipmapMode	Requested mipmap mode.
numSamples	Requested number of samples.

Returns: Framebuffer that fulfills the requirements.

Since: Kanzi 3.9.7; Kanzi 4.0.0 changed the type of width, height and numSamples parameters to size_t.

◆ acquireTemporaryCompositionTarget() [4/4]

TextureSharedPtr kanzi::CompositionManager::acquireTemporaryCompositionTarget ( const CompositionContentRequirements & requirements )

inline

Requests a temporary composition target.

Keep in mind that you must release the composition target using releaseTemporaryCompositionTarget().

Parameters

requirements Content requirements details.

Returns: Framebuffer that fulfills the requirements.

Since: Kanzi 3.9.7

◆ releaseTemporaryCompositionTarget()

virtual void kanzi::CompositionManager::releaseTemporaryCompositionTarget ( const TextureSharedPtr & texture )

virtual

Releases an composition target acquired earlier.

This, released composition target may be re-used by successive requests.

Parameters

texture Target to release.

◆ createPersistentCompositionTarget() [1/2]

virtual TextureSharedPtr kanzi::CompositionManager::createPersistentCompositionTarget ( const Request & compositionReq )

virtual

Creates a persistent composition target.

Caller has ownership of all the components of this composition target, it is not stored within the composition manager.

Parameters

compositionReq Request details.

Returns: Composition target that fulfills the requirements.

◆ createPersistentCompositionTarget() [2/2]

TextureSharedPtr kanzi::CompositionManager::createPersistentCompositionTarget	(	size_t	width,
		size_t	height,
		bool	alpha,
		bool	depth,
		bool	stencil )

inline

Creates a persistent composition target.

This function returns only returns a color texture. Potential depth and stencil are renderbuffers. Caller has ownership of all the components of this composition target, it is not stored within the composition manager.

Parameters

width	Requested width.
height	Requested height.
alpha	Whether to require the alpha channel.
depth	Whether to require the depth buffer.
stencil	Whether to require the stencil buffer.

Returns: Composition target that fulfills the requirements.

Since: Kanzi 4.0.0 changed the type of width and height parameters to size_t.

◆ findClosestTexture()

TextureSharedPtr kanzi::CompositionManager::findClosestTexture ( const CompositionManager::Request & compositionReq )

Finds the color texture, which most closely matches a given composition requirement, and marks it used.

Parameters

compositionReq Request details.

Returns: Color texture most closely matching given requirements or an empty shared pointer.

◆ getReuseParameters()

ReuseParameters kanzi::CompositionManager::getReuseParameters ( ) const

inline

Gets the reuse and pruning parameters for unused composition targets.

Returns: A struct that contains the reuse and pruning parameters.

See also: ReuseParameters

Since: Kanzi 3.9.5

◆ setReuseParameters()

void kanzi::CompositionManager::setReuseParameters ( const ReuseParameters & reuseParameters )

inline

Sets the reuse and pruning parameters for unused composition targets.

Parameters

reuseParameters The struct that contains the reuse and pruning parameters.

See also: ReuseParameters

Since: Kanzi 3.9.5

◆ getColorFormat()

GraphicsFormat kanzi::CompositionManager::getColorFormat ( bool alpha ) const

inline

Gets color texture format format depending on alpha requirement.

Parameters

alpha Whether to require alpha.

Returns: Color texture format.

◆ getDepthTextureFormat()

GraphicsFormat kanzi::CompositionManager::getDepthTextureFormat ( ) const

inline

Gets format for depth textures.

Returns: Depth texture format.

◆ getDepthStencilFormat()

GraphicsFormat kanzi::CompositionManager::getDepthStencilFormat	(	bool	depth,
		bool	stencil ) const

inline

Gets the depth or stencil renderbuffer format depending on requirements.

Parameters

depth	Whether to require depth.
stencil	Whether to require stencil.

Returns: Depth or stencil renderbuffer format.

◆ getDepthRenderbufferFormat()

GraphicsFormat kanzi::CompositionManager::getDepthRenderbufferFormat ( ) const

inline

Gets depth renderbuffer format.

Returns: Depth renderbuffer format.

◆ getDepthStencilRenderbufferFormat()

GraphicsFormat kanzi::CompositionManager::getDepthStencilRenderbufferFormat ( ) const

inline

Gets depth + stencil format.

Returns: Depth + stencil renderbuffer format.

◆ getStencilRenderbufferFormat()

GraphicsFormat kanzi::CompositionManager::getStencilRenderbufferFormat ( ) const

inline

Gets stencil renderbuffer format.

Returns: Stencil renderbuffer format.

◆ getAvailableTextures()

AvailableTextureSpan kanzi::CompositionManager::getAvailableTextures ( ) const

inline

Gets a span over the available textures.

Do not call this function directly. Kanzi uses this function for internal verification.

Returns: Span over the available texture array.

Since: Kanzi 3.9.6

◆ getUsedTextures()

UsedTextureSpan kanzi::CompositionManager::getUsedTextures ( ) const

inline

Gets a span over the textures that are in use.

Do not call this function directly. Kanzi uses this function for internal verification.

Returns: Span over the used texture array.

Since: Kanzi 3.9.6

◆ getUnusedTargetCount()

size_t kanzi::CompositionManager::getUnusedTargetCount ( ) const

inline

Gets the numbers of unused composition targets for statistics and test purposes.

The returned value makes no distinction

Since: Kanzi 4.0.0 renamed from getUnusedTargetCounts.; Kanzi 4.0.0 removed output parameters, changed return value type to size_t.

◆ compositionTargetMatches() [1/2]

static bool kanzi::CompositionManager::compositionTargetMatches	(	const Texture &	target,
		const Request &	compositionReq,
		float	downScaleLimit )

static

Checks if a given composition target is an acceptable match for given requirements.

Parameters

target	Composition target to test.
compositionReq	Request details.
downScaleLimit	Limit for matching against smaller composition targets.

Returns: True if acceptable, false if not.

◆ compositionTargetMatches() [2/2]

static bool kanzi::CompositionManager::compositionTargetMatches	(	const Texture &	target,
		const Request &	compositionReq )

static

Checks if a given composition target texture is an acceptable match for given requirements.

Size matching is exact.

Parameters

target	Composition target to test.
compositionReq	Request details.

Returns: True if acceptable, false if not.

◆ releasePendingTemporaryCompositionTarget()

void kanzi::CompositionManager::releasePendingTemporaryCompositionTarget ( span< TextureSharedPtr > textures )

Releases the textures that have been pending release.

This is called when command re-ordering will no longer occur for the affected textures meaning they are actually available for reuse. The textures processed by this function must have been previously released with the releaseTemporaryCompositionTarget function.

Parameters

textures The pending textures to release.

Since: Kanzi 4.0.0

◆ createCompositionTargetInternal()

TextureSharedPtr kanzi::CompositionManager::createCompositionTargetInternal ( const CompositionManager::Request & compositionReq ) const

protected

Internal creation of the composition target.

Both the temporary and permanent composition target creation paths eventually come here.

Parameters

compositionReq Request details.

Returns: Newly created composition target.

Since: Kanzi 4.0.0

◆ compositionTargetMatchesOmitSize()

static bool kanzi::CompositionManager::compositionTargetMatchesOmitSize	(	const Texture &	target,
		const Request &	compositionReq )

staticprotected

Checks if a given composition target texture is an acceptable match for given requirements.

Size checking is omitted. Called internally by compositionTargetMatches().

Parameters

target	Composition target to test.
compositionReq	Request details.

Returns: True if acceptable, false if not.

◆ getTextureMatchLevel()

size_t kanzi::CompositionManager::getTextureMatchLevel	(	const Texture &	texture,
		const Request &	compositionReq ) const

protected

Gets texture match level for given requirements.

Parameters

texture	Texture to test.
compositionReq	Request details.

Returns: 0 if no match, 1 if exact match, greater values if size of texture exceeds requested size.

◆ getTargetMatchLevel()

template<typename TargetType >

size_t kanzi::CompositionManager::getTargetMatchLevel	(	const Request &	request,
		const TargetType &	target ) const

inlineprotected

Calculates a match score between requested size and target size.

Parameters

request	Composition request.
target	Composition target candidate for reuse.

Template Parameters

TargetType Composition target type.

Returns: Target match score. The lower the score, the better the size match. If the target is either too small or too large for reuse, returns 0.

Since: Kanzi 3.9.5; Kanzi 4.0.0 changed the type of the return value to size_t.

Member Data Documentation

◆ m_availableTextures

AvailableTextureContainer kanzi::CompositionManager::m_availableTextures

protected

Temporary composition target textures available.

◆ m_usedTextures

vector<TextureSharedPtr> kanzi::CompositionManager::m_usedTextures

protected

Composition target textures currently in use.

◆ m_pendingReleaseTextures

vector<TextureSharedPtr> kanzi::CompositionManager::m_pendingReleaseTextures

protected

Composition target textures currently pending release.

◆ m_domain

Domain* kanzi::CompositionManager::m_domain

protected

Owning domain.

◆ m_alphaColorTextureFormat

GraphicsFormat kanzi::CompositionManager::m_alphaColorTextureFormat

protected

Alpha color graphics format.

◆ m_opaqueColorTextureFormat

GraphicsFormat kanzi::CompositionManager::m_opaqueColorTextureFormat

protected

Opaque color graphics format.

◆ m_depthTextureFormat

GraphicsFormat kanzi::CompositionManager::m_depthTextureFormat

protected

Depth format for depth textures.

◆ m_depthRenderbufferFormat

GraphicsFormat kanzi::CompositionManager::m_depthRenderbufferFormat

protected

Depth format for renderbuffers.

◆ m_depthStencilRenderbufferFormat

GraphicsFormat kanzi::CompositionManager::m_depthStencilRenderbufferFormat

protected

Depth + stencil format for renderbuffers.

◆ m_stencilRenderbufferFormat

GraphicsFormat kanzi::CompositionManager::m_stencilRenderbufferFormat

protected

Stencil format for renderbuffers.

◆ m_frameNumber

uint64_t kanzi::CompositionManager::m_frameNumber

protected

Current frame number used for freeing unused resources.

◆ m_reuseParameters

ReuseParameters kanzi::CompositionManager::m_reuseParameters

protected

Parameters for reuse and pruning of unused render targets.

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

kanzi/core.ui/graphics2d/composition_manager.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ AvailableTextureContainer

◆ AvailableTextureSpan

◆ UsedTextureSpan

Constructor & Destructor Documentation

◆ CompositionManager()

◆ ~CompositionManager()

Member Function Documentation

◆ initialize()

◆ clear()

◆ pruneUnusedTargets()

◆ acquireTemporaryCompositionTarget() [1/4]

◆ acquireTemporaryCompositionTarget() [2/4]

◆ acquireTemporaryCompositionTarget() [3/4]

◆ acquireTemporaryCompositionTarget() [4/4]

◆ releaseTemporaryCompositionTarget()

◆ createPersistentCompositionTarget() [1/2]

◆ createPersistentCompositionTarget() [2/2]

◆ findClosestTexture()

◆ getReuseParameters()

◆ setReuseParameters()

◆ getColorFormat()

◆ getDepthTextureFormat()

◆ getDepthStencilFormat()

◆ getDepthRenderbufferFormat()

◆ getDepthStencilRenderbufferFormat()

◆ getStencilRenderbufferFormat()

◆ getAvailableTextures()

◆ getUsedTextures()

◆ getUnusedTargetCount()

◆ compositionTargetMatches() [1/2]

◆ compositionTargetMatches() [2/2]

◆ releasePendingTemporaryCompositionTarget()

◆ createCompositionTargetInternal()

◆ compositionTargetMatchesOmitSize()

◆ getTextureMatchLevel()

◆ getTargetMatchLevel()

Member Data Documentation

◆ m_availableTextures

◆ m_usedTextures

◆ m_pendingReleaseTextures

◆ m_domain

◆ m_alphaColorTextureFormat

◆ m_opaqueColorTextureFormat

◆ m_depthTextureFormat

◆ m_depthRenderbufferFormat

◆ m_depthStencilRenderbufferFormat

◆ m_stencilRenderbufferFormat

◆ m_frameNumber

◆ m_reuseParameters