Package VASSAL.tools.imageop

Interface ImageOp

All Superinterfaces:

Op<BufferedImage>

All Known Subinterfaces:

CropOp, GamePieceOp, RotateOp, RotateScaleOp, ScaleOp, SourceOp, SVGOp

All Known Implementing Classes:

AbstractOpImpl, AbstractTiledOpImpl, AbstractTileOpImpl, CropOpBitmapImpl, FixedScaleOpBitmapImpl, FixedScaleOpTiledBitmapImpl, GamePieceOpImpl, GridOp, ImageItem.BaseOp, ImageSourceOpBitmapImpl, Labeler.HTMLLabelOp, Labeler.LabelOp, OrthoRotateOpBitmapImpl, RotateScaleOpBitmapImpl, RotateScaleOpSVGImpl, ScaleOpBitmapImpl, ScaleOpTiledBitmapImpl, SolidColorOp, SourceOpBitmapImpl, SourceOpDiskCacheBitmapImpl, SourceOpSVGImpl, SourceOpTiledBitmapImpl, SourceTileOpBitmapImpl, SourceTileOpSVGImpl

public interface ImageOp
extends Op<BufferedImage>

An abstract representation of an operation which may be applied to an {link Image}. ImageOp is the interface 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, no images retrieved from an ImageOp are returned defensively. 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

Method Summary

Modifier and Type	Method	Description
BufferedImage	eval()	The image computation itself happens in this method.
Future<BufferedImage>	getFutureImage(ImageOpObserver obs)	Submits a request for the BufferedImage produced by this operation, and returns a reference to that request.
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 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.
int	getNumXTiles()	Returns the number of tiles along the x-axis.
int	getNumYTiles()	Returns the number of tiles along the y-axis.
Dimension	getSize()	Returns the size of the BufferedImage which would be returned by getImage().
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.
int	getTileHeight()	Returns the standard height of the BufferedImage tiles which are returned by getTile(java.awt.Point, VASSAL.tools.imageop.ImageOpObserver).
Point[]	getTileIndices(Rectangle rect)	Returns an array of Points representing the tiles intersecting the given Rectangle.
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.
Dimension	getTileSize()	Returns the standard size of the BufferedImage tiles which are returned by getTile(java.awt.Point, VASSAL.tools.imageop.ImageOpObserver).
int	getTileWidth()	Returns the standard width of the BufferedImage tiles which are returned by getTile(java.awt.Point, VASSAL.tools.imageop.ImageOpObserver).
int	getWidth()	Returns the width of the BufferedImage which would be returned by getImage().

Methods inherited from interface VASSAL.tools.opcache.Op

getSources, newKey, update

Method Details

eval

BufferedImage eval()
            throws Exception

The image computation itself happens in this method.

Warning: This method is not intended to be called from anywhere except getImage().

Specified by:

eval in interface Op<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

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.

Returns:

the resulting BufferedImage

getImage

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.

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:

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

getFutureImage

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.

Parameters:

obs - the observer to be notified on completion

Returns:

a Future for the resulting BufferedImage

Throws:

ExecutionException - if the operation failed

See Also:

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

getSize

Dimension getSize()

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

Returns:

the size of the resulting BufferedImage in pixels

See Also:

• getHeight()
• getWidth()

getWidth

int getWidth()

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

Returns:

the width of the resulting BufferedImage in pixels

See Also:

• getHeight()
• getSize()

getHeight

int getHeight()

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

Returns:

the height of the resulting BufferedImage in pixels

See Also:

• getWidth()
• getSize()

getTileSize

Dimension getTileSize()

Returns the standard size of the BufferedImage tiles which are returned by 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.

Returns:

the size of BufferedImage tiles in pixels

See Also:

• getTileHeight()
• getTileWidth()

getTileHeight

int getTileHeight()

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

Returns:

the height of BufferedImage tiles in pixels

See Also:

• getTileSize()
• getTileWidth()

getTileWidth

int getTileWidth()

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

Returns:

the width of BufferedImage tiles in pixels

See Also:

• getTileSize()
• getTileHeight()

getNumXTiles

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()).

Returns:

the number of tiles along the x-axis

getNumYTiles

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()).

Returns:

the number of tiles along the y-axis

getTile

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.

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

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.

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

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.

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

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.

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

ImageOp getTileOp(Point p)

Returns an ImageOp which can produce the requested tile.

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

Parameters:

p - the position of the requested tile

Returns:

the ImageOp which produces the requested tile

getTileOp

ImageOp getTileOp(int tileX,
 int tileY)

Returns an ImageOp which can produce the requested tile.

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

Point[] getTileIndices(Rectangle rect)

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

Parameters:

rect - the rectangle

Returns:

the positions of the tiles hit by the rectangle

Throws:

IllegalArgumentException - if rect == null.