001: /*
002: * $RCSfile: TileCache.java,v $
003: *
004: * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
005: *
006: * Use is subject to license terms.
007: *
008: * $Revision: 1.1 $
009: * $Date: 2005/02/11 04:57:22 $
010: * $State: Exp $
011: */
012: package javax.media.jai;
013:
014: import java.awt.Point;
015: import java.awt.image.Raster;
016: import java.util.Comparator;
017: import java.awt.image.RenderedImage;
018:
019: /**
020: * A class implementing a caching mechanism for image tiles.
021: *
022: * <p> <code>TileCache</code> provides a mechanism by which an
023: * <code>OpImage</code> may cache its computed tiles. There may be
024: * multiple <code>TileCache</code>s used in an application up to the
025: * point of having a different <code>TileCache</code> for each
026: * <code>OpImage</code>.
027: *
028: * <p> The <code>TileCache</code> used for a particular <code>OpImage</code>
029: * is derived from the <code>RenderingHints</code> assigned to the
030: * associated imaging chain node. If the node is constructed using
031: * <code>JAI.create()</code> and no <code>TileCache</code> is specified
032: * in the <code>RenderingHints</code> parameter, then one is derived
033: * from the <code>RenderingHints</code> associated with the instance of the
034: * <code>JAI</code> class being used.
035: *
036: * <p> In the Sun reference implementation, the cache size is limited by
037: * the memory capacity, which is set to a default value at construction
038: * or subsequently using the <code>setMemoryCapacity()</code> method.
039: * The initial value may be obtained using <code>getMemoryCapacity()</code>.
040: * The tile capacity is not used as different images may have very different
041: * tile sizes so that this metric is not a particularly meaningful control
042: * of memory resource consumption in general.
043: *
044: * @see JAI
045: * @see RenderedOp
046: * @see java.awt.RenderingHints
047: */
048: public interface TileCache {
049:
050: /**
051: * Adds a tile to the cache.
052: *
053: * @param owner The <code>RenderedImage</code> that the tile belongs to.
054: * @param tileX The X index of the tile in the owner's tile grid.
055: * @param tileY The Y index of the tile in the owner's tile grid.
056: * @param data A <code>Raster</code> containing the tile data.
057: */
058: void add(RenderedImage owner, int tileX, int tileY, Raster data);
059:
060: /**
061: * Adds a tile to the cache with an associated compute cost
062: *
063: * @param owner The <code>RenderedImage</code> that the tile belongs to.
064: * @param tileX The X index of the tile in the owner's tile grid.
065: * @param tileY The Y index of the tile in the owner's tile grid.
066: * @param data A <code>Raster</code> containing the tile data.
067: * @param tileCacheMetric An <code>Object</code> as a tile metric.
068: *
069: * @since JAI 1.1
070: */
071: void add(RenderedImage owner, int tileX, int tileY, Raster data,
072: Object tileCacheMetric);
073:
074: /**
075: * Advises the cache that a tile is no longer needed. It is legal
076: * to implement this method as a no-op.
077: *
078: * @param owner The <code>RenderedImage</code> that the tile belongs to.
079: * @param tileX The X index of the tile in the owner's tile grid.
080: * @param tileY The Y index of the tile in the owner's tile grid.
081: */
082: void remove(RenderedImage owner, int tileX, int tileY);
083:
084: /**
085: * Retrieves a tile. Returns <code>null</code> if the tile is not
086: * present in the cache.
087: *
088: * @param owner The <code>RenderedImage</code> that the tile belongs to.
089: * @param tileX The X index of the tile in the owner's tile grid.
090: * @param tileY The Y index of the tile in the owner's tile grid.
091: */
092: Raster getTile(RenderedImage owner, int tileX, int tileY);
093:
094: /**
095: * Retrieves an array of all tiles in the cache which are owned by the
096: * specified image.
097: *
098: * @param owner The <code>RenderedImage</code> to which the tiles belong.
099: * @return An array of all tiles owned by the specified image or
100: * <code>null</code> if there are none currently in the cache.
101: *
102: * @since JAI 1.1
103: */
104: Raster[] getTiles(RenderedImage owner);
105:
106: /**
107: * Advises the cache that all tiles associated with a given image
108: * are no longer needed. It is legal to implement this method as
109: * a no-op.
110: *
111: * @param owner The <code>RenderedImage</code> owner of the tiles
112: * to be removed.
113: */
114: void removeTiles(RenderedImage owner);
115:
116: /**
117: * Adds an array of tiles to the tile cache.
118: *
119: * @param owner The <code>RenderedImage</code> that the tile belongs to.
120: * @param tileIndices An array of <code>Point</code>s containing the
121: * <code>tileX</code> and <code>tileY</code> indices for each tile.
122: * @param tiles The array of tile <code>Raster</code>s containing tile data.
123: * @param tileCacheMetric Object which provides an ordering metric
124: * associated with the <code>RenderedImage</code> owner.
125: *
126: * @since JAI 1.1
127: */
128: void addTiles(RenderedImage owner, Point[] tileIndices,
129: Raster[] tiles, Object tileCacheMetric);
130:
131: /**
132: * Returns an array of tile <code>Raster</code>s from the cache.
133: * Any or all of the elements of the returned array may be
134: * <code>null</code> if the corresponding tile is not in the cache.
135: * The length of the returned array must be the same as that of the
136: * parameter array and the <i>i</i>th <code>Raster</code> in the
137: * returned array must correspond to the <i>i</i>th tile index in
138: * the parameter array.
139: *
140: * @param owner The <code>RenderedImage</code> that the tile belongs to.
141: * @param tileIndices An array of <code>Point</code>s containing the
142: * <code>tileX</code> and <code>tileY</code> indices for each tile.
143: *
144: * @since JAI 1.1
145: */
146: Raster[] getTiles(RenderedImage owner, Point[] tileIndices);
147:
148: /**
149: * Advises the cache that all of its tiles may be discarded. It
150: * is legal to implement this method as a no-op.
151: */
152: void flush();
153:
154: /**
155: * Advises the cache that some of its tiles may be discarded. It
156: * is legal to implement this method as a no-op.
157: *
158: * @since JAI 1.1
159: */
160: void memoryControl();
161:
162: /**
163: * Sets the tile capacity to a desired number of tiles.
164: * If the capacity is smaller than the current capacity,
165: * tiles are flushed from the cache. It is legal to
166: * implement this method as a no-op.
167: *
168: * @param tileCapacity The new capacity, in tiles.
169: *
170: * @deprecated as of JAI 1.1.
171: */
172: void setTileCapacity(int tileCapacity);
173:
174: /**
175: * Returns the tile capacity in tiles. It is legal to
176: * implement this method as a no-op which should be
177: * signaled by returning zero.
178: *
179: * @deprecated as of JAI 1.1.
180: */
181: int getTileCapacity();
182:
183: /**
184: * Sets the memory capacity to a desired number of bytes.
185: * If the memory capacity is smaller than the amount of
186: * memory currently used by the cache, tiles are flushed
187: * until the <code>TileCache</code>'s memory usage is less than
188: * <code>memoryCapacity</code>.
189: *
190: * @param memoryCapacity The new capacity, in bytes.
191: */
192: void setMemoryCapacity(long memoryCapacity);
193:
194: /**
195: * Returns the memory capacity in bytes.
196: */
197: long getMemoryCapacity();
198:
199: /**
200: * Sets the <code>memoryThreshold</code> value to a floating
201: * point number that ranges from 0.0 to 1.0.
202: * When the cache memory is full, the memory
203: * usage will be reduced to this fraction of
204: * the total cache memory capacity. For example,
205: * a value of .75 will cause 25% of the memory
206: * to be cleared, while retaining 75%.
207: *
208: * @param memoryThreshold. Retained fraction of memory
209: * @throws IllegalArgumentException if the memoryThreshold
210: * is less than 0.0 or greater than 1.0
211: *
212: * @since JAI 1.1
213: */
214: void setMemoryThreshold(float memoryThreshold);
215:
216: /**
217: * Returns the memory threshold, which is the fractional
218: * amount of cache memory to retain during tile removal.
219: *
220: * @since JAI 1.1
221: */
222: float getMemoryThreshold();
223:
224: /**
225: * Sets a <code>Comparator</code> which imposes an order on the
226: * <code>CachedTile</code>s stored in the <code>TileCache</code>.
227: * This ordering is used in <code>memoryControl()</code> to determine
228: * the sequence in which tiles will be removed from the
229: * <code>TileCache</code> so as to reduce the memory to the level given
230: * by the memory threshold. The <code>Object</code>s passed to the
231: * <code>compare()</code> method of the <code>Comparator</code> will
232: * be instances of <code>CachedTile</code>. <code>CachedTile</code>s
233: * will be removed from the <code>TileCache</code> in the ascending
234: * order imposed by this <code>Comparator</code>. If no
235: * <code>Comparator</code> is currently set, the <code>TileCache</code>
236: * should use an implementation-dependent default ordering. In the
237: * Sun Microsystems, Inc., implementation of <code>TileCache</code>,
238: * this ordering is the <u>l</u>east <u>r</u>ecently <u>u</u>sed
239: * ordering, i.e., the tiles least recently used will be removed first
240: * by <code>memoryControl()</code>.
241: *
242: * @param comparator A <code>Comparator</code> which orders the
243: * <code>CachedTile</code>s stored by the <code>TileCache</code>;
244: * if <code>null</code> an implementation-dependent algorithm
245: * will be used.
246: *
247: * @since JAI 1.1
248: */
249: void setTileComparator(Comparator comparator);
250:
251: /**
252: * Returns the <code>Comparator</code> currently set for use in ordering
253: * the <code>CachedTile</code>s stored by the <code>TileCache</code>.
254: *
255: * @return The tile <code>Comparator</code> or <code>null</code> if the
256: * implementation-dependent ordering algorithm is being used.
257: *
258: * @since JAI 1.1
259: */
260: Comparator getTileComparator();
261: }
|