Kanzi Framework  3.9.0
Kanzi Engine API
kanzi::NodeCompositor2D Class Reference

Composition functionality for 2D nodes. More...

#include <kanzi/core.ui/node/node_compositor2d.hpp>

Classes

struct  CompositionState
 CompositionState defines the state held by the compositor while Kanzi performs the composition, that is, between calls to beginComposition and blitComposition. More...
 

Public Types

enum  CompositingBits {
  CompositingBitUserTarget, CompositingBitCache, CompositingBitForce, CompositingBitOffscreen,
  CompositingBitOpacityAndChildren, CompositingBitPerspective, CompositingBitRequest, CompositingBitEffect,
  CompositingBitCount
}
 Enum for compositing bit flags. More...
 
enum  PotentialCompositingBits { PotentialCompositingBitCache, PotentialCompositingBitViewport, PotentialCompositingBitCount }
 Enum for compositing potential bit flags. More...
 

Public Member Functions

bool beginComposition (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager, Vector2 requiredSize, bool alphaRequired, bool depthRequired, bool stencilRequired, bool drawFlagSet)
 Begins the composition. More...
 
void blitComposition (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager, QuadDescription &backgroundQuad, const Matrix3x3 &transform, Vector2 quadSize, const Matrix4x4 *perspectiveMatrix, const Matrix4x4 *projectionMatrix)
 Blits the composition. More...
 
void disableCaching ()
 Disable caching. More...
 
void enableCaching (CachingMode mode)
 Enable caching. More...
 
void endComposition (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager)
 End final composition. More...
 
CachingMode getCachingMode () const
 Gets the caching mode stored in the compositor. More...
 
BrushRenderergetCompositionBrushRenderer () const
 Access composition brush renderer. More...
 
TextureSharedPtr getCompositionTarget () const
 Access managed composition target. More...
 
NodeEffect2DgetEffect () const
 Gets the active effect or null pointer. More...
 
NodeEffectRenderer2DgetEffectRenderer () const
 Gets the active effect renderer or null pointer if compositor has no active effect. More...
 
TextureSharedPtr getManagedCompositionTarget () const
 Gets the managed composition target. More...
 
Vector2 getUserCompositionTargetSize () const
 Gets the size of user composition target. More...
 
bool hasCompositionBrushRenderer () const
 Tell if composition brush renderer has been created. More...
 
bool hasManagedCompositionTarget () const
 Indicates whether a managed composition target has been allocated. More...
 
bool hasUserCompositionTarget () const
 Indicates whether user composition target is set. More...
 
void invalidateCompositionBrush ()
 Invalidate composition brush. More...
 
bool isCacheValid () const
 Indicates whether or not the cache is valid. More...
 
bool isCompositionPotentiallyRequired () const
 Indicates whether composition can potentially be required during rendering. More...
 
bool isCompositionRequested () const
 Indicates whether composition is requested from code. More...
 
bool isCompositionRequired () const
 Indicates whether compositing the node is required. More...
 
bool isCompositionRequiredDuringRendering (const optional< Matrix3x3 > &transform, bool drawFlagSet) const
 Indicates whether compositing the node is required during rendering. More...
 
bool isForceComposition () const
 Indicates whether force composition flag is set. More...
 
bool isOffscreenRendering () const
 Indicates whether offscreen rendering is enabled. More...
 
bool isOpacityCompositionRequest () const
 Indicates whether composition due to opacity is requested. More...
 
bool isPerspectiveCompositionRequested () const
 Indicates whether composition due to perspective transform is requested. More...
 
bool isPotentialCompositionBitViewport () const
 Indicates whether potential composition request flag is set. More...
 
 NodeCompositor2D ()
 Constructor. More...
 
void onDetached ()
 Run when node owning the compositor becomes detached. More...
 
void renderCompositionQuad (Renderer3D &renderer, BrushRenderer &brushRenderer, const Texture &texture, QuadDescription &backgroundQuad, const Matrix4x4 &transform, Vector2 quadSize)
 Render composition quad. More...
 
void resizeUserCompositionTarget (Vector2 compositionSize)
 Resize automatic sizes in user composition target if necessary. More...
 
