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, 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 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.