1. DESCRIPTION

AmanithSVG is a commercial middleware for reading and rendering of SVG files. The library is written in ANSI C++ and supports several platforms including: Android (ARM, ARMv7, MIPS, X86) - iOS7 (Universal Binary) - MacOS X (Universal Binary) - Windows (X86, X86_64) - Linux (ARM, ARMv7, MIPS, PPC, X86, X86_64).

  • Based on the robust AmanithVG SRE rendering engine
  • Really high antialiasing quality: analytical pixel coverage
  • Really fast rendering: 30ms tiger on Nexus4 at max resolution
  • Support of SVG Tiny 1.2 specifications with the exception of animation, text, images
  • Support of some SVG Full 1.1 features: radial gradients, gradients spread modes, path 'd' attribute complete syntax, inline styles.

2. STANDALONE API DOCUMENTATION

svgtInit

Initialize the library.
You must specify the device screen width and height (in pixels), and the dpi as well, in order to perform correct calculation on SVG measure units.
It returns SVGT_NO_ERROR if the operation was completed successfully, else an error code.
SVGTErrorCode svgtInit(SVGTuint screenWidth, 
                       SVGTuint screenHeight,
                       SVGTfloat dpi);

svgtDone

Destroy the library, freeing all allocated resources.
void svgtDone(void);

svgtSurfaceCreate

Create a new drawing surface, specifying its dimensions in pixels.
Specified width and height must be greater than zero.

Return SVGT_INVALID_HANDLE in case of errors, else a valid drawing surface handle.
SVGTHandle svgtSurfaceCreate(SVGTuint width,
                             SVGTuint height);

svgtSurfaceDestroy

Destroy a previously created drawing surface.

It returns SVGT_NO_ERROR if the operation was completed successfully, else an error code.
SVGTErrorCode svgtSurfaceDestroy(SVGTHandle surface);

svgtSurfaceResize

Resize a drawing surface, specifying new dimensions in pixels.
Specified newWidth and newHeight must be greater than zero.

After resizing, the surface viewport will be reset to the whole surface (see svgtSurfaceViewportGet / svgtSurfaceViewportSet), and the relative transformation will be reset to identity (pivot = [0; 0], angle = 0, post-translation = [0; 0], see svgtSurfaceViewportTransformGet / svgtSurfaceViewportTransformSet for details).

It returns SVGT_NO_ERROR if the operation was completed successfully, else an error code.
SVGTErrorCode svgtSurfaceResize(SVGTHandle surface,
                                SVGTuint newWidth,
                                SVGTuint newHeight);

svgtSurfaceWidth

Get width dimension (in pixels), of the specified drawing surface.
If the specified surface handle is not valid, 0 is returned.
SVGTuint svgtSurfaceWidth(SVGTHandle surface);

svgtSurfaceHeight

Get height dimension (in pixels), of the specified drawing surface.
If the specified surface handle is not valid, 0 is returned.
SVGTuint svgtSurfaceHeight(SVGTHandle surface);

svgtSurfacePixels

Get access to the drawing surface pixels.
If the specified surface handle is not valid, NULL is returned.

Please use this function to access surface pixels for read-only purposes (e.g. blit the surface on the screen, according to the platform graphic subsystem, upload pixels into a GPU texture, and so on).
Writing or modifying surface pixels by hand is still possible, but not advisable.
const void* svgtSurfacePixels(SVGTHandle surface);

svgtSurfaceCopy

Copy drawing surface content into the specified pixels buffer.
This method is a shortcut for the following copy operation:

    MemCopy(dstPixels32, svgtSurfacePixels(surface), svgtSurfaceWidth(surface) * svgtSurfaceHeight(surface) * 4)