void restoreResources (Vector2 compositionSize)
 Restore resources. More...
 
void setCacheValid (bool valid)
 Set cache validity flag. More...
 
void setCompositionRequested (bool enabled)
 Sets the compositing request. More...
 
void setEffect (NodeEffect2D *effect)
 Sets the active effect or clears the active effect with empty shared pointer. More...
 
void setForceComposition (bool enabled)
 Sets force composition. More...
 
void setOffscreenRendering (bool enabled)
 Sets the offscreen rendering flag. More...
 
void setOpacityCompositionRequested (bool enabled)
 Sets the opacity composition request flag. More...
 
void setPerspectiveCompositionRequested (bool enabled)
 Sets the perspective composition request flag. More...
 
void setPotentialCompositionBitVierport (bool enabled)
 Sets the potential composition request flag. More...
 
void setUserCompositionBrush (BrushSharedPtr brush)
 Set user composition brush. More...
 
void setUserCompositionTarget (TextureSharedPtr texture)
 Set user composition target. More...
 
void updateRender (Node2D &node, Vector2 actualSize, bool alphaRequired, bool depthRequired, bool stencilRequired, float opacity, bool opaquenessHint, bool translucencyHint)
 Update for rendering, recreating composition targets and brush renderers as needed. More...
 
 ~NodeCompositor2D ()
 Destructor. More...
 

Protected Member Functions

TextureSharedPtr beginFinalComposition (CompositionStack &compositionStack, CompositionManager *compositionManager, Vector2 requiredSize, bool alphaRequired, bool depthRequired, bool stencilRequired, bool needsRender)
 Begins the final composition. More...
 
void blitFinalComposition (Renderer3D &renderer, CompositionStack &compositionStack, CompositionManager *compositionManager, TextureSharedPtr renderTargetTexture, QuadDescription &backgroundQuad, const Matrix3x3 &transform, Vector2 quadSize, const Matrix4x4 *perspectiveMatrix, const Matrix4x4 *projectionMatrix)
 Blits the final composition. More...
 
void endFinalComposition (CompositionStack &compositionStack)
 Ends the final composition. More...
 
bool isRenderRequired (bool drawFlagSet) const
 Indicates whether node rendering is required. More...
 
bool updatePersistentCompositionTarget (Node2D &node, TextureSharedPtr &managedCompositionTarget, Vector2 requiredSize, bool alphaRequired, bool depthRequired, bool stencilRequired)
 Update the managed composition target to match current requirements. More...
 

Protected Attributes

bool m_brushRenderersDirty
 Brush renderer dirty flag. More...
 
bool m_cacheValid
 Cache status flag. More...
 
CachingMode m_cachingMode
 Caching mode setting. More...
 
bitset< CompositingBitCountm_compositingMask
 Bit mask for states affecting whether or not the node should compose itself and its children. More...
 
BrushRendererPtr m_compositionBrushRenderer
 Composition brush renderer. More...
 
NodeEffectRenderer2DUniquePtr m_effectRenderer
 Effect renderer instance, or null if no effect is active. More...
 
CompositionBrushSharedPtr m_managedCompositionBrush
 Composition brush managed by node. More...
 
TextureSharedPtr m_managedCompositionTarget
 Current framebuffer. More...
 
bool m_opaquenessHint
 Saved opaqueness hint. More...
 
bitset< PotentialCompositingBitCountm_potentialCompositingMask
 Bit mask for states affecting whether or not the node should potentially compose itself and its children. More...
 
optional< CompositionStatem_state
 Active composition state, or nullopt if the composition is not active. More...
 
bool m_translucencyHint
 Saved tTranslucency hint. More...
 
BrushSharedPtr m_userCompositionBrush
 User-set composition brush. More...
 
TextureSharedPtr m_userCompositionTarget
 User-set composition target. More...
 

Detailed Description

Composition functionality for 2D nodes.

Member Enumeration Documentation

◆ CompositingBits

Enum for compositing bit flags.

Enumerator
CompositingBitUserTarget 

User composition target explicitly set.

CompositingBitCache 

Caching mode is set to enabled.

CompositingBitForce 

Force composition from property.

CompositingBitOffscreen 

