OpenGUI::Brush Class Reference

#include <OpenGUI_Brush.h>

Inheritance diagram for OpenGUI::Brush:

Detailed Description

The base of all widget rendering operations.

The Brush object is provided during widget onDraw events, and is used by the widget to draw itself. Functions that should use the Brush object will be provided one as a function parameter.

Modifier Stack:: Brushes implement stack modifiers that are applied to all output they generate. The available modifiers are color, clipping rects, output mask, position offsets, and rotations about the origin. These modifiers are not retroactive. For instance, changing the color modifier will not alter the color of operations you have already performed, it will only affect new operations.

: Each brush is created with a completely empty modifier stack. That doesn't mean that the brush you may have received in a draw function has an empty stack (as the caller will likely have initialized the brush with some stack pushes)

: The stack is always processed from top to bottom. (The last modifier you pushed is applied first, and the first modifier pushed is applied last.) Also, certain stack modifiers are "sticky". This means that the first one of these "sticky" modifiers evaluated will be the only modifier of that type that is evaluated. For instance, color is sticky. If you push the color Blue and then later push the color Red, the output will be Red (not purple) until the Red is popped, at which time the color will return to Blue. Conversely, the position modifier is additive. So multiple pushed position modifiers will result in an overall origin translation that equals their sum.

: Another important concept to understand is that stack operations are non-commutative. In other words, they affect each other in order dependent ways. What this means is that if you pushPosition and then pushRotation, the rotation will occur at the new origin, not the original origin. The same applies for clipping rects and masks. You can perform a rotation to an arbitrary angle, and then apply a clipping rect or mask, followed by the inverse of the previously used angle, and you will have created a non-axis aligned clipping rect or mask. Very powerful indeed.

: As much fun as these modifiers are, they come with a price tag. The more stack operations you add, the more operations must be applied to your output. We do our best to optimize the process, but nothing is perfect. Basically, if you're responsible you'll never run into performance issues.

Position Modifier:

Function: pushPosition()

: Position modifiers are offsets that will be applied (added) to each operation you perform. This is effectively like translating the origin to the given position.

Rotation Modifier:

Function: pushRotation()

: Rotation modifiers are origin centered rotations that will be applied to each operation you perform.

Color Modifier:

sticky
Function: pushColor()

: The last pushed color modifier will be used as the base color for all output. If no color has ever been pushed, the default color is Color(1.0, 1.0, 1.0, 1.0)

Clipping Rect Modifier:

Function: pushClippingRect()

: Clipping rects will perform geometric clipping to the operations performed. Position and rotation modifiers can be combined with clipping rects to perform non-axis aligned clips.

Mask Modifier:

sticky
Function: pushMask(), pushMaskUnscaled()

: Masks are imagery that are used to determine alpha visibility on a texel level. You can create alpha masks of any shape and apply them using this modifier.

Public Member Functions

Brush ()

Constructor.

virtual ~Brush ()

Destructor.

void pushPosition (float x_offset, float y_offset)

Pushes a position offset onto the stack.

void pushPosition (const FVector2 &offset)

Pushes a position offset onto the stack.

void pushRotation (const Radian &angle)

Pushes a rotation offset onto the stack.

void pushColor (const Color &color)

Pushes a new color onto the stack.

void pushAlpha (float alpha)

Pushes another layer of alpha transparency onto the stack.

void pushClippingRect (const FRect &rect)

Pushes a new clipping rect onto the stack.

void pushMask (ImageryPtr mask_imagery, const FRect &mask_rect)

Pushes an imagery based mask onto the stack.

void pushMaskUnscaled (ImageryPtr mask_imagery, const FVector2 &mask_position)

Pushes an imagery based mask onto the stack.

void pushPixelAlignment ()

Pushes a position offset onto the stack that aligns the origin with the nearest pixel of this Brush's output target.

void pop ()

Pops the last modifier off the stack.

void _pushMarker (void *markerID)

void _popMarker (void *markerID)

virtual const FVector2 & getPPU_Raw () const =0

Returns the raw (uncorrected) PPU (pixels per unit) of this Brush.

virtual const FVector2 & getUPI_Raw () const =0

Returns the raw (uncorrected) UPI (units per inch) of this Brush.

const Radian & getRotation ()

returns the Brush's current total rotation

