/*
 * $RCSfile: SnapshotImage.java,v $
 *
 * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * $Revision: 1.2 $
 * $Date: 2005/05/12 18:24:34 $
 * $State: Exp $
 */
package javax.media.jai;
import java.awt.Point;
import java.awt.image.Raster;
import java.awt.image.TileObserver;
import java.awt.image.WritableRaster;
import java.awt.image.WritableRenderedImage;
import java.util.Enumeration;
import java.util.HashSet;
import java.util.Hashtable;
import java.util.Iterator;

/**
 * A (Raster, X, Y) tuple.
 */
final class TileCopy {

    /** The tile's <code>Raster</code> data. */
    Raster tile;

    /** The tile's column within the image tile grid. */
    int tileX;

    /** The tile's row within the image tile grid. */
    int tileY;

    /**
     * Constructs a TileCopy object given the tile's <code>Raster</code> data
     * and its location in the tile grid.
     *
     * @param tile the <code>Raster</code> containing the tile's data.
     * @param tileX the tile's X position in the tile grid.
     * @param tileY the tile's X position in the tile grid.
     */
    TileCopy(Raster tile, int tileX, int tileY) {
        this.tile = tile;
        this.tileX = tileX;
        this.tileY = tileY;
    }
}


/**
 * A proxy for <code>Snapshot</code> that calls
 * <code>Snapshot.dispose()</code> when finalized.
 * No references to a SnapshotProxy are held internally, only user
 * references.  Thus it will be garbage collected when the last user
 * reference is relinquished.  The <code>Snapshot</code>'s
 * <code>dispose()</code> method
 * is called from <code>SnapshotProxy.finalize()</code>, ensuring that all
 * of the resources held by the <code>Snapshot</code> will become collectable.
 */
final class SnapshotProxy extends PlanarImage {
    /**
     * The parent <code>Snapshot</code> to which we forward
     * <code>getTile()</code> calls.
     */
    Snapshot parent;

    /**
     * Construct a new proxy for a given <code>Snapshot</code>.
     *
     * @param parent the <code>Snapshot</code> to which method calls will
     * be forwarded.
     */
    SnapshotProxy(Snapshot parent) {
        super(new ImageLayout(parent), null, null);
        this.parent = parent;
    }

    /**
     * Forwards a tile request to the parent <code>Snapshot</code>.
     *
     * @param tileX the X index of the tile.
     * @param tileY the Y index of the tile.
     * @return the tile as a <code>Raster</code>.
     */
    public Raster getTile(int tileX, int tileY) {
        return parent.getTile(tileX, tileY);
    }

    /** Disposes of resources held by this proxy. */
    public void dispose() {
        parent.dispose();
    }
}

/**
 * A non-public class that holds a portion of the state associated
 * with a <code>SnapShotImage</code>.  A <code>Snapshot</code> provides the
 * appearance of a <code>PlanarImage</code> with fixed contents.  In order to
 * provide this illusion, however, the <code>Snapshot</code> relies on the
 * fact that it belongs to a linked list of <code>Snapshot</code>s rooted in a
 * particular <code>SnapShotImage</code>; it cannot function independently.
 *
 */
final class Snapshot extends PlanarImage {

    /** The creator of this image. */
    SnapshotImage parent;

    /** The next <code>Snapshot</code> in a doubly-linked list. */
    Snapshot next;

    /** The previous <code>Snapshot</code> in a doubly-linked list. */
    Snapshot prev;

    /** A set of cached TileCopy elements. */
    Hashtable tiles = new Hashtable();

    /** True if <code>dispose()</code> has been called. */
    boolean disposed = false;

    /**
     * Constructs a <code>Snapshot</code> that will provide a synchronous
     * view of a <code>SnapshotImage</code> at a particular moment in time.
     *
     * @param parent a <code>SnapshotImage</code> this image will be viewing.
     */
    Snapshot(SnapshotImage parent) {
        super(new ImageLayout(parent), null, null);
        this.parent = parent;
    }

