| Frames | No Frames |
1: /* VolatileImage.java -- a hardware-accelerated image buffer 2: Copyright (C) 2002, 2005 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package java.awt.image; 40: 41: import java.awt.Graphics; 42: import java.awt.Graphics2D; 43: import java.awt.GraphicsConfiguration; 44: import java.awt.Image; 45: import java.awt.Transparency; 46: import java.awt.ImageCapabilities; 47: 48: /** 49: * VolatileImage represents a hardware-accelerated graphics buffer. 50: * The native graphics system may free or damage the resources 51: * occupied by a VolatileImage at any time. As such, one must 52: * frequently check the "validity" of the image buffer's resources. 53: * 54: * A volatile image's "validity" depends on multiple factors. Its 55: * resources may have become unavailble in which case you must 56: * reallocate them. If you move the image from one output device to 57: * another, you may need to recreate the image's resources if the new 58: * output device's capabilities don't match the old one's. Finally, 59: * if the contents of the image's buffer have been damaged you must 60: * re-render the image. 61: * 62: * VolatileImages should always be created using either 63: * Component.createVolatileImage or 64: * GraphicsConfiguration.createCompatibleVolatileImage. 65: */ 66: public abstract class VolatileImage extends Image 67: implements Transparency 68: { 69: /** 70: * One of validate's possible return values. Indicates that the 71: * image buffer matches its graphics configuration's capabilities 72: * and that its resources are initialized and ready to be drawn 73: * into. Also implies that any existing image rendered to the 74: * buffer is intact and need not be re-rendered. 75: */ 76: public static final int IMAGE_OK = 0; 77: 78: /** 79: * One of validate's possible return values. Indicates that the 80: * image buffer has been restored, meaning that it is valid and 81: * ready-to-use but that its previous contents have been lost. This 82: * return value implies that the image needs to be re-rendered. 83: */ 84: public static final int IMAGE_RESTORED = 1; 85: 86: /** 87: * One of validate's possible return values. Indicates that the 88: * image buffer type is unsupported by the current graphics 89: * configuration. The graphics configuration may have changed, for 90: * example if the image moved from one output device to another. 91: * This return value implies that the image buffer's resources 92: * should be re-acquired. 93: */ 94: public static final int IMAGE_INCOMPATIBLE = 2; 95: 96: /** 97: * This image's transparency type. One of Transparency.BITMASK, 98: * Transparency.OPAQUE or Transparency.TRANSLUCENT. 99: * 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: }