Cookies info

This website uses Google cookies to analyse traffic. Information about your use of our site is shared with Google for that purpose. See details.

AmanithSVG native plugins for Unity, requirements and limitations

AmanithSVG native plugins for Unity differ from other AmanithSVG standalone builds because they implement some specific methods to speed up the upload of pixels to textures as much as possible. These specific methods make direct use of native graphics APIs, which are different for each supported platform. In the detail, AmanithSVG native plugins for Unity support:

Vulkan graphics API is not supported by AmanithSVG native plugins for Unity.

To make sure that AmanithSVG for Unity can continue to be used even in the presence of unsupported native graphics APIs, several fallbacks have been implemented using standard (but slower) Unity calls (GetRawTextureData, GetUnsafeBufferPointerWithoutChecks, LoadRawTextureData). The use of fast texture upload via native graphics APIs, or the fallbacks mechanism via Unity legacy functions, is controlled by the Fast upload flag of SVGTextureBehaviour, SVGBackgroundBehaviour, SVGAtlas classes.

Unity binding

Unity is a cross-platform game engine that can be used to create both three-dimensional and two-dimensional games as well as simulations for its many platforms. Unity engine offers a primary scripting API in C#, for both the Unity editor in the form of plugins, and games themselves, as well as drag and drop functionality.

So the AmanithSVG binding for Unity consists in a set of C# classes and editor plugins in order to expose AmanithSVG functionalities in a simple way; the binding extends the higher layer C# binding already discussed here. In particular four new classes have been introduced:

Then, using these new classes, the Unity binding exposes additional classes that integrate AmanithSVG features with Unity specific mechanisms (e.g. monobehaviour, sprites, texture atlas and so on). Here’s the list of implemented Unity-specific classes:

When working with Unity engine, it is mandatory to use SVGAssetsUnity class and not the basic SVGAssets one.

SVGSurfaceUnity

This class extends SVGSurface by providing methods to generate Unity textures out of surface pixels.

/*
    Create a 2D texture compatible with the drawing surface.

    NB: textures passed to Copy and CopyAndDestroy must be created
    through this function.
*/
Texture2D CreateCompatibleTexture(bool bilinearFilter,
                                  bool wrapRepeat,
                                  HideFlags hideFlags);


/*
    Copy drawing surface content into the specified Unity texture.
    NB: the given texture must have been created by the CreateCompatibleTexture
    method.

    It returns SVGError.None if the operation was completed successfully, else
    an error code.
*/
SVGError Copy(Texture2D texture);

/*
    Copy drawing surface content into the specified Unity texture, then destroy
    the native drawing surface. The SVGSurfaceUnity instance is not destroyed, but
    its native AmanithSVG counterpart it will. The result will be that every
    called method will fail silently.

    In order to ensure the maximum speed, the copy process will use native GPU
    platform-specific methods:

    - UpdateSubresource (Direct3D 11)
    - glTexSubImage2D (OpenGL and OpenGL ES)
    - replaceRegion (Metal)

    NB: the given texture must have been created by the CreateCompatibleTexture
    method.

    It returns SVGError.None if the operation was completed successfully, else
    an error code.
*/
SVGError CopyAndDestroy(Texture2D texture);

An SVGSurfaceUnity can be created by using the SVGAssetsUnity.CreateSurface function, specifying its dimensions in pixels.

SVGResourceUnity

This class extends SVGResource by providing the mandatory GetBytes method to get an in-memory representation of the underlying binary TTF / OTF / WOFF / JPEG / PNG file. The constructor takes a TextAsset and sets the given unique string identifier, the type (font or image) and hints. The access to the underlying binary data is implemented by using the TextAsset.bytes property.

SVGAssetsConfigUnity

This class extends SVGAssetsConfig by implementing an internal list of SVGResourceUnity resources. Items within this list can be added, moved and deleted. Most importantly this class implements the mandatory ResourcesCount and GetResource methods from SVGAssetsConfig class, in order to get the resources.

SVGAssetsUnity

SVGAssetsUnity is a static class through which SVGDocument, SVGSurfaceUnity and SVGPacker instances can be created. It extends SVGAssets class by implementing additional methods specific for Unity:

/* Get screen resolution width, in pixels. */
uint ScreenWidth;

/* Get screen resolution height, in pixels. */
uint ScreenHeight;

/* Get screen dpi. */
float ScreenDpi;

