#include <CUGradient.h>

Public Member Functions
	Gradient ()

	Gradient (const Gradient &grad)

	Gradient (Gradient &&grad)

	~Gradient ()

void	dispose ()

bool	init (const Color4f color)

bool	initLinear (const Color4 inner, const Color4 outer, const Vec2 start, const Vec2 end)

bool	initRadial (const Color4 inner, const Color4 outer, const Vec2 center, float radius)

bool	initRadial (const Color4 inner, const Color4 outer, const Vec2 center, float iradius, float oradius)

bool	initBox (const Color4 inner, const Color4 outer, const Rect box, float radius, float feather)

bool	initBox (const Color4 inner, const Color4 outer, const Vec2 origin, const Size size, float radius, float feather)

bool	initCopy (const std::shared_ptr< Gradient > &grad)

bool	initWithData (const std::shared_ptr< JsonValue > &data)

Gradient &	operator= (const Gradient &other)

Gradient &	operator= (Gradient &&other)

Gradient &	operator= (const Color4 color)

Gradient &	set (const Gradient &grad)

Gradient &	set (const std::shared_ptr< Gradient > &grad)

Gradient &	set (const Color4 color)

Gradient &	set (const Color4 inner, const Color4 outer, const Vec2 start, const Vec2 end)

Gradient &	set (const Color4 inner, const Color4 outer, const Vec2 center, float radius)

Gradient &	set (const Color4 inner, const Color4 outer, const Vec2 center, float iradius, float oradius)

Gradient &	set (const Color4 inner, const Color4 outer, const Rect box, float radius, float feather)

Gradient &	set (const Color4 inner, const Color4 outer, const Vec2 origin, const Size size, float radius, float feather)

Affine2	getTransform () const

void	setTransform (const Affine2 &transform)

void	setTransform (const Mat4 &transform)

Color4	getInnerColor () const

void	setInnerColor (const Color4 color)

Color4	getOuterColor () const

void	setOuterColor (const Color4 color)

Vec2	getExtent () const

void	setExtent (const Vec2 extent)

float	getRadius () const

void	setRadius (float radius)

float	getFeather () const

void	setFeather (float feather)

Gradient &	rotate (float angle)

Gradient &	scale (float value)

Gradient &	scale (const Vec2 s)

Gradient &	scale (float sx, float sy)

Gradient &	translate (const Vec2 t)

Gradient &	translate (float tx, float ty)

Gradient &	multiply (const Mat4 &mat)

Gradient &	multiply (const Affine2 &aff)

Gradient &	operator*= (const Mat4 &mat)

Gradient &	operator*= (const Affine2 &aff)

Gradient	operator* (const Mat4 &mat) const

Gradient	operator* (const Affine2 &aff) const

float *	getData (float *array) const

float *	getComponents (float *array) const

std::string	toString (bool verbose=false) const

	operator std::string () const

Static Public Member Functions
static std::shared_ptr< Gradient >	alloc (const Color4 color)

static std::shared_ptr< Gradient >	allocLinear (const Color4 inner, const Color4 outer, const Vec2 start, const Vec2 end)

static std::shared_ptr< Gradient >	allocRadial (const Color4 inner, const Color4 outer, const Vec2 center, float radius)

static std::shared_ptr< Gradient >	allocRadial (const Color4 inner, const Color4 outer, const Vec2 center, float iradius, float oradius)

static std::shared_ptr< Gradient >	allocBox (const Color4 inner, const Color4 outer, const Rect box, float radius, float feather)

static std::shared_ptr< Gradient >	allocBox (const Color4 inner, const Color4 outer, const Vec2 origin, const Size size, float radius, float feather)

static std::shared_ptr< Gradient >	allocCopy (const std::shared_ptr< Gradient > &grad)

static std::shared_ptr< Gradient >	allocWithData (const std::shared_ptr< JsonValue > &data)

Detailed Description

This class defines a two color gradient.

