Create, manipulate and draw vector graphics to bitmaps.

The Vector module exports a small number of functions to assist the Vector class, as well as some primitive functions for creating paths and rendering them to bitmaps.

Functions

ApplyPath | ArcTo | CharWidth | ClosePath | Curve3 | Curve4 | DrawPath | FlushMatrix | GenerateEllipse | GeneratePath | GenerateRectangle | GetFontHandle | GetFontMetrics | GetVertex | LineTo | MoveTo | Multiply | MultiplyMatrix | ParseTransform | ReadPainter | ResetMatrix | RewindPath | Rotate | Scale | Skew | Smooth3 | Smooth4 | StringWidth | TracePath | Translate | TranslatePath

Structures

DiffusionCurveRecord | FontMetrics | GouraudVertex | GradientStop | MergeSource | MeshControl | MeshPatchRecord | PathCommand | Transition | VectorMatrix | VectorPainter | VectorPoint | VoronoiPoint

Classes

BlurFX | ColourFX | CompositeFX | ConvolveFX | DisplacementFX | FilterEffect | FloodFX | Gradient | GradientConic | GradientContour | GradientDiamond | GradientDiffusion | GradientDistal | GradientGouraud | GradientLinear | GradientMesh | GradientRadial | GradientVoronoi | ImageFX | LightingFX | MergeFX | MorphologyFX | OffsetFX | RemapFX | SourceFX | TurbulenceFX | Vector | VectorClip | VectorColour | VectorEllipse | VectorFilter | VectorGroup | VectorImage | VectorPath | VectorPattern | VectorPolygon | VectorRectangle | VectorScene | VectorShape | VectorSpiral | VectorText | VectorTransition | VectorViewport | VectorWave | WaveFunctionFX

Constants

ARC | JET | JTYPE | PE | VSF

ApplyPath()

Applies a generated path resource to a VectorPath object.

Any path originating from GeneratePath(), GenerateEllipse() or GenerateRectangle() can be applied to a VectorPath object by calling ApplyPath(). The source Path can then be deallocated with FreeResource() if it is no longer required.

This function is intended for paths that are generated or changed at run-time, where converting the path back to a string would add unnecessary processing overhead.

Error Codes

ArcTo()

Appends an arc command to a generated path.

This function appends an arc segment from the current point to X,Y. The LARGE and SWEEP values in Flags control which of the possible arcs is selected.

CharWidth()

Returns the rendered width of a single character.

This function returns the pixel width of a font character. The character is specified as a Unicode value in the Char parameter. Kerning can also be returned for positioning the character against a preceding character. Pass the preceding character in KChar and a Kerning pointer to receive the horizontal adjustment. If kerning information is not required, set KChar to zero and Kerning to NULL.

The font's glyph spacing value is not used in calculating the character width.

Result

The pixel width of the character, or 0 if FontHandle is NULL.

ClosePath()

Closes the current sub-path.

This function appends a close-path command that connects the current point to the beginning of the current sub-path.

Closing a path does not terminate the path resource. Further sub-paths can be added to the sequence, and fill rules can then be used to control how overlapping areas are rendered.

Curve3()

Appends a quadratic Bezier curve to a generated path.

This function appends a quadratic Bezier segment from the current point to X,Y using CtrlX,CtrlY as the control point.

Curve4()

Appends a cubic Bezier curve to a generated path.

This function appends a cubic Bezier segment from the current point to X,Y using two control points.

DrawPath()

Draws a generated vector path to a target bitmap.

Use DrawPath() to draw a generated path to a Bitmap, using customised fill and stroke definitions. This functionality provides an effective alternative to configuring vector scenes for situations where only simple vector shapes are required. However, it is limited in that advanced rendering options and effects are not available to the client.

At least one of StrokeStyle or FillStyle is required to render visible output. Valid styles are allocated and configured using recognised vector style objects, specifically VectorImage, VectorPattern and Gradient. If a fill or stroke operation is not required, set the relevant parameter to NULL. Stroke rendering is also disabled when StrokeWidth is less than 0.001.

Error Codes

FlushMatrix()

Marks a vector transform as changed after direct matrix edits.

If a vector's matrix values have been modified directly by the client, call FlushMatrix() before the next draw cycle so the owning vector is marked for transform recalculation.