Offscreen rendering.

CompositingBitOpacityAndChildren 

Composition due to opacity and children.

CompositingBitPerspective 

Composition due to perspective transform and children.

CompositingBitRequest 

Custom request from code.

CompositingBitEffect 

Composition due to applied post-processing effect.

CompositingBitCount 

Number of options.

◆ PotentialCompositingBits

Enum for compositing potential bit flags.

Enumerator
PotentialCompositingBitCache 

Caching mode is set to automatic.

PotentialCompositingBitViewport 

Potential non-aligned viewport.

PotentialCompositingBitCount 

Number of options.

Constructor & Destructor Documentation

◆ NodeCompositor2D()

kanzi::NodeCompositor2D::NodeCompositor2D ( )
explicit

Constructor.

◆ ~NodeCompositor2D()

kanzi::NodeCompositor2D::~NodeCompositor2D ( )

Destructor.

Member Function Documentation

◆ updatePersistentCompositionTarget()

bool kanzi::NodeCompositor2D::updatePersistentCompositionTarget ( Node2D node,
TextureSharedPtr managedCompositionTarget,
Vector2  requiredSize,
bool  alphaRequired,
bool  depthRequired,
bool  stencilRequired 
)
protected

Update the managed composition target to match current requirements.

If the composition target does not exist or the settings required from it have been changed, it is (re)created.

Parameters
nodeNode to attach to.
managedCompositionTargetExisting composition target.
requiredSizeSize required of the composition target.
alphaRequiredAlpha requirement.
depthRequiredDepth requirement.
stencilRequiredStencil requirement.
Returns
True if composition target was updated, false if not.

◆ beginFinalComposition()

TextureSharedPtr kanzi::NodeCompositor2D::beginFinalComposition ( CompositionStack compositionStack,
CompositionManager compositionManager,
Vector2  requiredSize,
bool  alphaRequired,
bool  depthRequired,
bool  stencilRequired,
bool  needsRender 
)
protected

Begins the final composition.

Parameters
compositionStackComposition stack to use.
compositionManagerComposition manager to use.
requiredSizeSize required of the composition target.
alphaRequiredAlpha requirement.
depthRequiredDepth requirement.
stencilRequiredStencil requirement.
needsRenderWhether to perform node rendering.
Returns
Render target to use.
Since
Kanzi 3.9.0

◆ endFinalComposition()

void kanzi::NodeCompositor2D::endFinalComposition ( CompositionStack compositionStack)
protected

Ends the final composition.

Parameters
compositionStackComposition stack to use.

◆ blitFinalComposition()

void kanzi::NodeCompositor2D::blitFinalComposition ( Renderer3D renderer,
CompositionStack compositionStack,
CompositionManager compositionManager,
TextureSharedPtr  renderTargetTexture,
QuadDescription backgroundQuad,
const Matrix3x3 transform,
Vector2  quadSize,
const Matrix4x4 perspectiveMatrix,
const Matrix4x4 projectionMatrix 
)
protected

Blits the final composition.

Parameters
rendererRenderer to use.
compositionStackComposition stack to use.
compositionManagerComposition manager to use.
renderTargetTextureRender target texture used.
backgroundQuadClip quad for background area.
transformTransform used for rendering.
quadSizeRendered quad size.
perspectiveMatrixOptional transform to use for perspective projection.
projectionMatrixOptional projection to use for perspective projection.

◆ isRenderRequired()

bool kanzi::NodeCompositor2D::isRenderRequired ( bool  drawFlagSet) const
protected

Indicates whether node rendering is required.

Returns
Whether to perform node rendering.
Since
Kanzi 3.9.0

◆ beginComposition()

bool kanzi::NodeCompositor2D::beginComposition ( Renderer3D renderer,
CompositionStack compositionStack,
CompositionManager compositionManager,
Vector2  requiredSize,
bool  alphaRequired,
bool  depthRequired,
bool  stencilRequired,
bool  drawFlagSet 
)

Begins the composition.

Parameters
rendererRenderer to use.
compositionStackComposition stack to use.
compositionManagerComposition manager to use.
requiredSizeSize required of the composition target.
alphaRequiredAlpha requirement.
depthRequiredDepth requirement.
stencilRequiredStencil requirement.
drawFlagSetWhether the draw flag is set for the node or any of its descendants.
Returns
Whether to perform the rendering.