All gradients, including linear and radial gradients, are variations of (rounded) box gradients. A box gradient is defined by (in terms of largest to smallest data):

An affine transform (for offset and rotation)
An inner color
An outer color
A size vector of the gradient
A corner radius for the rounded rectangle
A feather factor for the transition speed.

Assuming this data is in std140 format, this is a 24 element array of floats. And this is the format that this data is represented in the getData method so that it can be passed to a UniformBuffer for improved performance. It is also possible to get access to the individual components of the paint gradient, to pass them to a shader directly (though the transform must be inverted first if it is passed directly).

Paint gradients are applied to surfaces in the same way textures are. The gradient is defined on a unit square from (0,0) to (1,1). To be consistent with textures, the origin is at the top right corner. To apply the gradient, the shader should use the texture coordinates of each vertex (or an attribute similar to texture coordinates) combined with the uniforms for this gradient. For a tutorial on how to do this, see the SpriteShader shaders in the the CUGL render package.

For simplicity we only permit two colors in a gradient. For multicolored gradients, the shape should be tesellated with multiple gradient values.

Constructor & Destructor Documentation

◆ Gradient() [1/3]

cugl::Gradient::Gradient ( )

Creates a degenerate, white-colored gradient.

◆ Gradient() [2/3]

cugl::Gradient::Gradient ( const Gradient & grad )

inline

Creates a copy of the given gradient.

Parameters

grad	The gradient to copy

◆ Gradient() [3/3]

cugl::Gradient::Gradient ( Gradient && grad )

Creates a copy with the resources of the given gradient.

The original gradient is no longer safe to use after calling this constructor.

Parameters

grad	The gradient to take from

◆ ~Gradient()

cugl::Gradient::~Gradient ( )

inline

Deletes this gradient, releasing all resources.

Member Function Documentation

◆ alloc()

static std::shared_ptr<Gradient> cugl::Gradient::alloc ( const Color4 color )

inlinestatic

Returns a new degenerate gradient of the given color.

Parameters

color The gradient color

Returns: a new degenerate gradient of the given color.

◆ allocBox() [1/2]