/*
    Create a drawing surface, specifying its dimensions in pixels.

    Supplied dimensions should be positive numbers greater than zero, else
    a null instance will be returned.
*/
SVGSurfaceUnity CreateSurface(uint width,
                              uint height);

/*
    Create and load an SVG document, specifying the whole XML string.
    If supplied XML string is null or empty, a null instance will be returned.
*/
SVGDocument CreateDocument(string xmlText);

/*
    Create an SVG packer, specifying a scale factor.

    Every collected SVG document/element will be packed into rectangular bins,
    whose dimensions won't exceed the specified 'maxTexturesDimension' in pixels.

    If true, 'pow2Textures' will force bins to have power-of-two dimensions.
    Each rectangle will be separated from the others by the specified 'border' in pixels.

    The specified 'scale' factor will be applied to all collected SVG documents/elements,
    in order to realize resolution-independent atlases.
*/
SVGPacker CreatePacker(float scale,
                       uint maxTexturesDimension,
                       uint border,
                       bool pow2Textures);

/*
    Create an SVG packer, specifying a scale factor.

    Every collected SVG document/element will be packed into rectangular bins.

    Each rectangle will be separated from the others by the specified 'border' in pixels.

    The specified 'scale' factor will be applied to all collected SVG documents/elements,
    in order to realize resolution-independent atlases.

    NB: maximum dimension of textures is auto-detected.
*/
SVGPacker CreatePacker(float scale,
                       uint border);

/*
    Create a sprite out of the given texture.
    The sprite will use the specified rectangular section of the
    texture, and it will have the provided pivot.
*/
Sprite CreateSprite(Texture2D texture,
                    Rect rect,
                    Vector2 pivot);

When working with Unity engine, it is mandatory to use SVGAssetsUnity class and not the basic SVGAssets one.

SVGTextureBehaviour

This monobehaviour script performs a single SVG file rendering on a Texture2D. It takes in input the SVG file (as a TextAsset), the texture dimensions and a clear color. Such color will be used to clear the surface before to start the rendering. The rendering is performed in the Start function, that assigns the generated texture to the renderer.sharedMaterial.mainTexture field of the associated GameObject. The Fast upload flag enables the native update of the texture instead to use the (slower) legacy LoadRawTextureData + Apply method.

 
Editor mask for the SVGTextureBehaviour component

If the Fast upload checkbox is selected, AmanithSVG native plugins for Unity will update the Unity texture using the following methods:

You can see the usage of SVGTextureBehaviour script by opening the plane scene.

 
The “plane” scene

SVGBackgroundBehaviour

This monobehaviour script performs the rendering of a single SVG file on a Texture2D, and creates a new sprite out of it (covering the whole texture). The sprite is then assigned to the SpriteRenderer component. As for the SVGTextureBehaviour script, it is possible to specify a clear color and the Fast upload flag too.

The script has two operational modes: sliced or not sliced (according to the relative checkbox).

When sliced, the script takes two additional parameters, Width and Height: at runtime, the generated texture/sprite will be sized at Width x Height exactly, in a way to preserve the SVG aspect ratio and at the same time to cover the largest dimension between Width and Height (SVG will be aligned to the center).

 
Editor mask for the SVGBackgroundBehaviour component

Sliced mode is useful to generate static backgrounds that must cover exactly the whole device screen; you can have a look at the game scene for a such usage case.

 
The “game” scene

In the non-sliced mode, the SVGBackgroundBehaviour script takes two different additional parameters, Scale adaption and Size. The first one could be Horizontal or Vertical, while the second one is expressed in pixels. The rendering is performed keeping the (horizontal or vertical) dimension equal to the specified Size value, and calculates the other texture dimension preserving the original SVG aspect ratio. So the final generated texture will have a size of:

The non-sliced mode is useful to generate static “scrollable” backgrounds (i.e. camera viewport smaller than the generated texture); you can have a look at the orc scene for a such usage case.

 
The “orc” scene

NB: in order to work properly, the SVGBackgroundBehaviour script must be assigned to a GameObject with a SpriteRenderer component already attached (e.g. you can create it by using the GameObject → 2D Object → Sprite menu).

SVGCameraBehaviour

In order to work properly, SVGCameraBehaviour script must be attached to an orthographic Camera. The script ensures that both camera aspect ratio and orthographic size match the current screen resolution. In addition, the script is in charge of communicating a possible change of the screen resolution (e.g. when a mobile device is rotated or a window resized) to all OnResize listeners.

 
Editor mask for the SVGCameraBehaviour component

Both orc scene and game scene use the SVGCameraBehaviour script.

