Manages the scene graph for a collection of vectors.

The VectorScene class acts as a container and control point for the management of vector definitions. Its main purpose is to draw the scene to a target Bitmap or Surface provided by the client.

Vector scenes are created by initialising multiple Vector objects such as VectorPath and VectorViewport and positioning them within a vector tree. The VectorScene must lie at the root of the tree.

The default mode of operation is for scenes to be manually drawn, for which the client must set the target Bitmap and call the Draw() action as required. Automated drawing can be enabled by setting the target Surface prior to initialisation. In automated mode the PageWidth and PageHeight will reflect the dimensions of the target surface at all times.

Vector definitions can be saved and loaded from permanent storage by using the SVG class.

Structure

The VectorScene class consists of the following fields:

Access

Name

Type

Comment

Bitmap *Bitmap Target bitmap for drawing vectors.

The target bitmap to use when drawing the vectors must be specified here.

Flags VPF Optional flags.

Name	Description
VPF::BITMAP_SIZED	Automatically adjust the VectorScene⇒PageWidth and VectorScene⇒PageHeight to match the target Bitmap⇒Width and Bitmap⇒Height.
VPF::OUTLINE_VIEWPORTS	Draw a green outline around all viewport paths. Extremely useful for debugging layout issues.
VPF::RENDER_TIME	Compute the drawing frame-rate for the `RenderTime` field.
VPF::RESIZE	The vector will be stretched to fit the VectorScene⇒PageWidth and VectorScene⇒PageHeight values, if defined by the client.
VPF::STABLE_RENDER	Use rendering algorithms that are stable across all platforms.

HostScene *VectorScene Refers to a top-level VectorScene object, if applicable.

Set HostScene to another VectorScene object if it is intended that this scene is a child of the other. This allows some traits such as vector definitions to be automatically inherited from the host scene.

This feature is useful in circumstances where a hidden group of vectors need to be managed separately, while retaining access to established definitions and vectors in the main.

PageHeight INT The height of the page that contains the vector.

This value defines the pixel height of the page that contains the vector scene graph. If the RESIZE Flags option is used then the viewport will be scaled to fit within the page.

PageWidth INT The width of the page that contains the vector.

This value defines the pixel width of the page that contains the vector scene graph. If the RESIZE Flags option is used then the viewport will be scaled to fit within the page.

RenderTime INT64 Returns the rendering time of the last scene.

RenderTime returns the rendering time of the last scene that was drawn, measured in microseconds. This value can also be used to compute frames-per-second with 1000000 / RenderTime.

The RENDER_TIME flag must be set before fetching this value, as it is required to enable the timing feature. If RENDER_TIME is not set, it will be set automatically so that subsequent calls return a correct value.

SampleMethod VSM The sampling method to use when interpolating images and patterns.

The SampleMethod controls the sampling algorithm that is used when images and patterns in the vector definition are affected by rotate, skew and scale transforms. The choice of method will have a significant impact on the speed and quality of the images that are displayed in the rendered scene. The recommended default is AUTO, which allows the drawing algorithms to choose the best quality option dynamically.

Name	Description
VSM::AUTO	The default option is chosen by the system. This will typically be `BILINEAR`, but slow machines may switch to nearest neighbour and high speed machines could use more advanced methods.
VSM::BESSEL	Uses a broad Bessel filter that can preserve detail during resampling, but is slower than the smaller-kernel methods.
VSM::BICUBIC	Produces a similar result to `BILINEAR` at a slightly higher CPU cost and a marginally sharper after-effect.
VSM::BILINEAR	Bilinear is a common algorithm that produces a reasonable quality image quickly.
VSM::BLACKMAN	Five times slower than `BILINEAR`, the final result will be less sharp than SINC.
VSM::GAUSSIAN	Uses a Gaussian filter that softens the result, reducing aliasing at the cost of sharp edge detail.
VSM::KAISER	Uses a Kaiser-windowed filter, giving smooth interpolation with low ringing and a cost close to `BILINEAR`.
VSM::LANCZOS	This well known algorithm may serve as a point of comparison for evaluating the results of other methods. It shares characteristics with `SINC` and `BLACKMAN`.
VSM::MITCHELL	Uses a Mitchell-Netravali filter, balancing sharpness and smoothness at a cost similar to `BICUBIC`.
VSM::NEIGHBOUR	Nearest neighbour is the fastest sampler at the cost of poor quality.
VSM::QUADRIC	Uses a quadratic filter with a modest kernel, giving smoother results than `BILINEAR` with limited extra cost.
VSM::SINC	Five times slower than `BILINEAR`, the final result is of very good quality.
VSM::SPLINE16	About twice as slow as `BILINEAR`, this method samples a 4x4 area and produces a considerably better result, and is a good choice for enlarging images without producing artifacts when contrasting colours are present.

Surface OBJECTID May refer to a Surface object for enabling automatic rendering.

Setting the Surface field will enable automatic rendering to a display Surface. The use of features such as input event handling and user focus management will also require an associated surface as a pre-requisite.

Viewport *VectorViewport References the first object in the scene, which must be a VectorViewport object.

The first object in the vector scene is referenced here. It must belong to the VectorViewport class, which will be used to define the size and location of the area rendered by the scene.

The Viewport value cannot be set by the client. It will be automatically defined when the first VectorViewport owned by the VectorScene is initialised.

Actions

The following actions are currently supported:

Draw Renders the scene to a bitmap.

ERR acDraw(*Object, DOUBLE X, DOUBLE Y, DOUBLE Width, DOUBLE Height)

