001 /*
002 * Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.image;
027
028 import java.awt.Color;
029 import java.awt.Graphics;
030 import java.awt.Graphics2D;
031 import java.awt.GraphicsConfiguration;
032 import java.awt.GraphicsDevice;
033 import java.awt.Image;
034 import java.awt.ImageCapabilities;
035 import java.awt.Toolkit;
036 import java.awt.Transparency;
037
038 /**
039 * VolatileImage is an image which can lose its
040 * contents at any time due to circumstances beyond the control of the
041 * application (e.g., situations caused by the operating system or by
042 * other applications). Because of the potential for hardware acceleration,
043 * a VolatileImage object can have significant performance benefits on
044 * some platforms.
045 * <p>
046 * The drawing surface of an image (the memory where the image contents
047 * actually reside) can be lost or invalidated, causing the contents of that
048 * memory to go away. The drawing surface thus needs to be restored
049 * or recreated and the contents of that surface need to be
050 * re-rendered. VolatileImage provides an interface for
051 * allowing the user to detect these problems and fix them
052 * when they occur.
053 * <p>
054 * When a VolatileImage object is created, limited system resources
055 * such as video memory (VRAM) may be allocated in order to support
056 * the image.
057 * When a VolatileImage object is no longer used, it may be
058 * garbage-collected and those system resources will be returned,
059 * but this process does not happen at guaranteed times.
060 * Applications that create many VolatileImage objects (for example,
061 * a resizing window may force recreation of its back buffer as the
062 * size changes) may run out of optimal system resources for new
063 * VolatileImage objects simply because the old objects have not
064 * yet been removed from the system.
065 * (New VolatileImage objects may still be created, but they
066 * may not perform as well as those created in accelerated
067 * memory).
068 * The flush method may be called at any time to proactively release
069 * the resources used by a VolatileImage so that it does not prevent
070 * subsequent VolatileImage objects from being accelerated.
071 * In this way, applications can have more control over the state
072 * of the resources taken up by obsolete VolatileImage objects.
073 * <p>
074 * This image should not be subclassed directly but should be created
075 * by using the {@link java.awt.Component#createVolatileImage(int, int)
076 * Component.createVolatileImage} or
077 * {@link java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int, int)
078 * GraphicsConfiguration.createCompatibleVolatileImage(int, int)} methods.
079 * <P>
080 * An example of using a VolatileImage object follows:
081 * <pre>
082 * // image creation
083 * VolatileImage vImg = createVolatileImage(w, h);
084 *
085 *
086 * // rendering to the image
087 * void renderOffscreen() {
088 * do {
089 * if (vImg.validate(getGraphicsConfiguration()) ==
090 * VolatileImage.IMAGE_INCOMPATIBLE)
091 * {
092 * // old vImg doesn't work with new GraphicsConfig; re-create it
093 * vImg = createVolatileImage(w, h);
094 * }
095 * Graphics2D g = vImg.createGraphics();
096 * //
097 * // miscellaneous rendering commands...
098 * //
099 * g.dispose();
100 * } while (vImg.contentsLost());
101 * }
102 *
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
134 Transparency {
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 // Volatile management methods
245
246 /**
247 * Attempts to restore the drawing surface of the image if the surface
248 * had been lost since the last <code>validate</code> call. Also
249 * validates this image against the given GraphicsConfiguration
250 * parameter to see whether operations from this image to the
251 * GraphicsConfiguration are compatible. An example of an
252 * incompatible combination might be a situation where a VolatileImage
253 * object was created on one graphics device and then was used
254 * to render to a different graphics device. Since VolatileImage
255 * objects tend to be very device-specific, this operation might
256 * not work as intended, so the return code from this validate
257 * call would note that incompatibility. A null or incorrect
258 * value for gc may cause incorrect values to be returned from
259 * <code>validate</code> and may cause later problems with rendering.
260 *
261 * @param gc a <code>GraphicsConfiguration</code> object for this
262 * image to be validated against. A null gc implies that the
263 * validate method should skip the compatibility test.
264 * @return <code>IMAGE_OK</code> if the image did not need validation<BR>
265 * <code>IMAGE_RESTORED</code> if the image needed restoration.
266 * Restoration implies that the contents of the image may have
267 * been affected and the image may need to be re-rendered.<BR>
268 * <code>IMAGE_INCOMPATIBLE</code> if the image is incompatible
269 * with the <code>GraphicsConfiguration</code> object passed
270 * into the <code>validate</code> method. Incompatibility
271 * implies that the image may need to be recreated with a
272 * new <code>Component</code> or
273 * <code>GraphicsConfiguration</code> in order to get an image
274 * that can be used successfully with this
275 * <code>GraphicsConfiguration</code>.
276 * An incompatible image is not checked for whether restoration
277 * was necessary, so the state of the image is unchanged
278 * after a return value of <code>IMAGE_INCOMPATIBLE</code>
279 * and this return value implies nothing about whether the
280 * image needs to be restored.
281 * @see java.awt.GraphicsConfiguration
282 * @see java.awt.Component
283 * @see #IMAGE_OK
284 * @see #IMAGE_RESTORED
285 * @see #IMAGE_INCOMPATIBLE
286 */
287 public abstract int validate(GraphicsConfiguration gc);
288
289 /**
290 * Returns <code>true</code> if rendering data was lost since last
291 * <code>validate</code> call. This method should be called by the
292 * application at the end of any series of rendering operations to
293 * or from the image to see whether
294 * the image needs to be validated and the rendering redone.
295 * @return <code>true</code> if the drawing surface needs to be restored;
296 * <code>false</code> otherwise.
297 */
298 public abstract boolean contentsLost();
299
300 /**
301 * Returns an ImageCapabilities object which can be
302 * inquired as to the specific capabilities of this
303 * VolatileImage. This would allow programmers to find
304 * out more runtime information on the specific VolatileImage
305 * object that they have created. For example, the user
306 * might create a VolatileImage but the system may have
307 * no video memory left for creating an image of that
308 * size, so although the object is a VolatileImage, it is
309 * not as accelerated as other VolatileImage objects on
310 * this platform might be. The user might want that
311 * information to find other solutions to their problem.
312 * @return an <code>ImageCapabilities</code> object that contains
313 * the capabilities of this <code>VolatileImage</code>.
314 * @since 1.4
315 */
316 public abstract ImageCapabilities getCapabilities();
317
318 /**
319 * The transparency value with which this image was created.
320 * @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int,
321 * int,int)
322 * @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int,
323 * int,ImageCapabilities,int)
324 * @see Transparency
325 * @since 1.5
326 */
327 protected int transparency = TRANSLUCENT;
328
329 /**
330 * Returns the transparency. Returns either OPAQUE, BITMASK,
331 * or TRANSLUCENT.
332 * @return the transparency of this <code>VolatileImage</code>.
333 * @see Transparency#OPAQUE
334 * @see Transparency#BITMASK
335 * @see Transparency#TRANSLUCENT
336 * @since 1.5
337 */
338 public int getTransparency() {
339 return transparency;
340 }
341 }
|