001/* VolatileImage.java -- a hardware-accelerated image buffer 002 Copyright (C) 2002, 2005 Free Software Foundation, Inc. 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038 039package java.awt.image; 040 041import java.awt.Graphics; 042import java.awt.Graphics2D; 043import java.awt.GraphicsConfiguration; 044import java.awt.Image; 045import java.awt.Transparency; 046import java.awt.ImageCapabilities; 047 048/** 049 * VolatileImage represents a hardware-accelerated graphics buffer. 050 * The native graphics system may free or damage the resources 051 * occupied by a VolatileImage at any time. As such, one must 052 * frequently check the "validity" of the image buffer's resources. 053 * 054 * A volatile image's "validity" depends on multiple factors. Its 055 * resources may have become unavailble in which case you must 056 * reallocate them. If you move the image from one output device to 057 * another, you may need to recreate the image's resources if the new 058 * output device's capabilities don't match the old one's. Finally, 059 * if the contents of the image's buffer have been damaged you must 060 * re-render the image. 061 * 062 * VolatileImages should always be created using either 063 * Component.createVolatileImage or 064 * GraphicsConfiguration.createCompatibleVolatileImage. 065 */ 066public abstract class VolatileImage extends Image 067 implements Transparency 068{ 069 /** 070 * One of validate's possible return values. Indicates that the 071 * image buffer matches its graphics configuration's capabilities 072 * and that its resources are initialized and ready to be drawn 073 * into. Also implies that any existing image rendered to the 074 * buffer is intact and need not be re-rendered. 075 */ 076 public static final int IMAGE_OK = 0; 077 078 /** 079 * One of validate's possible return values. Indicates that the 080 * image buffer has been restored, meaning that it is valid and 081 * ready-to-use but that its previous contents have been lost. This 082 * return value implies that the image needs to be re-rendered. 083 */ 084 public static final int IMAGE_RESTORED = 1; 085 086 /** 087 * One of validate's possible return values. Indicates that the 088 * image buffer type is unsupported by the current graphics 089 * configuration. The graphics configuration may have changed, for 090 * example if the image moved from one output device to another. 091 * This return value implies that the image buffer's resources 092 * should be re-acquired. 093 */ 094 public static final int IMAGE_INCOMPATIBLE = 2; 095 096 /** 097 * This image's transparency type. One of Transparency.BITMASK, 098 * Transparency.OPAQUE or Transparency.TRANSLUCENT. 099 * 100 * @since 1.5 101 */ 102 protected int transparency; 103 104 /** 105 * Default constructor. VolatileImages should not be created 106 * directly. Rather, you should use Component.createVolatileImage 107 * or GraphicsConfiguration.createCompatibleVolatileImage. 108 */ 109 public VolatileImage() 110 { 111 } 112 113 /** 114 * Returns an image representing the current state of the volatile 115 * image buffer. The returned image is static meaning that it is 116 * not updated after being created. It is a snapshot of the 117 * volatile image buffer at the time getSnapshot is called. 118 * 119 * This method, which reads pixels from the volatile image buffer, 120 * may be less-performant than methods that write pixels since 121 * VolatileImages are typically optimized for writing. 122 * 123 * @return a BufferedImage representing this VolatileImage 124 */ 125 public abstract BufferedImage getSnapshot(); 126 127 /** 128 * Returns the width of this image buffer. 129 * 130 * @return the width of this VolatileImage 131 */ 132 public abstract int getWidth(); 133 134 /** 135 * Returns the height of this image buffer. 136 * 137 * @return the height of this VolatileImage 138 */ 139 public abstract int getHeight(); 140 141 /** 142 * Calling this method is equivalent to calling 143 * getSnapshot().getSource(). The ImageProducer produces pixels 144 * from the BufferedImage snapshot and not from the VolatileImage 145 * itself. Thus, changes to the VolatileImage that occur after this 146 * ImageProducer has been retrieved will not be reflected in the 147 * produced pixels. 148 * 149 * This method, which reads pixels from the volatile image buffer, 150 * may be less-performant than methods that write pixels since 151 * VolatileImages are typically optimized for writing. 152 * 153 * @return an ImageProducer for a static BufferedImage snapshot of 154 * this image buffer 155 */ 156 public ImageProducer getSource() 157 { 158 return getSnapshot().getSource(); 159 } 160 161 /** 162 * Releases the system resources taken by this image. 163 */ 164 public void flush() 165 { 166 } 167 168 /** 169 * Returns a Graphics2D object that can be used to draw onto this 170 * image. This method is present for backwards-compatibility. It 171 * simply returns the result of createGraphics. 172 * 173 * @return a Graphics2D object that can be used to draw onto this 174 * image 175 */ 176 public Graphics getGraphics() 177 { 178 return createGraphics(); 179 } 180 181 /** 182 * Returns a Graphics2D object that can be used to draw onto this 183 * image. 184 * 185 * @return a Graphics2D object that can be used to draw onto this 186 * image 187 */ 188 public abstract Graphics2D createGraphics(); 189 190 /** 191 * Validates and restores this image. If the image buffer has 192 * become unavailable for further use since the last call to 193 * validate, validate will allocate a new image buffer. The image 194 * is also "validated" against the GraphicsConfiguration parameter. 195 * 196 * "Validating" the image means checking that the capabilities it 197 * requires of the output device are indeed supported by the given 198 * output device. If the image's characteristics, which can be 199 * highly output device-specific, are not supported by the graphics 200 * configuration, then IMAGE_INCOMPATIBLE will be returned. This 201 * can happen, for example, if this image was created on one output 202 * device, then validated against a different output device with 203 * different capabilities. Calling validate with a NULL gc argument 204 * causes validate to skip the validation test. 205 * 206 * @param gc graphics configuration against which to validate or 207 * NULL 208 * 209 * @return a code indicating the result of validation. One of: 210 * <ul> 211 * <li><code>IMAGE_OK</code> if the image did not need to be 212 * validated and didn't need to be restored</li> 213 * <li><code>IMAGE_RESTORED</code> if the image may need to be 214 * re-rendered.</li> 215 * <li><code>IMAGE_INCOMPATIBLE</code> if this image's 216 * requirements are not fulfilled by the graphics configuration 217 * parameter. This implies that you need to create a new 218 * VolatileImage for the different GraphicsConfiguration or 219 * Component. This return value implies nothing about whether the 220 * image is valid or needs to be re-rendered.</li> 221 * </ul> 222 */ 223 public abstract int validate(GraphicsConfiguration gc); 224 225 /** 226 * Returns true if the contents of the image buffer have been 227 * damaged or if the image buffer's resources have been reclaimed by 228 * the graphics system. You should call this method after a series 229 * of rendering operations to or from the image, to see if the image 230 * buffer needs to be revalidated or the image re-rendered. 231 * 232 * @return true if the validate should be called, false otherwise 233 */ 234 public abstract boolean contentsLost(); 235 236 /** 237 * Returns the capabilities of this image buffer. 238 * 239 * @return the capabilities of this image buffer 240 */ 241 public abstract ImageCapabilities getCapabilities(); 242 243 /** 244 * Returns the transparency type of this image. 245 * 246 * @return Transparency.OPAQUE, Transparency.BITMASK or 247 * Transparency.TRANSLUCENT 248 */ 249 public int getTransparency() 250 { 251 return transparency; 252 } 253}