    /**
     * Returns the version of a tile "seen" by this <code>Snapshot</code>.
     * The tile "seen" is the oldest copy of the tile made after
     * the creation of this <code>Snapshot</code>; it may be held in the
     * tiles <code>Hashtable</code> of this <code>Snapshot</code> or one of
     * its successors.  If no later <code>Snapshot</code> holds a copy of
     * the tile, the current version of the tile from the source image is
     * returned.
     *
     * <p> <code>getTile()</code> is synchronized in order to prevent calls to
     * <code>dispose()</code>, which will cause the list of
     * <code>Snapshot</code>s to change, from occurring at the same time as
     * the walking of the list.
     *
     * @param tileX the X index of the tile.
     * @param tileY the Y index of the tile.
     * @return the tile as a <code>Raster</code>.
     */
    public Raster getTile(int tileX, int tileY) {
        // Make sure dispose() and getTile() are mutually exclusive
        synchronized(parent) {
            // Check local set of tile copies, if not there move
            // forward to the next <code>Snapshot</code>, if last image
            // get the tile from the real source image.

            TileCopy tc = (TileCopy)tiles.get(new Point(tileX, tileY));
            if (tc != null) {
                return tc.tile;
            } else if (next != null) {
                return next.getTile(tileX, tileY);
            } else {
                return parent.getTrueSource().getTile(tileX, tileY);
            }
        }
    }

    /**
     * Sets the next <code>Snapshot</code> in the list to a given
     * <code>Snapshot</code>.
     *
     * @param next the next <code>Snapshot</code> in the list.
     */
    void setNext(Snapshot next) {
        this.next = next;
    }

    /**
     * Sets the previous <code>Snapshot</code> in the list to a given
     * <code>Snapshot</code>.
     *
     * @param prev the previous <code>Snapshot</code> in the list.
     */
    void setPrev(Snapshot prev) {
        this.prev = prev;
    }

    /**
     * Returns true if this <code>Snapshot</code> already stores a version
     * of a specified tile.
     *
     * @param tileX the X index of the tile.
     * @param tileY the Y index of the tile.
     * @return true if this <code>Snapshot</code> holds a copy of the tile.
     */
    boolean hasTile(int tileX, int tileY) {
        TileCopy tc = (TileCopy)tiles.get(new Point(tileX, tileY));
        return tc != null;
    }

    /**
     * Stores a given tile in this <code>Snapshot</code>.  The caller should
     * not attempt to store more than one version of a given tile.
     *
     * @param tile a <code>Raster</code> containing the tile data.
     * @param tileX the tile's column within the image tile grid.
     * @param tileY the tile's row within the image tile grid.
     */
    void addTile(Raster tile, int tileX, int tileY) {
        TileCopy tc = new TileCopy(tile, tileX, tileY);
        tiles.put(new Point(tileX, tileY), tc);
    }

    /** This image will no longer be referenced by the user. */
    public void dispose() {
        // Make sure dispose() and getTile() are mutually exclusive
        synchronized(parent) {
            // Make it idempotent
            if (disposed) {
                return;
            }
            disposed = true;

            // If this is the last Snapshot, inform the parent
            if (parent.getTail() == this) {
                parent.setTail(prev);
            }

            // Remove 'this' from the chain
            if (prev != null) {
                prev.setNext(next);
            }
            if (next != null) {
                next.setPrev(prev);
            }

            // If there is a previous node, push tiles back to it
            if (prev != null) {
                // Push tiles back to the previous Snapshot
                Enumeration enumeration = tiles.elements();
                while (enumeration.hasMoreElements()) {
                    TileCopy tc = (TileCopy)enumeration.nextElement();
                    if (!prev.hasTile(tc.tileX, tc.tileY)) {
                        prev.addTile(tc.tile, tc.tileX, tc.tileY);
                    }
                }
            }

            // Null out links to help the GC
            parent = null;
            next = prev = null;
            tiles = null;
        }
    }
}