const FVector2 & getPPU ()

Returns the PPU mapped against the Brush's current rotation.

const FVector2 & getUPI ()

Returns the UPI mapped against the Brush's current rotation.

virtual bool isRTTContext () const =0

returns true if the brush context is a render to texture surface

Public Attributes

BrushPrimitive Primitive

access to primitive drawing operations

BrushImagery Image

access to imagery based drawing operations

BrushText Text

access to text drawing operations

Protected Member Functions

virtual void appendRenderOperation (RenderOperation &renderOp)

Final output RenderOperations are passed to this function.

virtual void onActivate ()=0

Called automatically when this Brush becomes the active Brush.

virtual void onClear ()=0

Called when this Brush has been told to clear the contents of its render surface.

void markActive ()

Marks this brush as the active brush, if it is not already.

bool isActive ()

returns true if this is marked as the active brush

void _clear ()

Clears the contents of this Brush's output target.

Constructor & Destructor Documentation

OpenGUI::Brush::Brush ( )

Constructor.

OpenGUI::Brush::~Brush ( ) [virtual]

Destructor.

Member Function Documentation

void OpenGUI::Brush::_clear ( ) [protected]

Clears the contents of this Brush's output target.
This is not something that most users would want to do.

void OpenGUI::Brush::_popMarker ( void * markerID )

Warning:
pushMarker and popMarker are dangerous. They are used internally within OpenGUI and really should not be required by any Widgets for drawing.
When popping back to a marker, if the given marker cannot be found the entire stack will be popped as a result of looking for it. If a marker is found while popping that is not the marker given, an exception will be thrown.

void OpenGUI::Brush::_pushMarker ( void * markerID )

See also:
_popMarker()

virtual void OpenGUI::Brush::appendRenderOperation ( RenderOperation & renderOp ) [inline, protected, virtual]

Final output RenderOperations are passed to this function.
It is up to specialized Brush implementations to capture final output with this function. At this point, the Brush is guaranteed to already to be active.
Reimplemented in OpenGUI::Brush_Caching, OpenGUI::Brush_Memory, and OpenGUI::Brush_RTT.

const FVector2 & OpenGUI::Brush::getPPU ( )

Returns the PPU mapped against the Brush's current rotation.

See also:
Screen::getPPU()

virtual const FVector2& OpenGUI::Brush::getPPU_Raw ( ) const [pure virtual]

Returns the raw (uncorrected) PPU (pixels per unit) of this Brush.

See also:
Screen::getPPU()

Implemented in OpenGUI::Brush_Caching, OpenGUI::Brush_Memory, and OpenGUI::Brush_RTT.

const Radian & OpenGUI::Brush::getRotation ( )

returns the Brush's current total rotation

const FVector2 & OpenGUI::Brush::getUPI ( )

Returns the UPI mapped against the Brush's current rotation.

See also:
Screen::getPPU()

virtual const FVector2& OpenGUI::Brush::getUPI_Raw ( ) const [pure virtual]

Returns the raw (uncorrected) UPI (units per inch) of this Brush.

See also:
Screen::getUPI()

Implemented in OpenGUI::Brush_Caching, OpenGUI::Brush_Memory, and OpenGUI::Brush_RTT.

bool OpenGUI::Brush::isActive ( ) [protected]

returns true if this is marked as the active brush

virtual bool OpenGUI::Brush::isRTTContext ( ) const [pure virtual]

returns true if the brush context is a render to texture surface

Implemented in OpenGUI::Brush_Caching, OpenGUI::Brush_Memory, and OpenGUI::Brush_RTT.

void OpenGUI::Brush::markActive ( ) [protected]

Marks this brush as the active brush, if it is not already.

virtual void OpenGUI::Brush::onActivate ( ) [protected, pure virtual]

Called automatically when this Brush becomes the active Brush.

Implemented in OpenGUI::Brush_Caching, OpenGUI::Brush_Memory, and OpenGUI::Brush_RTT.

virtual void OpenGUI::Brush::onClear ( ) [protected, pure virtual]

Called when this Brush has been told to clear the contents of its render surface.
The Brush is guaranteed to be active at this point
Implemented in OpenGUI::Brush_Caching, OpenGUI::Brush_Memory, and OpenGUI::Brush_RTT.

void OpenGUI::Brush::pop ( )

Pops the last modifier off the stack.

void OpenGUI::Brush::pushAlpha ( float alpha )

Pushes another layer of alpha transparency onto the stack.

void OpenGUI::Brush::pushClippingRect ( const FRect & rect )

Pushes a new clipping rect onto the stack.

void OpenGUI::Brush::pushColor ( const Color & color )

Pushes a new color onto the stack.

void OpenGUI::Brush::pushMask ( ImageryPtr mask_imagery,

const FRect & mask_rect

)

Pushes an imagery based mask onto the stack.

void OpenGUI::Brush::pushMaskUnscaled ( ImageryPtr mask_imagery,

const FVector2 & mask_position

)

Pushes an imagery based mask onto the stack.

void OpenGUI::Brush::pushPixelAlignment ( )

Pushes a position offset onto the stack that aligns the origin with the nearest pixel of this Brush's output target.
This is as close to pixel alignment as you can get. Things like rotation will cause inaccurate results, but in those cases pixel alignment is neither achievable nor necessary.

void OpenGUI::Brush::pushPosition ( const FVector2 & offset )

Pushes a position offset onto the stack.

void OpenGUI::Brush::pushPosition ( float x_offset,

float y_offset

)

Pushes a position offset onto the stack.

void OpenGUI::Brush::pushRotation ( const Radian & angle )

Pushes a rotation offset onto the stack.
Positive values result in clockwise rotation.

Member Data Documentation

BrushImagery OpenGUI::Brush::Image

access to imagery based drawing operations

BrushPrimitive OpenGUI::Brush::Primitive

access to primitive drawing operations

BrushText OpenGUI::Brush::Text

access to text drawing operations

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

OpenGUI_Brush.h
OpenGUI_Brush.cpp


Public Member Functions
	Brush ()
	Constructor.
virtual	~Brush ()
	Destructor.
void	pushPosition (float x_offset, float y_offset)
	Pushes a position offset onto the stack.
void	pushPosition (const FVector2 &offset)
	Pushes a position offset onto the stack.
void	pushRotation (const Radian &angle)
	Pushes a rotation offset onto the stack.
void	pushColor (const Color &color)
	Pushes a new color onto the stack.
void	pushAlpha (float alpha)
	Pushes another layer of alpha transparency onto the stack.
void	pushClippingRect (const FRect &rect)
	Pushes a new clipping rect onto the stack.
void	pushMask (ImageryPtr mask_imagery, const FRect &mask_rect)
	Pushes an imagery based mask onto the stack.
void	pushMaskUnscaled (ImageryPtr mask_imagery, const FVector2 &mask_position)
	Pushes an imagery based mask onto the stack.
void	pushPixelAlignment ()
	Pushes a position offset onto the stack that aligns the origin with the nearest pixel of this Brush's output target.
void	pop ()
	Pops the last modifier off the stack.
void	_pushMarker (void *markerID)
void	_popMarker (void *markerID)
virtual const FVector2 &	getPPU_Raw () const =0
	Returns the raw (uncorrected) PPU (pixels per unit) of this Brush.
virtual const FVector2 &	getUPI_Raw () const =0
	Returns the raw (uncorrected) UPI (units per inch) of this Brush.
const Radian &	getRotation ()
	returns the Brush's current total rotation
const FVector2 &	getPPU ()
	Returns the PPU mapped against the Brush's current rotation.
const FVector2 &	getUPI ()
	Returns the UPI mapped against the Brush's current rotation.
virtual bool	isRTTContext () const =0
	returns true if the brush context is a render to texture surface
Public Attributes
BrushPrimitive	Primitive
	access to primitive drawing operations
BrushImagery	Image
	access to imagery based drawing operations
BrushText	Text
	access to text drawing operations
Protected Member Functions
virtual void	appendRenderOperation (RenderOperation &renderOp)
	Final output RenderOperations are passed to this function.
virtual void	onActivate ()=0
	Called automatically when this Brush becomes the active Brush.
virtual void	onClear ()=0
	Called when this Brush has been told to clear the contents of its render surface.
void	markActive ()
	Marks this brush as the active brush, if it is not already.
bool	isActive ()
	returns `true` if this is marked as the active brush
void	_clear ()
	Clears the contents of this Brush's output target.