Kanzi  3.9.5
Kanzi Engine API
kanzi::CompositionManager Class Reference

Composition manager. More...

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

Classes

class  Request
 Composition request class. More...
 
struct  ReuseParameters
 Reuse and pruning parameters for unused composition targets. More...
 
class  Target
 Composition target. More...
 

Public Member Functions

virtual Target acquireTemporaryCompositionTarget (const Request &compositionReq)
 Request a composition target. More...
 
TextureSharedPtr acquireTemporaryCompositionTarget (unsigned int width, unsigned int height, GraphicsFormat colorFormat, GraphicsFormat depthStencilFormat)
 Request a composition target. More...
 
TextureSharedPtr acquireTemporaryCompositionTarget (unsigned int width, unsigned int height, bool alpha, bool depth, bool stencil)
 Request a composition target. More...
 
void clear ()
 Remove all allocated temporary composition targets. More...
 
bool colorRenderbufferMatches (const Renderbuffer &renderbuffer, const Request &compositionReq) const
 Tell if given color render buffer matches composition requirements. More...
 
bool colorTextureMatches (const Texture &texture, const Request &compositionReq) const
 Tell if given color texture matches composition requirements. More...
 
 CompositionManager (ResourceManager *resourceManager)
 Constructor. More...
 
bool compositionTargetMatches (const Target &target, const Request &compositionReq, float downScaleLimit) const
 Checks if a given composition target is an acceptable match for given requirements. More...
 
bool compositionTargetMatches (const Target &target, const Request &compositionReq) const
 Checks if a given composition target texture is an acceptable match for given requirements. More...
 
bool compositionTargetMatches (TextureSharedPtr texture, unsigned int width, unsigned int height, GraphicsFormat colorFormat, GraphicsFormat depthStencilFormat) const
 Checks if a given composition target texture is an acceptable match for given requirements. More...
 
bool compositionTargetMatches (TextureSharedPtr texture, unsigned int width, unsigned int height, bool alpha, bool depth, bool stencil, float downScaleLimit) const
 Checks if a given composition target texture is an acceptable match for given requirements. More...
 
bool compositionTargetMatches (TextureSharedPtr texture, unsigned int width, unsigned int height, bool alpha, bool depth, bool stencil) const
 Checks if a given composition target texture is an acceptable match for given requirements. More...
 
RenderbufferSharedPtr createPersistentColorRenderbuffer (const CompositionManager::Request &compositionReq)
 Create a persistent color renderbuffer. More...
 
virtual Target createPersistentCompositionTarget (const Request &compositionReq)
 Create a persistent composition target. More...
 
TextureSharedPtr createPersistentCompositionTarget (unsigned int width, unsigned int height, GraphicsFormat colorFormat, GraphicsFormat depthStencilFormat, Sampler::AddressingMode addressingMode)
 Create a persistent composition target. More...
 
TextureSharedPtr createPersistentCompositionTarget (unsigned int width, unsigned int height, bool alpha, bool depth, bool stencil)
 Create a persistent composition target. More...
 
virtual RenderbufferSharedPtr createPersistentDepthStencilRenderbuffer (const CompositionManager::Request &compositionReq)
 Creates a persistent depth and/or stencil renderbuffer. More...
 
RenderbufferSharedPtr createPersistentDepthStencilRenderbuffer (unsigned int width, unsigned int height, GraphicsFormat depthStencilFormat, unsigned int samples)
 Creates a persistent depth and/or stencil renderbuffer. More...
 
RenderbufferSharedPtr createPersistentDepthStencilRenderbuffer (unsigned int width, unsigned int height, bool depth, bool stencil, unsigned int samples)
 Creates a persistent depth and/or stencil renderbuffer. More...
 
TextureSharedPtr createPersistentDepthTexture (const CompositionManager::Request &compositionReq)
 Create a persistent depth texture. More...
 
TextureSharedPtr createPersistentTexture (const CompositionManager::Request &compositionReq)
 Create a persistent color texture. More...
 
bool depthTextureMatches (const Texture &texture, const Request &compositionReq) const
 Tell if given depth texture matches composition requirements. More...
 
GraphicsFormat getColorFormat (bool alpha) const
 Gets color texture format format depending on alpha requirement. More...
 
GraphicsFormat getDepthRenderbufferFormat () const
 Gets depth renderbuffer format. More...
 
