Crayon

AboutTutorialsDocumentationDemosDownloadSource

ImageResources

Library for loading image resources. Also abstracts auto-image sheet/atlas resources.

class ImageLoader[link]

Loads an ImageResource from the program's compile-time embedded resources.

function getImage()[link]

Returns the image once loading is complete. Code must call .isDone() before calling this method. Even if the image has finished loading, this function will throw a Core.InvalidOperationException if .isDone() was never called.

Return Value

TypeDescription
ImageResources.ImageResource

The image

function isDone()[link]

Returns true if the image has finished loading.

Return Value

TypeDescription
boolean

true if loading is complete

function loadFromResources(resourcePath)[link]

Loads a compile-time image resource synchronously and returns it. To load an image asynchronously, use .loadFromResourcesAsync(). This function cannot be used for image resources that are consolidated into an image sheet, in which case, the ImageSheet class must be used instead for loading.

Arguments

NameTypeDescription
resourcePath string

Path to the image resource.

Return Value

TypeDescription
ImageResources.ImageResource

An image resource object.

function loadFromResourcesAsync(resourcePath)[link]

Loads a compile-time image resource asynchronously and returns the loader object that can be queried for status or the final result. To check load progress, use .isDone(). To get the image after loading is complete, use .getImage(). To load an image synchronously and get an ImageResource instance directly, use .loadFromResources(). This function cannot be used for image resources that are consolidated into an image sheet, in which case, the ImageSheet class must be used instead for loading.

Arguments

NameTypeDescription
resourcePath string

Path to the image resource.

Return Value

TypeDescription
ImageResources.ImageLoader

A reference to a new loader object.

class ImageNotFoundException[link]

Exception thrown when an image path does not exist.

Fields

NameTypeDescription
.path string

Path of the image which was being attempted to load

class ImageResource[link]

Represents an image. Generally, this class cannot do much on its own (aside from querying width and height), and is meant to be used in a secondary library such as Graphics2D or ImageEncoder.

new ImageResource(width, height)[link]

Creates a new image resource with the given size. To load an existing image from the program's embedded resources, see ImageLoader. To load an existing image from an image sheet declared in the build file, see ImageSheet.

Arguments

NameTypeDescription
width integer

Width of the image in pixels.

height integer

Height of the image in pixels.

function getHeight()[link]

Gets the height of the image in pixels.

Return Value

TypeDescription
integer

image height

function getWidth()[link]

Gets the width of the image in pixels.

Return Value

TypeDescription
integer

image width

class ImageSheet[link]

An image sheet is a collection of image resources. The way the images are aggregated is defined by the build file. By aggregating images, loading images from disk is generally faster as it reduces the number of hard disk reads (or in the case of JavaScript, image download requests). Furthermore, OpenGL based platforms can load all the images into a single texture atlas to prevent texture context switches. If there are lots of images to load, this simplifies the process of providing a progress bar since the completion percentage is calculated by the library. All ImageResources that are loaded from an image sheet abstract the aggregation away from your code such that operations will appear as though the image is a standalone image file.

function getFiles()[link]

Returns a list of all the image resource paths available in this image sheet.

Return Value

TypeDescription
List of strings

List of all image resource paths in this sheet.

function getImage(resourcePath)[link]

Returns an image resource that is contained in this image sheet. If the image sheet is loaded asynchronously, this method cannot be called without calling .isDone() first, even if the image sheet has finished loading.

Arguments

NameTypeDescription
resourcePath string

Path to an image resource

Return Value

TypeDescription
ImageResources.ImageResource

An image resource

function getProgress()[link]

Returns a ratio of loading progress from 0 to 1. This is a convenience method for showing progress to the user, but .isDone() must still be called before accessing any image resources.

Return Value

TypeDescription
float

Ratio of progress

function isDone()[link]

Returns true if the image sheet is done loading. This method is only applicable to asynchronously-loaded image sheets. This method must be called for all asynchronous image sheets before getImage() is called, otherwise an InvalidOperationException is thrown, even if the image sheet is actually done loading.

Return Value

TypeDescription
boolean

true if the image sheet is done loading

function loadFromResources(idOrIds)[link]

Returns a new image sheet object. If multiple sheet ID's are passed to this method, all those image sheets will be aggregated into one single ImageSheet instance. This function will block execution of your program until loading has completed which can potentially be very slow. To load asynchronously, use .loadFromResourcesAsync().

Arguments

NameTypeDescription
idOrIds string or List of strings

An image sheet ID or a list of image sheet IDs

Return Value

TypeDescription
ImageResources.ImageSheet

An image sheet

function loadFromResourcesAsync(idOrIds)[link]

Returns a new image sheet object which is not completely loaded yet. If multiple sheet ID's are passed to this method, all those image sheets will be aggregated into one single ImageSheet instance. To check to see if the image sheet is done loading, use .isDone(). To check the progress of loading, use .getProgress().

Arguments

NameTypeDescription
idOrIds string or List of strings

An image sheet ID or a list of image sheet IDs

Return Value

TypeDescription
ImageResources.ImageSheet

An image sheet

class LoadFailedException[link]

Exception thrown when an image fails to load. The exception message field may contain more information.

class SheetNotFoundException[link]

Exception thrown when an image sheet with a given ID does not exist.

Fields

NameTypeDescription
.id string

ID of the image sheet that does not exist