An interface for specialized brush renderers, which implement brush rendering. More...

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

Inheritance diagram for kanzi::BrushRenderer:

Public Types
enum	RenderMode { RenderModeNone, RenderModeContent, RenderModeNoContent }
	Enum signifying currently selected render mode. More...

Public Member Functions
MaterialSharedPtr	acquireErrorMaterial ()
	Acquires an error material for rendering. More...

void	attachMaterial (MaterialSharedPtr material)
	Attaches a custom material. More...

void	bind (Renderer3D &renderer, PropertyObject *object)
	Binds a brush renderer for rendering. More...

void	bind (Renderer3D &renderer)
	Binds a brush renderer for rendering. More...

void	draw (Renderer &renderer, const Geometry &quad, const Matrix4x4 &transform)
	Draws a brush using a given quad. More...

void	draw (Renderer &renderer, const Geometry &quad, const Matrix3x3 &transform)
	Overload for drawing a brush using a given quad. More...

optional< int >	getBlendModeOverride () const
	Gets the blend mode override value. More...

int	getBlendModeValue () const
	Gets the last used blend mode value. More...

Brush *	getBrush () const
	Gets the brush for which Kanzi created this brush renderer. More...

TextureSharedPtr	getContentTexture () const
	Gets the content texture used by the brush renderer. More...

MaterialSharedPtr	getMaterial () const
	Gets the currently set material for the renderer. More...

Node *	getNode () const
	Gets the attached node. More...

bool	getOpaquenessHint () const
	Gets the opaqueness hint value. More...

unsigned int	getPropertyChangeCounter () const
	Gets the brush property change counter. More...

RenderMode	getRenderMode () const
	Gets the currently selected render mode. More...

float	getRenderOpacity () const
	Gets the render opacity. More...

GlRenderState &	getRenderState ()
	Gets the internal render state. More...

void	invalidateRenderValues ()
	Invalidates all render values. More...

bool	isOpaque () const
	Indicates whether the rendered brush is opaque. More...

bool	isRenderable () const
	Indicates whether a brush is in a renderable state. More...

void	restoreResources ()
	Restores resources after sleep. More...

void	setBlendModeOverride (optional< int > blendMode)
	Sets the blend mode override value. More...

void	setContentTexture (TextureSharedPtr texture)
	Sets the content texture for the brush renderer. More...

void	setOpaquenessHint (bool value)
	Sets the opaqueness hint. More...

void	setRenderOpacity (float opacity)
	Sets the render opacity to use for the next attach. More...

void	updateRender ()
	Prepares a brush for rendering. More...

virtual	~BrushRenderer ()=default
	Destructor. More...

Protected Member Functions
virtual bool	bindOverride (Renderer3D &renderer, PropertyObject *object)
	BrushRenderer-specific bind implementation. More...

	BrushRenderer (Brush brush, Node node)
	Constructor. More...

virtual void	drawOverride (Renderer &renderer, const Geometry &geometry, const Matrix4x4 &transform)=0
	Draws geometry using the brush. More...

virtual bool	isChangeCounterSame ()
	Checks whether the property change counter matches that of the brush. More...

virtual void	restoreResourcesOverride ()
	BrushRenderer-specific restore resources implementation. More...

virtual void	setContentTextureOverride (TextureSharedPtr texture)
	BrushRenderer-specific update of the content texture. More...

void	setRenderMode (RenderMode selection)
	Sets the render mode. More...

virtual void	updateChangeCounter ()
	Updates the property change counter to match the counter value from the brush. More...

virtual void	updateRenderOverride ()=0
	BrushRenderer-specific opacity override implementation. More...

Protected Attributes
Brush *	m_brush
	Brush attached to. More...

unsigned int	m_brushPropertyChangeCounter
	Property change counter to track brush. More...

TextureSharedPtr	m_contentTexture
	Content texture provided to the brush renderer from outside. For example, from Node2D. More...

GlRenderState::HandleType	m_contentTextureHandle
	Render value handle. More...

bool	m_isRenderable
	Indicates whether the last bind() call was successful and the brush can be rendered. More...

Node *	m_node
	Node attached to. More...

RenderMode	m_renderMode
	Currently used render mode (or none if not selected). More...

float	m_renderOpacity
	Render opacity provided to the brush renderer from outside. For example, from Node2D. More...

GlRenderState::HandleType	m_renderOpacityHandle
	Render value handle. More...

GlRenderState	m_renderState
	Contained render state. More...

GlRenderValueBinding	m_renderValueBinding
	Property binding handler. More...

Detailed Description

An interface for specialized brush renderers, which implement brush rendering.

You can use the BrushRenderer to render a brush manually.

To render a brush manually:

