CUGL 2.1
Cornell University Game Library
Public Member Functions | Static Public Member Functions | List of all members
cugl::Gradient Class Reference

#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)
 
Gradientoperator= (const Gradient &other)
 
Gradientoperator= (Gradient &&other)
 
Gradientoperator= (const Color4 color)
 
Gradientset (const Gradient &grad)
 
Gradientset (const std::shared_ptr< Gradient > &grad)
 
Gradientset (const Color4 color)
 
Gradientset (const Color4 inner, const Color4 outer, const Vec2 start, const Vec2 end)
 
Gradientset (const Color4 inner, const Color4 outer, const Vec2 center, float radius)
 
Gradientset (const Color4 inner, const Color4 outer, const Vec2 center, float iradius, float oradius)
 
Gradientset (const Color4 inner, const Color4 outer, const Rect box, float radius, float feather)
 
Gradientset (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)
 
Gradientrotate (float angle)
 
Gradientscale (float value)
 
Gradientscale (const Vec2 s)
 
Gradientscale (float sx, float sy)
 
Gradienttranslate (const Vec2 t)
 
Gradienttranslate (float tx, float ty)
 
Gradientmultiply (const Mat4 &mat)
 
Gradientmultiply (const Affine2 &aff)
 
Gradientoperator*= (const Mat4 &mat)
 
Gradientoperator*= (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< Gradientalloc (const Color4 color)
 
static std::shared_ptr< GradientallocLinear (const Color4 inner, const Color4 outer, const Vec2 start, const Vec2 end)
 
static std::shared_ptr< GradientallocRadial (const Color4 inner, const Color4 outer, const Vec2 center, float radius)
 
static std::shared_ptr< GradientallocRadial (const Color4 inner, const Color4 outer, const Vec2 center, float iradius, float oradius)
 
static std::shared_ptr< GradientallocBox (const Color4 inner, const Color4 outer, const Rect box, float radius, float feather)
 
static std::shared_ptr< GradientallocBox (const Color4 inner, const Color4 outer, const Vec2 origin, const Size size, float radius, float feather)
 
static std::shared_ptr< GradientallocCopy (const std::shared_ptr< Gradient > &grad)
 
static std::shared_ptr< GradientallocWithData (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):

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
gradThe 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
gradThe 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
colorThe 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
innerThe inner gradient color
outerThe outer gradient color
boxThe bounds of the rounded rectangle.
radiusThe corner radius of the rounded rectangle.
featherThe 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
innerThe inner gradient color
outerThe outer gradient color
originThe origin of the rounded rectangle.
sizeThe size of the rounded rectangle.
radiusThe corner radius of the rounded rectangle.
featherThe 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
gradThe 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
innerThe inner gradient color
outerThe outer gradient color
startThe start position of the inner color
endThe 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
innerThe inner gradient color
outerThe outer gradient color
centerThe center of the radial gradient
iradiusThe radius for the inner color
oradiusThe 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
innerThe inner gradient color
outerThe outer gradient color
centerThe center of the radial gradient
radiusThe 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
dataThe 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
arrayThe 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
arrayThe 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
colorThe 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
innerThe inner gradient color
outerThe outer gradient color
boxThe bounds of the rounded rectangle.
radiusThe corner radius of the rounded rectangle.
featherThe 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
innerThe inner gradient color
outerThe outer gradient color
originThe origin of the rounded rectangle.
sizeThe size of the rounded rectangle.
radiusThe corner radius of the rounded rectangle.
featherThe 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
gradThe 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
innerThe inner gradient color
outerThe outer gradient color
startThe start position of the inner color
endThe 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
innerThe inner gradient color
outerThe outer gradient color
centerThe center of the radial gradient
iradiusThe radius for the inner color
oradiusThe 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
innerThe inner gradient color
outerThe outer gradient color
centerThe center of the radial gradient
radiusThe 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
dataThe 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
affThe 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
matThe 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
affThe 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
matThe 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
affThe 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
matThe 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
colorThe 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
otherThe 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
otherThe 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
angleThe 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
sThe 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
sxThe amount to scale along the x-axis.
syThe 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
valueThe 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
colorThe 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
innerThe inner gradient color
outerThe outer gradient color
boxThe bounds of the rounded rectangle.
radiusThe corner radius of the rounded rectangle.
featherThe 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
innerThe inner gradient color
outerThe outer gradient color
centerThe center of the radial gradient
iradiusThe radius for the inner color
oradiusThe 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
innerThe inner gradient color
outerThe outer gradient color
centerThe center of the radial gradient
radiusThe 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
innerThe inner gradient color
outerThe outer gradient color
originThe origin of the rounded rectangle.
sizeThe size of the rounded rectangle.
radiusThe corner radius of the rounded rectangle.
featherThe 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
innerThe inner gradient color
outerThe outer gradient color
startThe start position of the inner color
endThe 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
gradThe 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
gradThe 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
extentThe 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
featherThe 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
colorThe 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
colorThe 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
radiusThe 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
transformThe 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
transformThe 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
verboseWhether 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
tThe 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
txThe translation offset for the x-axis.
tyThe translation offset for the y-axis.
Returns
This gradient, after translation.

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