◆ endComposition()

void kanzi::NodeCompositor2D::endComposition ( Renderer3D renderer,
CompositionStack compositionStack,
CompositionManager compositionManager 
)

End final composition.

Parameters
rendererRenderer to use.
compositionStackComposition stack to use.
compositionManagerComposition manager to use.

◆ blitComposition()

void kanzi::NodeCompositor2D::blitComposition ( Renderer3D renderer,
CompositionStack compositionStack,
CompositionManager compositionManager,
QuadDescription backgroundQuad,
const Matrix3x3 transform,
Vector2  quadSize,
const Matrix4x4 perspectiveMatrix,
const Matrix4x4 projectionMatrix 
)

Blits the composition.

Parameters
rendererRenderer to use.
compositionStackComposition stack to use.
compositionManagerComposition manager to use.
backgroundQuadClip quad for background area.
transformTransform used for rendering.
quadSizeRendered quad size.
perspectiveMatrixOptional transform to use for perspective projection.
projectionMatrixOptional projection to use for perspective projection.

◆ renderCompositionQuad()

void kanzi::NodeCompositor2D::renderCompositionQuad ( Renderer3D renderer,
BrushRenderer brushRenderer,
const Texture texture,
QuadDescription backgroundQuad,
const Matrix4x4 transform,
Vector2  quadSize 
)

Render composition quad.

Parameters
rendererRenderer to use.
brushRendererBrush renderer to use.
textureTexture used.
backgroundQuadClip quad for background area.
transformTransform used for rendering.
quadSizeRendered quad size.

◆ getCompositionTarget()

TextureSharedPtr kanzi::NodeCompositor2D::getCompositionTarget ( ) const

Access managed composition target.

Returns
User composition target if set, otherwise the managed composition target or nullptr.

◆ resizeUserCompositionTarget()

void kanzi::NodeCompositor2D::resizeUserCompositionTarget ( Vector2  compositionSize)

Resize automatic sizes in user composition target if necessary.

Parameters
compositionSizeComposition size to resize to.

◆ onDetached()

void kanzi::NodeCompositor2D::onDetached ( )

Run when node owning the compositor becomes detached.

◆ restoreResources()

void kanzi::NodeCompositor2D::restoreResources ( Vector2  compositionSize)

Restore resources.

Will restore all GL resources and resize render targets with automatic size.

Parameters
compositionSizeComposition size to resize to.

◆ updateRender()

void kanzi::NodeCompositor2D::updateRender ( Node2D node,
Vector2  actualSize,
bool  alphaRequired,
bool  depthRequired,
bool  stencilRequired,
float  opacity,
bool  opaquenessHint,
bool  translucencyHint 
)

Update for rendering, recreating composition targets and brush renderers as needed.

Parameters
nodeNode to attach to.
actualSizeSize required of the composition target.
alphaRequiredAlpha requirement.
depthRequiredDepth requirement.
stencilRequiredStencil requirement.
opacityOpacity value that should be used for rendering.
opaquenessHintShould opaque rendering especially be used?
translucencyHintShould translucent rendering especially be used?

◆ getCompositionBrushRenderer()

BrushRenderer* kanzi::NodeCompositor2D::getCompositionBrushRenderer ( ) const
inline

Access composition brush renderer.

◆ hasCompositionBrushRenderer()

bool kanzi::NodeCompositor2D::hasCompositionBrushRenderer ( ) const
inline

Tell if composition brush renderer has been created.

◆ setUserCompositionBrush()

void kanzi::NodeCompositor2D::setUserCompositionBrush ( BrushSharedPtr  brush)
inline

Set user composition brush.

◆ getUserCompositionTargetSize()

Vector2 kanzi::NodeCompositor2D::getUserCompositionTargetSize ( ) const

Gets the size of user composition target.

Returns
Size of composition target or zero vector.

◆ hasUserCompositionTarget()

bool kanzi::NodeCompositor2D::hasUserCompositionTarget ( ) const
inline

Indicates whether user composition target is set.