Create the brush renderer by calling the implementation of the Brush::createBrushRenderer() function in the class of the brush type that you want to render.
Call setContentTexture() to set the content texture for the brush renderer.

You must do this before you call updateRender().
Call updateRender() to prepare the brush for rendering.

You must call updateRender() once after you set the content texture and before you bind the brush renderer for rendering. You do not need to call this function every time after changing the content texture, unless you change the content texture to or from nullptr.
Call setRenderOpacity() to set the render opacity.

You can do this before or after calling updateRender().
(Optional) If you want to set the blend mode as determined by layouting, call setBlendModeOverride().

This function takes precedence over the blend mode that the renderer reads from the brush.
(Optional) If you want to indicate that a node can be rendered using opaque blend mode, call setOpaquenessHint().

For example, this happens when a node is rendered as the bottom-most element in a framebuffer.
Call bind() every frame before you render with the brush.
To draw with the brush, call draw().

After you call bind(), you can call draw() multiple times for different geometries and transformations.

For example:

    // Create a brush.
    BrushSharedPtr brush = ColorBrush::create(domain, "My Color Brush", ColorRGBA(0.4f, 0.7f, 0.8f, 1.0f));
    // Create a brush renderer for the brush.
    // If you render for a node, pass to this function the pointer to that node.
    BrushRendererPtr brushRenderer = brush->createBrushRenderer(nullptr);
    // Set the content texture for the brush renderer.
    // You must do this before you call updateRender().
    // You need to call updateRender() again only if you change the content texture to or from nullptr.
    // The default is nullptr.
    brushRenderer->setContentTexture(nullptr);
    // Prepare the brush for rendering.
    // You need to call updateRender() only once.
    brushRenderer->updateRender();
    // Set the blend mode override before you call bind().
    // This is the blend mode from the layouting phase.
    // To read the blend mode from the brush, use nullopt (default value).
    brushRenderer->setBlendModeOverride(nullopt);
    // When you want to indicate that the brush can be rendered with the opaque blend mode,
    // set the opaqueness hint before you call bind().
    // For example, when a brush is rendered as the first element at the back of a framebuffer,
    // set the opaqueness hint to true.
    // The default is false.
    brushRenderer->setOpaquenessHint(false);
    // Bind the brush for rendering.
    // You must call bind() every frame before rendering with the brush.
    brushRenderer->bind(*renderer3d);
    // Draw using the brush.
    // You can call draw() multiple times for different geometries and transformations after you call bind().
    Matrix3x3 transform = Matrix3x3::createTranslation(50.0f, 10.0f);
    brushRenderer->draw(*renderer, *geometry, transform);

Since: Kanzi 3.9.9 removed the hasRenderMode() function.

Member Enumeration Documentation

enum kanzi::BrushRenderer::RenderMode

Enum signifying currently selected render mode.

Enumerator

RenderModeNone

No selection.

RenderModeContent

Content specified for brush.

Since: Kanzi 3.9.1

RenderModeNoContent

No content specified for brush.

Since: Kanzi 3.9.1

Constructor & Destructor Documentation

virtual kanzi::BrushRenderer::~BrushRenderer ( )

virtualdefault

Destructor.

kanzi::BrushRenderer::BrushRenderer	(	Brush *	brush,
		Node *	node
	)

explicitprotected

Constructor.

Parameters

node	The node to which to attach the renderer.
brush	The brush to which to attach the renderer.

Member Function Documentation

void kanzi::BrushRenderer::updateRender ( )

inline

Prepares a brush for rendering.

Called from Node2D::updateRender(), which calls NodeVisual2D::updateRender(). Kanzi calls this function during layout.

Call this function after the brush material or attached nodes change. Unlike bind(), you do not need to call updateRender() every frame before draw().

If the render mode of a brush does not change, implementations of this function do nothing.

Since: Kanzi 3.9.1 added blendMode parameter.; Kanzi 3.9.6 removed forceOpaque parameter.; Kanzi 3.9.9 removed blendMode and translucencyHint parameters.

void kanzi::BrushRenderer::bind	(	Renderer3D &	renderer,
		PropertyObject *	object
	)

inline

Binds a brush renderer for rendering.

You must call this function before you call draw(). This function sets the renderable flag that you can query with isRenderable().

Parameters

renderer	The renderer to use.
object	The object from which to fetch properties.

Since: Kanzi 3.9.7 moved here from MaterialBrushRenderer.

void kanzi::BrushRenderer::bind ( Renderer3D & renderer )

inline

Binds a brush renderer for rendering.

You must call this function before you call draw(). This function sets the renderable flag that you can query with isRenderable().

Parameters

renderer Renderer to use.

