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.

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 BIGINT 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 should also 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 succeed correctly.

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 BILINEAR, which provides a comparatively average result and execution speed. The most advanced method is BLACKMAN8, which produces an excellent level of quality at the cost of very poor execution speed.

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
VSM::BICUBIC	Produces a similar result to `BILINEAR` with a marginally sharper after-effect.
VSM::BILINEAR	Bilinear is a common algorithm that produces a reasonable quality image quickly.
VSM::BLACKMAN3	Five times slower than `BILINEAR`, the final result will lack sharpness when compared to SINC3.
VSM::BLACKMAN8	15 times slower than `BILINEAR`, the final result is of excellent quality and sharpness is well balanced.
VSM::GAUSSIAN
VSM::KAISER
VSM::LANCZOS3	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::LANCZOS8
VSM::MITCHELL
VSM::NEIGHBOUR	Nearest neighbour is the fastest sampler at the cost of poor quality.
VSM::QUADRIC
VSM::SINC3	Five times slower than `BILINEAR`, the final result is of very good quality.
VSM::SINC8	15 times slower than `BILINEAR`, the final result is of excellent quality but may be marginally over-sharpened.
VSM::SPLINE16	About half the speed of `BILINEAR`, this method produces a considerably better result.

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, CSTRING 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, VectorGradient, 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, CSTRING 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)

SearchByID Search for a vector by numeric ID.

ERR sc::SearchByID(OBJECTPTR Object, LONG ID, OBJECTPTR * Result)

Parameter	Description
ID	The ID to search for.
Result	This parameter will be updated with the discovered vector, or `NULL` if not found.

This method will search a scene for an object that matches a given ID (vector ID's can be set with the Vector⇒NumericID or Vector⇒ID fields). If multiple vectors are using the same ID, repeated calls can be made to this method to find them all. This is achieved by calling this method on the vector that was last returned as a Result.

Note that searching for string-based ID's is achieved by converting the string to a case-sensitive hash with strhash() and using that as the ID.

Error Codes

Okay	Operation successful.
Search	A vector with a matching ID 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.

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
VSM::BICUBIC	Produces a similar result to `BILINEAR` with a marginally sharper after-effect.
VSM::BILINEAR	Bilinear is a common algorithm that produces a reasonable quality image quickly.
VSM::BLACKMAN3	Five times slower than `BILINEAR`, the final result will lack sharpness when compared to SINC3.
VSM::BLACKMAN8	15 times slower than `BILINEAR`, the final result is of excellent quality and sharpness is well balanced.
VSM::GAUSSIAN
VSM::KAISER
VSM::LANCZOS3	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::LANCZOS8
VSM::MITCHELL
VSM::NEIGHBOUR	Nearest neighbour is the fastest sampler at the cost of poor quality.
VSM::QUADRIC
VSM::SINC3	Five times slower than `BILINEAR`, the final result is of very good quality.
VSM::SINC8	15 times slower than `BILINEAR`, the final result is of excellent quality but may be marginally over-sharpened.
VSM::SPLINE16	About half the speed of `BILINEAR`, this method produces a considerably better result.

VectorScene Class

Structure

Actions

Methods

VPF Type

VSM Type