WritableRenderedImage


1   /*
2    * @(#)WritableRenderedImage.java   1.18 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   /* ****************************************************************
9    ******************************************************************
10   ******************************************************************
11   *** COPYRIGHT (c) Eastman Kodak Company, 1997
12   *** As  an unpublished  work pursuant to Title 17 of the United
13   *** States Code.  All rights reserved.
14   ******************************************************************
15   ******************************************************************
16   ******************************************************************/
17  
18  package java.awt.image;
19  import java.awt.Point  ;
20  
21  /**
22   * WriteableRenderedImage is a common interface for objects which 
23   * contain or can produce image data in the form of Rasters and
24   * which can be modified and/or written over.  The image
25   * data may be stored/produced as a single tile or a regular array
26   * of tiles.
27   * <p>
28   * WritableRenderedImage provides notification to other interested
29   * objects when a tile is checked out for writing (via the
30   * getWritableTile method) and when the last writer of a particular
31   * tile relinquishes its access (via a call to releaseWritableTile).
32   * Additionally, it allows any caller to determine whether any tiles
33   * are currently checked out (via hasTileWriters), and to obtain a
34   * list of such tiles (via getWritableTileIndices, in the form of a Vector
35   * of Point objects).
36   * <p>
37   * Objects wishing to be notified of changes in tile writability must
38   * implement the TileObserver interface, and are added by a
39   * call to addTileObserver.  Multiple calls to
40   * addTileObserver for the same object will result in multiple
41   * notifications.  An existing observer may reduce its notifications
42   * by calling removeTileObserver; if the observer had no
43   * notifications the operation is a no-op.
44   * <p>
45   * It is necessary for a WritableRenderedImage to ensure that
46   * notifications occur only when the first writer acquires a tile and
47   * the last writer releases it.
48   *
49   */
50  
51  public interface WritableRenderedImage extends RenderedImage  
52  {
53  
54    /**
55     * Adds an observer.  If the observer is already present,
56     * it will receive multiple notifications.
57     * @param to the specified <code>TileObserver</code>
58     */
59    public void addTileObserver(TileObserver   to);
60   
61    /**
62     * Removes an observer.  If the observer was not registered,
63     * nothing happens.  If the observer was registered for multiple
64     * notifications, it will now be registered for one fewer.
65     * @param to the specified <code>TileObserver</code>
66     */
67    public void removeTileObserver(TileObserver   to);
68   
69    /**
70     * Checks out a tile for writing.  
71     * 
72     * The WritableRenderedImage is responsible for notifying all
73     * of its TileObservers when a tile goes from having
74     * no writers to having one writer.
75     *
76     * @param tileX the X index of the tile.
77     * @param tileY the Y index of the tile.
78     * @return a writable tile.
79     */
80    public WritableRaster   getWritableTile(int tileX, int tileY);
81  
82    /**
83     * Relinquishes the right to write to a tile.  If the caller 
84     * continues to write to the tile, the results are undefined.
85     * Calls to this method should only appear in matching pairs
86     * with calls to getWritableTile; any other use will lead
87     * to undefined results.
88     *
89     * The WritableRenderedImage is responsible for notifying all of
90     * its TileObservers when a tile goes from having one writer
91     * to having no writers.
92     *
93     * @param tileX the X index of the tile.
94     * @param tileY the Y index of the tile.
95     */
96    public void releaseWritableTile(int tileX, int tileY);
97  
98    /**
99     * Returns whether a tile is currently checked out for writing.
100    *
101    * @param tileX the X index of the tile.
102    * @param tileY the Y index of the tile.
103    * @return <code>true</code> if specified tile is checked out 
104    *         for writing; <code>false</code> otherwise.
105    */
106   public boolean isTileWritable(int tileX, int tileY);
107 
108   /**
109    * Returns an array of Point objects indicating which tiles
110    * are checked out for writing.  Returns null if none are
111    * checked out.
112    * @return an array containing the locations of tiles that are
113    *         checked out for writing.
114    */
115   public Point  [] getWritableTileIndices();
116 
117   /**
118    * Returns whether any tile is checked out for writing.
119    * Semantically equivalent to (getWritableTileIndices() != null).
120    * @return <code>true</code> if any tiles are checked out for 
121    *         writing; <code>false</code> otherwise.
122    */
123   public boolean hasTileWriters();
124 
125   /**
126    * Sets a rect of the image to the contents of the Raster r, which is
127    * assumed to be in the same coordinate space as the WritableRenderedImage.
128    * The operation is clipped to the bounds of the WritableRenderedImage.
129    * @param r the specified <code>Raster</code>
130    */
131   public void setData(Raster   r);
132 
133 }
134
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags