001: /*
002: * $RCSfile: TileComputationListener.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.EventListener;
017:
018: /**
019: * Interface to monitor tiles which have been submitted to the
020: * <code>TileScheduler</code> for non-prefetch background processing.
021: * The request parameter of each method corresponds to the value
022: * returned by the method used to queue the tiles, i.e.,
023: * <code>TileScheduler.scheduleTiles()</code> or more commonly
024: * <code>PlanarImage.queueTiles()</code>. The <code>eventSource</code>
025: * parameter provides the identity of the emitter of the event. If the
026: * event is emitted by the <code>TileScheduler</code> itself this will
027: * be a reference to the <code>TileScheduler</code> object; if it is
028: * emitted by a <code>RenderedOp</code> this will be the
029: * <code>RenderedOp</code> node. The <code>image</code> parameter will
030: * in all cases be the image actually specified to the
031: * <code>TileScheduler</code>.
032: *
033: * <p> With respect to standard rendered imaging chains consisting of
034: * <code>RenderedOp</code> nodes, any <code>TileComputationListener</code>s
035: * registered with the <code>RenderedOp</code> itself will receive events
036: * from the <code>RenderedOp</code> so that the event source will be the
037: * <code>RenderedOp</code>. If the listener is registered with the
038: * rendering of the node, then the event source will likely be the
039: * <code>TileScheduler</code> itself. This is definitely the case if
040: * the rendering is either an <code>OpImage</code> or is a
041: * <code>PlanarImage</code> which has not overridden <code>queueTiles()</code>.
042: *
043: * <p> The <code>image</code> parameter passed to any registered listener of
044: * a <code>RenderedOp</code> will contain a reference to the rendering of the
045: * node rather than to the node itself.
046: *
047: * <p> For a given <code>TileComputationListener</code> exactly one of the
048: * tile status callbacks should be invoked during the life cycle of a given
049: * tile in the <code>TileScheduler</code>.
050: *
051: * @see TileScheduler
052: * @see TileRequest
053: * @see RenderedOp
054: * @see OpImage
055: *
056: * @since JAI 1.1
057: */
058: public interface TileComputationListener extends EventListener {
059:
060: /**
061: * To be invoked after each tile is computed.
062: *
063: * @param eventSource The actual emitter of the tile scheduling event, i.e.,
064: * the caller of this method.
065: * @param requests The relevant tile computation requests as returned
066: * by the method used to queue the tile.
067: * @param image The image for which tiles are being computed as
068: * specified to the <code>TileScheduler</code>.
069: * @param tileX The X index of the tile in the tile array.
070: * @param tileY The Y index of the tile in the tile array.
071: * @param tile The computed tile.
072: */
073: void tileComputed(Object eventSource, TileRequest[] requests,
074: PlanarImage image, int tileX, int tileY, Raster tile);
075:
076: /**
077: * To be invoked after a tile is cancelled.
078: *
079: * @param eventSource The actual emitter of the tile scheduling event, i.e.,
080: * the caller of this method.
081: * @param requests The relevant tile computation requests as returned
082: * by the method used to queue the tile.
083: * @param image The image for which tiles are being computed as
084: * specified to the <code>TileScheduler</code>.
085: * @param tileX The X index of the tile in the tile array.
086: * @param tileY The Y index of the tile in the tile array.
087: */
088: void tileCancelled(Object eventSource, TileRequest[] requests,
089: PlanarImage image, int tileX, int tileY);
090:
091: /**
092: * To be invoked when an exceptional situation prevents computation of
093: * a tile.
094: *
095: * @param eventSource The actual emitter of the tile scheduling event, i.e.,
096: * the caller of this method.
097: * @param requests The relevant tile computation requests as returned
098: * by the method used to queue the tile.
099: * @param image The image for which tiles are being computed as
100: * specified to the <code>TileScheduler</code>.
101: * @param tileX The X index of the tile in the tile array.
102: * @param tileY The Y index of the tile in the tile array.
103: * @param situation An object describing the error or exception which
104: * prevented computation of the tile.
105: */
106: void tileComputationFailure(Object eventSource,
107: TileRequest[] requests, PlanarImage image, int tileX,
108: int tileY, Throwable situation);
109: }
|