org.cell2d

Class Sprite

java.lang.Object

org.cell2d.Sprite

All Implemented Interfaces:

Animatable, Drawable, Loadable

public class Sprite
extends java.lang.Object
implements Animatable, Drawable, Loadable

A Sprite is a static image that can be drawn to a Graphics context. Like other Loadables, Sprites can be manually loaded and unloaded into and out of memory. Loading may take a moment, but while a Sprite is not loaded, it cannot be drawn. A Sprite may also be treated as an Animatable with exactly one frame, namely itself, that has a duration of 0.

A Sprite has a fixed set of Filters, specified upon its creation, that can have an effect on it when applied to it with its draw() method. The Sprite makes this possible by making a copy of its image data with each Filter applied upon being loaded. Thus, the amount of memory that a loaded Sprite occupies is proportional to its number of applicable Filters plus 1.

See Also:

Filter, SpriteSheet, Animation

Field Summary

Fields

Modifier and Type	Field and Description
static Sprite	BLANK A blank Sprite with no appearance.

Constructor Summary

Constructors

Constructor and Description
Sprite(Image image, Filter... filters) Constructs a Sprite from a Celick Image.
Sprite(java.lang.String path, int originX, int originY, boolean load, Filter... filters) Constructs a Sprite from an image file.
Sprite(java.lang.String path, int originX, int originY, Color transColor, boolean load, Filter... filters) Constructs a Sprite from an image file.
Sprite(java.lang.String path, int originX, int originY, int transR, int transG, int transB, boolean load, Filter... filters) Constructs a Sprite from an image file.

Method Summary

Modifier and Type	Method and Description
void	draw(Graphics g, int x, int y) Draws this Drawable's image to the specified Graphics context.
void	draw(Graphics g, int x, int y, boolean xFlip, boolean yFlip, double angle, double alpha, Filter filter) Draws this Drawable's image to the specified Graphics context.
void	draw(Graphics g, int x, int y, double scale, boolean xFlip, boolean yFlip, double alpha, Filter filter) Draws this Drawable's image to the specified Graphics context.
void	draw(Graphics g, int x, int y, int left, int right, int top, int bottom) Draws a rectangular region of this Drawable's image to the specified Graphics context.
void	draw(Graphics g, int x, int y, int left, int right, int top, int bottom, boolean xFlip, boolean yFlip, double angle, double alpha, Filter filter) Draws a rectangular region of this Drawable's image to the specified Graphics context.
void	draw(Graphics g, int x, int y, int left, int right, int top, int bottom, double scale, boolean xFlip, boolean yFlip, double alpha, Filter filter) Draws a rectangular region of this Drawable's image to the specified Graphics context.
boolean	framesAreCompatible(int index1, int index2) Returns whether the two frames at the specified indices are compatible for AnimationInstances' transitioning purposes.
Sprite	getFilteredCopy(Filter filter, boolean load) Returns a new Animatable created by applying a Filter to all of the Sprites of which this Animatable is ultimately composed.
java.util.Set<Filter>	getFilters() Returns an unmodifiable Set view of the Filters that will have an effect on this Sprite when applied to it with draw().
Animatable	getFrame(int index) Returns this Animatable's frame at the specified index.
long	getFrameDuration(int index) Returns the duration in fracunits of this Animatable's frame at the specified index.
int	getHeight() Returns this Sprite's height in pixels.
Drawable	getInstance() Returns a Drawable instantiation of this Sprite - which is simply this Sprite itself, since Sprites are already Drawables.
int	getLevel() Returns how many levels of Animations this Animatable and its frames and sub-frames comprise.
int	getNumFrames() Returns how many frames this Animatable has.
int	getOriginX() Returns the x-coordinate in pixels of this Sprite's origin.
int	getOriginY() Returns the y-coordinate in pixels of this Sprite's origin.
java.util.Set<Sprite>	getSprites() Returns an unmodifiable Set view of all of the Sprites that ultimately compose this Animatable.
SpriteSheet	getSpriteSheet() Returns the SpriteSheet that this Sprite is part of, or null if it is not part of one.
int	getWidth() Returns this Sprite's width in pixels.
boolean	isLoaded() Returns whether this Loadable is loaded.
boolean	load() Loads this Sprite if it is not already loaded.
boolean	unload() Unloads this Sprite if it is currently loaded.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.cell2d.Drawable