Note that if the client uses API functions to modify a VectorMatrix, a call to FlushMatrix() is unnecessary as the vector will have already been marked for an update.

Error Codes

GenerateEllipse()

Generates an elliptical path resource.

Use GenerateEllipse() to create an elliptical path suitable for passing to vector functions that receive a Path parameter. The path must be manually deallocated with FreeResource() once it is no longer required.

Error Codes

GeneratePath()

Generates a path resource from an SVG path command sequence.

This function generates a vector path from a sequence of coordinates and path instructions. The resulting path can then be passed to vector functions that receive a Path parameter. The path must be manually deallocated with FreeResource() once it is no longer required.

The Sequence string is based on the SVG path element's d attribute. Uppercase commands use absolute coordinates; lowercase commands use coordinates relative to the previous command.

The following commands are supported:

M: Move To
L: Line To
V: Vertical Line To
H: Horizontal Line To
Q: Quadratic Curve To
T: Quadratic Smooth Curve To
C: Curve To
S: Smooth Curve To
A: Arc
Z: Close Path

If Sequence is empty, an empty path resource will be generated. This path can be populated with functions such as MoveTo() and LineTo().

Error Codes

GenerateRectangle()

Generates a rectangular path resource.

Use GenerateRectangle() to create a rectangular path suitable for passing to vector functions that receive a Path parameter. The path must be manually deallocated with FreeResource() once it is no longer required.

Error Codes

GetFontHandle()

Returns a cached handle for a font family, style and size.

For a given font family, style and size, this function returns a Handle that can be passed to font querying functions.

The handle is deterministic and permanent, remaining valid for the lifetime of the program.

Error Codes

GetFontMetrics()

Returns display metrics for a font handle.

Call GetFontMetrics() to retrieve the font height, line spacing, ascent and descent values for a font handle.

Error Codes

GetVertex()

Retrieves the next vertex from a generated path.

The coordinates of the next vertex are returned in X and Y. The return value is the internal command value for that vertex, or the path stop command when there are no more vertices to read.

Result

The internal command value for the vertex will be returned.

LineTo()

Appends a line segment to a generated path.

This function appends a straight line from the current point to X,Y.

MoveTo()

Moves the current point in a generated path.

This function appends a move command. The current point is moved to X,Y without drawing a line.

Multiply()

Multiplies a matrix by explicit affine transform values.

This function multiplies the target VectorMatrix by the supplied affine transform values.

Error Codes

MultiplyMatrix()

Multiplies a target matrix by a source matrix.

This function multiplies Target by Source and stores the result in Target.

Error Codes

ParseTransform()

Parses an SVG transform string and applies it to a matrix.

This function parses a sequence of SVG transform instructions and applies them to a matrix.

The string must be written using SVG transform attribute syntax. For example, skewX(20) rotate(45 50 50) is valid. Transform instructions are applied in reverse order, as required by the SVG transform model. Unsupported transform text is skipped.

Any existing values in Matrix are reset before the parsed transforms are applied. If existing matrix values need to be retained, parse into a separate matrix and use MultiplyMatrix() to combine the result.

Error Codes

ReadPainter()

Parses a painter string to its colour, gradient, pattern or image value.

This function will parse an SVG style IRI into its equivalent logical values. The results can then be processed for rendering a stroke or fill operation in the chosen style.

Colours can be expressed in the following formats:

A Gradient, Image or Pattern can be referenced using the url(#name) format, where name is a definition registered with the provided Scene object. If Scene is NULL then it will not be possible to find the reference. Any failure to look up a reference will result in an error. The Scene parameter accepts either a VectorScene or a Vector object if its Scene field value is defined.

To access one of the pre-defined colourmaps, use the format url(#cmap:name). The colourmap will be accessible as a linear gradient that belongs to the Scene. Valid colourmap names are cmap:crest, cmap:flare, cmap:icefire, cmap:inferno, cmap:magma, cmap:mako, cmap:plasma, cmap:rocket, cmap:viridis.

A VectorPainter structure must be provided by the client and will be used to store the final result. All pointers that are returned will remain valid as long as the provided Scene exists with its registered painter definitions. An optional Result string can store a reference to the character position up to which the IRI was parsed.

Note: To ensure that colour values are never clipped, values stored in the Colour field are unclamped from the sRGB colour space (colours may be negative or exceed 1.0). Clients must clamp colours as necessary when converting to their target colour space.

Error Codes

ResetMatrix()

Resets a transformation matrix to the identity transform.

Call ResetMatrix() to clear all scaling, skewing, rotation and translation from a !VectorMatrix.

Error Codes

RewindPath()

Resets path iteration to the first vertex.

Rewinding a path resets its internal vertex iterator to the first vertex. The next call to GetVertex() will read from the start of the path.

If the referenced Path is empty, this function does nothing.

Rotate()

Applies a rotation transform to a matrix.

This function rotates a matrix by Angle degrees. Rotation occurs around (0, 0) unless CenterX and CenterY specify another centre point.

Error Codes

Scale()

Applies a scale transform to a matrix.

This function scales a matrix on the x and y axes. Values less than 1.0 shrink the affected vector path, while values greater than 1.0 enlarge it.

Scaling is relative to position (0, 0). If the width and height of the vector path needs to be transformed without affecting its top-left position, the client must translate the path to (0, 0) around its centre point. The path should then be scaled before being transformed back to its original top-left coordinate.

The scale operation can also be used to flip a vector path if negative values are used. For instance, a value of -1.0 on the x axis results in a 1:1 horizontal flip.

Error Codes

Skew()

Applies a skew transform to a matrix.

The Skew function applies a skew transformation to the horizontal and/or vertical axis of the matrix. Valid X and Y values are in the range -90 < Angle < 90.

If X is valid and Y is outside the valid range, the horizontal skew is applied before ERR::OutOfRange is returned.

Error Codes

Smooth3()

Appends a smooth quadratic Bezier curve to a generated path.

This function appends a quadratic Bezier segment from the current point to X,Y. The control point is reflected from the previous curve command.

Smooth4()

Appends a smooth cubic Bezier curve to a generated path.

This function appends a cubic Bezier segment from the current point to X,Y. The previous curve command supplies the reflected first control point, and CtrlX,CtrlY supply the second control point.

StringWidth()

Calculates the rendered width of a UTF-8 string.

This function calculates the pixel width of String for a known font. Line-feeds are treated as line breaks, so for multi-line strings the width of the longest line is returned.

For scalable fonts, kerning is included when computing the distance between glyphs.

Result

The pixel width of the string, or 0 if FontHandle or String is NULL.

TracePath()

Calls a function for each traced coordinate in a generated path.

Any generated path can be traced by calling this function. Tracing allows the caller to follow the Path point-by-point as it would be rendered with a stroke. The Callback function signature is ERR Function(*Path, INT Index, INT Command, DOUBLE X, DOUBLE Y, *Meta).

The Index is an incrementing counter for each plotted point. The Command value identifies the internal path command, and X,Y are the traced coordinates.

If the Callback returns ERR::Terminate, processing stops and the function returns immediately.

Error Codes

Translate()

Applies a translation transform to a matrix.

This function adds the supplied x and y offsets to the matrix translation values.

Error Codes

TranslatePath()

Translates every vertex in a generated path.

This function offsets all vertices in Path by X,Y. If Path is NULL, the call is ignored.

ARC Type

Options for drawing arcs.

JET Type

JET constants are documented in GetInputEvent()

JTYPE Type

JTYPE flags are used to categorise input types

PE Type

VSF Type

Filter source types - these are used internally

DiffusionCurveRecord Structure

Describes one curve for the GradientDiffusion Curves field.

FontMetrics Structure

Font metrics, measured in pixels relative to the display

GouraudVertex Structure

Describes a coloured vertex for the GradientGouraud Vertices field.

GradientStop Structure

Describes a colour stop for the Gradient Stops field.

MergeSource Structure

Input source declaration for MergeFX

MeshControl Structure

Describes one control point for the GradientMesh.

MeshPatchRecord Structure

Describes one bilinear Coons patch for the GradientMesh Patches field.

PathCommand Structure

Base structure for path commands.

Transition Structure

For VectorTransition definitions

VectorMatrix Structure

Vector transformation matrix.

VectorPainter Structure

Deserialised painter information; compliant with SVG painter definitions.

VectorPoint Structure

Structure for the VectorPolygon PointsArray field.

VoronoiPoint Structure

Describes a feature point for the GradientVoronoi Points field.