static std::shared_ptr<Gradient> cugl::Gradient::allocBox	(	const Color4	inner,
		const Color4	outer,
		const Rect	box,
		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. The box position and corner radius are given in texture coordinates. That is, (0,0) is the top left corner of the gradient bounding box and (1,1) is the bottom right corner. It is permissible for these coordinates to be out of range (so negative values or greater than 1). Such values will be interpretted accordingly.

To be well-defined, the corner radius should be no larger than half the width and height (at which point it defines an ellipse). 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.

So, if feather is 0, there is no gradient and the shift from inner color to outer color is immediate. On the other hand, if feather is larger than the width and hight of the rectangle, the inner color immediately transitions to the outer color.

Parameters

inner	The inner gradient color
outer	The outer gradient color
box	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.

◆ allocBox() [2/2]

static std::shared_ptr<Gradient> cugl::Gradient::allocBox	(	const Color4	inner,
		const 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. The box position and corner radius are given in texture coordinates. That is, (0,0) is the top left corner of the gradient bounding box and (1,1) is the bottom right corner. It is permissible for these coordinates to be out of range (so negative values or greater than 1). Such values will be interpretted accordingly.

To be well-defined, the corner radius should be no larger than half the width and height (at which point it defines an ellipse). 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.

So, if feather is 0, there is no gradient and the shift from inner color to outer color is immediate. On the other hand, if feather is larger than the width and hight of the rectangle, the inner color immediately transitions to the outer color.

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.

◆ allocCopy()

static std::shared_ptr<Gradient> cugl::Gradient::allocCopy ( const std::shared_ptr< Gradient > & grad )

inlinestatic

Returns a new copy of the given gradient.

Parameters

grad	The gradient to copy

Returns: a new copy of the given gradient.

◆ allocLinear()

static std::shared_ptr<Gradient> cugl::Gradient::allocLinear	(	const Color4	inner,
		const Color4	outer,
		const Vec2	start,
		const Vec2	end
	)

inlinestatic

Returns a new linear gradient of the two colors.

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.

The values start and end are specified in texture coordinates. That is, (0,0) is the top left corner of the gradient bounding box and (1,1) is the bottom right corner. It is permissible to have coordinates out of range (so negative or greater than 1). Such values will be interpretted accordingly.

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 of the two colors.

◆ allocRadial() [1/2]

static std::shared_ptr<Gradient> cugl::Gradient::allocRadial	(	const Color4	inner,
		const 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.

The center and radii are all specified in texture coordinates. That is, (0,0) is the top left corner of the gradient bounding box and (1,1) is the bottom right corner. It is permissible to a center value out of range (so coordinates negative or greater than 1). Such value will be interpretted accordingly.

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.

◆ allocRadial() [2/2]

static std::shared_ptr<Gradient> cugl::Gradient::allocRadial	(	const Color4	inner,
		const 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.

The center and radius are specified in texture coordinates. That is, (0,0) is the top left corner of the gradient bounding box and (1,1) is the bottom right corner. It is permissible to a center value out of range (so coordinates negative or greater than 1). Such values will be interpretted accordingly.

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.

◆ allocWithData()

static std::shared_ptr<Gradient> cugl::Gradient::allocWithData ( const std::shared_ptr< JsonValue > & data )

inlinestatic

Returns a new gradient from the given JsonValue

The JsonValue should a JSON object. It supports the following attributes:

"type":      One of 'linear', 'radial', or 'box'
"inner":     The inner gradient color (string or 4-element array 0..255)
"outer":     The outer gradient color (string or 4-element array 0..255)
"center":    A two-element array representing the gradient center
"extent":    A two-element array representing the gradient extent
"radius":    A number representing the radius of the inner color
             (radial and box gradients only)
"feather":   A number representing the feather value (box gradients only)

All values are optional. Note, however, that specifying no values results in a solid white color, and not specifying the "center" and/or "extent" will produce a solid color of the inner color.

For a linear gradient, the "center" is the start and the "extent" is the end. All other values are ignored. For a radial gradient, the "extent" defines the outer radius, while the "radius" is the "radius" of the inner color. If radius is not specified, then the inner and outer radius are the same.

Finally for box gradients, the "center" is the center, while the "extent" defines the width and height. All other values are interpretted normally.

Parameters

data	The JSON object specifying the gradient

Returns: a new gradient from the given JsonValue

◆ dispose()

void cugl::Gradient::dispose ( )

Deletes the gradient and resets all attributes.

You must reinitialize the gradient to use it.

◆ getComponents()

float* cugl::Gradient::getComponents ( float * array ) const

Reads the gradient into the provided array

The gradient is written to the array so that it can be passed the the shader one component at a time (e.g. NOT in std140 format). It differs from getData in that it only uses 9 floats for the affine transform (as a 3x3 homogenous matrix).

Parameters

array The array to store the values

Returns: a reference to the array for chaining

◆ getData()

float* cugl::Gradient::getData ( float * array ) const

Reads the gradient into the provided array

The gradient is written to the given array in std140 format. That is (1) 12 floats for the affine transform (as a 3x3 homogenous matrix), (2) 4 floats for the inner color, (3) 4 floats for the outer color, (4) 2 floats for the extent, (5) 1 float for the corner radius, and (6) 1 float for the feather value. Values are written in this order.

Parameters

array The array to store the values

Returns: a reference to the array for chaining

◆ getExtent()

Vec2 cugl::Gradient::getExtent ( ) const

inline

Returns the extent of this gradient

The extent is the vector from the center of the rounded rectangle to one of its corners. It defines the size of the rounded rectangle.

Returns: the extent of this gradient

◆ getFeather()

float cugl::Gradient::getFeather ( ) const

inline

Returns the feather value for this gradient.

The feature value is perhaps the trickiest value to understand. This 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.

So, if feather is 0, there is no gradient and the shift from inner color to outer color is immediate. On the other hand, if feather is larger than the width and hight of the rectangle, the inner color immediately transitions to the outer color.

Returns: the feather value for this gradient.

◆ getInnerColor()

Color4 cugl::Gradient::getInnerColor ( ) const

inline

Returns the inner color of this gradient

The inner color is the color inside of the rounded rectangle defining the gradient.

Returns: the inner color of this gradient

◆ getOuterColor()

Color4 cugl::Gradient::getOuterColor ( ) const

inline

Returns the outer color of this gradient

The outer color is the color outside of the rounded rectangle defining the gradient.

Returns: the outer color of this gradient

◆ getRadius()

float cugl::Gradient::getRadius ( ) const

inline

Returns the corner radius of the gradient rectangle

The corner radius is the radius of the circle inscribed in (each) corner of the rounded rectangle.

To be well-defined, it should be no more than half the width and height. When it is equal to both half the width and half the height, the rectangle becomes a circle. For large values this inner rectangle will collapse and disappear completely.

Returns: the corner radius of the gradient rectangle

◆ getTransform()

Affine2 cugl::Gradient::getTransform ( ) const

Returns the transform component of this gradient

The transform maps the origin of the current coordinate system to the center and rotation of the rounded rectangular box with the inner color. Applying further transforms will adjust the gradient in texture space.

The transform is primarily for representing rotation. It typically only has a scale component when the gradient is linear.

If this transform is passed directly to a gradient shader, it should be inverted first. If you really need to pass individual components to a shader, you should use getComponents instead.

Returns: the transform component of this gradient

◆ init()

bool cugl::Gradient::init ( const Color4f color )

Initializes a degenerate gradient of the given color.

Parameters

color The gradient color

Returns: true if initialization was successful.

◆ initBox() [1/2]

bool cugl::Gradient::initBox	(	const Color4	inner,
		const Color4	outer,
		const Rect	box,
		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. The box position and corner radius are given in texture coordinates. That is, (0,0) is the top left corner of the gradient bounding box and (1,1) is the bottom right corner. It is permissible for these coordinates to be out of range (so negative values or greater than 1). Such values will be interpretted accordingly.

To be well-defined, the corner radius should be no larger than half the width and height (at which point it defines an ellipse). 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.

So, if feather is 0, there is no gradient and the shift from inner color to outer color is immediate. On the other hand, if feather is larger than the width and hight of the rectangle, the inner color immediately transitions to the outer color.

Parameters

inner	The inner gradient color
outer	The outer gradient color
box	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.

◆ initBox() [2/2]

bool cugl::Gradient::initBox	(	const Color4	inner,
		const 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. The box position and corner radius are given in texture coordinates. That is, (0,0) is the top left corner of the gradient bounding box and (1,1) is the bottom right corner. It is permissible for these coordinates to be out of range (so negative values or greater than 1). Such values will be interpretted accordingly.

To be well-defined, the corner radius should be no larger than half the width and height (at which point it defines an ellipse). 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.

So, if feather is 0, there is no gradient and the shift from inner color to outer color is immediate. On the other hand, if feather is larger than the width and hight of the rectangle, the inner color immediately transitions to the outer color.

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.

◆ initCopy()

bool cugl::Gradient::initCopy ( const std::shared_ptr< Gradient > & grad )

Initializes this gradient to be a copy of the given gradient.

Parameters

grad	The gradient to copy

Returns: true if initialization was successful.

◆ initLinear()

bool cugl::Gradient::initLinear	(	const Color4	inner,
		const Color4	outer,
		const Vec2	start,
		const Vec2	end
	)

Initializes a linear gradient of the two colors.

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.

The values start and end are specified in texture coordinates. That is, (0,0) is the top left corner of the gradient bounding box and (1,1) is the bottom right corner. It is permissible to have coordinates out of range (so negative or greater than 1). Such values will be interpretted accordingly.

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.

◆ initRadial() [1/2]

bool cugl::Gradient::initRadial	(	const Color4	inner,
		const 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.

The center and radii are all specified in texture coordinates. That is, (0,0) is the top left corner of the gradient bounding box and (1,1) is the bottom right corner. It is permissible to a center value out of range (so coordinates negative or greater than 1). Such value will be interpretted accordingly.

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.

◆ initRadial() [2/2]

bool cugl::Gradient::initRadial	(	const Color4	inner,
		const Color4	outer,
		const Vec2	center,
		float	radius
	)

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.

The center and radius are specified in texture coordinates. That is, (0,0) is the top left corner of the gradient bounding box and (1,1) is the bottom right corner. It is permissible to a center value out of range (so coordinates negative or greater than 1). Such values will be interpretted accordingly.

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.

◆ initWithData()

bool cugl::Gradient::initWithData ( const std::shared_ptr< JsonValue > & data )

Initializes a gradient from the given JsonValue

The JsonValue should a JSON object. It supports the following attributes:

"type":      One of 'linear', 'radial', or 'box'
"inner":     The inner gradient color (string or 4-element array 0..255)
"outer":     The outer gradient color (string or 4-element array 0..255)
"center":    A two-element array representing the gradient center
"extent":    A two-element array representing the gradient extent
"radius":    A number representing the radius of the inner color
             (radial and box gradients only)
"feather":   A number representing the feather value (box gradients only)

All values are optional. Note, however, that specifying no values results in a solid white color, and not specifying the "center" and/or "extent" will produce a solid color of the inner color.

For a linear gradient, the "center" is the start and the "extent" is the end. All other values are ignored. For a radial gradient, the "extent" defines the outer radius, while the "radius" is the "radius" of the inner color. If radius is not specified, then the inner and outer radius are the same.

Finally for box gradients, the "center" is the center, while the "extent" defines the width and height. All other values are interpretted normally.

Parameters

data	The JSON object specifying the gradient

Returns: true if initialization was successful.

◆ multiply() [1/2]

Gradient& cugl::Gradient::multiply ( const Affine2 & aff )

inline

Applies the given transform to this gradient.

This transform is applied after the existing gradient transform (which is natural, since the transform defines the gradient shape). To pre-multiply a transform, set the transform directly.

Parameters

aff	The matrix to multiply by.

Returns: A reference to this (modified) Gradient for chaining.

◆ multiply() [2/2]

Gradient& cugl::Gradient::multiply ( const Mat4 & mat )

inline

Applies the given transform to this gradient.

This transform is applied after the existing gradient transform (which is natural, since the transform defines the gradient shape). To pre-multiply a transform, set the transform directly.

Parameters

mat	The matrix to multiply by.

Returns: A reference to this (modified) Gradient for chaining.

◆ operator std::string()

cugl::Gradient::operator std::string ( ) const

inline

Cast from Gradient to a string.

◆ operator*() [1/2]

Gradient cugl::Gradient::operator* ( const Affine2 & aff ) const

inline

Returns a copy of the gradient transformed by the given matrix.

The matrix transform is applied after the existing gradient transform (which is natural, since the transform defines the gradient shape). To pre-multiply a transform, set the transform directly.

Note: This does not modify the gradient.

Parameters

aff	The transform to multiply by.

Returns: a copy of the gradient transformed by the given matrix.

◆ operator*() [2/2]

Gradient cugl::Gradient::operator* ( const Mat4 & mat ) const

inline

Returns a copy of the gradient transformed by the given matrix.

The matrix transform is applied after the existing gradient transform (which is natural, since the transform defines the gradient shape). To pre-multiply a transform, set the transform directly.

Note: This does not modify the gradient.

Parameters

mat	The transform to multiply by.

Returns: a copy of the gradient transformed by the given matrix.

◆ operator*=() [1/2]

Gradient& cugl::Gradient::operator*= ( const Affine2 & aff )

Applies the given transform to this gradient.

This transform is applied after the existing gradient transform (which is natural, since the transform defines the gradient shape). To pre-multiply a transform, set the transform directly.

Parameters

aff	The matrix to multiply by.

Returns: A reference to this (modified) Gradient for chaining.

◆ operator*=() [2/2]

Gradient& cugl::Gradient::operator*= ( const Mat4 & mat )

Applies the given transform to this gradient.

This transform is applied after the existing gradient transform (which is natural, since the transform defines the gradient shape). To pre-multiply a transform, set the transform directly.

Parameters

mat	The matrix to multiply by.

Returns: A reference to this (modified) Gradient for chaining.

◆ operator=() [1/3]

Gradient& cugl::Gradient::operator= ( const Color4 color )

inline

Sets this to be a degenerate gradient with the given color.

The inner color and outer color will be the same, so there will be no transition.

Parameters

color The gradient color

Returns: this gradient, returned for chaining

◆ operator=() [2/3]

Gradient& cugl::Gradient::operator= ( const Gradient & other )

inline

Sets this gradient to be a copy of the given one.

Parameters

other The gradient to copy

Returns: this gradient, returned for chaining

◆ operator=() [3/3]

Gradient& cugl::Gradient::operator= ( Gradient && other )

inline

Sets this gradient to be have the resources of the given one.

The original gradient is no longer safe to use after calling this operator.

Parameters

other The gradient to take from

Returns: this gradient, returned for chaining

◆ rotate()

Gradient& cugl::Gradient::rotate ( float angle )

Applies a rotation to this gradient.

The rotation is in radians, counter-clockwise about the given axis.

Parameters

angle The angle (in radians).

Returns: This gradient, after rotation.

◆ scale() [1/3]

Gradient& cugl::Gradient::scale ( const Vec2 s )

Applies a non-uniform scale to this gradient.

Parameters

s	The vector storing the individual scaling factors

Returns: This gradient, after scaling.

◆ scale() [2/3]

Gradient& cugl::Gradient::scale	(	float	sx,
		float	sy
	)

inline

Applies a non-uniform scale to this gradient.

Parameters

sx	The amount to scale along the x-axis.
sy	The amount to scale along the y-axis.

Returns: This gradient, after scaling.

◆ scale() [3/3]

Gradient& cugl::Gradient::scale ( float value )

Applies a uniform scale to this gradient.

Parameters

value The scalar to multiply by.

Returns: This gradient, after scaling.

◆ set() [1/8]

Gradient& cugl::Gradient::set ( const Color4 color )

Sets this to be a degenerate gradient with the given color.

The inner color and outer color will be the same, so there will be no transition.

Parameters

color The gradient color

Returns: this gradient, returned for chaining

◆ set() [2/8]

Gradient& cugl::Gradient::set	(	const Color4	inner,
		const Color4	outer,
		const Rect	box,
		float	radius,
		float	feather
	)

Sets this to be 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. The box position and corner radius are given in texture coordinates. That is, (0,0) is the top left corner of the gradient bounding box and (1,1) is the bottom right corner. It is permissible for these coordinates to be out of range (so negative values or greater than 1). Such values will be interpretted accordingly.

To be well-defined, the corner radius should be no larger than half the width and height (at which point it defines an ellipse). 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.

So, if feather is 0, there is no gradient and the shift from inner color to outer color is immediate. On the other hand, if feather is larger than the width and hight of the rectangle, the inner color immediately transitions to the outer color.

Parameters

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

Returns: this gradient, returned for chaining

◆ set() [3/8]

Gradient& cugl::Gradient::set	(	const Color4	inner,
		const Color4	outer,
		const Vec2	center,
		float	iradius,
		float	oradius
	)

Sets this to be 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.

The center and radii are all specified in texture coordinates. That is, (0,0) is the top left corner of the gradient bounding box and (1,1) is the bottom right corner. It is permissible to a center value out of range (so coordinates negative or greater than 1). Such value will be interpretted accordingly.

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: this gradient, returned for chaining

◆ set() [4/8]

Gradient& cugl::Gradient::set	(	const Color4	inner,
		const Color4	outer,
		const Vec2	center,
		float	radius
	)

Sets this to be 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.

The center and radius are specified in texture coordinates. That is, (0,0) is the top left corner of the gradient bounding box and (1,1) is the bottom right corner. It is permissible to a center value out of range (so coordinates negative or greater than 1). Such values will be interpretted accordingly.

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: this gradient, returned for chaining

◆ set() [5/8]

Gradient& cugl::Gradient::set	(	const Color4	inner,
		const Color4	outer,
		const Vec2	origin,
		const Size	size,
		float	radius,
		float	feather
	)

Sets this to be 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. The box position and corner radius are given in texture coordinates. That is, (0,0) is the top left corner of the gradient bounding box and (1,1) is the bottom right corner. It is permissible for these coordinates to be out of range (so negative values or greater than 1). Such values will be interpretted accordingly.

To be well-defined, the corner radius should be no larger than half the width and height (at which point it defines an ellipse). 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.

So, if feather is 0, there is no gradient and the shift from inner color to outer color is immediate. On the other hand, if feather is larger than the width and hight of the rectangle, the inner color immediately transitions to the outer color.

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: this gradient, returned for chaining

◆ set() [6/8]

Gradient& cugl::Gradient::set	(	const Color4	inner,
		const Color4	outer,
		const Vec2	start,
		const Vec2	end
	)

Sets this to be a linear gradient of the two colors.

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

The values start and end are specified in texture coordinates. That is, (0,0) is the top left corner of the gradient bounding box and (1,1) is the bottom right corner. It is permissible to have coordinates out of range (so negative or greater than 1). Such values will be interpretted accordingly.

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: this gradient, returned for chaining

◆ set() [7/8]

Gradient& cugl::Gradient::set ( const Gradient & grad )

Sets this gradient to be a copy of the given one.

Parameters

grad	The gradient to copy

Returns: this gradient, returned for chaining

◆ set() [8/8]

Gradient& cugl::Gradient::set ( const std::shared_ptr< Gradient > & grad )

inline

Sets this gradient to be a copy of the given one.

Parameters

grad	The gradient to copy

Returns: this gradient, returned for chaining

◆ setExtent()

void cugl::Gradient::setExtent ( const Vec2 extent )

inline

Sets the extent of this gradient

The extent is the vector from the center of the rounded rectangle to one of its corners. It defines the size of the rounded rectangle.

Parameters

extent The extent of this gradient

◆ setFeather()

void cugl::Gradient::setFeather ( float feather )

inline

Sets the feather value for this gradient.

The feature value is perhaps the trickiest value to understand. This 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.

So, if feather is 0, there is no gradient and the shift from inner color to outer color is immediate. On the other hand, if feather is larger than the width and hight of the rectangle, the inner color immediately transitions to the outer color.

Parameters

feather The feather value for this gradient.

◆ setInnerColor()

void cugl::Gradient::setInnerColor ( const Color4 color )

inline

Sets the inner color of this gradient

The inner color is the color inside of the rounded rectangle defining the gradient.

Parameters

color The inner color of this gradient

◆ setOuterColor()

void cugl::Gradient::setOuterColor ( const Color4 color )

inline

Sets the outer color of this gradient

The outer color is the color outside of the rounded rectangle defining the gradient.

Parameters

color The outer color of this gradientt

◆ setRadius()

void cugl::Gradient::setRadius ( float radius )

inline

Sets the corner radius of the gradient rectangle

The corner radius is the radius of the circle inscribed in (each) corner of the rounded rectangle.

To be well-defined, it should be no more than half the width and height. When it is equal to both half the width and half the height, the rectangle becomes a circle. For large values this inner rectangle will collapse and disappear completely.

Parameters

radius The corner radius of the gradient rectangle

◆ setTransform() [1/2]

void cugl::Gradient::setTransform ( const Affine2 & transform )

Sets the transform component of this gradient

The transform maps the origin of the current coordinate system to the center and rotation of the rounded rectangular box with the inner color. Applying further transforms will adjust the gradient in texture space.

The transform is primarily for representing rotation. It typically only has a scale component when the gradient is linear.

If this transform is passed directly to a gradient shader, it should be inverted first. If you really need to pass individual components to a shader, you should use getComponents instead.

Parameters

transform The transform component of this gradient

◆ setTransform() [2/2]

void cugl::Gradient::setTransform ( const Mat4 & transform )

Sets the transform component of this gradient

The transform maps the origin of the current coordinate system to the center and rotation of the rounded rectangular box with the inner color. Applying further transforms will adjust the gradient in texture space.

The transform is primarily for representing rotation. It typically only has a scale component when the gradient is linear.

If this transform is passed directly to a gradient shader, it should be inverted first. If you really need to pass individual components to a shader, you should use getComponents instead.

Parameters

transform The transform component of this gradient

◆ toString()

std::string cugl::Gradient::toString ( bool verbose = false ) const

Returns a string representation of this gradient for debuggging purposes.

If verbose is true, the string will include class information. This allows us to unambiguously identify the class.

Parameters

verbose Whether to include class information

Returns: a string representation of this gradient for debuggging purposes.

◆ translate() [1/2]

Gradient& cugl::Gradient::translate ( const Vec2 t )

Applies a translation to this gradient.

The translation should be in texture coordinates, which (generally) have values 0 to 1.

Parameters

t	The vector storing the individual translation offsets

Returns: This gradient, after translation.

◆ translate() [2/2]

Gradient& cugl::Gradient::translate	(	float	tx,
		float	ty
	)

inline

Applies a translation to this gradient.

The translation should be in texture coordinates, which (generally) have values 0 to 1.

Parameters

tx	The translation offset for the x-axis.
ty	The translation offset for the y-axis.

Returns: This gradient, after translation.

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

include/cugl/render/CUGradient.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Gradient() [1/3]

◆ Gradient() [2/3]

◆ Gradient() [3/3]

◆ ~Gradient()

Member Function Documentation

◆ alloc()

◆ allocBox() [1/2]

◆ allocBox() [2/2]

◆ allocCopy()

◆ allocLinear()

◆ allocRadial() [1/2]

◆ allocRadial() [2/2]

◆ allocWithData()

◆ dispose()

◆ getComponents()

◆ getData()

◆ getExtent()

◆ getFeather()

◆ getInnerColor()

◆ getOuterColor()

◆ getRadius()

◆ getTransform()

◆ init()

◆ initBox() [1/2]

◆ initBox() [2/2]

◆ initCopy()

◆ initLinear()

◆ initRadial() [1/2]

◆ initRadial() [2/2]

◆ initWithData()

◆ multiply() [1/2]

◆ multiply() [2/2]

◆ operator std::string()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator*=() [1/2]

◆ operator*=() [2/2]

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ rotate()

◆ scale() [1/3]

◆ scale() [2/3]

◆ scale() [3/3]

◆ set() [1/8]

◆ set() [2/8]

◆ set() [3/8]

◆ set() [4/8]

◆ set() [5/8]

◆ set() [6/8]

◆ set() [7/8]

◆ set() [8/8]

◆ setExtent()

◆ setFeather()

◆ setInnerColor()

◆ setOuterColor()

◆ setRadius()

◆ setTransform() [1/2]

◆ setTransform() [2/2]

◆ toString()

◆ translate() [1/2]

◆ translate() [2/2]