001 /* VolatileImage.java -- a hardware-accelerated image buffer
002 Copyright (C) 2002, 2005 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package java.awt.image;
040
041 import java.awt.Graphics;
042 import java.awt.Graphics2D;
043 import java.awt.GraphicsConfiguration;
044 import java.awt.Image;
045 import java.awt.Transparency;
046 import 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 */
066 public 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 }