ImageResources
Library for loading image resources. Also abstracts auto-image sheet/atlas resources.
- namespace ImageResources
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
| Type | Description |
|---|---|
| ImageResources.ImageResource | The image |
function isDone()[link]
Returns true if the image has finished loading.
Return Value
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| resourcePath | string | Path to the image resource. |
Return Value
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| resourcePath | string | Path to the image resource. |
Return Value
| Type | Description |
|---|---|
| ImageResources.ImageLoader | A reference to a new loader object. |
class ImageNotFoundException[link]
Exception thrown when an image path does not exist.
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
| Name | Type | Description |
|---|---|---|
| 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
| Type | Description |
|---|---|
| integer | image height |
function getWidth()[link]
Gets the width of the image in pixels.
Return Value
| Type | Description |
|---|---|
| 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
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| resourcePath | string | Path to an image resource |
Return Value
| Type | Description |
|---|---|
| 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
| Type | Description |
|---|---|
| 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
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| idOrIds | string or List of strings | An image sheet ID or a list of image sheet IDs |
Return Value
| Type | Description |
|---|---|
| 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
| Name | Type | Description |
|---|---|---|
| idOrIds | string or List of strings | An image sheet ID or a list of image sheet IDs |
Return Value
| Type | Description |
|---|---|
| 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.