1 /*

     2  * Portions Copyright 1997-2000 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 

    26 /* ****************************************************************

    27  ******************************************************************

    28  ******************************************************************

    29  *** COPYRIGHT (c) Eastman Kodak Company, 1997

    30  *** As  an unpublished  work pursuant to Title 17 of the United

    31  *** States Code.  All rights reserved.

    32  ******************************************************************

    33  ******************************************************************

    34  ******************************************************************/

    35 

    36 package java.awt.image;

    37 import java.awt.Point;

    38 

    39 /**

    40  * WriteableRenderedImage is a common interface for objects which

    41  * contain or can produce image data in the form of Rasters and

    42  * which can be modified and/or written over.  The image

    43  * data may be stored/produced as a single tile or a regular array

    44  * of tiles.

    45  * <p>

    46  * WritableRenderedImage provides notification to other interested

    47  * objects when a tile is checked out for writing (via the

    48  * getWritableTile method) and when the last writer of a particular

    49  * tile relinquishes its access (via a call to releaseWritableTile).

    50  * Additionally, it allows any caller to determine whether any tiles

    51  * are currently checked out (via hasTileWriters), and to obtain a

    52  * list of such tiles (via getWritableTileIndices, in the form of a Vector

    53  * of Point objects).

    54  * <p>

    55  * Objects wishing to be notified of changes in tile writability must

    56  * implement the TileObserver interface, and are added by a

    57  * call to addTileObserver.  Multiple calls to

    58  * addTileObserver for the same object will result in multiple

    59  * notifications.  An existing observer may reduce its notifications

    60  * by calling removeTileObserver; if the observer had no

    61  * notifications the operation is a no-op.

    62  * <p>

    63  * It is necessary for a WritableRenderedImage to ensure that

    64  * notifications occur only when the first writer acquires a tile and

    65  * the last writer releases it.

    66  *

    67  */

    68 

    69 public interface WritableRenderedImage extends RenderedImage

    70 {

    71 

    72   /**

    73    * Adds an observer.  If the observer is already present,

    74    * it will receive multiple notifications.

    75    * @param to the specified <code>TileObserver</code>

    76    */

    77   public void addTileObserver(TileObserver to);

    78 

    79   /**

    80    * Removes an observer.  If the observer was not registered,

    81    * nothing happens.  If the observer was registered for multiple

    82    * notifications, it will now be registered for one fewer.

    83    * @param to the specified <code>TileObserver</code>

    84    */

    85   public void removeTileObserver(TileObserver to);

    86 

    87   /**

    88    * Checks out a tile for writing.

    89    *

    90    * The WritableRenderedImage is responsible for notifying all

    91    * of its TileObservers when a tile goes from having

    92    * no writers to having one writer.

    93    *

    94    * @param tileX the X index of the tile.

    95    * @param tileY the Y index of the tile.

    96    * @return a writable tile.

    97    */

    98   public WritableRaster getWritableTile(int tileX, int tileY);

    99 

   100   /**

   101    * Relinquishes the right to write to a tile.  If the caller

   102    * continues to write to the tile, the results are undefined.

   103    * Calls to this method should only appear in matching pairs

   104    * with calls to getWritableTile; any other use will lead

   105    * to undefined results.

   106    *

   107    * The WritableRenderedImage is responsible for notifying all of

   108    * its TileObservers when a tile goes from having one writer

   109    * to having no writers.

   110    *

   111    * @param tileX the X index of the tile.

   112    * @param tileY the Y index of the tile.

   113    */

   114   public void releaseWritableTile(int tileX, int tileY);

   115 

   116   /**

   117    * Returns whether a tile is currently checked out for writing.

   118    *

   119    * @param tileX the X index of the tile.

   120    * @param tileY the Y index of the tile.

   121    * @return <code>true</code> if specified tile is checked out

   122    *         for writing; <code>false</code> otherwise.

   123    */

   124   public boolean isTileWritable(int tileX, int tileY);

   125 

   126   /**

   127    * Returns an array of Point objects indicating which tiles

   128    * are checked out for writing.  Returns null if none are

   129    * checked out.

   130    * @return an array containing the locations of tiles that are

   131    *         checked out for writing.

   132    */

   133   public Point[] getWritableTileIndices();

   134 

   135   /**

   136    * Returns whether any tile is checked out for writing.

   137    * Semantically equivalent to (getWritableTileIndices() != null).

   138    * @return <code>true</code> if any tiles are checked out for

   139    *         writing; <code>false</code> otherwise.

   140    */

   141   public boolean hasTileWriters();

   142 

   143   /**

   144    * Sets a rect of the image to the contents of the Raster r, which is

   145    * assumed to be in the same coordinate space as the WritableRenderedImage.

   146    * The operation is clipped to the bounds of the WritableRenderedImage.

   147    * @param r the specified <code>Raster</code>

   148    */

   149   public void setData(Raster r);

   150 

   151 }