Parasol Framework Manual

Provides comprehensive support for parsing, rendering and animating SVG documents.

The SVG class serves as a complete solution for integrating Scalable Vector Graphics documents into applications. It parses SVG statements into a scene graph consisting of Vector objects and related constructs, providing direct programmatic access to all graphical elements. The generated scene graph is accessible via the Scene and Viewport fields, enabling real-time manipulation of individual elements.

Key capabilities include:

W3C-compliant SVG parsing with support for advanced features including gradients, filters, and patterns
SMIL animation support with automatic frame-based playback
Dynamic scene graph manipulation for real-time graphics modification
Flexible rendering targets via the Target field for integration with existing UI components
Symbol-based graphics with macro-like functionality through ParseSymbol()
Resolution-independent scaling with automatic adaptation to display characteristics
Export capabilities to multiple formats including PNG images

The class supports both file-based loading via Path and direct string-based parsing via Statement. SVG documents can be integrated into existing scene graphs by setting the Target field, or rendered independently through the automatically created scene structure.

Animation timing is controlled through the FrameRate field, with callback support via FrameCallback for custom rendering workflows. The implementation maintains compatibility with the complete SVG specification while providing enhanced programmatic access unique to the Parasol framework.

Please refer to the W3C's online documentation for exhaustive information on the SVG standard.

Structure

The SVG class consists of the following fields:

Access

Name

Type

Comment

Colour STRING Defines the default fill to use for currentColor references.

Set the Colour value to alter the default fill that is used for currentColor references. Typically a standard RGB painter fill reference should be used for this purpose, e.g. rgb(255,255,255). It is however, also acceptable to use URL references to named definitions such as gradients and images. This will work as long as the named definition is registered in the top-level VectorScene object.

Supported formats:

RGB values: rgb(red, green, blue)
Hexadecimal notation: #RRGGBB or #RGB
Named colours: Standard SVG colour names
URL references: url(#gradientId) for complex paint definitions

Flags SVF Configuration flags that modify SVG processing behaviour.

Name	Description
SVF::ALPHA	Generate an alpha channel in the rendered image.
SVF::AUTOSCALE	In auto-resize mode, vector dimensions are scaled to the width and height of the vector page. The VectorScene⇒PageWidth and VectorScene⇒PageHeight must be set for this.
SVF::ENFORCE_TRACKING	Enforce tracking of definition objects when a Target is used.

Frame INT Constrains rendering to a specific frame number for frame-based display systems.

This field enables frame-synchronised rendering by restricting graphics display to specific frame numbers within frame-based container systems. When set to a non-zero value, the SVG content will only be rendered when the container's current frame matches this field's value.

The default value of 0 disables frame-based filtering, allowing the SVG content to be rendered continuously regardless of the container's frame state.

FrameCallback FUNCTION Function callback executed after each animation frame preparation.

This field enables integration of custom logic into the animation processing pipeline by specifying a callback function that executes after each animation frame is computed. The callback mechanism provides precise timing for implementing custom rendering workflows, frame capture systems, or animation synchronisation logic.

The callback function receives a pointer to the SVG object, enabling access to the current scene state and rendering control. This is commonly used for rendering the animated SVG content to target bitmaps, implementing video capture, or synchronising with external animation systems.

Timing behaviour: The callback executes immediately after frame preparation but before automatic scene redrawing, ensuring that custom logic can modify or capture the scene state at the optimal moment.

Animation dependency: Callbacks are only triggered for SVG documents containing SMIL animation features. Static documents will not invoke the callback function.

Function prototype: void Function(*SVG)

FrameRate INT Controls the maximum frame rate for SVG animation playback.

This field establishes the upper limit for animation frame processing, measured in frames per second. The frame rate directly impacts animation smoothness and system resource consumption, requiring careful balance between visual quality and performance efficiency.

Recommended ranges:

Standard displays: 60 FPS matches most modern display refresh rates
Balanced performance: 30-50 FPS provides smooth animation with moderate resource usage
Low-power devices: 20-30 FPS conserves battery while maintaining acceptable quality

Performance considerations: Higher frame rates increase CPU usage proportionately. A frame rate of 100 FPS consumes approximately twice the processing power of 50 FPS, with corresponding impact on power consumption and thermal characteristics.

Valid range: 20-1000 FPS, though values above 120 FPS rarely provide perceptible improvements on standard displays.

The frame rate only affects animated SVG documents containing SMIL features. Static documents are unaffected by this setting.

Path STRING File system path to the source SVG document.

This field specifies the location of the SVG file to be loaded and processed during object initialisation. The path supports both absolute and relative file references, with relative paths resolved according to the current working directory context.

The loading process occurs automatically during initialisation when a valid path is specified. The referenced file must contain well-formed SVG content that conforms to W3C SVG standards for successful parsing.

Supported file types: Standard SVG files (*.svg) and compressed SVG files (*.svgz) are both supported, with automatic decompression handling for compressed formats.

Path resolution: The file system path is resolved through the standard Parasol file access mechanisms, supporting virtual file systems, archives, and network-accessible resources where configured.

When both Path and Statement are specified, the Path field takes precedence and the Statement content is ignored during initialisation.

Scene OBJECTPTR Reference to the VectorScene object containing the SVG scene graph.

This read-only field provides direct access to the VectorScene object that manages the complete SVG scene graph structure. The scene object serves as the root container for all generated vector elements and provides essential rendering coordination.

The scene reference remains valid throughout the SVG object's lifetime and enables direct manipulation of scene-wide properties including page dimensions, rendering settings, and global definitions. This field simplifies access to the scene graph for applications requiring programmatic control over the complete document structure.

Scene relationship: When a Target is specified, the Scene field references the VectorScene that owns the target object. For automatically generated scenes, this field references the internally created scene object.

Statement STRING String containing complete SVG document markup.

SVG data can be loaded from a string by specifying it here prior to initialisation. If the Path field has been defined, it will take precedent and the Statement is ignored.

For incremental data parsing after initialisation, consider using the DataFeed() action instead, which supports progressive document construction from data streams.

Target OBJECTPTR Destination container for the generated SVG scene graph elements.

This field redirects the generated SVG scene graph to an existing container object instead of creating an independent scene structure. The target approach enables seamless integration of SVG content into established UI hierarchies and composite scene graphs.

Default behaviour: When no target is specified, the SVG object creates and manages a dedicated VectorViewport to contain the generated content. This viewport and its children remain under direct SVG object ownership.

Target requirements: The target object must be part of an existing scene graph owned by a VectorScene object. While any vector object can serve as a target, VectorViewport objects are recommended for optimal compatibility and performance.

Ownership implications: Specifying a target makes the generated scene graph independent of the SVG object lifecycle. The SVG object can be terminated without affecting the created vector elements, enabling flexible resource management patterns.

Resource tracking: When independent operation is not desired, enable the ENFORCE_TRACKING flag to maintain resource tracking relationships between the SVG object and generated definitions, ensuring proper cleanup on object destruction.

Title STRING The title of the SVG document.

The title of an SVG document is declared with a title element that can embedded anywhere in the document. In cases where a title has been specified, it will be possible to read it from this field. If no title is in the document then NULL will be returned.

Viewport OBJECTPTR Reference to the primary VectorViewport containing the SVG document content.

This read-only field provides direct access to the main VectorViewport object that contains the root-level SVG content.

Actions

The following actions are currently supported:

Activate Initiates playback of SVG animations.

ERR acActivate(*Object)

SVG documents containing SMIL animation features will remain static until activated through this action. Upon activation, the animation system begins processing animation sequences in the background according to the configured FrameRate. The Scene will be automatically redrawn as each frame is computed, ensuring smooth visual transitions.

To integrate custom rendering logic with the animation cycle, configure the FrameCallback field with an appropriate function. This callback will be triggered after each frame preparation, enabling applications to implement custom rendering workflows or capture animation frames.

Note: If the SVG document contains no animation elements, this action completes successfully but has no visual effect.

DataFeed Processes SVG data streams for incremental document parsing.

ERR acDataFeed(*Object, OBJECTID Object, DATA Datatype, APTR Buffer, INT Size)

Parameter	Description
Object	Must refer to the unique ID of the object that you represent. If you do not represent an object, set this parameter to the current task ID.
Datatype	The type of data being sent.
Buffer	The data being sent to the target object.
Size	The size of the data in Buffer.

The DataFeed action enables real-time processing of SVG data streams, allowing documents to be parsed incrementally as data becomes available. This is particularly useful for network-based loading scenarios or when processing large SVG documents that may arrive in segments.

The action accepts XML data streams and integrates them into the existing document structure. Multiple DataFeed calls can be made to build up complex SVG documents progressively.

Supported data types: DATA::XML for SVG content streams.

This mechanism provides an alternative to the static Statement field for scenarios requiring dynamic content loading or streaming workflows.

Deactivate Halts all SVG animation playback and suspends frame processing.

ERR acDeactivate(*Object)

This action immediately terminates any active animation playback, stopping all animation timers and suspending frame processing. The SVG document will remain visible in its current state, but no further animation updates will occur until the object is reactivated.

The deactivation process is immediate and does not affect the underlying scene graph structure. Animation sequences can be resumed from their current positions by calling the Activate() action again.

This action is particularly useful for implementing pause functionality or conserving system resources when animations are not required.

Init Initialises the SVG object and processes source content.

ERR InitObject(*Object)

The initialisation process establishes the scene graph structure and processes any specified SVG source content. If a Path has been configured, the referenced SVG file will be loaded and parsed immediately. Alternatively, if Statement contains SVG data, that content will be processed instead.

The default behaviour creates a local VectorScene object to contain the generated scene graph. This can be overridden by setting the Target field to redirect content into an existing scene graph structure, enabling integration with existing UI components.

The initialisation sequence includes:

Scene graph structure creation or validation of the specified Target
SVG document parsing and scene graph population
Resolution of SVG references, definitions, and symbol libraries
Animation sequence preparation for documents containing SMIL features

Successfully initialised SVG objects provide immediate access to the generated scene graph via the Scene and Viewport fields, enabling programmatic manipulation of individual graphic elements.

SaveImage Saves the SVG document as a PNG image.

ERR acSaveImage(*Object, OBJECTID Dest, CLASSID ClassID)

Parameter	Description
Dest	Refers to an object that will receive the encoded image data.
ClassID	The Picture class to use for encoding the image data.

This action will render the SVG document to a bitmap and save the resulting image. The size of the image is determined by the VectorScene⇒PageWidth and VectorScene⇒PageHeight of the Scene, or if not defined, the default of 1920x1080 is applied.

The image will be saved in PNG format by default, but can be changed by specifying an alternate ClassID. PNG is recommended in particular because it supports an alpha channel.

SaveToObject Saves the SVG document to a data object.

ERR acSaveToObject(*Object, OBJECTID Dest, CLASSID ClassID)

Parameter	Description
Dest	Refers to an object that will receive the encoded data.
ClassID	Can refer to a sub-class that should be used when encoding the data.

Methods

The following methods are currently supported:

ParseSymbol Instantiates an SVG symbol definition within a target viewport.

ERR svg::ParseSymbol(OBJECTPTR Object, CSTRING ID, objVectorViewport * Viewport)

Parameter	Description
ID	Name of the symbol to parse.
Viewport	The target viewport.

ParseSymbol() enables dynamic instantiation of SVG symbol definitions that were declared within the loaded document. This method provides macro-like functionality, allowing complex graphical elements to be replicated and positioned as needed throughout the application. This approach promotes efficient memory usage and consistent visual design while enabling dynamic scene graph construction.

The specified ID must correspond to a symbol element that exists within the current document's definition library. The generated content will be structured within the provided VectorViewport, which must be part of an established scene graph.

Render Performs high-quality rasterisation of the SVG document to a target bitmap.

ERR svg::Render(OBJECTPTR Object, objBitmap * Bitmap, INT X, INT Y, INT Width, INT Height)

Parameter	Description
Bitmap	The target bitmap object to receive the rendered content.
X	Horizontal position within the target bitmap.
Y	Vertical position within the target bitmap.
Width	Desired width of the rendered output in pixels.
Height	Desired height of the rendered output in pixels.

This method executes complete rasterisation of the SVG scene graph, producing a pixel-based representation within the specified target bitmap. The rendering process handles all vector elements, gradients, filters, and effects with full anti-aliasing and precision.

The rendered output is positioned at coordinates (X,Y) within the target bitmap and scaled to the specified (Width,Height) dimensions. The scaling operation maintains aspect ratios and applies appropriate filtering to ensure optimal visual quality.

The scene's page dimensions are temporarily adjusted to match the specified width and height, ensuring that the entire document content is properly scaled and positioned within the target area. This approach enables flexible rendering at arbitrary resolutions without affecting the original scene graph.

Performance considerations: Rendering complex SVG documents with multiple effects and high resolutions may require significant processing time. Consider using appropriate dimensions that balance quality requirements with performance constraints.

SVG Class

Structure

Actions

Methods

SVF Type