Images class

A cache of decoded Images, keyed by name.

The cache owns every image in it and disposes of an image when it is removed, either explicitly through clear and clearCache or through eviction.

Eviction

Images can be evicted automatically once they are no longer used, so that a game that loads images as it goes does not grow its memory usage without bound. Eviction is opt-in: with no maxSizeBytes set and no calls to evictUnused, the cache keeps every image until it is cleared.

The cache knows which images are in use through reference counting. Every component that renders an image retains it with retain while it is mounted and releases it with release when it is removed, which the Flame components do through the ImageRetainer mixin. An image with no retainers is eligible for eviction once gracePeriod has passed since it was last loaded, fetched or released. The grace period covers the gap between loading an image, typically in onLoad, and the component that uses it being mounted.

Eviction runs when evictUnused is called, and automatically when a load pushes the cache over maxSizeBytes, in which case the least recently used eligible images are disposed until the cache fits in its budget again.

An evicted image is gone from the cache, so with eviction enabled obtain images with load rather than fromCache, since load decodes the image again when it is missing and fromCache fails. Images that your own code keeps outside of a retaining component must be retained manually.

Constructors

Images({AssetBundle? bundle, int? maxSizeBytes})

Properties

bundle ↔ AssetBundle: The AssetBundle from which images are loaded. defaults to Flame.bundle.
getter/setter pair
gracePeriod ↔ Duration: How long an image stays in the cache after it was last loaded, fetched, retained or released before it becomes eligible for eviction.
getter/setter pair
hashCode → int: The hash code for this object.
no setterinherited
keys → List<String>: Returns the list of keys in the cache.
no setter
maxSizeBytes ↔ int?: The soft upper bound, in bytes, for the images held by this cache.
getter/setter pair
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
sizeBytes → int: The estimated size, in bytes, of all the loaded images in the cache.
no setter

Methods

add(String name, Image image) → void: Adds the image into the cache under the key name.
addFromBase64Data(String name, String base64Data) → Future<void>: Transform the base64 encoded image into an Image and adds it into the cache.
clear(String name) → void: Removes the image name from the cache.
clearCache() → void: Removes all cached images.
containsKey(String key) → bool: Whether the cache contains the specified key or not.
evictUnused() → int: Disposes every image in the cache that is not retained and has not been loaded, fetched, retained or released within gracePeriod.
fetchOrGenerate(String name, Future<Image> imageGenerator()) → Future<Image>: If the image with name exists in the cache that is returned, otherwise the image generated by imageGenerator is returned.
findKeyForImage(Image image) → String?
fromBase64(String key, String base64) → Future<Image>
fromCache(String name) → Image: Returns the image name from the cache.
load(String fileName, {String? key, String? package}) → Future<Image>: Loads the image at fileName into the cache.
loadAll(List<String> fileNames) → Future<List<Image>>: Loads all images with the specified fileNames into the cache.
loadAllFromPattern(Pattern pattern, {required String directory}) → Future<List<Image>>: Loads all images under directory that match the specified pattern.
loadAllImages({required String directory}) → Future<List<Image>>: Loads every image found under directory into the cache.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
ready() → Future<void>: Waits until all currently pending image loading operations complete.
release(Image image) → void: Undoes one call to retain for image.
retain(Image image) → void: Marks image as in use, which protects it from eviction until it is released with release as many times as it was retained.
retainCount(String key) → int: The number of times that the image under key is currently retained.
sizeBytesOf(String key) → int: The estimated size, in bytes, of the image under key.
toString() → String: A string representation of this object.
inherited

Operators

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

Static Methods

ownerOf(Image image) → Images?: Returns the cache that image was loaded into, or null if the image does not belong to any cache.
resolvePath(String fileName, String? package) → String: Resolves fileName to the path it is loaded from, and cached under, when it belongs to package.