Constructs filter pipelines that alter rendered vector graphics.

The VectorFilter class allows post-effect filters to be applied to vectors as they are being rendered. Filter support is closely modelled around the SVG standard, and effect results are intended to match that of the standard. Once created, a filter can be utilised by vector objects through their Vector⇒Filter field. By way of example in SVG:

<circle cx="160" cy="50" r="40" fill="#f00" filter="url(#EffectPipeline)"/>

Filter pipelines are constructed from effects based on the FilterEffect class, such as CompositeFX and FloodFX. Construct a new pipeline by creating effect objects and placing them under the ownership of the VectorFilter that will be supporting them. The VectorFilter will automatically detect them and they will be processed in the order in which they are added. It is most optimal to create each pipeline in advance, and a new VectorFilter object should be created for each pipeline as necessary.

It is important to note that filter effects are CPU intensive tasks and real-time performance may be disappointing. If this is an issue, consider pre-rendering the filter effects in advance and caching the results in memory or files.

It is a requirement that VectorFilter objects are owned by the VectorScene they are targeting.

Structure

The VectorFilter class consists of the following fields:

Access

Name

Type

Comment

AspectRatio VFA Aspect ratio to use when scaling X/Y values

Name	Description
VFA::MEET	Scale X/Y values independently and in relation to the width/height of the parent viewport.
VFA::NONE	Scale X/Y values on a `1:1` basis, in relation to the diagonal of the parent viewport.

ColourSpace VCS The colour space of the filter graphics (SRGB or linear RGB).

By default, colour filters are processed in SRGB format. This is the same colour space as used by the rest of the graphics system, which means that no special conversion is necessary prior to and post filter processing. However, linear RGB is better suited for producing high quality results at a cost of speed.

Note that if SVG compatibility is required, linear RGB must be used as the default.

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.

Dimensions DMF Dimension flags define whether individual dimension fields contain fixed or scaled values.

The following dimension flags are supported:

Name	Description
FIXED_X	The X value is a fixed coordinate.
FIXED_Y	The Y value is a fixed coordinate.
SCALED_X	The X value is a scaled coordinate.
SCALED_Y	The Y value is a scaled coordinate.
FIXED_WIDTH	The Width value is a fixed coordinate.
FIXED_HEIGHT	The Height value is a fixed coordinate.
SCALED_WIDTH	The Width value is a scaled coordinate.
SCALED_HEIGHT	The Height value is a scaled coordinate.

EffectXML STRING Returns a SVG XML string that defines the filter's effects.

This field value will return a purpose-built string that defines the filter's effects in SVG compliant XML. The string is allocated and must be freed once no longer in use.

Height DOUBLE The height of the filter area. Can be expressed as a fixed or scaled coordinate.

The height of the filter area is expressed here as a fixed or scaled coordinate. The Width and Height effectively restrain the working space for the effect processing, making them an important consideration for efficiency.

The coordinate system for the width and height depends on the value for Units.

The default values for Width and Height is 120%, as per the SVG standard. This provides a buffer space for the filter algorithms to work with, and is usually a sufficient default.

Inherit *VectorFilter Inherit attributes from a VectorFilter referenced here.

Attributes can be inherited from another filter by referencing that gradient in this field. This feature is provided primarily for the purpose of simplifying SVG compatibility and its use may result in an unnecessary performance penalty.

Opacity DOUBLE The opacity of the filter.

The opacity of the filter is defined as a value between 0.0 and 1.0, with 1.0 being fully opaque. The default value is 1.0.

PrimitiveUnits VUNIT Alters the behaviour of some effects that support alternative position calculations.

PrimitiveUnits alters the behaviour of some effects when their dimensions are calculated. The default value is USERSPACE. When set to BOUNDING_BOX, the effect may calculate its dimensions strictly based on the client vector using a scaled coordinate space of (0, 0, 100%, 100%).

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.

ResX INT Width of the intermediate images, measured in pixels.

The combination of ResX and ResY define the available space for rendering of filter effects. It is recommended that the client does not set these values because the default 1:1 pixel ratio is appropriate in the majority of circumstances.

ResY INT Height of the intermediate images, measured in pixels.