Returns
If user composition target has been set true, otherwise false.

◆ setUserCompositionTarget()

void kanzi::NodeCompositor2D::setUserCompositionTarget ( TextureSharedPtr  texture)
inline

Set user composition target.

◆ invalidateCompositionBrush()

void kanzi::NodeCompositor2D::invalidateCompositionBrush ( )
inline

Invalidate composition brush.

◆ getCachingMode()

CachingMode kanzi::NodeCompositor2D::getCachingMode ( ) const
inline

Gets the caching mode stored in the compositor.

Returns
Caching mode.

◆ enableCaching()

void kanzi::NodeCompositor2D::enableCaching ( CachingMode  mode)
inline

Enable caching.

Parameters
modeNew caching mode, must not be CachingModeDisabled.

◆ disableCaching()

void kanzi::NodeCompositor2D::disableCaching ( )
inline

Disable caching.

◆ isCacheValid()

bool kanzi::NodeCompositor2D::isCacheValid ( ) const
inline

Indicates whether or not the cache is valid.

Returns
True if yes, false if no.

◆ setCacheValid()

void kanzi::NodeCompositor2D::setCacheValid ( bool  valid)
inline

Set cache validity flag.

Parameters
validCache status flag.

◆ isCompositionRequired()

bool kanzi::NodeCompositor2D::isCompositionRequired ( ) const
inline

Indicates whether compositing the node is required.

This query does not take draw flags into account.

Returns
If composition is required true, otherwise false.

◆ isCompositionPotentiallyRequired()

bool kanzi::NodeCompositor2D::isCompositionPotentiallyRequired ( ) const
inline

Indicates whether composition can potentially be required during rendering.

This status is in addition to the obligatory requirement.

Returns
If composition may be required during rendering, true, otherwise false.

◆ isCompositionRequiredDuringRendering()

bool kanzi::NodeCompositor2D::isCompositionRequiredDuringRendering ( const optional< Matrix3x3 > &  transform,
bool  drawFlagSet 
) const

Indicates whether compositing the node is required during rendering.

This status is in addition to the obligatory requirement.

Parameters
transformLocal override transform for the node.
drawFlagSetWhether the draw flag is set for the node or any of its descendants.
Returns
If composition is required during rendering true, otherwise false.

◆ isCompositionRequested()

bool kanzi::NodeCompositor2D::isCompositionRequested ( ) const
inline

Indicates whether composition is requested from code.

Returns
If flag is set true, otherwise false.

◆ setCompositionRequested()

void kanzi::NodeCompositor2D::setCompositionRequested ( bool  enabled)
inline

Sets the compositing request.

Parameters
enabledNew flag state.

◆ isForceComposition()

bool kanzi::NodeCompositor2D::isForceComposition ( ) const
inline

Indicates whether force composition flag is set.

Returns
If flag is set true, otherwise false.

◆ setForceComposition()

void kanzi::NodeCompositor2D::setForceComposition ( bool  enabled)
inline

Sets force composition.

Parameters
enabledNew flag state.

◆ isOffscreenRendering()

bool kanzi::NodeCompositor2D::isOffscreenRendering ( ) const
inline

Indicates whether offscreen rendering is enabled.

Returns
If flag is set true, otherwise false.

◆ setOffscreenRendering()

void kanzi::NodeCompositor2D::setOffscreenRendering ( bool  enabled)
inline

Sets the offscreen rendering flag.

Parameters
enabledNew flag state.

◆ isOpacityCompositionRequest()

bool kanzi::NodeCompositor2D::isOpacityCompositionRequest ( ) const
inline

Indicates whether composition due to opacity is requested.

Returns
If flag is set true, otherwise false.

◆ setOpacityCompositionRequested()

void kanzi::NodeCompositor2D::setOpacityCompositionRequested ( bool  enabled)
inline

Sets the opacity composition request flag.

Parameters
enabledNew flag state.

◆ isPerspectiveCompositionRequested()

bool kanzi::NodeCompositor2D::isPerspectiveCompositionRequested ( ) const
inline

Indicates whether composition due to perspective transform is requested.

Returns
If flag is set true, otherwise false.

◆ setPerspectiveCompositionRequested()

