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.
The VectorFilter class consists of the following fields:
Access | Name | Type | Comment | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
AspectRatio | VFA | Aspect ratio to use when scaling X/Y values | |||||||||||||||||||
| |||||||||||||||||||||
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.
| |||||||||||||||||||||
Dimensions | DMF | Dimension flags define whether individual dimension fields contain fixed or scaled values. | |||||||||||||||||||
The following dimension flags are supported:
| |||||||||||||||||||||
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 | |||||||||||||||||||||
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
| |||||||||||||||||||||
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 | |||||||||||||||||||||
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 | |||||||||||||||||||||
Units | VUNIT | Defines the coordinate system for X, Y, Width and Height. | |||||||||||||||||||
The default coordinate system is
| |||||||||||||||||||||
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 | |||||||||||||||||||||
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 | |||||||||||||||||||||
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 |
The following actions are currently supported:
Name | Comment | |
---|---|---|
Clear | Removes all filter effects. |
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 |
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. |
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. |
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. |
Class Info | |
---|---|
ID | ID_VECTORFILTER |
Category | Graphics |
Include | modules/vectorfilter.h |
Version | 1 |