SVGAtlas

This ScriptableObject allows the generation of sprites from different SVG files, packing the generated sprites into one or more textures, according to the specified parameters.

 
Editor mask for the SVGAtlas scriptable object

Each SVG file can be drag&dropped in the relative section (the region labeled with “Drag & drop SVG assets here”). Dragged items can be moved within the list, changing their order: this will induce an automatic z-order (i.e. Order in Layer value of SpriteRenderer components) of generated sprites. In the detail, sprites will be ordered in a way such that the one on the top of the list will be placed behind all others.

For each SVG entry, it is possible to specify if the altas generator must render it as a whole single sprite (“Separate groups” option unchecked), or if first level groups (<g>tags) must be rendered as separate sprites (“Separate groups” option checked). This option will allow the animation of each group.

 
Example of generated textures and sprites

Being vector based, SVG can be freely scaled without visual quality loss. In order to give the user an effective way to control the scaling factor, SVGAtlas makes available the following parameters:

The general formula to calculate the scaling factor is:

Scl = (Device dimension / Reference dimension) * OffsetScale

where device dimension is the one chosen by the screen match mode parameter.

For example, lets have:

On a 640 x 480 device resolution, the sprite will be rendered at 62 x 94 pixels, because scaling factor is 0.625 (480 / 768). On a 1536 x 2048 device resolution, the sprite will be rendered at 266 x 400 pixels, because scaling factor is 2.667 (2048 / 768).

For the complete formula, please have a look at the ScaleFactorCalc method of SVGScaler class.

Two additional script parameters control some aspects relative to the generated textures:

The last two script parameters control how many pixels will separate each sprite from any other (Sprite padding) and the color that is used to clear the surface before to start the rendering (Clear color). The Fast upload flag has the same meaning described for the SVGTextureBehaviour class.

SVGSpriteLoaderBehaviour

This monobehaviour script takes care to render the associated sprite at runtime on the device, according to its original SVGAtlas generator settings.

 
Editor mask for the SVGSpriteLoaderBehaviour component

Editable parameters consist in:

Atlas and Sprite properties refer to the SVGAtlas object that has generated this sprite.

SVGSpriteLoaderBehaviour component is attached automatically to those sprites instantiated through the SVGAtlasEditor editor mask.

SVGUIAtlas

SVGUIAtlas is really similar to SVGAtlas, with the only exception that all parameters that determine the scale factor for SVG contents (e.g. reference resolution, screen match mode, and so on) are provided by a CanvasScaler component. SVGUIAtlas objects cannot be instantiated as a standalone asset (as opposed to SVGAtlas), but they are strictly attached to SVGCanvasBehaviour components: each SVGCanvasBehaviour instance contains a single SVGUIAtlas instance. Because SVGCanvasBehaviour components can be attached to Canvas only, it follows that SVGUIAtlas instances are in a 1-1 relation to canvas instances.

SVGUISpriteLoaderBehaviour

This monobehaviour script takes care to render the associated UI sprite at runtime on the device, according to its original SVGUIAtlas generator settings.

 
Editor mask for the SVGUISpriteLoaderBehaviour component

Editable parameters consist in:

The Edit button is a shortcut to the pivot and borders editor that would still be reachable by selecting the original SVGCanvasBehaviour component.

SVGUISpriteLoaderBehaviour component is attached automatically to those UI sprites instantiated through the SVGCanvasEditor editor mask.

SVGCanvasBehaviour

This monobehaviour script can be attached to Canvas components only, and it is in charge of storing an instance of SVGUIAtlas. The main role of SVGCanvasBehaviour is to communicate the canvas scale factor to the maintained SVGUIAtlas instance.

 
Editor mask for the SVGCanvasBehaviour component

Editor scripts

To make sure that the use of AmanithSVG is as simple and convenient as possible from the Unity editor, a set of editor scripts have been implemented:

SVGAssetsConfigProvider

This editor script implements a SettingsProvider for the editing of SVGAssetsConfigUnity. Is is possible to configure user-agent language, curves quality and log facilities. In addition it is possible to drag&drop resource files (fonts and images) and edit their parameters. The editing window is available throught the Edit → Project Settings → SVGAssets menu.

SVGBackgroundEditor

This editor script implements the inspector mask for the editing of SVGBackgroundBehaviour components. The layout allows to edit all SVGBackgroundBehaviour parameters, taking care to present only those needed ones according to the current operational mode (sliced or not-sliced).

 
Editor mask for the SVGBackgroundBehaviour component

