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.

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 uses the higher layer C# binding already discussed here.

Here’s a list of classes exposed by the Unity binding (you can find them here):


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.material.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 library 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 GameObject2D ObjectSprite 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: they can be found here.


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.