com.threerings.media.tile
Class TileSet

java.lang.Object
  com.threerings.media.tile.TileSet

All Implemented Interfaces:

Serializable, Cloneable

Direct Known Subclasses:

SwissArmyTileSet, TrimmedObjectTileSet, TrimmedTileSet, UniformTileSet

public abstract class TileSet
extends Object
implements Cloneable, Serializable

A tileset stores information on a single logical set of tiles. It provides a clean interface for the TileManager or other entities to retrieve individual tiles from the tile set and encapsulates the potentially sophisticated process of extracting the tile image from a composite tileset image.

Tiles are referenced by their tile id. The tile id is essentially the tile number, assuming the tile at the top-left of the image is tile id zero and tiles are numbered, in ascending order, left to right, top to bottom.

This class is serializable and will be serialized, so derived classes should be sure to mark non-persistent fields as transient.

See Also:

Serialized Form

Nested Class Summary

static interface

TileSet.Colorizer Used to assign colorizations to tiles that require them.

Field Summary

protected static Map<Tile.Key,SoftReference<Tile>>	_atiles A map containing weak references to all "active" tiles.
protected static Throttle	_cacheStatThrottle Throttle our cache status logging to once every 300 seconds.
protected String	_imagePath The path to the file containing the tile images.
protected ImageProvider	_improv The entity from which we obtain our tile image.
protected static Tile.Key	_key A key used to look things up in the cache without creating craploads of keys unduly.
protected String	_name The tileset name.
protected Colorization[]	_zations Colorizations to be applied to tiles created from this tileset.

Constructor Summary

TileSet()

Method Summary

protected boolean	checkTileIndex(int tileIndex) Used to ensure that the specified tile index is valid.
TileSet	clone(Colorization[] zations) Creates a copy of this tileset which will apply the supplied colorizations to its tileset image when creating tiles.
TileSet	clone(String imagePath) Returns a new tileset that is a clone of this tileset with the image path updated to reference the given path.
abstract Rectangle	computeTileBounds(int tileIndex, Rectangle bounds) Computes and fills in the bounds for the specified tile based on the mechanism used by the derived class to do such things.
protected Tile	createTile() Creates a blank tile of the appropriate type for this tileset.
protected Colorization[]	getColorizations(int tileIndex, TileSet.Colorizer rizer) Returns colorizations for the specified tile image.
String	getImagePath() Returns the path to the composite image used by this tileset.
String	getName() Returns the tileset name.
BufferedImage	getRawTileImage(int tileIndex) Returns the raw (unprepared) image that would be used by the tile at the specified index.
BufferedImage	getRawTileSetImage() Returns the entire, raw, uncut, unprepared tileset source image.
Tile	getTile(int tileIndex) Equivalent to getTile(int,Colorizer) with a null Colorizer argument.
Tile	getTile(int tileIndex, Colorization[] zations) Creates a Tile object from this tileset corresponding to the specified tile id and returns that tile.
Tile	getTile(int tileIndex, TileSet.Colorizer rizer) Creates a Tile object from this tileset corresponding to the specified tile id and returns that tile.
abstract int	getTileCount() Returns the number of tiles in the tileset.
Mirage	getTileMirage(int tileIndex) Returns a prepared version of the image that would be used by the tile at the specified index.
Mirage	getTileMirage(int tileIndex, Colorization[] zations) Returns a prepared version of the image that would be used by the tile at the specified index.
Mirage[]	getTileMirages() Returns prepared versions of the images that would be used for each of the tiles.
protected void	initTile(Tile tile, int tileIndex, Colorization[] zations) Initializes the supplied tile.
protected void	reportCachePerformance() Reports statistics detailing the image manager cache performance and the current size of the cached images.
void	setImagePath(String imagePath) Sets the path to the image that will be used by this tileset.
void	setImageProvider(ImageProvider improv) Configures this tileset with an image provider that it can use to load its tileset image.
void	setName(String name) Specifies the tileset name.
String	toString()
protected void	toString(StringBuilder buf) Derived classes can override this, calling super.toString(buf) and then appending additional information to the buffer.

Methods inherited from class java.lang.Object

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

Field Detail

_imagePath

protected String _imagePath

The path to the file containing the tile images.

_name

protected String _name

The tileset name.

_zations

protected transient Colorization[] _zations

Colorizations to be applied to tiles created from this tileset.

_improv

protected transient ImageProvider _improv

The entity from which we obtain our tile image.

_atiles

protected static Map<Tile.Key,SoftReference<Tile>> _atiles

A map containing weak references to all "active" tiles.

_key

protected static Tile.Key _key

A key used to look things up in the cache without creating craploads of keys unduly.

_cacheStatThrottle

protected static Throttle _cacheStatThrottle

Throttle our cache status logging to once every 300 seconds.

Constructor Detail

TileSet

public TileSet()

Method Detail

setImageProvider

public void setImageProvider(ImageProvider improv)

Configures this tileset with an image provider that it can use to load its tileset image. This will be called automatically when the tileset is fetched via the TileManager.

getName

public String getName()

Returns the tileset name.

setName

public void setName(String name)

Specifies the tileset name.

setImagePath

public void setImagePath(String imagePath)

Sets the path to the image that will be used by this tileset. This must be called before the first call to getTile(int).

getImagePath

public String getImagePath()

Returns the path to the composite image used by this tileset.

getTileCount

public abstract int getTileCount()

Returns the number of tiles in the tileset.

clone

public TileSet clone(Colorization[] zations)

Creates a copy of this tileset which will apply the supplied colorizations to its tileset image when creating tiles.

clone

public TileSet clone(String imagePath)
              throws CloneNotSupportedException

Returns a new tileset that is a clone of this tileset with the image path updated to reference the given path. Useful for configuring a single tileset and then generating additional tilesets with new images with the same configuration.

Throws:

CloneNotSupportedException

computeTileBounds

public abstract Rectangle computeTileBounds(int tileIndex,
                                            Rectangle bounds)

Computes and fills in the bounds for the specified tile based on the mechanism used by the derived class to do such things. The width and height of the bounds should be the size of the tile image and the x and y offset should be the offset in the tileset image for the image data of the specified tile.

Parameters:

tileIndex - the index of the tile whose bounds are to be computed.

bounds - the rectangle object into which to fill the bounds.

Returns:

the rectangle passed into the bounds parameter.

getTile

public Tile getTile(int tileIndex)

Equivalent to getTile(int,Colorizer) with a null Colorizer argument.

getTile

public Tile getTile(int tileIndex,
                    TileSet.Colorizer rizer)

Creates a Tile object from this tileset corresponding to the specified tile id and returns that tile. A null tile will never be returned, but one with an error image may be returned if a problem occurs loading the underlying tileset image.

Parameters:

tileIndex - the index of the tile in the tileset. Tile indexes start with zero as the upper left tile and increase by one as the tiles move left to right and top to bottom over the source image.

rizer - an entity that will be used to obtain colorizations for tilesets that are recolorizable. Passing null if the tileset is known not to be recolorizable is valid.

Returns:

the tile object.

getTile

public Tile getTile(int tileIndex,
                    Colorization[] zations)

Creates a Tile object from this tileset corresponding to the specified tile id and returns that tile. A null tile will never be returned, but one with an error image may be returned if a problem occurs loading the underlying tileset image.

Parameters:

tileIndex - the index of the tile in the tileset. Tile indexes start with zero as the upper left tile and increase by one as the tiles move left to right and top to bottom over the source image.

zations - colorizations to be applied to the tile image prior to returning it. These may be null for uncolorized images.

Returns:

the tile object.

getTileMirage

public Mirage getTileMirage(int tileIndex)

Returns a prepared version of the image that would be used by the tile at the specified index. Because tilesets are often used simply to provide access to a collection of uniform images, this method is provided to bypass the creation of a Tile object when all that is desired is access to the underlying image.

getTileMirages

public Mirage[] getTileMirages()

Returns prepared versions of the images that would be used for each of the tiles. Because tilesets are often used simply to provide access to a collection of uniform images, this method is provided to bypass the creation of a Tile objects when all that is desired is access to the underlying images.

getTileMirage

public Mirage getTileMirage(int tileIndex,
                            Colorization[] zations)

Returns a prepared version of the image that would be used by the tile at the specified index. Because tilesets are often used simply to provide access to a collection of uniform images, this method is provided to bypass the creation of a Tile object when all that is desired is access to the underlying image.

getRawTileSetImage

public BufferedImage getRawTileSetImage()

Returns the entire, raw, uncut, unprepared tileset source image. Don't use this method unless you know what you're doing! This image should not be rendered directly to the screen, you should obtain a tile (getTile(int)), or a tile mirage (getTileMirage(int)).

getRawTileImage

public BufferedImage getRawTileImage(int tileIndex)

Returns the raw (unprepared) image that would be used by the tile at the specified index. Don't use this method unless you know what you're doing! If you're going to be painting this image onto the screen directly, use getTileMirage(int) because that prepares the image for display. Only use this if you're going to do further processing and prepare the subsequent image for display onscreen.

getColorizations

protected Colorization[] getColorizations(int tileIndex,
                                          TileSet.Colorizer rizer)

Returns colorizations for the specified tile image. The default is to return any colorizations associated with the tileset via a call to clone(Colorization[]), however derived classes may have dynamic colorization policies that look up colorization assignments from the supplied colorizer.

checkTileIndex

protected boolean checkTileIndex(int tileIndex)

Used to ensure that the specified tile index is valid.

createTile

protected Tile createTile()

Creates a blank tile of the appropriate type for this tileset.

Returns:

a blank tile ready to be populated with its image and metadata.

initTile

protected void initTile(Tile tile,
                        int tileIndex,
                        Colorization[] zations)

Initializes the supplied tile. Derived classes can override this method to add in their own tile information, but should be sure to call super.initTile().

Parameters:

tile - the tile to initialize.

tileIndex - the index of the tile.

zations - the colorizations to be used when generating the tile image.

toString

public String toString()

Overrides:

toString in class Object

reportCachePerformance

protected void reportCachePerformance()

Reports statistics detailing the image manager cache performance and the current size of the cached images.

toString

protected void toString(StringBuilder buf)

Derived classes can override this, calling super.toString(buf) and then appending additional information to the buffer.