GraphicsFormat getDepthStencilFormat (bool depth, bool stencil) const
 Gets depth/stencil renderbuffer format depending on requirements. More...
 
GraphicsFormat getDepthStencilRenderbufferFormat () const
 Gets depth + stencil format. More...
 
GraphicsFormat getDepthTextureFormat () const
 Gets format for depth textures. More...
 
ReuseParameters getReuseParameters () const
 Gets the reuse and pruning parameters for unused composition targets. More...
 
GraphicsFormat getStencilRenderbufferFormat () const
 Gets stencil renderbuffer format. More...
 
void getUnusedTargetCounts (size_t &textures, size_t &renderBuffers, size_t &depthTextures)
 Gets the numbers of unused composition targets for statistics and test purposes. More...
 
void initialize (Renderer &renderer)
 Initialize composition manager. More...
 
void pruneUnusedTargets ()
 Prunes unused composition targets from free lists. More...
 
virtual void releaseTemporaryCompositionTarget (const Target &target)
 Release an earlier composition target. More...
 
void setReuseParameters (const ReuseParameters &reuseParameters)
 Sets the reuse and pruning parameters for unused composition targets. More...
 
virtual ~CompositionManager ()
 Destructor. More...
 

Protected Member Functions

Target createTemporaryCompositionTarget (const CompositionManager::Request &compositionReq, TextureSharedPtr texture, RenderbufferSharedPtr colorRenderbuffer, TextureSharedPtr depthTexture)
 Create a temporary composition target. More...
 
RenderbufferSharedPtr findClosestColorRenderbuffer (const CompositionManager::Request &compositionReq)
 Finds the renderbuffer, which most closely matches a given composition requirement, and marks it used. More...
 
TextureSharedPtr findClosestDepthTexture (const CompositionManager::Request &compositionReq)
 Finds the depth texture, which most closely matches a given composition requirement, and marks it used. More...
 
TextureSharedPtr findClosestTexture (const CompositionManager::Request &compositionReq)
 Finds the color texture, which most closely matches a given composition requirement, and marks it used. More...
 
unsigned int getColorRenderbufferMatchLevel (const Renderbuffer &renderbuffer, const Request &compositionReq) const
 Get color renderbuffer match level for given requirements. More...
 
unsigned int getDepthTextureMatchLevel (const Texture &texture, const Request &compositionReq) const
 Get depth texture match level for given requirements. More...
 
unsigned int getTextureMatchLevel (const Texture &texture, const Request &compositionReq) const
 Get color texture match level for given requirements. More...
 
void markColorRenderbufferUnused (RenderbufferSharedPtr colorRenderbuffer)
 Mark given color renderbuffer as available. More...
 
void markDepthTextureUnused (TextureSharedPtr depthTexture)
 Mark given depth texture as available. More...
 
void markTextureUnused (TextureSharedPtr texture)
 Mark given color texture as available. More...
 

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.

Constructor & Destructor Documentation

◆ CompositionManager()

kanzi::CompositionManager::CompositionManager ( ResourceManager resourceManager)
explicit

Constructor.

Parameters
resourceManagerResource manager owning this composition manager.

◆ ~CompositionManager()

virtual kanzi::CompositionManager::~CompositionManager ( )
inlinevirtual

Destructor.

Member Function Documentation

◆ initialize()

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

Initialize composition manager.

Should be run after Renderer is initialized.

Parameters
rendererRenderer to retrieve information about supported composition types from.

◆ clear()

void kanzi::CompositionManager::clear ( )

Remove all allocated temporary composition targets.

◆ pruneUnusedTargets()

void kanzi::CompositionManager::pruneUnusedTargets ( )

Prunes unused composition targets from free lists.

Since
Kanzi 3.9.5

◆ acquireTemporaryCompositionTarget() [1/3]

virtual Target kanzi::CompositionManager::acquireTemporaryCompositionTarget ( const Request compositionReq)
virtual

Request a composition target.

Parameters
compositionReqRequest details.
Returns
Composition target that fulfills the requirements.

◆ acquireTemporaryCompositionTarget() [2/3]

TextureSharedPtr kanzi::CompositionManager::acquireTemporaryCompositionTarget ( unsigned int  width,
unsigned int  height,
GraphicsFormat  colorFormat,
GraphicsFormat  depthStencilFormat 
)

