Parasol Framework Manual

Provides support for the filling and stroking of vectors with colour gradients.

The VectorGradient class is used by Vector painting algorithms to fill and stroke vectors with gradients. This is achieved by initialising a VectorGradient object with the desired settings and then registering it with a VectorScene via the VectorScene⇒AddDef() method.

Any vector within the target scene will be able to utilise the gradient for filling or stroking by referencing its name through the Vector⇒Fill and Vector⇒Stroke fields. For instance 'url(#redgradient)'.

It is strongly recommended that the VectorGradient is owned by the VectorScene that is handling the definition. This will ensure that the VectorGradient is de-allocated when the scene is destroyed.

Structure

The VectorGradient class consists of the following fields:

Access

Name

Type

Comment

CenterX DOUBLE The horizontal center point of the gradient.

The (CenterX, CenterY) coordinates define the center point of the gradient. The center point will only be used if the gradient type requires it (such as the radial type). By default, the center point is set to 50%.

CenterY DOUBLE The vertical center point of the gradient.

Colour FLOAT [] The default background colour to use when clipping is enabled.

The colour value in this field is applicable only when a gradient is in clip-mode - by specifying the VSPREAD::CLIP flag in SpreadMethod. By default, this field has an alpha value of 0 to ensure that nothing is drawn outside the initial bounds of the gradient. Setting any other colour value here will otherwise fill-in those areas.

The Colour value is defined in floating-point RGBA format, using a range of 0 - 1.0 per component.

ColourMap STRING Assigns a pre-defined colourmap to the gradient.

An alternative to defining colour Stops in a gradient is available in the form of named colourmaps. Declaring a colourmap in this field will automatically populate the gradient with the colours defined in the map.

We currently support the following established colourmaps from the matplotlib and seaborn projects: cmap:crest, cmap:flare, cmap:icefire, cmap:inferno, cmap:magma, cmap:mako, cmap:plasma, cmap:rocket, cmap:viridis.

The use of colourmaps and custom stops are mutually exclusive.

ColourSpace VCS Defines the colour space to use when interpolating gradient colours.

By default, gradients are rendered using the standard RGB colour space and alpha blending rules. Changing the colour space to LINEAR_RGB will force the renderer to automatically convert sRGB values to linear RGB when blending.

Name	Description
VCS::INHERIT	Inherit the colour space option from the parent vector.
VCS::LINEAR_RGB	Linear RGB is the default colour space for SVG and produces the best results.
VCS::SRGB	The default colour-space is sRGB, recommended for its speed.

Flags VGF Dimension flags are stored here.

Dimension flags that indicate whether field values are fixed or scaled are defined here.

Name	Description
VGF::CONTAIN_FOCAL	Contain the FX,FY point to the base radius.
VGF::FIXED_CX	CX is fixed
VGF::FIXED_CY	CY is fixed
VGF::FIXED_FOCAL_RADIUS	Focal radius is fixed
VGF::FIXED_FX	FX is fixed
VGF::FIXED_FY	FY is fixed
VGF::FIXED_RADIUS	Radius is fixed
VGF::FIXED_X1	X1 is fixed
VGF::FIXED_X2	X2 is fixed
VGF::FIXED_Y1	Y1 is fixed
VGF::FIXED_Y2	Y2 is fixed
VGF::SCALED_CX	CX is scaled
VGF::SCALED_CY	CY is scaled
VGF::SCALED_FOCAL_RADIUS	Focal radius is scaled
VGF::SCALED_FX	FX is scaled
VGF::SCALED_FY	FY is scaled
VGF::SCALED_RADIUS	Radius is scaled
VGF::SCALED_X1	X1 is scaled
VGF::SCALED_X2	X2 is scaled
VGF::SCALED_Y1	Y1 is scaled
VGF::SCALED_Y2	Y2 is scaled

FocalRadius DOUBLE The size of the focal radius for radial gradients.

If a radial gradient has a defined focal point (by setting FocalX and FocalY) then the FocalRadius can be used to adjust the size of the focal area. The default of zero ensures that the focal area matches that defined by Radius, which is the standard maintained by SVG.

The FocalRadius value has no effect if the gradient is linear.

FocalX DOUBLE The horizontal focal point for radial gradients.

The (FocalX, FocalY) coordinates define the focal point for radial gradients. If left undefined, the focal point will match the center of the gradient.

FocalY DOUBLE The vertical focal point for radial gradients.

The (FocalX, FocalY) coordinates define the focal point for radial gradients. If left undefined, the focal point will match the center of the gradient.

ID STRING String identifier for a vector.

The ID field is provided for the purpose of SVG support. Where possible, we recommend that you use the existing object name and automatically assigned ID's for identifiers.

Matrices APTR A linked list of transform matrices that have been applied to the gradient.

All transforms that have been applied to the gradient can be read from the Matrices field. Each transform is represented by a VectorMatrix structure, and are linked in the order in which they were applied to the gradient.