getRenderableRegion

Field Detail

BLANK

public static final Sprite BLANK

A blank Sprite with no appearance. It is considered to always be loaded and cannot be unloaded.

Constructor Detail

Sprite

public Sprite(java.lang.String path,
              int originX,
              int originY,
              boolean load,
              Filter... filters)

Constructs a Sprite from an image file.

Parameters:

path - The relative path to the image file

originX - The x-coordinate in pixels of the origin on the image

originY - The y-coordinate in pixels of the origin on the image

load - Whether this Sprite should load upon creation

filters - The Filters that should have an effect on this Sprite when applied to it with draw()

Sprite

public Sprite(java.lang.String path,
              int originX,
              int originY,
              Color transColor,
              boolean load,
              Filter... filters)

Constructs a Sprite from an image file.

Parameters:

path - The relative path to the image file

originX - The x-coordinate in pixels of the origin on the image

originY - The y-coordinate in pixels of the origin on the image

transColor - This Sprite's transparent color, or null if there should be none

load - Whether this Sprite should load upon creation

filters - The Filters that should have an effect on this Sprite when applied to it with draw()

Sprite

public Sprite(java.lang.String path,
              int originX,
              int originY,
              int transR,
              int transG,
              int transB,
              boolean load,
              Filter... filters)

Constructs a Sprite from an image file.

Parameters:

path - The relative path to the image file

originX - The x-coordinate in pixels of the origin on the image

originY - The y-coordinate in pixels of the origin on the image

transR - The red value (0-255) of this Sprite's transparent color

transG - The green value (0-255) of this Sprite's transparent color

transB - The blue value (0-255) of this Sprite's transparent color

load - Whether this Sprite should load upon creation

filters - The Filters that should have an effect on this Sprite when applied to it with draw()

Sprite

public Sprite(Image image,
              Filter... filters)

Constructs a Sprite from a Celick Image. This Sprite's origin will be the Image's center of rotation with its coordinates rounded to the nearest integer. Once created, this Sprite will be independent of the Image from which it is created. This Sprite will be considered to be loaded from the start, and once unloaded, it cannot be reloaded.

Parameters:

image - The Image to create this Sprite from

filters - The Filters that should have an effect on this Sprite when applied to it with draw()

Method Detail

isLoaded

public final boolean isLoaded()

Description copied from interface: Loadable

Returns whether this Loadable is loaded.

Specified by:

isLoaded in interface Loadable

Returns:

Whether this Loadable is loaded

load

public final boolean load()

Loads this Sprite if it is not already loaded. If this Sprite was created from another Sprite or is part of a SpriteSheet, that other Sprite or SpriteSheet will be loaded as well.

Specified by:

load in interface Loadable

Returns:

Whether the loading occurred

unload

public final boolean unload()

Unloads this Sprite if it is currently loaded. If this Sprite is part of a SpriteSheet that had no other Sprites loaded, that SpriteSheet will be unloaded as well.

Specified by:

unload in interface Loadable

Returns:

Whether the unloading occurred

getLevel

public final int getLevel()

Description copied from interface: Animatable

Returns how many levels of Animations this Animatable and its frames and sub-frames comprise. For example, an Animation of Animations of Animations has a level of 3.

Specified by:

getLevel in interface Animatable

Returns:

This Animatable's level

getNumFrames

public final int getNumFrames()

Description copied from interface: Animatable

Returns how many frames this Animatable has.

Specified by:

getNumFrames in interface Animatable

Returns:

This Animatable's number of frames

getFrame

public final Animatable getFrame(int index)

Description copied from interface: Animatable

Returns this Animatable's frame at the specified index.

Specified by:

getFrame in interface Animatable

Parameters:

index - The index of the frame to be returned

Returns:

This Animatable's frame at the specified index

getFrameDuration

public final long getFrameDuration(int index)

Description copied from interface: Animatable

Returns the duration in fracunits of this Animatable's frame at the specified index.

Specified by:

getFrameDuration in interface Animatable

Parameters:

index - The index of the frame whose duration is to be returned

Returns:

The duration of this Animatable's frame at the specified index

framesAreCompatible

public final boolean framesAreCompatible(int index1,
                                         int index2)

Description copied from interface: Animatable

