Package VASSAL.tools.imageop

Class AbstractOpImpl

java.lang.Object

VASSAL.tools.opcache.AbstractOpImpl<BufferedImage>

VASSAL.tools.imageop.AbstractOpImpl

All Implemented Interfaces:

ImageOp, Op<BufferedImage>

Direct Known Subclasses:

AbstractTiledOpImpl, AbstractTileOpImpl

public abstract class AbstractOpImpl
extends AbstractOpImpl<BufferedImage>
implements ImageOp

An abstract representation of an operation which may be applied to an Image. ImageOp is the base class for all such operations. The results of all operations are memoized (using a memory-sensitive cache), so retrieving results is both fast and memory-efficient.

Warning: For efficiency reasons, the methods getImage() and getTile(java.awt.Point, VASSAL.tools.imageop.ImageOpObserver) do not return Images defensively, nor do the Future<Image>s returned by getFutureImage(VASSAL.tools.imageop.ImageOpObserver) and getFutureTile(java.awt.Point, VASSAL.tools.imageop.ImageOpObserver). That is, the Image returned is possibly the one retained internally by the ImageOp. Therefore, Images obtained from an ImageOp must not be altered, as this might interfere with image caching. If an Image obtained this way needs to be modified, copy the Image first and alter the copy.

Since:

3.1.0

Author:

Joel Uckelman

Field Summary

Fields

Modifier and Type	Field	Description
protected static final OpCache	cache	The cache which contains calculated Images.
protected Dimension	size	The cached size of this operation's resulting Image.

Constructor Summary

Constructors

Constructor	Description
AbstractOpImpl()

Method Summary

Modifier and Type	Method	Description
static void	clearCache()
abstract BufferedImage	eval()	Runs the Op.
protected abstract void	fixSize()	Sets the size which is used by getSize(), getHeight(), and getWidth().
Future<BufferedImage>	getFutureImage(ImageOpObserver obs)	Submits a request for the BufferedImage produced by this operation, and returns a reference to that request.
abstract Future<BufferedImage>	getFutureTile(int tileX, int tileY, ImageOpObserver obs)	Submits a request for tile (tileX,tileY), and returns a reference to that request.
Future<BufferedImage>	getFutureTile(Point p, ImageOpObserver obs)	Submits a request for tile (tileX,tileY), and returns a reference to that request.
int	getHeight()	Returns the height of the BufferedImage which would be returned by ImageOp.getImage().
BufferedImage	getImage()	Calculates the BufferedImage produced by this operation.
BufferedImage	getImage(ImageOpObserver obs)	Calculates the BufferedImage produced by this operation, and reports completion or failure to the specified ImageOpObserver.
abstract int	getNumXTiles()	Returns the number of tiles along the x-axis.
abstract int	getNumYTiles()	Returns the number of tiles along the y-axis.
Dimension	getSize()	Returns the size of the BufferedImage which would be returned by ImageOp.getImage().
protected Dimension	getSizeFromCache()	A utility method for retrieving the size of the computed Image from the cache if the Image is cached.
abstract BufferedImage	getTile(int tileX, int tileY, ImageOpObserver obs)	Calculates tile (tileX,tileY), and reports completion or failure to the specified ImageOpObserver.
BufferedImage	getTile(Point p, ImageOpObserver obs)	Calculates tile (p.x,p.y), and reports completion or failure to the specified ImageOpObserver.
abstract int	getTileHeight()	Returns the standard height of the BufferedImage tiles which are returned by ImageOp.getTile(java.awt.Point, VASSAL.tools.imageop.ImageOpObserver).
abstract Point[]	getTileIndices(Rectangle rect)	Returns an array of Points representing the tiles intersecting the given Rectangle.
abstract ImageOp	getTileOp(int tileX, int tileY)	Returns an ImageOp which can produce the requested tile.
ImageOp	getTileOp(Point p)	Returns an ImageOp which can produce the requested tile.
abstract Dimension	getTileSize()	Returns the standard size of the BufferedImage tiles which are returned by ImageOp.getTile(java.awt.Point, VASSAL.tools.imageop.ImageOpObserver).
abstract int	getTileWidth()	Returns the standard width of the BufferedImage tiles which are returned by ImageOp.getTile(java.awt.Point, VASSAL.tools.imageop.ImageOpObserver).
int	getWidth()	Returns the width of the BufferedImage which would be returned by ImageOp.getImage().

Methods inherited from class VASSAL.tools.opcache.AbstractOpImpl

get, get, getFuture, getSources, newKey, update

Methods inherited from class java.lang.Object

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

Methods inherited from interface VASSAL.tools.opcache.Op

getSources, newKey, update

Field Details

size

protected Dimension size

The cached size of this operation's resulting Image.

cache

protected static final OpCache cache

The cache which contains calculated Images.

Constructor Details

AbstractOpImpl

public AbstractOpImpl()

Method Details

clearCache

public static void clearCache()

eval

public abstract BufferedImage eval()
                            throws Exception

Runs the Op. This method should be called only by the caching framework.

Specified by:

eval in interface ImageOp

Specified by:

eval in interface Op<BufferedImage>

Specified by:

eval in class AbstractOpImpl<BufferedImage>

Returns:

the result of running this Op

Throws:

Exception - The operation represented by this ImageOp could be anything, so any exception may be thrown.

getImage

public BufferedImage getImage()

Calculates the BufferedImage produced by this operation. Calls to this method are memoized to prevent redundant computations.

Warning: BufferedImages returned by this method must not be modified.

Specified by:

getImage in interface ImageOp

Returns:

the resulting BufferedImage

getImage

public BufferedImage getImage(ImageOpObserver obs)
                       throws CancellationException,
InterruptedException,
ExecutionException

Calculates the BufferedImage produced by this operation, and reports completion or failure to the specified ImageOpObserver. Calls to this method are memoized to prevent redundant computations. If a non-null observer is given, then the operation may be done asynchronously. If the observer is null, then this method will block on completion of the operation.

When a non-blocking call is made (i.e., when obs != null), the cache is checked and if the image is found, it is returned immediately. If the image is already being calculated, obs is notified when the pre-existing request completes. Otherwise, a new request is queued and obs is notified when that completes.

When a blocking call is made (i.e., when obs == null), the cache is checked and if the image is found, it is returned immediately. If the image is already being calculated, this method blocks on the completion of the existing calculation. Otherwise, a new calculation is started and this method blocks on it. In all cases, when a calculation is completed, the result is cached.

Warning: BufferedImages returned by this method must not be modified.

Specified by:

getImage in interface ImageOp

Parameters:

obs - the observer to be notified on completion

Returns:

the resulting BufferedImage

Throws:

CancellationException - if the operation was cancelled

InterruptedException - if the operation was interrupted

ExecutionException - if the operation failed

See Also:

• ImageOp.getTile(java.awt.Point, VASSAL.tools.imageop.ImageOpObserver)
• ImageOp.getFutureTile(java.awt.Point, VASSAL.tools.imageop.ImageOpObserver)
• ImageOp.getFutureImage(VASSAL.tools.imageop.ImageOpObserver)

getFutureImage

public Future<BufferedImage> getFutureImage(ImageOpObserver obs)
                                     throws ExecutionException

Submits a request for the BufferedImage produced by this operation, and returns a reference to that request. If a non-null observer is given, then the operation may be done asynchronously. If the observer is null, then this method will block on completion of the operation.

This implementation uses a memory-sensitive cache to memoize calls to getFutureImage. It returns a Future<BufferedImage> so that the request may be cancelled if no longer needed.

Futures are returned immediately, except in the case where the is no observer and no pre-existing Future for this ImageOp's BufferedImage, in which case this method blocks on completion of the computation.

Warning: BufferedImages obtained from the Futures returned by this method must not be modified.

Specified by:

getFutureImage in interface ImageOp

Parameters:

obs - the observer to be notified on completion

Returns:

a Future for the resulting BufferedImage

Throws:

ExecutionException - if the operation failed

See Also:

• ImageOp.getTile(java.awt.Point, VASSAL.tools.imageop.ImageOpObserver)
• ImageOp.getFutureTile(java.awt.Point, VASSAL.tools.imageop.ImageOpObserver)
• ImageOp.getImage()

getSizeFromCache

protected Dimension getSizeFromCache()

A utility method for retrieving the size of the computed Image from the cache if the Image is cached.

Returns:

the size of the cached Image, or null if the Image isn't cached

fixSize

protected abstract void fixSize()

Sets the size which is used by getSize(), getHeight(), and getWidth().

getSize

public Dimension getSize()

Returns the size of the BufferedImage which would be returned by ImageOp.getImage(). The size is cached so that it need not be recalculated on each call.

Specified by:

getSize in interface ImageOp

Returns:

the size of the resulting BufferedImage in pixels

See Also:

• ImageOp.getHeight()
• ImageOp.getWidth()

getWidth

public int getWidth()

Returns the width of the BufferedImage which would be returned by ImageOp.getImage(). The width is cached so that it need not be recalculated on each call.

Specified by:

getWidth in interface ImageOp

Returns:

the width of the resulting BufferedImage in pixels

See Also:

• ImageOp.getHeight()
• ImageOp.getSize()

getHeight

public int getHeight()

Returns the height of the BufferedImage which would be returned by ImageOp.getImage(). The height is cached so that it need not be recalculated on each call.

Specified by:

getHeight in interface ImageOp

Returns:

the height of the resulting BufferedImage in pixels

See Also:

• ImageOp.getWidth()
• ImageOp.getSize()

getTileSize

public abstract Dimension getTileSize()

Returns the standard size of the BufferedImage tiles which are returned by ImageOp.getTile(java.awt.Point, VASSAL.tools.imageop.ImageOpObserver). Tiles which are in the extreme right column will not have full width if the BufferedImage width is not an integral multiple of the tile width. Similarly, tiles in the bottom row will not have full height if the BufferedImage height is not an integral multiple of the tile height.

Specified by:

getTileSize in interface ImageOp

Returns:

the size of BufferedImage tiles in pixels

See Also:

• ImageOp.getTileHeight()
• ImageOp.getTileWidth()

getTileHeight

public abstract int getTileHeight()

Returns the standard height of the BufferedImage tiles which are returned by ImageOp.getTile(java.awt.Point, VASSAL.tools.imageop.ImageOpObserver).

Specified by:

getTileHeight in interface ImageOp

Returns:

the height of BufferedImage tiles in pixels

See Also:

• ImageOp.getTileSize()
• ImageOp.getTileWidth()

getTileWidth

public abstract int getTileWidth()

Returns the standard width of the BufferedImage tiles which are returned by ImageOp.getTile(java.awt.Point, VASSAL.tools.imageop.ImageOpObserver).

Specified by:

getTileWidth in interface ImageOp

Returns:

the width of BufferedImage tiles in pixels

See Also:

• ImageOp.getTileSize()
• ImageOp.getTileHeight()

getNumXTiles

public abstract int getNumXTiles()

Returns the number of tiles along the x-axis. There will always be at least one column of tiles. The number of columns should equal (int) Math.ceil((double) getWidth() / getTileWidth()).

Specified by:

getNumXTiles in interface ImageOp

Returns:

the number of tiles along the x-axis

getNumYTiles

public abstract int getNumYTiles()

Returns the number of tiles along the y-axis. There will always be at least one row of tiles. The number of rows should equal (int) Math.ceil((double) getHeight() / getTileHeight()).

Specified by:

getNumYTiles in interface ImageOp

Returns:

the number of tiles along the y-axis

getTile

public BufferedImage getTile(Point p,
 ImageOpObserver obs)
                      throws CancellationException,
InterruptedException,
ExecutionException

Calculates tile (p.x,p.y), and reports completion or failure to the specified ImageOpObserver. If a non-null observer is given, then the operation may be done asynchronously. If the observer is null, then this method will block on completion of the operation. Tiles are numbered from zero, so the tile in the upper-left corner of the main BufferedImage is (0,0). Note that p.x and p.y are indices into the tile array, not pixel locations.