The combination of ResX and ResY define the available space for rendering of filter effects. It is recommended that the client does not set these values because the default 1:1 pixel ratio is appropriate in the majority of circumstances.

Units VUNIT Defines the coordinate system for X, Y, Width and Height.

The default coordinate system is BOUNDING_BOX, which positions the filter within the client vector. The alternative is USERSPACE, which positions the filter relative to the client vector's nearest 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.

Width DOUBLE The width of the filter area. Can be expressed as a fixed or scaled coordinate.

The width of the filter area is expressed here as a fixed or scaled coordinate. The Width and Height effectively restrain the working space for the effect processing, making them an important consideration for efficiency.

The coordinate system for the width and height depends on the value for Units.

The default values for Width and Height is 120%, as per the SVG standard. This provides a buffer space for the filter algorithms to work with, and is usually a sufficient default.

X DOUBLE X coordinate for the filter.

The meaning of the (X, Y) field values depend on the value for Units. In userspace mode, the filter position will be relative to the client vector's parent viewport. In bounding-box mode, the filter position is relative to the vector's position. It is important to note that coordinates are measured before any transforms are applied.

The default values for X and Y is 10%, as per the SVG standard. This provides a buffer space for the filter algorithms to work with, and is usually a sufficient default.

Y DOUBLE Y coordinate for the filter.

The meaning of the (X, Y) field values depend on the value for Units. In userspace mode, the filter position will be relative to the client vector's parent viewport. In bounding-box mode, the filter position is relative to the vector's position. It is important to note that coordinates are measured before any transforms are applied.

The default values for X and Y is 10%, as per the SVG standard. This provides a buffer space for the filter algorithms to work with, and is usually a sufficient default.

Actions

The following actions are currently supported:

	Clear	Removes all filter effects.

DMF Type

Name	Description
DMF::FIXED_CENTER_X	The CenterX field is a fixed size.
DMF::FIXED_CENTER_Y	The CenterY field is a fixed size.
DMF::FIXED_DEPTH	The Depth field is a fixed size.
DMF::FIXED_HEIGHT	The Height field is a fixed size.
DMF::FIXED_RADIUS_X	The RadiusX field is a fixed size.
DMF::FIXED_RADIUS_Y	The RadiusY field is a fixed size.
DMF::FIXED_WIDTH	The Width field is a fixed suze.
DMF::FIXED_X	The X field is a fixed coordinate.
DMF::FIXED_X_OFFSET	The XOffset field is a fixed coordinate.
DMF::FIXED_Y	The Y field is a fixed coordinate.
DMF::FIXED_Y_OFFSET	The YOffset field is a fixed coordinate.
DMF::FIXED_Z	The Z field is a fixed coordinate.
DMF::SCALED_CENTER_X	The CenterX field is scaled to this object's parent.
DMF::SCALED_CENTER_Y	The CenterY field is scaled to this object's parent.
DMF::SCALED_DEPTH	The Depth field is scaled to this object's parent.
DMF::SCALED_HEIGHT	The Height field is scaled to this object's parent.
DMF::SCALED_RADIUS_X	The RadiusX field is scaled to this object's parent.
DMF::SCALED_RADIUS_Y	The RadiusY field is a scaled size to this object's parent.
DMF::SCALED_WIDTH	The Width field is scaled to this object's parent.
DMF::SCALED_X	The X field is scaled to this object's parent.
DMF::SCALED_X_OFFSET	The XOffset field is scaled to this object's parent.
DMF::SCALED_Y	The Y field is scaled to this object's parent.
DMF::SCALED_Y_OFFSET	The YOffset field is scaled to this object's parent.
DMF::SCALED_Z	The Z field is a scaled coordinate to this object's parent.
DMF::STATUS_CHANGE_H
DMF::STATUS_CHANGE_V

VCS Type

Colour space options.

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.

VFA Type

Define the aspect ratio for VectorFilter unit scaling.

Name	Description
VFA::MEET	Scale X/Y values independently and in relation to the width/height of the parent viewport.
VFA::NONE	Scale X/Y values on a `1:1` basis, in relation to the diagonal of the parent viewport.

VUNIT Type