void kanzi::BrushRenderer::draw	(	Renderer &	renderer,
		const Geometry &	quad,
		const Matrix4x4 &	transform
	)

Draws a brush using a given quad.

Parameters

renderer	Renderer to use.
quad	Quad to draw.
transform	The transform as a 4x4 matrix to use.

void kanzi::BrushRenderer::draw	(	Renderer &	renderer,
		const Geometry &	quad,
		const Matrix3x3 &	transform
	)

inline

Overload for drawing a brush using a given quad.

Parameters

renderer	Renderer to use.
quad	Quad to draw.
transform	The transform as a 3x3 matrix to use.

void kanzi::BrushRenderer::restoreResources ( )

inline

Restores resources after sleep.

Brush* kanzi::BrushRenderer::getBrush ( ) const

inline

Gets the brush for which Kanzi created this brush renderer.

Returns: Brush pointer.

GlRenderState& kanzi::BrushRenderer::getRenderState ( )

inline

Gets the internal render state.

Returns: Reference to the render state.

Since: Kanzi 3.9.7

void kanzi::BrushRenderer::invalidateRenderValues ( )

inline

Invalidates all render values.

Since: Kanzi 3.9.7

MaterialSharedPtr kanzi::BrushRenderer::acquireErrorMaterial ( )

Acquires an error material for rendering.

Kanzi uses this function internally when the assigned material is not applicable.

Returns: Error material.

Since: Kanzi 3.9.7

unsigned int kanzi::BrushRenderer::getPropertyChangeCounter ( ) const

inline

Gets the brush property change counter.

Returns: Brush property change counter.

float kanzi::BrushRenderer::getRenderOpacity ( ) const

inline

Gets the render opacity.

Returns: Current render opacity.

void kanzi::BrushRenderer::setRenderOpacity ( float opacity )

inline

Sets the render opacity to use for the next attach.

Parameters

opacity New render opacity.

TextureSharedPtr kanzi::BrushRenderer::getContentTexture ( ) const

inline

Gets the content texture used by the brush renderer.

Returns: Current content texture.

void kanzi::BrushRenderer::setContentTexture ( TextureSharedPtr texture )

inline

Sets the content texture for the brush renderer.

Parameters

texture The content texture.

Node* kanzi::BrushRenderer::getNode ( ) const

inline

Gets the attached node.

Returns: Node pointer.

RenderMode kanzi::BrushRenderer::getRenderMode ( ) const

inline

Gets the currently selected render mode.

Returns: Current render mode.

bool kanzi::BrushRenderer::isRenderable ( ) const

inline

Indicates whether a brush is in a renderable state.

To set the renderable flag, call bind().

Returns: If the brush is in a renderable state true, otherwise false.

Since: Kanzi 3.9.9

MaterialSharedPtr kanzi::BrushRenderer::getMaterial ( ) const

Gets the currently set material for the renderer.

Returns: Shared pointer to the material that is currently set for the brush renderer. If not set, returns nullptr.

Since: Kanzi 3.9.7 made the function non-virtual.; Kanzi 3.9.9 made the function const.

int kanzi::BrushRenderer::getBlendModeValue ( ) const

Gets the last used blend mode value.

This function is intended for tests.

Returns: Blend mode.

Since: Kanzi 3.9.1; Kanzi 3.9.9 made the function const.

void kanzi::BrushRenderer::setBlendModeOverride ( optional< int > blendMode )

inline

Sets the blend mode override value.

This is the blend mode as determined by layouting. Calling this function has precedence over the blend mode read from brush or material.

Parameters

blendMode Blend mode.

Since: Kanzi 3.9.9

optional<int> kanzi::BrushRenderer::getBlendModeOverride ( ) const

inline

Gets the blend mode override value.

This function is intended for tests.

Returns: Blend mode override value.

Since: Kanzi 3.9.9

void kanzi::BrushRenderer::setOpaquenessHint ( bool value )

inline

Sets the opaqueness hint.

This hint indicates whether a node can be rendered using opaque blend mode. For example, this happens when a node is rendered as the bottom-most element in a framebuffer.

Parameters

value Opaqueness hint value.

Since: Kanzi 3.9.9

bool kanzi::BrushRenderer::getOpaquenessHint ( ) const

inline

Gets the opaqueness hint value.

This function is intended for tests.

Returns: Opaqueness hint value.

Since: Kanzi 3.9.9

bool kanzi::BrushRenderer::isOpaque ( ) const

inline

Indicates whether the rendered brush is opaque.

Returns: If the brush is opaque, true, otherwise false.

Since: Kanzi 3.9.9

void kanzi::BrushRenderer::attachMaterial ( MaterialSharedPtr material )

Attaches a custom material.