SVGCameraEditor

This editor script implements the inspector mask for SVGCameraBehaviour components. The layout simply displays the camera viewport size, both in pixels and world units.

 
Editor mask for the SVGCameraBehaviour component

SVGAtlasEditor

This editor script implements the inspector mask for the editing of SVGAtlas assets. The base class SVGBasicAtlasEditor (from which SVGAtlasEditor is derived) also implements a PostProcessBuild static class that will take care of some aspects relative to the building phase. In particular, it ensures that during the building process all generated atlases won’t be included in the final package (actually they are substituted by a dummy 1x1 texture), because they will be regenerated at runtime on the device. This will reduce the build size, showing the advantage of using SVG files instead of bitmaps.

SVGPivotEditor

This editor script allows the user to edit the pivot point of generates sprites. The pivot can be moved by simply clicking the mouse on the desired position or by changing values by hand. It is desirable to setup pivot points before instantiating and/or animating sprites.

 
The pivot editor window

SVGSpriteLoaderEditor

This editor script implements the inspector mask for the editing of SVGSpriteLoaderBehaviour components. The layout allows to edit (actually to check/uncheck) the Resize on start and Update transform properties. In addition the Atlas and Sprite buttons allow to show and/or select the sprite reference: in particular, such two buttons make use of SVGAtlasSelector and SVGSpriteSelector editor scripts.

 
Editor mask for the SVGSpriteLoaderBehaviour component

SVGAtlasSelector

This editor script implements a ScriptableWizard that allows the (visual) selection of SVGAtlas assets.

 
Select SVGAtlas objects wihtin the project

SVGSpriteSelector

This editor script implements a ScriptableWizard that allows the (visual) selection of a sprite asset generated by SVGAtlas objects.

 
Select a sprite belonging to an SVGAtlas object

SVGCanvasEditor

This editor script implements the inspector mask for the editing of SVGCanvasBehaviour components. In the detail the script displays the canvas scale factor and the underlying SVGUIAtlas object. The base class SVGBasicAtlasEditor (from which SVGCanvasEditor is derived) also implements a PostProcessBuild static class that will take care of some aspects relative to the building phase. In particular, it ensures that during the building process all generated atlases won’t be included in the final package (actually they are substituted by a dummy 1x1 texture), because they will be regenerated at runtime on the device. This will reduce the build size, showing the advantage of using SVG files instead of bitmaps.

 
Editor mask for the SVGCanvasBehaviour component

SVGUISpriteLoaderEditor

This editor script implements the inspector mask for the editing of SVGUISpriteLoaderBehaviour components. The layout allows to edit (actually to check/uncheck) the Resize on Start property. In addition the Sprite button allows to show and/or select the sprite reference: in particular, such button makes use of SVGSpriteSelector editor script. The Edit button allows the modification of sprite borders and pivot.

 
Editor mask for the SVGUISpriteLoaderBehaviour component

It is desirable to setup pivot points before instantiating UI sprites.

SVGRenamerImporter

This script implements an asset post-processor (AssetPostprocessor class). Its task consists in changing the extension of new asset files from .svg to .svg.txt, so Unity can recognize those files as text assets. The same kind of task is also performed on .ttf, .otf, .woff, .jpg and .png files: in this case they will be renamed by adding a .bytes suffix.

Unity binding FAQ

AmanithSVG native plugins for Android

AmanithSVG native plugins for Android must be placed in Assets/SVGAssets/Plugins/Android/libs folder. According to the target architecture, a different libAmanithSVG.so file is present in a different subdirectory. Be sure to follow this guide in order to import AmanithSVG native plugins for Android correctly; in the detail:

The official AmanithSVG SDK already includes the plugins set correctly.

AmanithSVG on iOS doesn’t render the SVG(s) and XCode does not show any messages about it. How to fix it?

Please double check that the folder Assets/SVGAssets/Plugins/iOS of your project contains both the static library libAmanithSVG.a and loader.m

”<xyz> elements are not supported in AmanithSVG Lite version” messages

Because some features are not present in AmanithSVG Lite, you could see some warning messages about SVG unsupported elements in the Unity console window. In particular the following SVG elements are not supported in AmanithSVG Lite: <linearGradient>, <radialGradient>, <pattern>, <image>, <mask>, <filter>. Such elements are supported in AmanithSVG Full only, that is available for licensing on Mazatech’s website. In order to use the Full version, it is not needed to change C# scripts, just substitute the native plugin.

For more information, please visit the dedicated page.