Request a composition target.

Only the color texture element is returned.

Parameters
widthRequested width.
heightRequested height.
colorFormatColor buffer format.
depthStencilFormatDepth and/or stencil buffer format.
Returns
Framebuffer that fulfills the requirements.

◆ acquireTemporaryCompositionTarget() [3/3]

TextureSharedPtr kanzi::CompositionManager::acquireTemporaryCompositionTarget ( unsigned int  width,
unsigned int  height,
bool  alpha,
bool  depth,
bool  stencil 
)
inline

Request a composition target.

Only the color texture element is returned.

Parameters
widthRequested width.
heightRequested height.
alphaIs alpha channel requested?
depthIs depth buffer requested?
stencilIs stencil buffer requested?
Returns
Framebuffer that fulfills the requirements.

◆ releaseTemporaryCompositionTarget()

virtual void kanzi::CompositionManager::releaseTemporaryCompositionTarget ( const Target target)
virtual

Release an earlier composition target.

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

Parameters
targetTarget to release.

◆ createPersistentCompositionTarget() [1/3]

virtual Target kanzi::CompositionManager::createPersistentCompositionTarget ( const Request compositionReq)
virtual

Create a persistent composition target.

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

Parameters
compositionReqRequest details.
Returns
Composition target that fulfills the requirements.

◆ createPersistentCompositionTarget() [2/3]

TextureSharedPtr kanzi::CompositionManager::createPersistentCompositionTarget ( unsigned int  width,
unsigned int  height,
GraphicsFormat  colorFormat,
GraphicsFormat  depthStencilFormat,
Sampler::AddressingMode  addressingMode 
)

Create a persistent composition target.

Only the color texture element is returned. Caller has ownership of this composition target, it is not stored within the composition manager.

Parameters
widthRequested width.
heightRequested height.
colorFormatColor buffer format.
depthStencilFormatDepth and/or stencil buffer format.
addressingModeAddressing mode (wrap/clamp/etc.).
Returns
Composition target that fulfills the requirements.

◆ createPersistentCompositionTarget() [3/3]

TextureSharedPtr kanzi::CompositionManager::createPersistentCompositionTarget ( unsigned int  width,
unsigned int  height,
bool  alpha,
bool  depth,
bool  stencil 
)
inline

Create a persistent composition target.

Only the color texture element is returned. Caller has ownership of this composition target, it is not stored within the composition manager. Determines color, depth and stencil formats from on/off boolean values.

Parameters
widthRequested width.
heightRequested height.
alphaAlpha channel requirement.
depthDepth buffer requirement.
stencilStencil buffer requirement.
Returns
Composition target that fulfills the requirements.

◆ createPersistentTexture()

TextureSharedPtr kanzi::CompositionManager::createPersistentTexture ( const CompositionManager::Request compositionReq)

Create a persistent color texture.

Note that the color format of this texture may be GraphicsFormatNone.

Parameters
compositionReqRequest details.
Returns
New color texture according to requirements.

◆ createPersistentColorRenderbuffer()

RenderbufferSharedPtr kanzi::CompositionManager::createPersistentColorRenderbuffer ( const CompositionManager::Request compositionReq)

Create a persistent color renderbuffer.

Parameters
compositionReqRequest details.
Returns
New color renderbuffer according to requirements.

◆ createPersistentDepthStencilRenderbuffer() [1/3]

virtual RenderbufferSharedPtr kanzi::CompositionManager::createPersistentDepthStencilRenderbuffer ( const CompositionManager::Request compositionReq)
virtual

Creates a persistent depth and/or stencil renderbuffer.

Parameters
compositionReqRequest details.
Returns
New depth and/or stencil renderbuffer according to requirements.

◆ createPersistentDepthStencilRenderbuffer() [2/3]

RenderbufferSharedPtr kanzi::CompositionManager::createPersistentDepthStencilRenderbuffer ( unsigned int  width,
unsigned int  height,
GraphicsFormat  depthStencilFormat,
unsigned int  samples 
)

Creates a persistent depth and/or stencil renderbuffer.

Parameters
widthThe width of the renderbuffer.
heightThe height of the renderbuffer.
depthStencilFormatDepth or stencil format.
samplesNumber of samples.
Returns
New depth and/or stencil renderbuffer according to requirements.

◆ createPersistentDepthStencilRenderbuffer() [3/3]

RenderbufferSharedPtr kanzi::CompositionManager::createPersistentDepthStencilRenderbuffer ( unsigned int  width,
unsigned int  height,
bool  depth,
bool  stencil,
unsigned int  samples 
)

Creates a persistent depth and/or stencil renderbuffer.

Parameters
widthThe width of the renderbuffer.
heightThe height of the renderbuffer.
depthIf depth is required true, otherwise false.
stencilIf stencil is required true, otherwise false.
samplesNumber of samples.
Returns
New depth and/or stencil renderbuffer according to requirements.

◆ createPersistentDepthTexture()

TextureSharedPtr kanzi::CompositionManager::createPersistentDepthTexture ( const CompositionManager::Request compositionReq)

Create a persistent depth texture.

Parameters
compositionReqRequest details.
Returns
New depth texture according to requirements.

◆ compositionTargetMatches() [1/5]

bool kanzi::CompositionManager::compositionTargetMatches ( const Target target,
const Request compositionReq,
float  downScaleLimit 
) const

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

Parameters
targetComposition target to test.
compositionReqRequest details.
downScaleLimitLimit for matching against smaller composition targets.
Returns
True if acceptable, false if not.

◆ compositionTargetMatches() [2/5]

bool kanzi::CompositionManager::compositionTargetMatches ( const Target target,
const Request compositionReq 
) const
inline

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

Parameters
targetComposition target to test.
compositionReqRequest details.
Returns
True if acceptable, false if not.

◆ compositionTargetMatches() [3/5]

bool kanzi::CompositionManager::compositionTargetMatches ( TextureSharedPtr  texture,
unsigned int  width,
unsigned int  height,
GraphicsFormat  colorFormat,
GraphicsFormat  depthStencilFormat 
) const
inline

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

Tolerance for how much smaller composition targets are accepted is determined automatically.

Parameters
textureComposition target texture to test.
widthRequested width.
heightRequested height.
colorFormatColor buffer format.
depthStencilFormatDepth/stencil buffer format.
Returns
True if acceptable, false if not.

◆ compositionTargetMatches() [4/5]

bool kanzi::CompositionManager::compositionTargetMatches ( TextureSharedPtr  texture,
unsigned int  width,
unsigned int  height,
bool  alpha,
bool  depth,
bool  stencil,
float  downScaleLimit 
) const
inline

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

Determines color, depth and stencil formats from on/off boolean values.

Parameters
textureComposition target texture to test.
widthRequested width.
heightRequested height.
alphaAlpha channel requirement.
depthDepth buffer requirement.
stencilStencil buffer requirement.
downScaleLimitLimit for matching against smaller composition targets.
Returns
True if acceptable, false if not.

◆ compositionTargetMatches() [5/5]

bool kanzi::CompositionManager::compositionTargetMatches ( TextureSharedPtr  texture,
unsigned int  width,
unsigned int  height,
bool  alpha,
bool  depth,
bool  stencil 
) const
inline

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

Determines color, depth and stencil formats from on/off boolean values. Tolerance for how much smaller composition targets are accepted is determined automatically.

Parameters
textureComposition target texture to test.
widthRequested width.
heightRequested height.
alphaAlpha channel requirement.
depthDepth buffer requirement.
stencilStencil buffer requirement.
Returns
True if acceptable, false if not.

◆ colorTextureMatches()

bool kanzi::CompositionManager::colorTextureMatches ( const Texture texture,
const Request compositionReq 
) const
inline

Tell if given color texture matches composition requirements.

Parameters
textureTexture to test.
compositionReqRequest details.
Returns
True if match, false otherwise.

◆ colorRenderbufferMatches()

bool kanzi::CompositionManager::colorRenderbufferMatches ( const Renderbuffer renderbuffer,
const Request compositionReq 
) const
inline

Tell if given color render buffer matches composition requirements.

Parameters
renderbufferRenderbuffer to test.
compositionReqRequest details.

◆ depthTextureMatches()

bool kanzi::CompositionManager::depthTextureMatches ( const Texture texture,
const Request compositionReq 
) const
inline

Tell if given depth texture matches composition requirements.

Parameters
textureTexture to test.
compositionReqRequest details.
Returns
True if match, false otherwise.