Field	Type	Description
Next	struct VectorMatrix *	The next transform in the list.
Vector	objVector *	The vector associated with the transform.
ScaleX	DOUBLE	Matrix value A
ShearY	DOUBLE	Matrix value B
ShearX	DOUBLE	Matrix value C
ScaleY	DOUBLE	Matrix value D
TranslateX	DOUBLE	Matrix value E
TranslateY	DOUBLE	Matrix value F
Tag	LONG	An optional tag value defined by the client for matrix identification.

NumericID INT A unique identifier for the vector.

This field assigns a numeric ID to a vector. Alternatively it can also reflect a case-sensitive hash of the ID field if that has been defined previously.

If NumericID is set by the client, then any value in ID will be immediately cleared.

Radius DOUBLE The radius of the gradient.

The radius of the gradient can be defined as a fixed unit or scaled relative to its container. A default radius of 50% (0.5) applies if this field is not set.

The Radius value has no effect if the gradient is linear.

SpreadMethod VSPREAD The behaviour to use when the gradient bounds do not match the vector path.

Indicates what happens if the gradient starts or ends inside the bounds of the target vector. The default is VSPREAD::PAD. Other valid options for gradients are REFLECT, REPEAT and CLIP.

Name	Description
VSPREAD::CLIP	Do not scale the graphic. Clip it if it extends past imposed boundaries.
VSPREAD::PAD	Scale the graphic to the object bounds.
VSPREAD::REFLECT	Tile the graphic, reflecting the image alternately on the X and Y axis.
VSPREAD::REFLECT_X	Tile the graphic, reflecting the image alternately on the X axis only.
VSPREAD::REFLECT_Y	Tile the graphic, reflecting the image alternately on the Y axis only.
VSPREAD::REPEAT	Tile the graphic repeatedly.
VSPREAD::UNDEFINED	Either the default setting will be applied or the setting will be inherited from a parent object.

Stops STRUCT [] Defines the colours to use for the gradient.

The colours that will be used for drawing a gradient are defined by the Stops array. At least two stops are required to define a start and end point for interpolating the gradient colours.

TotalStops INT Total number of stops defined in the Stops array.

This read-only field indicates the total number of stops that have been defined in the Stops array.

Transform STRING Applies a transform to the gradient.

A transform can be applied to the gradient by setting this field with an SVG compliant transform string.

Type VGT Specifies the type of gradient (e.g. RADIAL, LINEAR)

The type of the gradient to be drawn is specified here.

Name	Description
VGT::CONIC	The conic gradient is a variant on the radial type, whereby the colour values are drawn as a line that revolves around the cone's center point.
VGT::CONTOUR	Contoured gradients follow the contours of the vector path in which they are rendered.
VGT::DIAMOND	A diamond gradient is drawn as a square emanating from the center point.
VGT::LINEAR	A linear gradient is drawn from `(X1, Y1)` to `(X2, Y2)`.
VGT::RADIAL	A radial gradient is drawn from `CenterX, CenterY` to `Radius`. An optional focal point can be expressed with `FX` and `FY`.

Units VUNIT Defines the coordinate system for X1, Y1, X2 and Y2.

The default coordinate system for gradients is BOUNDING_BOX, which positions the gradient around the vector that references it. The alternative is USERSPACE, which positions the gradient scaled to the current viewport.

Name	Description
VUNIT::BOUNDING_BOX	Coordinates are scaled to the object's bounding box.
VUNIT::UNDEFINED	Either the default setting will be applied or the setting will be inherited from a parent object.
VUNIT::USERSPACE	Coordinates are scaled to the current viewport.

X1 DOUBLE Initial X coordinate for the gradient.

The (X1, Y1) field values define the starting coordinate for mapping linear gradients. Other gradient types ignore these values. The gradient will be drawn from (X1, Y1) to (X2, Y2).

Coordinate values can be expressed as percentages that are scaled to the target space.

X2 DOUBLE Final X coordinate for the gradient.

The (X2, Y2) field values define the end coordinate for mapping linear gradients. Other gradient types ignore these values. The gradient will be drawn from (X1, Y1) to (X2, Y2).

Coordinate values can be expressed as percentages that are scaled to the target space.

Y1 DOUBLE Initial Y coordinate for the gradient.

The (X1, Y1) field values define the starting coordinate for mapping linear gradients. Other gradient types ignore these values. The gradient will be drawn from (X1, Y1) to (X2, Y2).

Coordinate values can be expressed as percentages that are scaled to the target space.

Y2 DOUBLE Final Y coordinate for the gradient.

The (X2, Y2) field values define the end coordinate for mapping linear gradients. Other gradient types ignore these values. The gradient will be drawn from (X1, Y1) to (X2, Y2).

Coordinate values can be expressed as percentages that are scaled to the target space.

Class Info
ID	ID_VECTORGRADIENT
Category	Graphics
Include	modules/vectorgradient.h
Version	1

VectorGradient Class

Structure

VCS Type

VGF Type

VGT Type

VSPREAD Type

VUNIT Type

VectorMatrix Structure

Class Info

Class List