This function internally calls BrushRenderer::attachMaterial().

Parameters

material The material to attach.

Since: Kanzi 3.9.7 moved to the base class.

virtual void kanzi::BrushRenderer::drawOverride	(	Renderer &	renderer,
		const Geometry &	geometry,
		const Matrix4x4 &	transform
	)

protectedpure virtual

Draws geometry using the brush.

To be implemented by specific brush implementations.

Parameters

renderer	Renderer to use.
geometry	Quad to draw.
transform	Transform to use.

Implemented in kanzi::TextureBrushRenderer, kanzi::ColorBrushRenderer, kanzi::MaterialBrushRenderer, and kanzi::ContentBrushRenderer.

virtual bool kanzi::BrushRenderer::bindOverride	(	Renderer3D &	renderer,
		PropertyObject *	object
	)

protectedvirtual

BrushRenderer-specific bind implementation.

Parameters

renderer	Renderer to use.
object	The object from which to fetch properties.

Returns: If the brush is renderable after binding, true, otherwise false.

Since: Kanzi 3.9.7 added object.; Kanzi 3.9.9 changed the type of the return value to bool.

Reimplemented in kanzi::TextureBrushRenderer, kanzi::ColorBrushRenderer, and kanzi::ContentBrushRenderer.

virtual void kanzi::BrushRenderer::updateRenderOverride ( )

protectedpure virtual

BrushRenderer-specific opacity override implementation.

Since: Kanzi 3.9.1 added blendMode parameter.; Kanzi 3.9.6 removed forceOpaque parameter.; Kanzi 3.9.9 removed blendMode and translucencyHint parameters.

Implemented in kanzi::TextureBrushRenderer, kanzi::ColorBrushRenderer, kanzi::MaterialBrushRenderer, and kanzi::ContentBrushRenderer.

virtual void kanzi::BrushRenderer::restoreResourcesOverride ( )

protectedvirtual

BrushRenderer-specific restore resources implementation.

virtual void kanzi::BrushRenderer::setContentTextureOverride ( TextureSharedPtr texture )

inlineprotectedvirtual

BrushRenderer-specific update of the content texture.

Parameters

texture New renderer texture.

Since: Kanzi 3.9.5

void kanzi::BrushRenderer::setRenderMode ( RenderMode selection )

inlineprotected

Sets the render mode.

Parameters

selection The render mode to set.

virtual bool kanzi::BrushRenderer::isChangeCounterSame ( )

protectedvirtual

Checks whether the property change counter matches that of the brush.

Returns: If the property change counter matches and no update is needed, true, otherwise false.

Since: Kanzi 3.9.7 made the function virtual.

Reimplemented in kanzi::MaterialBrushRenderer.

virtual void kanzi::BrushRenderer::updateChangeCounter ( )

protectedvirtual

Updates the property change counter to match the counter value from the brush.

Since: Kanzi 3.9.7 made the function virtual.

Reimplemented in kanzi::MaterialBrushRenderer.

Member Data Documentation

Brush* kanzi::BrushRenderer::m_brush

protected

Brush attached to.

Since: Kanzi 3.9.1 changed protection from private to protected.

Node* kanzi::BrushRenderer::m_node

protected

Node attached to.

RenderMode kanzi::BrushRenderer::m_renderMode

protected

Currently used render mode (or none if not selected).

GlRenderState kanzi::BrushRenderer::m_renderState

protected

Contained render state.

Since: Kanzi 3.9.7 moved to the base class.

GlRenderValueBinding kanzi::BrushRenderer::m_renderValueBinding

protected

Property binding handler.

Since: Kanzi 3.9.7 moved to the base class.

GlRenderState::HandleType kanzi::BrushRenderer::m_renderOpacityHandle

protected

Render value handle.

Since: Kanzi 3.9.7 moved to the base class.

GlRenderState::HandleType kanzi::BrushRenderer::m_contentTextureHandle

protected

Render value handle.

Since: Kanzi 3.9.7 moved to the base class.

TextureSharedPtr kanzi::BrushRenderer::m_contentTexture

protected

Content texture provided to the brush renderer from outside. For example, from Node2D.

float kanzi::BrushRenderer::m_renderOpacity

protected

Render opacity provided to the brush renderer from outside. For example, from Node2D.

unsigned int kanzi::BrushRenderer::m_brushPropertyChangeCounter

protected

Property change counter to track brush.

bool kanzi::BrushRenderer::m_isRenderable

protected

Indicates whether the last bind() call was successful and the brush can be rendered.

The return value from bindOverride() is written here.

Since: Kanzi 3.9.9

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

kanzi/core.ui/graphics2d/brush_renderer.hpp

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation