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):
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:
LockRect + <mem copy> + UnlockRect (Direct3D 9)
UpdateSubresource (Direct3D 11)
glTexSubImage2D (OpenGL and OpenGL ES)
replaceRegion (Metal)
You can see the usage of SVGTextureBehaviour script by opening the plane scene.
| The “plane” scene |
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:
Size x (Size * SVG aspect ratio), if Scale adaption == Horizontal; or
(Size * SVG aspect ratio) x Size, if Scale adaption == Vertical
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).
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.
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:
Reference width, height: it’s the resolution at which SVG files would be rendered at the native dimensions, specified within the SVG file itself (outermost <svg> element, attributes width and height). It is really important that all used SVG files contain such attributes, because if they are not available, AmanithSVG will render each sprite filling a whole texture.
Device test (simulated) width, height: it’s the resolution that will be simulated to generate and test sprites in the editor. These settings allow the user to test different device resolutions in advance.
Screen match mode: it defines which device dimension will control the scaling factor. The match mode is defined by the SVGScalerMatchMode enum type, and it’s an extension of the Unity ScreenMatchMode.
Offset scale: an additional scale factor that will be applied to all SVG files.
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:
an SVG file with 100 x 150 dimensions (i.e. <svg width="100px" height="150px">)
a reference resolution set to 1024 x 768
screen match mode set to Vertical
offset scale set to 1
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:
Force pow2 textures: if checked, this parameters will force the atlas generator to produce textures whose dimensions are power-of-two values.
Max textures dimension: the maximum dimension allowed during the textures atlas generation. Please make sure that such value won’t exceed the real device capability.
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.
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:
Resize on Start: if checked (default value), the sprite will be regenerated at the Start of monobehaviour, else the user must update the sprite programmatically calling the public UpdateSprite function.
Update transform: if checked (default value), at every monobehaviour LateUpdate call, the sprite local position will be fixed according to its current dimensions. This will ensure that animated child sprites will be in the correct position relative to their father (just the position is relevant, rotation and scale do not need to be fixed). If the sprite is moved programmatically by code (e.g. a root body part of a character), this option must be unchecked.
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 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.
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:
Resize on Start: if checked (default value), the UI sprite will be regenerated at the Start of monobehaviour, else the user must update the sprite programmatically calling the public UpdateSprite function.
Sprite property refers to the sprite generated by the relative SVGUIAtlas object.
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.
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 |
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.
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 |
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 |
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.
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 |
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 |
This editor script implements a ScriptableWizard that allows the (visual) selection of SVGAtlas assets.
| Select SVGAtlas objects wihtin the project |
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 |
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 |
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.
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.