1/* 2 * Copyright (c) 1997, 2008, Oracle and/or its affiliates. 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. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * 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 36package java.awt.image; 37import java.awt.Point; 38 39/** 40 * WritableRenderedImage 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 69public 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} 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} 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} if specified tile is checked out 122 * for writing; {@code false} 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} if any tiles are checked out for 139 * writing; {@code false} 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} 148 */ 149 public void setData(Raster r); 150 151} 152