Returns whether the two frames at the specified indices are compatible for AnimationInstances' transitioning purposes. An AnimationInstance of this Animatable, if it is an Animation, or of an Animation that incorporates this Animatable may transition between the frames at the specified indices without resetting all of its indices at its lower levels to 0 if and only if this method returns true.

Specified by:

framesAreCompatible in interface Animatable

Parameters:

index1 - The index of the first frame

index2 - The index of the second frame

Returns:

Whether or not an AnimationInstance may transition between the two frames without resetting its lower indices to 0

getSprites

public final java.util.Set<Sprite> getSprites()

Description copied from interface: Animatable

Returns an unmodifiable Set view of all of the Sprites that ultimately compose this Animatable. If this Animatable is a Sprite, the returned Set will only contain the Sprite itself. If this Animatable is an Animation, the returned Set will be equal to the union of the return values of getSprites() for each of the Animation's frames.

Specified by:

getSprites in interface Animatable

Returns:

The Sprites that ultimately compose this Animatable

getFilteredCopy

public final Sprite getFilteredCopy(Filter filter,
                                    boolean load)

Description copied from interface: Animatable

Returns a new Animatable created by applying a Filter to all of the Sprites of which this Animatable is ultimately composed. The returned Animatable will have the same hierarchical Animation structure as this Animatable. In particular, if this Animatable is a Sprite, the returned Animatable will also be a Sprite. To avoid redundant Sprite creation, Sprites keep track of the filtered copies of themselves that have been created, so applying this method to the same Sprite twice will cause the same filtered Sprite to be returned twice.

Specified by:

getFilteredCopy in interface Animatable

Parameters:

filter - The Filter to apply to this Animatable's Sprites to create the new Animatable

load - Whether the new Animatable should load its Sprites upon its creation

Returns:

A filtered copy of this Animatable

getInstance

public final Drawable getInstance()

Returns a Drawable instantiation of this Sprite - which is simply this Sprite itself, since Sprites are already Drawables.

Specified by:

getInstance in interface Animatable

Returns:

A Drawable instantiation of this Sprite

getSpriteSheet

public final SpriteSheet getSpriteSheet()

Returns the SpriteSheet that this Sprite is part of, or null if it is not part of one.

Returns:

The SpriteSheet that this Sprite is part of

getFilters

public final java.util.Set<Filter> getFilters()

Returns an unmodifiable Set view of the Filters that will have an effect on this Sprite when applied to it with draw().

Returns:

The Set of Filters that will have an effect on this Sprite when applied to it with draw()

getOriginX

public final int getOriginX()

Returns the x-coordinate in pixels of this Sprite's origin.

Returns:

The x-coordinate in pixels of this Sprite's origin

getOriginY

public final int getOriginY()

Returns the y-coordinate in pixels of this Sprite's origin.

Returns:

The y-coordinate in pixels of this Sprite's origin

getWidth

public final int getWidth()

Returns this Sprite's width in pixels. If the Sprite is not loaded, this method will return 0.

Returns:

This Sprite's width in pixels

getHeight

public final int getHeight()

Returns this Sprite's height in pixels. If the Sprite is not loaded, this method will return 0.

Returns:

This Sprite's height in pixels

draw

public final void draw(Graphics g,
                       int x,
                       int y)

Description copied from interface: Drawable

Draws this Drawable's image to the specified Graphics context.

Specified by:

draw in interface Drawable

Parameters:

g - The Graphics context to draw the image to

x - The x-coordinate on the Graphics context of the drawn image's origin

y - The y-coordinate on the Graphics context of the drawn image's origin

draw

public final void draw(Graphics g,
                       int x,
                       int y,
                       boolean xFlip,
                       boolean yFlip,
                       double angle,
                       double alpha,
                       Filter filter)

Description copied from interface: Drawable

Draws this Drawable's image to the specified Graphics context.

Specified by:

draw in interface Drawable

Parameters:

g - The Graphics context to draw the image to

x - The x-coordinate on the Graphics context of the drawn image's origin

y - The y-coordinate on the Graphics context of the drawn image's origin

xFlip - If true, the drawn image is flipped along a vertical line through its origin

yFlip - If true, the drawn image is flipped along a horizontal line through its origin

angle - The angle in degrees by which to rotate the drawn image and its xFlip and yFlip lines counterclockwise around its origin

