103 * 104 * // copying from the image (here, gScreen is the Graphics 105 * // object for the onscreen window) 106 * do { 107 * int returnCode = vImg.validate(getGraphicsConfiguration()); 108 * if (returnCode == VolatileImage.IMAGE_RESTORED) { 109 * // Contents need to be restored 110 * renderOffscreen(); // restore contents 111 * } else if (returnCode == VolatileImage.IMAGE_INCOMPATIBLE) { 112 * // old vImg doesn't work with new GraphicsConfig; re-create it 113 * vImg = createVolatileImage(w, h); 114 * renderOffscreen(); 115 * } 116 * gScreen.drawImage(vImg, 0, 0, this); 117 * } while (vImg.contentsLost()); 118 * </pre> 119 * <P> 120 * Note that this class subclasses from the {@link Image} class, which 121 * includes methods that take an {@link ImageObserver} parameter for 122 * asynchronous notifications as information is received from 123 * a potential {@link ImageProducer}. Since this <code>VolatileImage</code> 124 * is not loaded from an asynchronous source, the various methods that take 125 * an <code>ImageObserver</code> parameter will behave as if the data has 126 * already been obtained from the <code>ImageProducer</code>. 127 * Specifically, this means that the return values from such methods 128 * will never indicate that the information is not yet available and 129 * the <code>ImageObserver</code> used in such methods will never 130 * need to be recorded for an asynchronous callback notification. 131 * @since 1.4 132 */ 133 public abstract class VolatileImage extends Image implements Transparency 134 { 135 136 // Return codes for validate() method 137 138 /** 139 * Validated image is ready to use as-is. 140 */ 141 public static final int IMAGE_OK = 0; 142 143 /** 144 * Validated image has been restored and is now ready to use. 145 * Note that restoration causes contents of the image to be lost. 146 */ 147 public static final int IMAGE_RESTORED = 1; 148 149 /** 150 * Validated image is incompatible with supplied 151 * <code>GraphicsConfiguration</code> object and should be 152 * re-created as appropriate. Usage of the image as-is 153 * after receiving this return code from <code>validate</code> 154 * is undefined. 155 */ 156 public static final int IMAGE_INCOMPATIBLE = 2; 157 158 /** 159 * Returns a static snapshot image of this object. The 160 * <code>BufferedImage</code> returned is only current with 161 * the <code>VolatileImage</code> at the time of the request 162 * and will not be updated with any future changes to the 163 * <code>VolatileImage</code>. 164 * @return a {@link BufferedImage} representation of this 165 * <code>VolatileImage</code> 166 * @see BufferedImage 167 */ 168 public abstract BufferedImage getSnapshot(); 169 170 /** 171 * Returns the width of the <code>VolatileImage</code>. 172 * @return the width of this <code>VolatileImage</code>. 173 */ 174 public abstract int getWidth(); 175 176 /** 177 * Returns the height of the <code>VolatileImage</code>. 178 * @return the height of this <code>VolatileImage</code>. 179 */ 180 public abstract int getHeight(); 181 182 // Image overrides 183 184 /** 185 * This returns an ImageProducer for this VolatileImage. 186 * Note that the VolatileImage object is optimized for 187 * rendering operations and blitting to the screen or other 188 * VolatileImage objects, as opposed to reading back the 189 * pixels of the image. Therefore, operations such as 190 * <code>getSource</code> may not perform as fast as 191 * operations that do not rely on reading the pixels. 192 * Note also that the pixel values read from the image are current 193 * with those in the image only at the time that they are 194 * retrieved. This method takes a snapshot 195 * of the image at the time the request is made and the 196 * ImageProducer object returned works with 197 * that static snapshot image, not the original VolatileImage. 198 * Calling getSource() 199 * is equivalent to calling getSnapshot().getSource(). 200 * @return an {@link ImageProducer} that can be used to produce the 201 * pixels for a <code>BufferedImage</code> representation of 202 * this Image. 203 * @see ImageProducer 204 * @see #getSnapshot() 205 */ 206 public ImageProducer getSource() { 207 // REMIND: Make sure this functionality is in line with the 208 // spec. In particular, we are returning the Source for a 209 // static image (the snapshot), not a changing image (the 210 // VolatileImage). So if the user expects the Source to be 211 // up-to-date with the current contents of the VolatileImage, 212 // they will be disappointed... 213 // REMIND: This assumes that getSnapshot() returns something 214 // valid and not the default null object returned by this class 215 // (so it assumes that the actual VolatileImage object is 216 // subclassed off something that does the right thing 217 // (e.g., SunVolatileImage). 218 return getSnapshot().getSource(); 219 } 220 221 // REMIND: if we want any decent performance for getScaledInstance(), 222 // we should override the Image implementation of it... 223 224 /** 225 * This method returns a {@link Graphics2D}, but is here 226 * for backwards compatibility. {@link #createGraphics() createGraphics} is more 227 * convenient, since it is declared to return a 228 * <code>Graphics2D</code>. 229 * @return a <code>Graphics2D</code>, which can be used to draw into 230 * this image. 231 */ 232 public Graphics getGraphics() { 233 return createGraphics(); 234 } 235 236 /** 237 * Creates a <code>Graphics2D</code>, which can be used to draw into 238 * this <code>VolatileImage</code>. 239 * @return a <code>Graphics2D</code>, used for drawing into this 240 * image. 241 */ 242 public abstract Graphics2D createGraphics(); 243 244 245 // Volatile management methods 246 247 /** 248 * Attempts to restore the drawing surface of the image if the surface 249 * had been lost since the last <code>validate</code> call. Also 250 * validates this image against the given GraphicsConfiguration 251 * parameter to see whether operations from this image to the 252 * GraphicsConfiguration are compatible. An example of an 253 * incompatible combination might be a situation where a VolatileImage 254 * object was created on one graphics device and then was used 255 * to render to a different graphics device. Since VolatileImage 256 * objects tend to be very device-specific, this operation might 257 * not work as intended, so the return code from this validate 258 * call would note that incompatibility. A null or incorrect 259 * value for gc may cause incorrect values to be returned from 260 * <code>validate</code> and may cause later problems with rendering. 261 * 262 * @param gc a <code>GraphicsConfiguration</code> object for this 263 * image to be validated against. A null gc implies that the 264 * validate method should skip the compatibility test. 265 * @return <code>IMAGE_OK</code> if the image did not need validation<BR> 266 * <code>IMAGE_RESTORED</code> if the image needed restoration. 267 * Restoration implies that the contents of the image may have 268 * been affected and the image may need to be re-rendered.<BR> 269 * <code>IMAGE_INCOMPATIBLE</code> if the image is incompatible 270 * with the <code>GraphicsConfiguration</code> object passed 271 * into the <code>validate</code> method. Incompatibility 272 * implies that the image may need to be recreated with a 273 * new <code>Component</code> or 274 * <code>GraphicsConfiguration</code> in order to get an image 275 * that can be used successfully with this 276 * <code>GraphicsConfiguration</code>. 277 * An incompatible image is not checked for whether restoration 278 * was necessary, so the state of the image is unchanged 279 * after a return value of <code>IMAGE_INCOMPATIBLE</code> 280 * and this return value implies nothing about whether the 281 * image needs to be restored. 282 * @see java.awt.GraphicsConfiguration 283 * @see java.awt.Component 284 * @see #IMAGE_OK 285 * @see #IMAGE_RESTORED 286 * @see #IMAGE_INCOMPATIBLE 287 */ 288 public abstract int validate(GraphicsConfiguration gc); 289 290 /** 291 * Returns <code>true</code> if rendering data was lost since last 292 * <code>validate</code> call. This method should be called by the 293 * application at the end of any series of rendering operations to 294 * or from the image to see whether 295 * the image needs to be validated and the rendering redone. 296 * @return <code>true</code> if the drawing surface needs to be restored; 297 * <code>false</code> otherwise. 298 */ 299 public abstract boolean contentsLost(); 300 301 /** 302 * Returns an ImageCapabilities object which can be 303 * inquired as to the specific capabilities of this 304 * VolatileImage. This would allow programmers to find 305 * out more runtime information on the specific VolatileImage 306 * object that they have created. For example, the user 307 * might create a VolatileImage but the system may have 308 * no video memory left for creating an image of that 309 * size, so although the object is a VolatileImage, it is 310 * not as accelerated as other VolatileImage objects on 311 * this platform might be. The user might want that 312 * information to find other solutions to their problem. 313 * @return an <code>ImageCapabilities</code> object that contains 314 * the capabilities of this <code>VolatileImage</code>. 315 * @since 1.4 316 */ 317 public abstract ImageCapabilities getCapabilities(); 318 319 /** 320 * The transparency value with which this image was created. 321 * @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int, 322 * int,int) 323 * @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int, 324 * int,ImageCapabilities,int) 325 * @see Transparency 326 * @since 1.5 327 */ 328 protected int transparency = TRANSLUCENT; 329 330 /** 331 * Returns the transparency. Returns either OPAQUE, BITMASK, 332 * or TRANSLUCENT. 333 * @return the transparency of this <code>VolatileImage</code>. 334 * @see Transparency#OPAQUE 335 * @see Transparency#BITMASK 336 * @see Transparency#TRANSLUCENT 337 * @since 1.5 338 */ 339 public int getTransparency() { 340 return transparency; 341 } 342 } | 103 * 104 * // copying from the image (here, gScreen is the Graphics 105 * // object for the onscreen window) 106 * do { 107 * int returnCode = vImg.validate(getGraphicsConfiguration()); 108 * if (returnCode == VolatileImage.IMAGE_RESTORED) { 109 * // Contents need to be restored 110 * renderOffscreen(); // restore contents 111 * } else if (returnCode == VolatileImage.IMAGE_INCOMPATIBLE) { 112 * // old vImg doesn't work with new GraphicsConfig; re-create it 113 * vImg = createVolatileImage(w, h); 114 * renderOffscreen(); 115 * } 116 * gScreen.drawImage(vImg, 0, 0, this); 117 * } while (vImg.contentsLost()); 118 * </pre> 119 * <P> 120 * Note that this class subclasses from the {@link Image} class, which 121 * includes methods that take an {@link ImageObserver} parameter for 122 * asynchronous notifications as information is received from 123 * a potential {@link ImageProducer}. Since this {@code VolatileImage} 124 * is not loaded from an asynchronous source, the various methods that take 125 * an {@code ImageObserver} parameter will behave as if the data has 126 * already been obtained from the {@code ImageProducer}. 127 * Specifically, this means that the return values from such methods 128 * will never indicate that the information is not yet available and 129 * the {@code ImageObserver} used in such methods will never 130 * need to be recorded for an asynchronous callback notification. 131 * @since 1.4 132 */ 133 public abstract class VolatileImage extends Image implements Transparency 134 { 135 136 // Return codes for validate() method 137 138 /** 139 * Validated image is ready to use as-is. 140 */ 141 public static final int IMAGE_OK = 0; 142 143 /** 144 * Validated image has been restored and is now ready to use. 145 * Note that restoration causes contents of the image to be lost. 146 */ 147 public static final int IMAGE_RESTORED = 1; 148 149 /** 150 * Validated image is incompatible with supplied 151 * {@code GraphicsConfiguration} object and should be 152 * re-created as appropriate. Usage of the image as-is 153 * after receiving this return code from {@code validate} 154 * is undefined. 155 */ 156 public static final int IMAGE_INCOMPATIBLE = 2; 157 158 /** 159 * Returns a static snapshot image of this object. The 160 * {@code BufferedImage} returned is only current with 161 * the {@code VolatileImage} at the time of the request 162 * and will not be updated with any future changes to the 163 * {@code VolatileImage}. 164 * @return a {@link BufferedImage} representation of this 165 * {@code VolatileImage} 166 * @see BufferedImage 167 */ 168 public abstract BufferedImage getSnapshot(); 169 170 /** 171 * Returns the width of the {@code VolatileImage}. 172 * @return the width of this {@code VolatileImage}. 173 */ 174 public abstract int getWidth(); 175 176 /** 177 * Returns the height of the {@code VolatileImage}. 178 * @return the height of this {@code VolatileImage}. 179 */ 180 public abstract int getHeight(); 181 182 // Image overrides 183 184 /** 185 * This returns an ImageProducer for this VolatileImage. 186 * Note that the VolatileImage object is optimized for 187 * rendering operations and blitting to the screen or other 188 * VolatileImage objects, as opposed to reading back the 189 * pixels of the image. Therefore, operations such as 190 * {@code getSource} may not perform as fast as 191 * operations that do not rely on reading the pixels. 192 * Note also that the pixel values read from the image are current 193 * with those in the image only at the time that they are 194 * retrieved. This method takes a snapshot 195 * of the image at the time the request is made and the 196 * ImageProducer object returned works with 197 * that static snapshot image, not the original VolatileImage. 198 * Calling getSource() 199 * is equivalent to calling getSnapshot().getSource(). 200 * @return an {@link ImageProducer} that can be used to produce the 201 * pixels for a {@code BufferedImage} representation of 202 * this Image. 203 * @see ImageProducer 204 * @see #getSnapshot() 205 */ 206 public ImageProducer getSource() { 207 // REMIND: Make sure this functionality is in line with the 208 // spec. In particular, we are returning the Source for a 209 // static image (the snapshot), not a changing image (the 210 // VolatileImage). So if the user expects the Source to be 211 // up-to-date with the current contents of the VolatileImage, 212 // they will be disappointed... 213 // REMIND: This assumes that getSnapshot() returns something 214 // valid and not the default null object returned by this class 215 // (so it assumes that the actual VolatileImage object is 216 // subclassed off something that does the right thing 217 // (e.g., SunVolatileImage). 218 return getSnapshot().getSource(); 219 } 220 221 // REMIND: if we want any decent performance for getScaledInstance(), 222 // we should override the Image implementation of it... 223 224 /** 225 * This method returns a {@link Graphics2D}, but is here 226 * for backwards compatibility. {@link #createGraphics() createGraphics} is more 227 * convenient, since it is declared to return a 228 * {@code Graphics2D}. 229 * @return a {@code Graphics2D}, which can be used to draw into 230 * this image. 231 */ 232 public Graphics getGraphics() { 233 return createGraphics(); 234 } 235 236 /** 237 * Creates a {@code Graphics2D}, which can be used to draw into 238 * this {@code VolatileImage}. 239 * @return a {@code Graphics2D}, used for drawing into this 240 * image. 241 */ 242 public abstract Graphics2D createGraphics(); 243 244 245 // Volatile management methods 246 247 /** 248 * Attempts to restore the drawing surface of the image if the surface 249 * had been lost since the last {@code validate} call. Also 250 * validates this image against the given GraphicsConfiguration 251 * parameter to see whether operations from this image to the 252 * GraphicsConfiguration are compatible. An example of an 253 * incompatible combination might be a situation where a VolatileImage 254 * object was created on one graphics device and then was used 255 * to render to a different graphics device. Since VolatileImage 256 * objects tend to be very device-specific, this operation might 257 * not work as intended, so the return code from this validate 258 * call would note that incompatibility. A null or incorrect 259 * value for gc may cause incorrect values to be returned from 260 * {@code validate} and may cause later problems with rendering. 261 * 262 * @param gc a {@code GraphicsConfiguration} object for this 263 * image to be validated against. A null gc implies that the 264 * validate method should skip the compatibility test. 265 * @return {@code IMAGE_OK} if the image did not need validation<BR> 266 * {@code IMAGE_RESTORED} if the image needed restoration. 267 * Restoration implies that the contents of the image may have 268 * been affected and the image may need to be re-rendered.<BR> 269 * {@code IMAGE_INCOMPATIBLE} if the image is incompatible 270 * with the {@code GraphicsConfiguration} object passed 271 * into the {@code validate} method. Incompatibility 272 * implies that the image may need to be recreated with a 273 * new {@code Component} or 274 * {@code GraphicsConfiguration} in order to get an image 275 * that can be used successfully with this 276 * {@code GraphicsConfiguration}. 277 * An incompatible image is not checked for whether restoration 278 * was necessary, so the state of the image is unchanged 279 * after a return value of {@code IMAGE_INCOMPATIBLE} 280 * and this return value implies nothing about whether the 281 * image needs to be restored. 282 * @see java.awt.GraphicsConfiguration 283 * @see java.awt.Component 284 * @see #IMAGE_OK 285 * @see #IMAGE_RESTORED 286 * @see #IMAGE_INCOMPATIBLE 287 */ 288 public abstract int validate(GraphicsConfiguration gc); 289 290 /** 291 * Returns {@code true} if rendering data was lost since last 292 * {@code validate} call. This method should be called by the 293 * application at the end of any series of rendering operations to 294 * or from the image to see whether 295 * the image needs to be validated and the rendering redone. 296 * @return {@code true} if the drawing surface needs to be restored; 297 * {@code false} otherwise. 298 */ 299 public abstract boolean contentsLost(); 300 301 /** 302 * Returns an ImageCapabilities object which can be 303 * inquired as to the specific capabilities of this 304 * VolatileImage. This would allow programmers to find 305 * out more runtime information on the specific VolatileImage 306 * object that they have created. For example, the user 307 * might create a VolatileImage but the system may have 308 * no video memory left for creating an image of that 309 * size, so although the object is a VolatileImage, it is 310 * not as accelerated as other VolatileImage objects on 311 * this platform might be. The user might want that 312 * information to find other solutions to their problem. 313 * @return an {@code ImageCapabilities} object that contains 314 * the capabilities of this {@code VolatileImage}. 315 * @since 1.4 316 */ 317 public abstract ImageCapabilities getCapabilities(); 318 319 /** 320 * The transparency value with which this image was created. 321 * @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int, 322 * int,int) 323 * @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int, 324 * int,ImageCapabilities,int) 325 * @see Transparency 326 * @since 1.5 327 */ 328 protected int transparency = TRANSLUCENT; 329 330 /** 331 * Returns the transparency. Returns either OPAQUE, BITMASK, 332 * or TRANSLUCENT. 333 * @return the transparency of this {@code VolatileImage}. 334 * @see Transparency#OPAQUE 335 * @see Transparency#BITMASK 336 * @see Transparency#TRANSLUCENT 337 * @since 1.5 338 */ 339 public int getTransparency() { 340 return transparency; 341 } 342 } |