/**
 * A class providing an arbitrary number of synchronous views of a
 * possibly changing <code>WritableRenderedImage</code>.
 * <code>SnapshotImage</code> is responsible for stabilizing changing sources
 * in order to allow deferred execution of operations dependent on such
 * sources.
 *
 * <p> Any <code>RenderedImage</code> may be used as the source of a
 * <code>SnapshotImage</code>; if it is a <code>WritableRenderedImage</code>,
 * the <code>SnapshotImage</code> will register itself as a
 * <code>TileObserver</code> and make copies of tiles that are about to change.
 * Multiple versions of each tile are maintained internally, as long as they
 * are in demand.  <code>SnapshotImage</code> is able to track demand and
 * should be able to simply forward requests for tiles to the source most
 * of the time, without the need to make a copy.
 *
 * <p> When used as a source, calls to getTile will simply be passed
 * along to the source.  In other words, <code>SnapshotImage</code> is
 * completely transparent.  However, by calling <code>createSnapshot()</code>
 * an instance of a non-public <code>PlanarImage</code> subclass (called
 * <code>Snapshot</code> in this implementation) will be created and returned.
 * This image will always return tile data with contents as of the time of its
 * construction.
 *
 * <p> When a particular <code>Snapshot</code> is no longer needed, its
 * <code>dispose()</code> method may be called.    The <code>dispose()</code>
 * method will be called automatically when the <code>Snapshot</code> is
 * finalized by the garbage collector.  Disposing of the <code>Snapshot</code>
 * allows tile data held by the <code>Snapshot</code> that is not needed by
 * any other <code>Snapshot</code> to be disposed of as well.
 *
 * <p> This implementation of <code>SnapshotImage</code> makes use of a
 * doubly-linked list of <code>Snapshot</code> objects.  A new
 * <code>Snapshot</code> is added to the tail of the list whenever
 * <code>createSnapshot()</code> is called.  Each <code>Snapshot</code>
 * has a cache containing copies of any tiles that were writable at the
 * time of its construction, as well as any tiles that become writable
 * between the time of its construction and the construction of the next
 * <code>Snapshot</code>.
 *
 * <p> When asked for a tile, a <code>Snapshot</code> checks its local cache
 * and returns its version of the tile if one is found.  Otherwise, it
 * forwards the request onto its successor.  This process continues
 * until the latest <code>Snapshot</code> is reached; if it does not contain
 * a copy of the tile, the tile is requested from the real source image.
 *
 * <p> When a <code>Snapshot</code> is no longer needed, its
 * <code>dispose()</code> method attempts to push the contents of its tile
 * cache back to the previous <code>Snapshot</code> in the linked list.  If
 * that image possesses a version of the same tile, the tile is not pushed
 * back and may be discarded.
 *
 * @see java.awt.image.RenderedImage
 * @see java.awt.image.TileObserver
 * @see java.awt.image.WritableRenderedImage
 * @see PlanarImage
 *
 */
public class SnapshotImage extends PlanarImage implements TileObserver {

    /** The real image source. */
    private PlanarImage source;

    /** The last entry in the list of <code>Snapshot</code>, initially null. */
    private Snapshot tail = null;

    /** The set of active tiles, represented as a HashSet of Points. */
    private HashSet activeTiles = new HashSet();

    /**
     * Constructs a <code>SnapshotImage</code> from a <code>PlanarImage</code>
     * source.
     *
     * @param source a <code>PlanarImage</code> source.
     * @throws IllegalArgumentException if source is null.
     */
    public SnapshotImage(PlanarImage source) {
        super(new ImageLayout(source), null, null);

        // Record the source image
        this.source = source;
        //  Set image parameters to match the source

        //  Determine which tiles of the source image are writable
        if (source instanceof WritableRenderedImage) {
            WritableRenderedImage wri = (WritableRenderedImage)source;
            wri.addTileObserver(this);

            Point[] pts = wri.getWritableTileIndices();
            if (pts != null) {
                int num = pts.length;
                for (int i = 0; i < num; i++) {
                    //  Add these tiles to the active list
                    Point p = pts[i];
                    activeTiles.add(new Point(p.x, p.y));
               }
            }
        }
    }

    /**
     * Returns the <code>PlanarImage</code> source of this
     * <code>SnapshotImage</code>.
     *
     * @return a <code>PlanarImage</code> that is the source of data for this
     * image.
     */
    protected PlanarImage getTrueSource() {
        return source;
    }

    /**
     * Sets the reference to the most current <code>Snapshot</code> to a given
     * <code>Snapshot</code>.
     *
     * @param tail a reference to the new most current <code>Snapshot</code>.
     */
    void setTail(Snapshot tail) {
        this.tail = tail;
    }

    /**
     * Returns a reference to the most current <code>Snapshot</code>.
     *
     * @return the <code>Snapshot</code> at the tail end of the list.
     */
    Snapshot getTail() {
        return tail;
    }

    /**
     * Creates and returns a <code>Raster</code> copy of a given source tile.
     *
     * @param tileX the X index of the tile.
     * @param tileY the Y index of the tile.
     * @return a newly-constructed <code>Raster</code> containing a copy
     *         of the tile data.
     */
    private Raster createTileCopy(int tileX, int tileY) {
        int x = tileXToX(tileX);
        int y = tileYToY(tileY);
        Point p = new Point(x, y);

        WritableRaster tile =
            RasterFactory.createWritableRaster(sampleModel, p);
        source.copyData(tile);
        return tile;
    }

    /**
     * Creates a snapshot of this image.  This snapshot may be used
     * indefinitely, and will always appear to have the pixel data that
     * this image has currently.  The snapshot is semantically a copy
     * of this image but may be implemented in a more efficient manner.
     * Multiple snapshots taken at different times may share tiles that
     * have not changed, and tiles that are currently static in this
     * image's source do not need to be copied at all.
     *
     * @return a <code>PlanarImage</code> snapshot.
     */
    public PlanarImage createSnapshot() {
        if (source instanceof WritableRenderedImage) {
            // Create a new Snapshot
            Snapshot snap = new Snapshot(this);

            // For each active tile:
            Iterator iter = activeTiles.iterator();
            while (iter.hasNext()) {
                Point p = (Point)iter.next();

                // Make a copy and store it in the Snapshot
                Raster tile = createTileCopy(p.x, p.y);
                snap.addTile(tile, p.x, p.y);
            }

            // Add the new Snapshot to the list of snapshots
            if (tail == null) {
                tail = snap;
            } else {
                tail.setNext(snap);
                snap.setPrev(tail);
                tail = snap;
            }

            // Create a proxy and return it
            return new SnapshotProxy(snap);
        } else {
            return source;
        }
    }

    /**
     * Receives the information that a tile is either about to become
     * writable, or is about to become no longer writable.
     *
     * @param source the <code>WritableRenderedImage</code> for which we
     *               are an observer.
     * @param tileX the X index of the tile.
     * @param tileY the Y index of the tile.
     * @param willBeWritable true if the tile is becoming writable.
     */
    public void tileUpdate(WritableRenderedImage source,
                           int tileX, int tileY,
                           boolean willBeWritable) {
        if (willBeWritable) {
            // If the last Snapshot doesn't have the tile, copy it
            if ((tail != null) && (!tail.hasTile(tileX, tileY))) {
                tail.addTile(createTileCopy(tileX, tileY), tileX, tileY);
            }
            // Add the tile to the active list
            activeTiles.add(new Point(tileX, tileY));
        } else {
            // Remove the tile from the active list
            activeTiles.remove(new Point(tileX, tileY));
        }
    }

    /**
     * Returns a non-snapshotted tile from the source.
     *
     * @param tileX the X index of the tile.
     * @param tileY the Y index of the tile.
     * @return the tile as a <code>Raster</code>.
     */
    public Raster getTile(int tileX, int tileY) {
        //  Return the current source tile (X, Y)
        return source.getTile(tileX, tileY);
    }
}