alpha - The drawn image's alpha (opacity) value from 0 to 1

filter - The Filter to apply to the drawn image, or null if none should be applied. Not every Filter has an effect on every Drawable.

draw

public final void draw(Graphics g,
                       int x,
                       int y,
                       double scale,
                       boolean xFlip,
                       boolean yFlip,
                       double alpha,
                       Filter filter)

Description copied from interface: Drawable

Draws this Drawable's image to the specified Graphics context.

Specified by:

draw in interface Drawable

Parameters:

g - The Graphics context to draw the image to

x - The x-coordinate on the Graphics context of the drawn image's origin

y - The y-coordinate on the Graphics context of the drawn image's origin

scale - The factor by which to scale the drawn image around its origin

xFlip - If true, the drawn image is flipped along a vertical line through its origin

yFlip - If true, the drawn image is flipped along a horizontal line through its origin

alpha - The drawn image's alpha (opacity) value from 0 to 1

filter - The Filter to apply to the drawn image, or null if none should be applied. Not every Filter has an effect on every Drawable.

draw

public final void draw(Graphics g,
                       int x,
                       int y,
                       int left,
                       int right,
                       int top,
                       int bottom)

Description copied from interface: Drawable

Draws a rectangular region of this Drawable's image to the specified Graphics context.

Specified by:

draw in interface Drawable

Parameters:

g - The Graphics context to draw the region to

x - The x-coordinate on the Graphics context of the image's origin

y - The y-coordinate on the Graphics context of the image's origin

left - The x-coordinate on the image, relative to its origin, of the region's left edge

right - The x-coordinate on the image, relative to its origin, of the region's right edge

top - The y-coordinate on the image, relative to its origin, of the region's top edge

bottom - The y-coordinate on the image, relative to its origin, of the region's bottom edge

draw

public final void draw(Graphics g,
                       int x,
                       int y,
                       int left,
                       int right,
                       int top,
                       int bottom,
                       boolean xFlip,
                       boolean yFlip,
                       double angle,
                       double alpha,
                       Filter filter)

Description copied from interface: Drawable

Draws a rectangular region of this Drawable's image to the specified Graphics context.

Specified by:

draw in interface Drawable

Parameters:

g - The Graphics context to draw the region to

x - The x-coordinate on the Graphics context of the image's origin

y - The y-coordinate on the Graphics context of the image's origin

left - The x-coordinate on the image, relative to its origin, of the region's left edge

right - The x-coordinate on the image, relative to its origin, of the region's right edge

top - The y-coordinate on the image, relative to its origin, of the region's top edge

bottom - The y-coordinate on the image, relative to its origin, of the region's bottom edge

xFlip - If true, the drawn region is flipped along a vertical line through the image's origin

yFlip - If true, the drawn region is flipped along a horizontal line through the image's origin

angle - The angle in degrees by which to rotate the drawn region and its xFlip and yFlip lines counterclockwise around the image's origin

alpha - The drawn region's alpha (opacity) value from 0 to 1

filter - The Filter to apply to the drawn region, or null if none should be applied. Not every Filter has an effect on every Drawable.

draw

public final void draw(Graphics g,
                       int x,
                       int y,
                       int left,
                       int right,
                       int top,
                       int bottom,
                       double scale,
                       boolean xFlip,
                       boolean yFlip,
                       double alpha,
                       Filter filter)

Description copied from interface: Drawable

Draws a rectangular region of this Drawable's image to the specified Graphics context.

Specified by:

draw in interface Drawable

Parameters:

g - The Graphics context to draw the region to

x - The x-coordinate on the Graphics context of the image's origin

y - The y-coordinate on the Graphics context of the image's origin

left - The x-coordinate on the image, relative to its origin, of the region's left edge

right - The x-coordinate on the image, relative to its origin, of the region's right edge

top - The y-coordinate on the image, relative to its origin, of the region's top edge

bottom - The y-coordinate on the image, relative to its origin, of the region's bottom edge

scale - The factor by which to scale the drawn region around the image's origin

xFlip - If true, the drawn region is flipped along a vertical line through the image's origin

yFlip - If true, the drawn region is flipped along a horizontal line through the image's origin

alpha - The drawn region's alpha (opacity) value from 0 to 1

filter - The Filter to apply to the drawn region, or null if none should be applied. Not every Filter has an effect on every Drawable.