◆ getColorFormat()

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

Gets color texture format format depending on alpha requirement.

Parameters
alphaIs alpha required?
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 depth/stencil renderbuffer format depending on requirements.

Parameters
depthIs depth required?
stencilIs stencil required?
Returns
Depth/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.

◆ getUnusedTargetCounts()

void kanzi::CompositionManager::getUnusedTargetCounts ( size_t &  textures,
size_t &  renderBuffers,
size_t &  depthTextures 
)
inline

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

Parameters
texturesNumber of available color textures.
renderBuffersNumber of available color renderbuffers.
depthTexturesNumber of available depth textures.

◆ 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
reuseParametersThe struct that contains the reuse and pruning parameters.
See also
ReuseParameters
Since
Kanzi 3.9.5

◆ createTemporaryCompositionTarget()

Target kanzi::CompositionManager::createTemporaryCompositionTarget ( const CompositionManager::Request compositionReq,
TextureSharedPtr  texture,
RenderbufferSharedPtr  colorRenderbuffer,
TextureSharedPtr  depthTexture 
)
protected

Create a temporary composition target.

Called internally from within acquireTemporaryCompositionTarget() if suitable existing elements are not found. Adds the components of the temporary composition target to the arrays of resources in use.

Parameters
compositionReqRequest details.
textureExisting main texture most closely matching the requirements.
colorRenderbufferExisting color renderbuffer most closely matching the requirements.
depthTextureExisting depth texture most closely matching the requirements.
Returns
Composition target that fulfills the requirements.

◆ getTextureMatchLevel()

unsigned int kanzi::CompositionManager::getTextureMatchLevel ( const Texture texture,
const Request compositionReq 
) const
protected

Get color texture match level for given requirements.

Parameters
textureTexture to test.
compositionReqRequest details.
Returns
0 if no match, 1 if exact match, greater values if size of texture exceeds requested size.

◆ getColorRenderbufferMatchLevel()

unsigned int kanzi::CompositionManager::getColorRenderbufferMatchLevel ( const Renderbuffer renderbuffer,
const Request compositionReq 
) const
protected

Get color renderbuffer match level for given requirements.

Parameters
renderbufferRenderbuffer to test.
compositionReqRequest details.
Returns
0 if no match, 1 if exact match, greater values if size of renderbuffer exceeds requested size.

◆ getDepthTextureMatchLevel()

unsigned int kanzi::CompositionManager::getDepthTextureMatchLevel ( const Texture texture,
const Request compositionReq 
) const
protected

Get depth texture match level for given requirements.

Parameters
textureTexture to test.
compositionReqRequest details.
Returns
0 if no match, 1 if exact match, greater values if size of texture exceeds requested size.

◆ findClosestTexture()

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

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

Parameters
compositionReqRequest details.
Returns
Color texture most closely matching given requirements or an empty shared pointer.

◆ findClosestColorRenderbuffer()

RenderbufferSharedPtr kanzi::CompositionManager::findClosestColorRenderbuffer ( const CompositionManager::Request compositionReq)
protected

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

Parameters
compositionReqRequest details.
Returns
Color renderbuffer most closely matching given requirements or an empty shared pointer.

◆ findClosestDepthTexture()

TextureSharedPtr kanzi::CompositionManager::findClosestDepthTexture ( const CompositionManager::Request compositionReq)
protected

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

Parameters
compositionReqRequest details.
Returns
Depth texture most closely matching given requirements or an empty shared pointer.

◆ markTextureUnused()

void kanzi::CompositionManager::markTextureUnused ( TextureSharedPtr  texture)
protected

Mark given color texture as available.

The texture must exist in used color textures.

Parameters
textureTexture to mark as used.

◆ markColorRenderbufferUnused()

void kanzi::CompositionManager::markColorRenderbufferUnused ( RenderbufferSharedPtr  colorRenderbuffer)
protected

Mark given color renderbuffer as available.

The renderbuffer must exist in used color renderbuffers.

Parameters
colorRenderbufferRenderbuffer to mark as used.

◆ markDepthTextureUnused()

void kanzi::CompositionManager::markDepthTextureUnused ( TextureSharedPtr  depthTexture)
protected

Mark given depth texture as available.

The texture must exist in used depth textures.

Parameters
depthTextureTexture to mark as used.

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