ScalableImage class abstract

The main entry point to this library. This class features several static methods to load a ScalableImage from various sources. It provides two in-memory representations: a memory-saving "compact" representation, as well as a faster internal graph structure. Provision is given to set a viewport, and prune away nodes that are outside this viewport. In this way, several smaller "views" onto a larger SI asset can be produced, with maximal resource sharing between the different assets.

A ScalableImage can be used directly, e.g. using a Flutter CustomPaint widget, or it can be displayed using a ScalableImageWidget.

Note that rendering a scalable image can be time-consuming if the underlying scene is complex. Notably, GPU performance can be a bottleneck. If one or more ScalableImage instances is used in animation, or has animation played over it, it might be worthwhile to cache a pre-rendered version of the ScalableImage. cf. Flutter's Picture.toImage and the notes about RepaintBoundary in ScalableImageWidget.

Note that, while ScalableImage is declared as @immutable, and obeys the @immutable contract, instances can contain images which can be loaded and unloaded (see prepareImages and unprepareImages). Used correctly, ScalableImage instances are what you might call semantically immutable. Indeed, aside from loading and unloading embedded assets, their internal state is read-only. However, they are not strictly immutable in the traditional computer science sense of the word, which requires all reachable objects being unmodifiable. A buggy application could corrupt the internal state by calling unprepareImages excessively, for example, which could cause embedded images to not render.

Annotations

@immutable

Properties

currentColor → Color: The currentColor value, as defined by Tiny s. 11.2. This is a color value in an SVG document for elements whose color is controlled by the SVG's container.
final
hashCode → int: The hash code for this object.
no setterinherited
height → double?: Height of the image, in pixels, if it was specified. This corresponds to the SVG tag's "height" attribute, and the AVD vector element's "android"height", if specified, or "android:viewportHeight" if not.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
tintColor → Color?: Color used to tint the ScalableImage. This feature, inspired by Android's tinting, allows you to apply a tint color to the entire asset. This can be used, for example, to color icons according to an application theme.
final
tintMode → BlendMode: BlendMode for applying the tintColor.
final
viewport → Rect: Give the viewport for this scalable image, in pixels. By default, it's determined by the parameters in the original asset, but see also ScalableImage.withNewViewport. If the original SVG asset didn't define a width and height, they will be calculated the first time the viewport is requested.
no setter
width → double?: Width of the image, in pixels, if it was specified. This corresponds to the SVG tag's "width" attribute, and the AVD vector element's "android:width", if specified, or by "android:viewportWidth" if not.
final

Methods

debugSizeMessage() → String: Give a String that describes the size of this ScalableImage, for debugging. For a compact image, this gives a size in bytes, and for the DAG representation, gives a node count.
modifyCurrentColor(Color newCurrentColor) → ScalableImage: Return a new ScalableImage like this one, with currentColor modified.
modifyTint({required BlendMode newTintMode, required Color? newTintColor}) → ScalableImage: Return a new ScalableImage like this one, with tint modified.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
paint(Canvas c) → void: Paint this ScalableImage to the canvas c. This method saves the Canvas's state, translates the canvas by the viewport's origin, clips to the viewport's size, paints the image, and restores the Canvas.
prepareImages() → Future<void>: Prepare any images in the ScalableImage, by decoding them. If this is not done, images will be invisible (unless a different ScalableImage that has been prepared shares the image instances, as could happen with viewport setting.). This method may be called multiple times on the same ScalableImage. Each call to prepareImages() must be balanced with a call to unprepareImages to enable releasing the image resources -- see Image.dispose() in the Flutter library.
toDag() → ScalableImage: Returns this SI as an in-memory directed acyclic graph of nodes. As compared to a compact scalable image, the DAG representation can be expected to render somewhat faster, at a significant cost in memory. In informal measurements, the DAG representation's paint method ran about 3x faster.
toSIBytes() → Uint8List: Give the bytes of the .si file representation of this ScalableImage, if this is the compact representation. If this is the DAG representation, throws a StateError. The compact representation is obtained by passing a compact flag when the image is created.
toString() → String: A string representation of this object.
inherited
unprepareImages() → void: Undo the effects of prepareImages. When the count of outstanding prepare calls falls to zero for a given image, native resources are released by calling dispose() on the relevant objects.
withNewViewport(Rect viewport, {bool prune = false, double pruningTolerance = 0}) → ScalableImage: Return a copy of this SI with a different viewport. The bulk of the data is shared between the original and the copy. If prune is true, it attempts to prune paths that are outside of the new viewport. Pruning away unneeded nodes will speed up rendering of the resulting ScalableImage.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

imageDisposeBugWorkaround ↔ ImageDisposeBugWorkaround: Set the global policy as regards the various bugs in the dispose() methods for parts of the Flutter image system. As of Flutter 2.5.0, the worst of these bugs appear to have been fixed, so the library default was changed from disposeNeither to disposeBoth in jovial_svg version 1.0.7. However, in June 2023 a new Flutter bug was reported, resulting in the addition of the silentlyIgnoreErrors value.
getter/setter pair

Static Methods

blank() → ScalableImage: Creates a new instance of a blank image.
fromAvdAsset(AssetBundle b, String key, {bool compact = false, bool bigFloats = false, bool warn = true, void warnF(String)?}) → Future<ScalableImage>: Load a string asset containing an Android Vector Drawable in XML format from b and parse it into a scalable image.
fromAvdHttpUrl(Uri url, {bool compact = false, bool bigFloats = false, bool warn = true, void warnF(String)?, Encoding defaultEncoding = utf8, Map<String, String>? httpHeaders}) → Future<ScalableImage>: Parse an Android Vector Drawable XML document from a URL to a scalable image. Usage:
fromAvdStream(Stream<String> stream, {bool compact = false, bool bigFloats = false, bool warn = true, void warnF(String)?}) → Future<ScalableImage>: Read a stream containing an Android Vector Drawable in XML format and parse it into a scalable image.
fromAvdString(String src, {bool compact = false, bool bigFloats = false, bool warn = true, void warnF(String)?}) → ScalableImage: Parse an Android Vector Drawable XML string to a scalable image.
fromSIAsset(AssetBundle b, String key, {bool compact = false, Color? currentColor}) → Future<ScalableImage>: Create an image from a .si file in an asset bundle. Loading a .si file is considerably faster than parsing an SVG or AVD file - about 5-20x faster in informal measurements, for reasonably large files. A .si file can be created with dart run jovial_svg:svg_to_si or dart run jovial_svg:avd_to_si.
fromSIBytes(Uint8List bytes, {bool compact = false, Color? currentColor}) → ScalableImage: Create an image from the contents of a .si file in a ByteData. Loading a .si file is considerably faster than parsing an SVG or AVD file - about 5-20x faster in informal measurements. A .si file can be created with dart run jovial_svg:svg_to_si or dart run jovial_svg:avd_to_si.
fromSvgAsset(AssetBundle b, String key, {bool compact = false, bool bigFloats = false, bool warn = true, void warnF(String)?, Color? currentColor}) → Future<ScalableImage>: Load a string asset containing an SVG from b and parse it into a scalable image.
fromSvgHttpUrl(Uri url, {bool compact = false, bool bigFloats = false, bool warn = true, void warnF(String)?, Color? currentColor, Encoding defaultEncoding = utf8, Map<String, String>? httpHeaders}) → Future<ScalableImage>: Parse an SVG XML document from a URL to a scalable image. Usage:
fromSvgStream(Stream<String> stream, {bool compact = false, bool bigFloats = false, bool warn = true, void warnF(String)?}) → Future<ScalableImage>: Read a stream containing an SVG and parse it into a scalable image.
fromSvgString(String src, {bool compact = false, bool bigFloats = false, bool warn = true, void warnF(String)?, Color? currentColor}) → ScalableImage: Parse an SVG XML string to a scalable image