## javax.media.jai
Interface TileCache

public interface TileCache

A class implementing a caching mechanism for image tiles.

`TileCache` provides a mechanism by which an `OpImage` may cache its computed tiles. There may be multiple `TileCache`s used in an application up to the point of having a different `TileCache` for each `OpImage`.

The `TileCache` used for a particular `OpImage` is derived from the `RenderingHints` assigned to the associated imaging chain node. If the node is constructed using `JAI.create()` and no `TileCache` is specified in the `RenderingHints` parameter, then one is derived from the `RenderingHints` associated with the instance of the `JAI` class being used.

In the Sun reference implementation, the cache size is limited by the memory capacity, which is set to a default value at construction or subsequently using the `setMemoryCapacity()` method. The initial value may be obtained using `getMemoryCapacity()`. The tile capacity is not used as different images may have very different tile sizes so that this metric is not a particularly meaningful control of memory resource consumption in general.

See Also:
  `JAI`, `RenderedOp`, `RenderingHints`

Method Summary
`void` `add(java.awt.image.RenderedImage owner, int tileX, int tileY, java.awt.image.Raster data)` Adds a tile to the cache.
`void` `add(java.awt.image.RenderedImage owner, int tileX, int tileY, java.awt.image.Raster data, java.lang.Object tileCacheMetric)` Adds a tile to the cache with an associated compute cost
`void` `addTiles(java.awt.image.RenderedImage owner, java.awt.Point[] tileIndices, java.awt.image.Raster[] tiles, java.lang.Object tileCacheMetric)` Adds an array of tiles to the tile cache.
`void` `flush()` Advises the cache that all of its tiles may be discarded.
`long` `getMemoryCapacity()` Returns the memory capacity in bytes.
`float` `getMemoryThreshold()` Returns the memory threshold, which is the fractional amount of cache memory to retain during tile removal.
`java.awt.image.Raster` `getTile(java.awt.image.RenderedImage owner, int tileX, int tileY)` Retrieves a tile.
`int` `getTileCapacity()` Deprecated. as of Java(tm) Advanced Imaging 1.1.
`java.util.Comparator` `getTileComparator()` Returns the `Comparator` currently set for use in ordering the `CachedTile`s stored by the `TileCache`.
`java.awt.image.Raster[]` `getTiles(java.awt.image.RenderedImage owner)` Retrieves an array of all tiles in the cache which are owned by the specified image.
`java.awt.image.Raster[]` `getTiles(java.awt.image.RenderedImage owner, java.awt.Point[] tileIndices)` Returns an array of tile `Raster`s from the cache.
`void` `memoryControl()` Advises the cache that some of its tiles may be discarded.
`void` `remove(java.awt.image.RenderedImage owner, int tileX, int tileY)` Advises the cache that a tile is no longer needed.
`void` `removeTiles(java.awt.image.RenderedImage owner)` Advises the cache that all tiles associated with a given image are no longer needed.
`void` `setMemoryCapacity(long memoryCapacity)` Sets the memory capacity to a desired number of bytes.
`void` `setMemoryThreshold(float memoryThreshold)` Sets the `memoryThreshold` value to a floating point number that ranges from 0.0 to 1.0.
`void` `setTileCapacity(int tileCapacity)` Deprecated. as of Java(tm) Advanced Imaging 1.1.
`void` `setTileComparator(java.util.Comparator comparator)` Sets a `Comparator` which imposes an order on the `CachedTile`s stored in the `TileCache`.

Method Detail

### add

    public void add(java.awt.image.RenderedImage owner,
                    int tileX,
                    int tileY,
                    java.awt.image.Raster data)

  Adds a tile to the cache.
  Parameters:
    `owner` - The `RenderedImage` that the tile belongs to.
    `tileX` - The X index of the tile in the owner's tile grid.
    `tileY` - The Y index of the tile in the owner's tile grid.
    `data` - A `Raster` containing the tile data.

### add

    public void add(java.awt.image.RenderedImage owner,
                    int tileX,
                    int tileY,
                    java.awt.image.Raster data,
                    java.lang.Object tileCacheMetric)

  Adds a tile to the cache with an associated compute cost
  Parameters:
    `owner` - The `RenderedImage` that the tile belongs to.
    `tileX` - The X index of the tile in the owner's tile grid.
    `tileY` - The Y index of the tile in the owner's tile grid.
    `data` - A `Raster` containing the tile data.
    `tileCacheMetric` - An `Object` as a tile metric.
  Since:
    1.1

### remove

    public void remove(java.awt.image.RenderedImage owner,
                       int tileX,
                       int tileY)

  Advises the cache that a tile is no longer needed. It is legal to implement this method as a no-op.
  Parameters:
    `owner` - The `RenderedImage` that the tile belongs to.
    `tileX` - The X index of the tile in the owner's tile grid.
    `tileY` - The Y index of the tile in the owner's tile grid.

### getTile

    public java.awt.image.Raster getTile(java.awt.image.RenderedImage owner,
                                         int tileX,
                                         int tileY)

  Retrieves a tile. Returns `null` if the tile is not present in the cache.
  Parameters:
    `owner` - The `RenderedImage` that the tile belongs to.
    `tileX` - The X index of the tile in the owner's tile grid.
    `tileY` - The Y index of the tile in the owner's tile grid.