void kanzi::NodeCompositor2D::setPerspectiveCompositionRequested ( bool  enabled)
inline

Sets the perspective composition request flag.

Parameters
enabledNew flag state.

◆ isPotentialCompositionBitViewport()

bool kanzi::NodeCompositor2D::isPotentialCompositionBitViewport ( ) const
inline

Indicates whether potential composition request flag is set.

Returns
If flag is set true, otherwise false.

◆ setPotentialCompositionBitVierport()

void kanzi::NodeCompositor2D::setPotentialCompositionBitVierport ( bool  enabled)
inline

Sets the potential composition request flag.

Parameters
enabledNew flag state.

◆ getManagedCompositionTarget()

TextureSharedPtr kanzi::NodeCompositor2D::getManagedCompositionTarget ( ) const
inline

Gets the managed composition target.

Returns
Current composition target.

◆ hasManagedCompositionTarget()

bool kanzi::NodeCompositor2D::hasManagedCompositionTarget ( ) const
inline

Indicates whether a managed composition target has been allocated.

Returns
If the managed composition target exists true, otherwise false.

◆ setEffect()

void kanzi::NodeCompositor2D::setEffect ( NodeEffect2D effect)

Sets the active effect or clears the active effect with empty shared pointer.

Since
Kanzi 3.9.0
Parameters
effectEffect instance or empty shared pointer.

◆ getEffect()

NodeEffect2D* kanzi::NodeCompositor2D::getEffect ( ) const

Gets the active effect or null pointer.

Returns
Effect instance or nullptr.
Since
Kanzi 3.9.0

◆ getEffectRenderer()

NodeEffectRenderer2D* kanzi::NodeCompositor2D::getEffectRenderer ( ) const
inline

Gets the active effect renderer or null pointer if compositor has no active effect.

Returns
NodeEffectRender2D instance or null pointer.
Since
Kanzi 3.9.0

Member Data Documentation

◆ m_managedCompositionTarget

TextureSharedPtr kanzi::NodeCompositor2D::m_managedCompositionTarget
protected

Current framebuffer.

◆ m_cachingMode

CachingMode kanzi::NodeCompositor2D::m_cachingMode
protected

Caching mode setting.

◆ m_cacheValid

bool kanzi::NodeCompositor2D::m_cacheValid
protected

Cache status flag.

◆ m_userCompositionBrush

BrushSharedPtr kanzi::NodeCompositor2D::m_userCompositionBrush
protected

User-set composition brush.

◆ m_userCompositionTarget

TextureSharedPtr kanzi::NodeCompositor2D::m_userCompositionTarget
protected

User-set composition target.

◆ m_managedCompositionBrush

CompositionBrushSharedPtr kanzi::NodeCompositor2D::m_managedCompositionBrush
protected

Composition brush managed by node.

◆ m_compositionBrushRenderer

BrushRendererPtr kanzi::NodeCompositor2D::m_compositionBrushRenderer
protected

Composition brush renderer.

◆ m_opaquenessHint

bool kanzi::NodeCompositor2D::m_opaquenessHint
protected

Saved opaqueness hint.

◆ m_translucencyHint

bool kanzi::NodeCompositor2D::m_translucencyHint
protected

Saved tTranslucency hint.

◆ m_brushRenderersDirty

bool kanzi::NodeCompositor2D::m_brushRenderersDirty
protected

Brush renderer dirty flag.

◆ m_compositingMask

bitset<CompositingBitCount> kanzi::NodeCompositor2D::m_compositingMask
protected

Bit mask for states affecting whether or not the node should compose itself and its children.

◆ m_potentialCompositingMask

bitset<PotentialCompositingBitCount> kanzi::NodeCompositor2D::m_potentialCompositingMask
protected

Bit mask for states affecting whether or not the node should potentially compose itself and its children.

◆ m_state

optional<CompositionState> kanzi::NodeCompositor2D::m_state
protected

Active composition state, or nullopt if the composition is not active.

◆ m_effectRenderer

NodeEffectRenderer2DUniquePtr kanzi::NodeCompositor2D::m_effectRenderer
protected

Effect renderer instance, or null if no effect is active.


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