cugl::scene2::CanvasNode::Paint Class Reference

#include <CUCanvasNode.h>

Public Member Functions
	Paint ()
bool	initLinearGradient (Color4 inner, Color4 outer, const Vec2 start, const Vec2 end)
bool	initRadialGradient (Color4 inner, Color4 outer, const Vec2 center, float radius)
bool	initRadialGradient (Color4 inner, Color4 outer, const Vec2 center, float iradius, float oradius)
bool	initBoxGradient (Color4 inner, Color4 outer, const Rect bounds, float radius, float feather)
bool	initBoxGradient (Color4 inner, Color4 outer, const Vec2 origin, const Size size, float radius, float feather)
bool	initPattern (std::shared_ptr< Texture > texture, const Rect bounds)
bool	initPattern (std::shared_ptr< Texture > texture, const Vec2 origin, const Size size)
bool	isGradient () const
const Affine2 &	getTransform () const
void	setTransform (const Affine2 &transform)

Static Public Member Functions
static std::shared_ptr< Paint >	allocLinearGradient (Color4 inner, Color4 outer, const Vec2 start, const Vec2 end)
static std::shared_ptr< Paint >	allocRadialGradient (Color4 inner, Color4 outer, const Vec2 center, float radius)
static std::shared_ptr< Paint >	allocRadialGradient (Color4 inner, Color4 outer, const Vec2 center, float iradius, float oradius)
static std::shared_ptr< Paint >	allocBoxGradient (Color4 inner, Color4 outer, const Rect bounds, float radius, float feather)
static std::shared_ptr< Paint >	allocBoxGradient (Color4 inner, Color4 outer, const Vec2 origin, const Size size, float radius, float feather)
static std::shared_ptr< Paint >	allocPattern (std::shared_ptr< Texture > texture, const Rect bounds)
static std::shared_ptr< Paint >	allocPattern (std::shared_ptr< Texture > texture, const Vec2 origin, const Size size)

Friends
class	Command

Detailed Description

A combination gradient/texture for painting on the canvas.

Traditional Gradient and Texture objects use classic texture coordinates, making them somewhat difficult to use. A paint is a more user-friendly approach that allows you to define these elements using positional coordinates. This makes it easier to align gradients or images with the shapes that are drawn.

For example, suppose a paint is a linear gradient that starts at the origin and ends at position (100,100). If applied to a rectangle at the origin with size 100x100, this gradient will span the entire rectangle, running along the diagonal. However, if it is applied to a rectangle of size 200x200, it will stop in the center.

An important limitation of the canvas node architecture is that any shape can either colored by a gradient or a texture, but not both. You should use a special purpose scene graph node such as PolygonNode if you need both at the same time.

Constructor & Destructor Documentation

Paint()

cugl::scene2::CanvasNode::Paint::Paint

(

)

Creates an uninitialized paint.

You must initialize this paint before use. Otherwise it will not do anything do anything when applied.

NEVER USE A CONSTRUCTOR WITH NEW. If you want to allocate a Node on the heap, use one of the static constructors instead.

Member Function Documentation

allocBoxGradient() [1/2]

static std::shared_ptr< Paint > cugl::scene2::CanvasNode::Paint::allocBoxGradient ( Color4  inner, Color4  outer, const Rect  bounds, float  radius, float  feather  )

inlinestatic

Returns a new box gradient of the two colors.

Box gradients paint the inner color in a rounded rectangle, and then use a feather setting to transition to the outer color. To be well-defined, the corner radius should be no larger than half the width and height (at which point it defines a capsule). Shapes with abnormally large radii are undefined.

The feather value acts like the inner and outer radius of a radial gradient. If a line is drawn from the center of the round rectangle to a corner, consider two segments. The first starts at the corner and moves towards the center of the rectangle half-feather in distance. The end of this segment is the end of the inner color The second second starts at the corner and moves in the opposite direction the same amount. The end of this segement is the other color. In between, the colors are smoothly interpolated. Hence the feather effectively defines the pixel size of the transition zone.

This initializer is very similar to Gradient#initBox, except that the positions are given in the coordinate system of the canvas node, and not using texture coordinates.

Parameters

inner	The inner gradient color
outer	The outer gradient color
bounds	The bounds of the rounded rectangle.
radius	The corner radius of the rounded rectangle.
feather	The feather value for color interpolation

Returns

a new box gradient of the two colors.

allocBoxGradient() [2/2]

static std::shared_ptr< Paint > cugl::scene2::CanvasNode::Paint::allocBoxGradient ( Color4  inner, Color4  outer, const Vec2  origin, const Size  size, float  radius, float  feather  )

inlinestatic

Returns a new box gradient of the two colors.

Box gradients paint the inner color in a rounded rectangle, and then use a feather setting to transition to the outer color. To be well-defined, the corner radius should be no larger than half the width and height (at which point it defines a capsule). Shapes with abnormally large radii are undefined.

The feather value acts like the inner and outer radius of a radial gradient. If a line is drawn from the center of the round rectangle to a corner, consider two segments. The first starts at the corner and moves towards the center of the rectangle half-feather in distance. The end of this segment is the end of the inner color The second second starts at the corner and moves in the opposite direction the same amount. The end of this segement is the other color. In between, the colors are smoothly interpolated. Hence the feather effectively defines the pixel size of the transition zone.

This initializer is very similar to Gradient#initBox, except that the positions are given in the coordinate system of the canvas node, and not using texture coordinates.

Parameters

inner	The inner gradient color
outer	The outer gradient color
origin	The origin of the rounded rectangle.
size	The size of the rounded rectangle.
radius	The corner radius of the rounded rectangle.
feather	The feather value for color interpolation

Returns

a new box gradient of the two colors.

allocLinearGradient()

static std::shared_ptr< Paint > cugl::scene2::CanvasNode::Paint::allocLinearGradient ( Color4  inner, Color4  outer, const Vec2  start, const Vec2  end  )

inlinestatic

Returns a new linear gradient with the given start and end positions.

In a linear gradient, the inner starts at position start, and transitions to the outer color at position end. The transition is along the vector end-start.

This initializer is very similar to Gradient#initLinear, except that the positions are given in the coordinate system of the canvas node, and not using texture coordinates.

Parameters

inner	The inner gradient color
outer	The outer gradient color
start	The start position of the inner color
end	The start position of the outer color

Returns

a new linear gradient with the given start and end positions.

allocPattern() [1/2]

static std::shared_ptr< Paint > cugl::scene2::CanvasNode::Paint::allocPattern ( std::shared_ptr< Texture >  texture, const Rect  bounds  )

inlinestatic

Returns a new texture pattern with the given bounds.

When painting a texture pattern, the texture is sized and offset to fit within the given bounds. The texture will either be clamped or repeated outside of these bounds, depending upon the texture settings. As with all paints, these bounds are specified in the coordinate system of the canvas node, and not using texture coordinates.

Typically a texture pattern is applied to a shape that fully fits within the bounds. For example, if these bounds are the bounding box of a polygon, and this paint is applied to the polygon, the effect is the same as for a PolygonNode.

Parameters

texture	The texture to paint with
bounds	The bounding box to place the texture

Returns

a new texture pattern with the given bounds.

allocPattern() [2/2]

static std::shared_ptr< Paint > cugl::scene2::CanvasNode::Paint::allocPattern ( std::shared_ptr< Texture >  texture, const Vec2  origin, const Size  size  )

inlinestatic

Returns a new texture pattern with the given bounds.

When painting a texture pattern, the texture is sized and offset to fit within the given bounds. The texture will either be clamped or repeated outside of these bounds, depending upon the texture settings. As with all paints, these bounds are specified in the coordinate system of the canvas node, and not using texture coordinates.

Typically a texture pattern is applied to a shape that fully fits within the bounds. For example, if these bounds are the bounding box of a polygon, and this paint is applied to the polygon, the effect is the same as for a PolygonNode.

Parameters

texture	The texture to paint with
origin	The position of the texture bottom left corner
size	The size to scale the texture

Returns

a new texture pattern with the given bounds.

allocRadialGradient() [1/2]

static std::shared_ptr< Paint > cugl::scene2::CanvasNode::Paint::allocRadialGradient ( Color4  inner, Color4  outer, const Vec2  center, float  iradius, float  oradius  )

inlinestatic

Returns a new general radial gradient of the two colors.

In a general radial gradient, the inner color starts at the center and continues to the inner radius. It then transitions smoothly to the outer color at the outer radius.

This initializer is very similar to Gradient#initRadial, except that the positions are given in the coordinate system of the canvas node, and not using texture coordinates.

Parameters

inner	The inner gradient color
outer	The outer gradient color
center	The center of the radial gradient
iradius	The radius for the inner color
oradius	The radius for the outer color

Returns

a new general radial gradient of the two colors.

allocRadialGradient() [2/2]

static std::shared_ptr< Paint > cugl::scene2::CanvasNode::Paint::allocRadialGradient ( Color4  inner, Color4  outer, const Vec2  center, float  radius  )

inlinestatic

Returns a new simple radial gradient of the two colors.

In a simple radial gradient, the inner color starts at the center and transitions smoothly to the outer color at the given radius.

This initializer is very similar to Gradient#initRadial, except that the positions are given in the coordinate system of the canvas node, and not using texture coordinates.

Parameters

inner	The inner gradient color
outer	The outer gradient color
center	The center of the radial gradient
radius	The radius for the outer color

Returns

a new simple radial gradient of the two colors.

getTransform()

const Affine2 & cugl::scene2::CanvasNode::Paint::getTransform ( ) const

inline

Returns the local transform for this paint

Local transforms are applied to all drawing commands, including paints. This is necessary because the paints are specified in the coordinate system of the canvas node.

Returns

the local transform for this paint

initBoxGradient() [1/2]

bool cugl::scene2::CanvasNode::Paint::initBoxGradient ( Color4  inner, Color4  outer, const Rect  bounds, float  radius, float  feather  )

inline

Initializes a box gradient of the two colors.

Box gradients paint the inner color in a rounded rectangle, and then use a feather setting to transition to the outer color. To be well-defined, the corner radius should be no larger than half the width and height (at which point it defines a capsule). Shapes with abnormally large radii are undefined.

The feather value acts like the inner and outer radius of a radial gradient. If a line is drawn from the center of the round rectangle to a corner, consider two segments. The first starts at the corner and moves towards the center of the rectangle half-feather in distance. The end of this segment is the end of the inner color The second second starts at the corner and moves in the opposite direction the same amount. The end of this segement is the other color. In between, the colors are smoothly interpolated. Hence the feather effectively defines the pixel size of the transition zone.

This initializer is very similar to Gradient#initBox, except that the positions are given in the coordinate system of the canvas node, and not using texture coordinates.

Parameters

inner	The inner gradient color
outer	The outer gradient color
bounds	The bounds of the rounded rectangle.
radius	The corner radius of the rounded rectangle.
feather	The feather value for color interpolation

Returns

true if initialization was successful.

initBoxGradient() [2/2]

bool cugl::scene2::CanvasNode::Paint::initBoxGradient	(	Color4	inner,
		Color4	outer,
		const Vec2	origin,
		const Size	size,
		float	radius,
		float	feather
	)

Initializes a box gradient of the two colors.

Box gradients paint the inner color in a rounded rectangle, and then use a feather setting to transition to the outer color. To be well-defined, the corner radius should be no larger than half the width and height (at which point it defines a capsule). Shapes with abnormally large radii are undefined.

The feather value acts like the inner and outer radius of a radial gradient. If a line is drawn from the center of the round rectangle to a corner, consider two segments. The first starts at the corner and moves towards the center of the rectangle half-feather in distance. The end of this segment is the end of the inner color The second second starts at the corner and moves in the opposite direction the same amount. The end of this segement is the other color. In between, the colors are smoothly interpolated. Hence the feather effectively defines the pixel size of the transition zone.

This initializer is very similar to Gradient#initBox, except that the positions are given in the coordinate system of the canvas node, and not using texture coordinates.

Parameters

inner	The inner gradient color
outer	The outer gradient color
origin	The origin of the rounded rectangle.
size	The size of the rounded rectangle.
radius	The corner radius of the rounded rectangle.
feather	The feather value for color interpolation

Returns

true if initialization was successful.

initLinearGradient()

bool cugl::scene2::CanvasNode::Paint::initLinearGradient	(	Color4	inner,
		Color4	outer,
		const Vec2	start,
		const Vec2	end
	)

Initializes a linear gradient with the given start and end positions.

In a linear gradient, the inner starts at position start, and transitions to the outer color at position end. The transition is along the vector end-start.

This initializer is very similar to Gradient#initLinear, except that the positions are given in the coordinate system of the canvas node, and not using texture coordinates.

Parameters

inner	The inner gradient color
outer	The outer gradient color
start	The start position of the inner color
end	The start position of the outer color

Returns

true if initialization was successful.

initPattern() [1/2]

bool cugl::scene2::CanvasNode::Paint::initPattern ( std::shared_ptr< Texture >  texture, const Rect  bounds  )

inline

Initializes a texture pattern with the given bounds.

When painting a texture pattern, the texture is sized and offset to fit within the given bounds. The texture will either be clamped or repeated outside of these bounds, depending upon the texture settings. As with all paints, these bounds are specified in the coordinate system of the canvas node, and not using texture coordinates.

Typically a texture pattern is applied to a shape that fully fits within the bounds. For example, if these bounds are the bounding box of a polygon, and this paint is applied to the polygon, the effect is the same as for a PolygonNode.

Parameters

texture	The texture to paint with
bounds	The bounding box to place the texture

Returns

true if initialization was successful.

initPattern() [2/2]

bool cugl::scene2::CanvasNode::Paint::initPattern	(	std::shared_ptr< Texture >	texture,
		const Vec2	origin,
		const Size	size
	)

Initializes a texture pattern with the given bounds.

When painting a texture pattern, the texture is sized and offset to fit within the given bounds. The texture will either be clamped or repeated outside of these bounds, depending upon the texture settings. As with all paints, these bounds are specified in the coordinate system of the canvas node, and not using texture coordinates.

Typically a texture pattern is applied to a shape that fully fits within the bounds. For example, if these bounds are the bounding box of a polygon, and this paint is applied to the polygon, the effect is the same as for a PolygonNode.

Parameters

texture	The texture to paint with
origin	The position of the texture bottom left corner
size	The size to scale the texture

Returns

true if initialization was successful.

initRadialGradient() [1/2]

bool cugl::scene2::CanvasNode::Paint::initRadialGradient	(	Color4	inner,
		Color4	outer,
		const Vec2	center,
		float	iradius,
		float	oradius
	)

Initializes a general radial gradient of the two colors.

In a general radial gradient, the inner color starts at the center and continues to the inner radius. It then transitions smoothly to the outer color at the outer radius.

This initializer is very similar to Gradient#initRadial, except that the positions are given in the coordinate system of the canvas node, and not using texture coordinates.

Parameters

inner	The inner gradient color
outer	The outer gradient color
center	The center of the radial gradient
iradius	The radius for the inner color
oradius	The radius for the outer color

Returns

true if initialization was successful.

initRadialGradient() [2/2]

bool cugl::scene2::CanvasNode::Paint::initRadialGradient ( Color4  inner, Color4  outer, const Vec2  center, float  radius  )

inline

Initializes a simple radial gradient of the two colors.

In a simple radial gradient, the inner color starts at the center and transitions smoothly to the outer color at the given radius.

This initializer is very similar to Gradient#initRadial, except that the positions are given in the coordinate system of the canvas node, and not using texture coordinates.

Parameters

inner	The inner gradient color
outer	The outer gradient color
center	The center of the radial gradient
radius	The radius for the outer color

Returns

true if initialization was successful.

isGradient()

bool cugl::scene2::CanvasNode::Paint::isGradient

(

)

const

Returns true if the paint is a gradient.

Note that only gradient paints may be applied to text. Images patterns applied to text will be ignored.

Returns

true if the paint is a gradient.

setTransform()

void cugl::scene2::CanvasNode::Paint::setTransform ( const Affine2 &  transform )

inline

Sets the local transform for this paint

Local transforms are applied to all drawing commands, including paints. This is necessary because the paints are specified in the coordinate system of the canvas node.

Parameters

transform

The local transform for this paint

Friends And Related Function Documentation

Command

friend class Command

friend

Allow a drawing command to access the attributes of this paint

---

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

• cugl/include/cugl/scene2/graph/CUCanvasNode.h