Parameter	Description
X	The X position of the region to be drawn.
Y	The Y position of the region to be drawn.
Width	The width of the region to be drawn.
Height	The height of the region to be drawn.

The Draw action will render the scene to the target Bitmap immediately. If Bitmap is NULL, an error will be returned.

In addition, the RenderTime field will be updated if the RENDER_TIME flag is defined.

Error Codes

Okay	Operation successful.
FieldNotSet	The Bitmap field is NULL.

Flush Flush buffered data from an object.

Redimension Redefines the size of the page.

ERR acRedimension(*Object, DOUBLE X, DOUBLE Y, DOUBLE Z, DOUBLE Width, DOUBLE Height, DOUBLE Depth)

Parameter	Description
X	The new X position to apply to the target object.
Y	The new Y position to apply to the target object.
Z	The new Z position to apply to the target object.
Width	The new width of the target object.
Height	The new height of the target object.
Depth	The new depth of the target object.

Reset Clears all registered definitions and resets field values. Child vectors are unmodified.

Resize Redefines the size of the page.

ERR acResize(*Object, DOUBLE Width, DOUBLE Height, DOUBLE Depth)

Parameter	Description
Width	The new width of the object.
Height	The new height of the object.
Depth	The new depth of the object.

Methods

The following methods are currently supported:

AddDef Registers a named definition object within a scene graph.

ERR sc::AddDef(OBJECTPTR Object, STRVIEW Name, OBJECTPTR Def)

Parameter	Description
Name	The unique name to associate with the definition.
Def	Reference to the definition object.

This method will add a new definition object to the root of a vector tree and gives it a name. This feature is provided to support SVG style referencing for features such as gradients, images and patterns. By providing a name with the definition object, the object can then be referenced in URL strings.

For example, if creating a gradient with a name of redGradient it would be possible to reference it with url(#redGradient) in common graphics attributes such as fill and stroke.

At the time of writing, the provided object must belong to one of the following classes to be valid: Vector, VectorScene, Gradient, VectorImage, VectorPath, VectorPattern, VectorFilter, VectorTransition, VectorClip.

Error Codes

Okay	Operation successful.
UnsupportedOwner	The definition is not owned by the scene.
ResourceExists	The given name is already in use as a definition.
NullArgs	Function call missing argument value(s)
InvalidObject	The definition is not an accepted object class.

Debug Internal functionality for debugging.

ERR sc::Debug(OBJECTPTR Object)

This internal method prints comprehensive information that describes the scene graph to the log.

Error Codes

Okay	Operation successful.

FindDef Search for a vector definition by name.

ERR sc::FindDef(OBJECTPTR Object, STRVIEW Name, OBJECTPTR * Def)

Parameter	Description
Name	The name of the definition.
Def	A pointer to the definition object is returned here if discovered.

Use the FindDef method to search for a vector definition by name. A reference to the definition will be returned if the search is successful.

Definitions are created with the AddDef() method.

Error Codes

Okay	Operation successful.
Search	A definition with the given Name was not found.
NullArgs	Function call missing argument value(s)

VPF Type

Optional flags for the VectorScene object.

Name	Description
VPF::BITMAP_SIZED	Automatically adjust the VectorScene⇒PageWidth and VectorScene⇒PageHeight to match the target Bitmap⇒Width and Bitmap⇒Height.
VPF::OUTLINE_VIEWPORTS	Draw a green outline around all viewport paths. Extremely useful for debugging layout issues.
VPF::RENDER_TIME	Compute the drawing frame-rate for the `RenderTime` field.
VPF::RESIZE	The vector will be stretched to fit the VectorScene⇒PageWidth and VectorScene⇒PageHeight values, if defined by the client.
VPF::STABLE_RENDER	Use rendering algorithms that are stable across all platforms.

VSM Type

Name	Description
VSM::AUTO	The default option is chosen by the system. This will typically be `BILINEAR`, but slow machines may switch to nearest neighbour and high speed machines could use more advanced methods.
VSM::BESSEL	Uses a broad Bessel filter that can preserve detail during resampling, but is slower than the smaller-kernel methods.
VSM::BICUBIC	Produces a similar result to `BILINEAR` at a slightly higher CPU cost and a marginally sharper after-effect.
VSM::BILINEAR	Bilinear is a common algorithm that produces a reasonable quality image quickly.
VSM::BLACKMAN	Five times slower than `BILINEAR`, the final result will be less sharp than SINC.
VSM::GAUSSIAN	Uses a Gaussian filter that softens the result, reducing aliasing at the cost of sharp edge detail.
VSM::KAISER	Uses a Kaiser-windowed filter, giving smooth interpolation with low ringing and a cost close to `BILINEAR`.
VSM::LANCZOS	This well known algorithm may serve as a point of comparison for evaluating the results of other methods. It shares characteristics with `SINC` and `BLACKMAN`.
VSM::MITCHELL	Uses a Mitchell-Netravali filter, balancing sharpness and smoothness at a cost similar to `BICUBIC`.
VSM::NEIGHBOUR	Nearest neighbour is the fastest sampler at the cost of poor quality.
VSM::QUADRIC	Uses a quadratic filter with a modest kernel, giving smoother results than `BILINEAR` with limited extra cost.
VSM::SINC	Five times slower than `BILINEAR`, the final result is of very good quality.
VSM::SPLINE16	About twice as slow as `BILINEAR`, this method samples a 4x4 area and produces a considerably better result, and is a good choice for enlarging images without producing artifacts when contrasting colours are present.

VectorScene Class

Structure

Actions

Methods

VPF Type

VSM Type