This function is useful for managed environments (e.g. C#, Unity, Java, Android), where the use of a direct pixels access (i.e. svgtSurfacePixels) is not advisable nor comfortable.

This function returns:
- SVGT_BAD_HANDLE_ERROR if the specified surface handle is not valid
- SVGT_ILLEGAL_ARGUMENT_ERROR if dstPixels32 pointer is NULL or if it's not properly aligned
- SVGT_NO_ERROR if the operation was completed successfully
SVGTErrorCode svgtSurfaceCopy(SVGTHandle surface,
                              void* dstPixels32);

svgtSurfaceViewportGet

Get current destination viewport (i.e. a drawing surface rectangular area), where to map the source document viewport.

The 'viewport' parameter must be an array of (at least) 4 float entries, it will be filled with:
- viewport[0] = top/left x
- viewport[1] = top/left y
- viewport[2] = width
- viewport[3] = height

This function returns:
- SVGT_BAD_HANDLE_ERROR if specified surface handle is not valid
- SVGT_ILLEGAL_ARGUMENT_ERROR if viewport pointer is NULL or if it's not properly aligned
- SVGT_NO_ERROR if the operation was completed successfully
SVGTErrorCode svgtSurfaceViewportGet(SVGTHandle surface,
                                     SVGTfloat* viewport);

svgtSurfaceViewportSet

Set destination viewport (i.e. a drawing surface rectangular area), where to map the source document viewport.

The 'viewport' parameter must be an array of (at least) 4 float entries, it must contains:
- viewport[0] = top/left x
- viewport[1] = top/left y
- viewport[2] = width
- viewport[3] = height

The combined use of svgtDocViewportSet and svgtSurfaceViewportSet induces a transformation matrix, that will be used to draw the whole SVG document. The induced matrix grants that the document viewport is mapped onto the surface viewport (respecting the specified alignment): all SVG content will be drawn accordingly.

This function returns:
- SVGT_BAD_HANDLE_ERROR if specified surface handle is not valid
- SVGT_ILLEGAL_ARGUMENT_ERROR if viewport pointer is NULL or if it's not properly aligned
- SVGT_ILLEGAL_ARGUMENT_ERROR if specified viewport width or height are less than or equal zero
- SVGT_NO_ERROR if the operation was completed successfully

NB: floating-point values of NaN are treated as 0, values of +Infinity and -Infinity are clamped to the largest and smallest available float values.
SVGTErrorCode svgtSurfaceViewportSet(SVGTHandle surface,
                                     SVGTfloat* viewport);

svgtSurfaceViewportTransformGet

Get the current surface viewport transformation: clockwise rotation around a point, followed by a post-translation. The pivot point (i.e. the point around which the rotation is performed) is expressed in the drawing surface coordinates system, the rotation angle must be specified in degrees.

The 'values' parameter must be an array of (at least) 5 float entries, it will be filled with:
- values[0] = rotation pivot x
- values[1] = rotation pivot y
- values[2] = rotation angle, in degrees
- values[3] = post-translation x
- values[4] = post-translation y

This function returns:
- SVGT_BAD_HANDLE_ERROR if specified surface handle is not valid
- SVGT_ILLEGAL_ARGUMENT_ERROR if values pointer is NULL or if it's not properly aligned
- SVGT_NO_ERROR if the operation was completed successfully
SVGTErrorCode svgtSurfaceViewportTransformGet(SVGTHandle surface,
                                              SVGTfloat* values);

svgtSurfaceViewportTransformSet

Set the current surface viewport transformation: clockwise rotation around a point, followed by a post-translation. The pivot point (i.e. the point around which the rotation is performed) is expressed in the drawing surface coordinates system, the rotation angle must be specified in degrees.

The 'values' parameter must be an array of (at least) 5 float entries, it must contain:
- values[0] = rotation pivot x
- values[1] = rotation pivot y
- values[2] = rotation angle, in degrees
- values[3] = post-translation x
- values[4] = post-translation y

This function returns:
- SVGT_BAD_HANDLE_ERROR if specified surface handle is not valid
- SVGT_ILLEGAL_ARGUMENT_ERROR if values pointer is NULL or if it's not properly aligned
- SVGT_NO_ERROR if the operation was completed successfully

NB: floating-point values of NaN are treated as 0, values of +Infinity and -Infinity are clamped to the largest and smallest available float values.
SVGTErrorCode svgtSurfaceViewportTransformSet(SVGTHandle surface,
                                              SVGTfloat* values);

svgtDocCreate

Create and load an SVG document, specifying the whole xml string.

Return SVGT_INVALID_HANDLE in case of errors, else a valid document handle.
SVGTHandle svgtDocCreate(const char* xmlText);

svgtDocDestroy

Destroy a previously created SVG document.

It returns SVGT_NO_ERROR if the operation was completed successfully, else an error code.
SVGTErrorCode svgtDocDestroy(SVGTHandle svgDoc);

svgtDocWidth

SVG content itself optionally can provide information about the appropriate viewport region for the content via the 'width' and 'height' XML attributes on the outermost <svg> element. Use this function to get the suggested viewport width, in pixels.

It returns -1 (i.e. an invalid width) in the following cases:
- the library has not previously been initialized through the svgtInit function
- outermost element is not an <svg> element
- outermost <svg> element doesn't have a 'width' attribute specified
- outermost <svg> element has a 'width' attribute specified in relative measure units (i.e. em, ex, % percentage)
SVGTfloat svgtDocWidth(SVGTHandle svgDoc);

svgtDocHeight

SVG content itself optionally can provide information about the appropriate viewport region for
the content via the 'width' and 'height' XML attributes on the outermost <svg> element.
Use this function to get the suggested viewport height, in pixels.

It returns -1 (i.e. an invalid height) in the following cases:
- the library has not previously been initialized through the svgtInit function
- outermost element is not an <svg> element
- outermost <svg> element doesn't have a 'height' attribute specified
- outermost <svg> element has a 'height' attribute specified in relative measure units (i.e. em, ex, % percentage)
SVGTfloat svgtDocHeight(SVGTHandle svgDoc);

svgtDocViewportGet

Get the document (logical) viewport to map onto the destination (drawing surface) viewport.
When an SVG document has been created through the svgtDocCreate function, the initial value
of its viewport is equal to the 'viewBox' attribute present in the outermost <svg> element.
If such element does not contain the viewBox attribute, SVGT_NO_ERROR is returned and viewport
array will be filled with zeros.

The 'viewport' parameter must be an array of (at least) 4 float entries, it will be filled with:
- viewport[0] = top/left x
- viewport[1] = top/left y
- viewport[2] = width
- viewport[3] = height

This function returns:
- SVGT_BAD_HANDLE_ERROR if specified document handle is not valid
- SVGT_ILLEGAL_ARGUMENT_ERROR if viewport pointer is NULL or if it's not properly aligned
- SVGT_NO_ERROR if the operation was completed successfully
SVGTErrorCode svgtDocViewportGet(SVGTHandle svgDoc,
                                 SVGTfloat* viewport);

svgtDocViewportSet

Set the document (logical) viewport to map onto the destination (drawing surface) viewport.

The 'viewport' parameter must be an array of (at least) 4 float entries, it must contain:
- viewport[0] = top/left x
- viewport[1] = top/left y
- viewport[2] = width
- viewport[3] = height

This function returns:
- SVGT_BAD_HANDLE_ERROR if specified document handle is not valid
- SVGT_ILLEGAL_ARGUMENT_ERROR if viewport pointer is NULL or if it's not properly aligned
- SVGT_ILLEGAL_ARGUMENT_ERROR if specified viewport width or height are less than or equal zero
- SVGT_NO_ERROR if the operation was completed successfully

NB: floating-point values of NaN are treated as 0, values of +Infinity and -Infinity are clamped to the largest and smallest available float values.
SVGTErrorCode svgtDocViewportSet(SVGTHandle svgDoc,
                                 SVGTfloat* viewport);

svgtDocViewportAlignmentGet

Get the document alignment.
The alignment parameter indicates whether to force uniform scaling and, if so, the alignment method to use in case the aspect ratio of the document viewport doesn't match the aspect ratio of the surface viewport.

The 'values' parameter must be an array of (at least) 2 unsigned integers entries, it will be filled with:
- values[0] = alignment (see SVGTAspectRatioAlign)
- values[1] = meetOrSlice (see SVGTAspectRatioMeetOrSlice)

This function returns:
- SVGT_BAD_HANDLE_ERROR if specified document handle is not valid
- SVGT_ILLEGAL_ARGUMENT_ERROR if values pointer is NULL or if it's not properly aligned
- SVGT_NO_ERROR if the operation was completed successfully
SVGTErrorCode svgtDocViewportAlignmentGet(SVGTHandle svgDoc,
                                          SVGTuint* values);

svgtDocViewportAlignmentSet

Set the document alignment.
The alignment parameter indicates whether to force uniform scaling and, if so, the alignment method to use in case the aspect ratio of the document viewport doesn't match the aspect ratio of the surface viewport.

The 'values' parameter must be an array of (at least) 2 unsigned integers entries, it must contain:
- values[0] = alignment (see SVGTAspectRatioAlign)
- values[1] = meetOrSlice (see SVGTAspectRatioMeetOrSlice)

This function returns:
- SVGT_BAD_HANDLE_ERROR if specified document handle is not valid
- SVGT_ILLEGAL_ARGUMENT_ERROR if viewport pointer is NULL or if it's not properly aligned
- SVGT_ILLEGAL_ARGUMENT_ERROR if specified alignment is not a valid SVGTAspectRatioAlign value
- SVGT_ILLEGAL_ARGUMENT_ERROR if specified meetOrSlice is not a valid SVGTAspectRatioMeetOrSlice value
- SVGT_NO_ERROR if the operation was completed successfully
SVGTErrorCode svgtDocViewportAlignmentSet(SVGTHandle svgDoc,
                                          SVGTuint* values);

svgtDocDraw

Draw an SVG document, on the specified drawing surface, with the given rendering quality.
If the specified SVG document is SVGT_INVALID_HANDLE, the drawing surface is cleared (or not) according to the current settings (see svgtClearColor and svgtClearPerform), and nothing else is drawn.

It returns SVGT_NO_ERROR if the operation was completed successfully, else an error code.
SVGTErrorCode svgtDocDraw(SVGTHandle svgDoc,
                          SVGTHandle surface,
                          SVGTRenderingQuality renderingQuality);

svgtClearColor

Set the clear color (i.e. the color used to clear the whole drawing surface).
Each color component must be a number between 0 and 1. Values outside this range
will be clamped.

It returns SVGT_NO_ERROR if the operation was completed successfully, else an error code.
SVGTErrorCode svgtClearColor(SVGTfloat r,
                             SVGTfloat g,
                             SVGTfloat b,
                             SVGTfloat a);

svgtClearPerform

Specify if the whole drawing surface must be cleared by the svgtDocDraw function, before to draw the SVG document.

It returns SVGT_NO_ERROR if the operation was completed successfully, else an error code.
SVGTErrorCode svgtClearPerform(SVGTboolean doClear);

svgtPointMap

Map a point, expressed in the document viewport system, into the surface viewport.
The transformation will be performed according to the current document viewport (see svgtDocViewportGet) and the current surface viewport (see svgtSurfaceViewportGet).

The includeDstViewportTransformation parameter specifies if the surface viewport transformation (see svgtSurfaceViewportTransformGet) must be considered/included during the mapping operation.

The 'dst' parameter must be an array of (at least) 2 float entries, it will be filled with:
- dst[0] = transformed x
- dst[1] = transformed y

This function returns:
- SVGT_BAD_HANDLE_ERROR if specified document (or surface) handle is not valid
- SVGT_ILLEGAL_ARGUMENT_ERROR if dst pointer is NULL or if it's not properly aligned
- SVGT_NO_ERROR if the operation was completed successfully

NB: floating-point values of NaN are treated as 0, values of +Infinity and -Infinity are clamped to the largest and smallest available float values.
SVGTErrorCode svgtPointMap(SVGTHandle svgDoc,
                           SVGTHandle surface,
                           SVGTfloat x,
                           SVGTfloat y,
                           SVGTboolean includeSurfaceViewportTransformation,
                           SVGTfloat* dst);

svgtGetString

Get renderer and version information.
const char* svgtGetString(SVGTStringID name);

3. UNITY API DOCUMENTATION

SVGColor

Simple color class.
public class SVGColor {
Constructor.
public SVGColor();
Set constructor.
public SVGColor(float r, float g, float b, float a);
Red component (read only).
public float Red;
Green component (read only).
public float Green;
Blue component (read only).
public float Blue;
Alpha component (read only).
public float Alpha;
}

SVGPoint

public class SVGPoint {
Constructor.
public SVGPoint();
Set constructor.
public SVGPoint(float x, float y);
Abscissa.
public float X;
Ordinate.
public float Y;
}

SVGViewport

SVG viewport.
A viewport represents a rectangular area, specified by its top/left corner, a width and an height. The positive x-axis points towards the right, the positive y-axis points down.
public class SVGViewport {
Constructor.
public SVGViewport();
Set constructor.
public SVGViewport(float x, float y, float width, float height);
Top/left corner, abscissa.
public float X;
Top/left corner, ordinate.
public float Y;
Viewport width.
public float Width;
Viewport height.
public float Height;
}

SVGViewportTransform

A viewport transformation: clockwise rotation around a point, followed by a (post)translation.
The pivot point (i.e. the point around which the rotation is performed) is expressed in the drawing surface coordinates system, the rotation angle must be specified in degrees.
public class SVGViewportTransform {
Constructor.
public SVGViewportTransform();
Set constructor.
public SVGViewportTransform(SVGPoint pivot, float degAngle, SVGPoint translation);
The pivot point (i.e. the point around which the rotation is performed).
public SVGPoint Pivot;
The rotation angle, expressed in degrees.
public float Angle;
The post-translation vector.
public SVGPoint Translation;
}

SVGAspectRatio

public class SVGAspectRatio {
Constructor.
public SVGAspectRatio();
Set constructor.
public SVGAspectRatio(SVGAlign alignment, SVGMeetOrSlice meetOrSlice);
Alignment.
public SVGAlign Alignment;
Meet or slice.
public SVGMeetOrSlice MeetOrSlice;
}

SVGDocument

SVG document.

An SVG document can be created through SVGAssets.CreateDocument function, specifying the xml text. The document will be parsed immediately, and the internal drawing tree will be created.

Once the document has been created, it can be drawn several times onto one (or more) drawing surface. In order to draw a document:

(1) create a drawing surface using SVGAssets.CreateSurface
(2) call surface Draw method, specifying the document to draw
public class SVGDocument {
Map a point, expressed in the document viewport system, into the surface viewport.
The transformation will be performed according to the current document viewport and the current surface viewport.

The includeDstViewportTransformation parameter specifies if the surface viewport transformation must be considered during the mapping operation.
public SVGPoint pointMap(SVGSurface surface, SVGPoint p, bool includeSurfaceViewportTransformation);
SVG content itself optionally can provide information about the appropriate viewport region for the content via the 'width' and 'height' XML attributes on the outermost <svg> element.
Use this property to get the suggested viewport width, in pixels.

It returns -1 (i.e. an invalid width) in the following cases:
- the library has not previously been initialized through the svgtInit function
- outermost element is not an <svg> element
- outermost <svg> element doesn't have a 'width' attribute specified
- outermost <svg> element has a 'width' attribute specified in relative measure units (i.e. em, ex, % percentage)
public float Width;
SVG content itself optionally can provide information about the appropriate viewport region for the content via the 'width' and 'height' XML attributes on the outermost <svg> element.
Use this property to get the suggested viewport height, in pixels.

It returns -1 (i.e. an invalid height) in the following cases:
- the library has not previously been initialized through the svgtInit function
- outermost element is not an <svg> element
- outermost <svg> element doesn't have a 'height' attribute specified
- outermost <svg> element has a 'height' attribute specified in relative measure units (i.e. em, ex, % percentage)
public float Height;
The document (logical) viewport to map onto the destination (drawing surface) viewport.
When an SVG document has been created through the SVGAssets.CreateDocument function, the initial value of its viewport is equal to the 'viewBox' attribute present in the outermost <svg> element.
public SVGViewport Viewport;
Viewport aspect ratio.
The alignment parameter indicates whether to force uniform scaling and, if so, the alignment method to use in case the aspect ratio of the document viewport doesn't match the aspect ratio of the surface viewport.
public SVGAspectRatio AspectRatio;
}

SVGSurface

Drawing surface.

A drawing surface is just a rectangular area made of pixels, where each pixel is represented internally by a 32bit unsigned integer. A pixel is made of four 8-bit components: red, green, blue, alpha.

Coordinate system is the same of SVG specifications: top/left pixel has coordinate (0, 0), with the positive x-axis pointing towards the right and the positive y-axis pointing down.
public class SVGSurface {
Resize the surface, specifying new dimensions in pixels; it returns true if the operation was completed successfully, else false.

After resizing, the surface viewport will be reset to the whole surface, and the relative transformation will be reset to identity (pivot = [0; 0], angle = 0, post-translation = [0; 0]).
public bool Resize(uint newWidth, uint newHeight);
Draw an SVG document, on this drawing surface.

First the drawing surface is cleared if a valid (i.e. not null) clear color is provided. Then the specified document, if valid, is drawn.

It returns true if the operation was completed successfully, else false.
public bool Draw(SVGDocument document, SVGColor clearColor, SVGRenderingQuality renderingQuality);
Copy drawing surface content into the specified texture.
This function is useful for managed environments (e.g. C#, Unity, Java, Android), where the use of a direct pixels
access is not advisable nor comfortable.
It returns true if the operation was completed successfully, else false.
public bool Copy(Texture2D texture);
Get current surface width, in pixels.
public uint Width;
Get current surface height, in pixels.
public uint Height;
The surface viewport (i.e. a drawing surface rectangular area), where to map the source document viewport.
The combined use of surface and document viewport, induces a transformation matrix, that will be used to draw the whole SVG document. The induced matrix grants that the document viewport is mapped onto the surface viewport (respecting the specified alignment): all SVG content will be drawn accordingly.
public SVGViewport Viewport;
The current surface viewport transformation: clockwise rotation around a point, followed by a post-translation.
The pivot point (i.e. the point around which the rotation is performed) is expressed in the drawing surface coordinates system, the rotation angle is specified in degrees.
public SVGViewportTransform ViewportTransform;
}

SVGAssets

static class SVGAssets {
Create a drawing surface, specifying its dimensions in pixels.
public static SVGSurface CreateSurface(uint width, uint height);
Create and load an SVG document, specifying the whole xml string.
public static SVGDocument CreateDocument(string xmlText);
Get library version.
public static string GetVersion();
Get library vendor.
public static string GetVendor();
}