### getTiles

    public java.awt.image.Raster[] getTiles(java.awt.image.RenderedImage owner)

  Retrieves an array of all tiles in the cache which are owned by the specified image.
  Parameters:
    `owner` - The `RenderedImage` to which the tiles belong.
  Returns:
    An array of all tiles owned by the specified image or `null` if there are none currently in the cache.
  Since:
    1.1

### removeTiles

    public void removeTiles(java.awt.image.RenderedImage owner)

  Advises the cache that all tiles associated with a given image are no longer needed. It is legal to implement this method as a no-op.
  Parameters:
    `owner` - The `RenderedImage` owner of the tiles to be removed.

### addTiles

    public void addTiles(java.awt.image.RenderedImage owner,
                         java.awt.Point[] tileIndices,
                         java.awt.image.Raster[] tiles,
                         java.lang.Object tileCacheMetric)

  Adds an array of tiles to the tile cache.
  Parameters:
    `owner` - The `RenderedImage` that the tile belongs to.
    `tileIndices` - An array of `Point`s containing the `tileX` and `tileY` indices for each tile.
    `tiles` - The array of tile `Raster`s containing tile data.
    `tileCacheMetric` - Object which provides an ordering metric associated with the `RenderedImage` owner.
  Since:
    1.1

### getTiles

    public java.awt.image.Raster[] getTiles(java.awt.image.RenderedImage owner,
                                            java.awt.Point[] tileIndices)

  Returns an array of tile `Raster`s from the cache. Any or all of the elements of the returned array may be `null` if the corresponding tile is not in the cache. The length of the returned array must be the same as that of the parameter array and the ith `Raster` in the returned array must correspond to the ith tile index in the parameter array.
  Parameters:
    `owner` - The `RenderedImage` that the tile belongs to.
    `tileIndices` - An array of `Point`s containing the `tileX` and `tileY` indices for each tile.
  Since:
    1.1

### flush

    public void flush()

  Advises the cache that all of its tiles may be discarded. It is legal to implement this method as a no-op.

### memoryControl

    public void memoryControl()

  Advises the cache that some of its tiles may be discarded. It is legal to implement this method as a no-op.
  Since:
    1.1

### setTileCapacity

    public void setTileCapacity(int tileCapacity)

  Deprecated. as of Java(tm) Advanced Imaging 1.1.

  Sets the tile capacity to a desired number of tiles. If the capacity is smaller than the current capacity, tiles are flushed from the cache. It is legal to implement this method as a no-op.
  Parameters:
    `tileCapacity` - The new capacity, in tiles.

### getTileCapacity

    public int getTileCapacity()

  Deprecated. as of Java(tm) Advanced Imaging 1.1.

  Returns the tile capacity in tiles. It is legal to implement this method as a no-op which should be signaled by returning zero.

### setMemoryCapacity

    public void setMemoryCapacity(long memoryCapacity)

  Sets the memory capacity to a desired number of bytes. If the memory capacity is smaller than the amount of memory currently used by the cache, tiles are flushed until the `TileCache`'s memory usage is less than `memoryCapacity`.
  Parameters:
    `memoryCapacity` - The new capacity, in bytes.

### getMemoryCapacity

    public long getMemoryCapacity()

  Returns the memory capacity in bytes.

### setMemoryThreshold

    public void setMemoryThreshold(float memoryThreshold)

  Sets the `memoryThreshold` value to a floating point number that ranges from 0.0 to 1.0. When the cache memory is full, the memory usage will be reduced to this fraction of the total cache memory capacity. For example, a value of .75 will cause 25% of the memory to be cleared, while retaining 75%.
  Parameters:
    `memoryThreshold.` - Retained fraction of memory
  Throws:
    `java.lang.IllegalArgumentException` - if the memoryThreshold is less than 0.0 or greater than 1.0
  Since:
    1.1

### getMemoryThreshold

    public float getMemoryThreshold()

  Returns the memory threshold, which is the fractional amount of cache memory to retain during tile removal.

### setTileComparator

    public void setTileComparator(java.util.Comparator comparator)

  Sets a `Comparator` which imposes an order on the `CachedTile`s stored in the `TileCache`. This ordering is used in `memoryControl()` to determine the sequence in which tiles will be removed from the `TileCache` so as to reduce the memory to the level given by the memory threshold. The `Object`s passed to the `compare()` method of the `Comparator` will be instances of `CachedTile`. `CachedTile`s will be removed from the `TileCache` in the ascending order imposed by this `Comparator`. If no `Comparator` is currently set, the `TileCache` should use an implementation-dependent default ordering. In the Sun Microsystems, Inc., implementation of `TileCache`, this ordering is the least recently used ordering, i.e., the tiles least recently used will be removed first by `memoryControl()`.
  Parameters:
    `comparator` - A `Comparator` which orders the `CachedTile`s stored by the `TileCache`; if `null` an implementation-dependent algorithm will be used.
  Since:
    1.1

### getTileComparator

    public java.util.Comparator getTileComparator()

  Returns the `Comparator` currently set for use in ordering the `CachedTile`s stored by the `TileCache`.
  Returns:
    The tile `Comparator` or `null` if the implementation-dependent ordering algorithm is being used.
  Since:
    1.1