This convenience method is equivalent to getTile(p.x, p.y, obs).

Warning: BufferedImages returned by this method must not be modified.

Specified by:

getTile in interface ImageOp

Parameters:

p - the position of the requested tile

obs - the observer

Returns:

the resulting BufferedImage

Throws:

CancellationException - if the operation was cancelled

InterruptedException - if the operation was interrupted

ExecutionException - if the operation failed

getTile

public abstract BufferedImage getTile(int tileX,
 int tileY,
 ImageOpObserver obs)
                               throws CancellationException,
InterruptedException,
ExecutionException

Calculates tile (tileX,tileY), and reports completion or failure to the specified ImageOpObserver. If a non-null observer is given, then the operation may be done asynchronously. If the observer is null, then this method will block on completion of the operation. Tiles are numbered from zero, so the tile in the upper-left corner of the main BufferedImage is (0,0). Note that tileX and tileY are indices into the tile array, not pixel locations.

Warning: BufferedImages returned by this method must not be modified.

Specified by:

getTile in interface ImageOp

Parameters:

tileX - the x position of the requested tile

tileY - the y position of the requested tile

obs - the observer to be notified on completion

Returns:

the resulting BufferedImage

Throws:

CancellationException - if the operation was cancelled

InterruptedException - if the operation was interrupted

ExecutionException - if the operation failed

getFutureTile

public Future<BufferedImage> getFutureTile(Point p,
 ImageOpObserver obs)
                                    throws ExecutionException

Submits a request for tile (tileX,tileY), and returns a reference to that request. If a non-null observer is given, then the operation may be done asynchronously. If the observer is null, then this method will block on completion of the operation. Tiles are numbered from zero, so the tile in the upper-left corner of the main BufferedImage is (0,0). Note that tileX and tileY are indices into the tile array, not pixel locations.

This convenience method is equivalent to getFutureTile(p.x, p.y, obs).

Warning: BufferedImages obtained from the Futures returned by this method must not be modified.

Specified by:

getFutureTile in interface ImageOp

Parameters:

p - the position of the requested tile

obs - the observer to be notified on completion

Returns:

a Future for the resulting BufferedImage

Throws:

ExecutionException - if the operation failed

getFutureTile

public abstract Future<BufferedImage> getFutureTile(int tileX,
 int tileY,
 ImageOpObserver obs)
                                             throws ExecutionException

Submits a request for tile (tileX,tileY), and returns a reference to that request. If a non-null observer is given, then the operation may be done asynchronously. If the observer is null, then this method will block on completion of the operation. Tiles are numbered from zero, so the tile in the upper-left corner of the main BufferedImage is (0,0). Note that tileX and tileY are indices into the tile array, not pixel locations.

Warning: BufferedImages obtained from the Futures returned by this method must not be modified.

Specified by:

getFutureTile in interface ImageOp

Parameters:

tileX - the x position of the requested tile

tileY - the y position of the requested tile

obs - the observer to be notified on completion

Returns:

a Future for the resulting BufferedImage

Throws:

ExecutionException - if the operation failed

getTileOp

public ImageOp getTileOp(Point p)

Returns an ImageOp which can produce the requested tile.

This convenience method is equivalent to getTileOp(p.x, p.y).

Specified by:

getTileOp in interface ImageOp

Parameters:

p - the position of the requested tile

Returns:

the ImageOp which produces the requested tile

getTileOp

public abstract ImageOp getTileOp(int tileX,
 int tileY)

Returns an ImageOp which can produce the requested tile.

Specified by:

getTileOp in interface ImageOp

Parameters:

tileX - the x position of the requested tile

tileY - the y position of the requested tile

Returns:

the ImageOp which produces the requested tile

getTileIndices

public abstract Point[] getTileIndices(Rectangle rect)

Returns an array of Points representing the tiles intersecting the given Rectangle.

Specified by:

getTileIndices in interface ImageOp

Parameters:

rect - the rectangle

Returns:

the positions of the tiles hit by the rectangle