KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > awt > image > VolatileImage


1 /*
2  * @(#)VolatileImage.java 1.17 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.awt.image;
9
10 import java.awt.Color JavaDoc;
11 import java.awt.Graphics JavaDoc;
12 import java.awt.Graphics2D JavaDoc;
13 import java.awt.GraphicsConfiguration JavaDoc;
14 import java.awt.GraphicsDevice JavaDoc;
15 import java.awt.Image JavaDoc;
16 import java.awt.ImageCapabilities JavaDoc;
17 import java.awt.Toolkit JavaDoc;
18 import java.awt.Transparency JavaDoc;
19
20 /**
21  * VolatileImage is an image which can lose its
22  * contents at any time due to circumstances beyond the control of the
23  * application (e.g., situations caused by the operating system or by
24  * other applications). Because of the potential for hardware acceleration,
25  * a VolatileImage object can have significant performance benefits on
26  * some platforms.
27  * <p>
28  * The drawing surface of an image (the memory where the image contents
29  * actually reside) can be lost or invalidated, causing the contents of that
30  * memory to go away. The drawing surface thus needs to be restored
31  * or recreated and the contents of that surface need to be
32  * re-rendered. VolatileImage provides an interface for
33  * allowing the user to detect these problems and fix them
34  * when they occur.
35  * <p>
36  * This image should not be subclassed directly but should be created
37  * by using the {@link java.awt.Component#createVolatileImage(int, int)
38  * Component.createVolatileImage} or
39  * {@link java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int, int)
40  * GraphicsConfiguration.createCompatibleVolatileImage(int, int)} methods.
41  * <P>
42  * An example of using a VolatileImage object follows:
43  * <pre>
44  * // image creation
45  * VolatileImage vImg = createVolatileImage(w, h);
46  *
47  *
48  * // rendering to the image
49  * void renderOffscreen() {
50  * do {
51  * if (vImg.validate(getGraphicsConfiguration()) ==
52  * VolatileImage.IMAGE_INCOMPATIBLE)
53  * {
54  * // old vImg doesn't work with new GraphicsConfig; re-create it
55  * vImg = createVolatileImage(w, h);
56  * }
57  * Graphics2D g = vImg.createGraphics();
58  * //
59  * // miscellaneous rendering commands...
60  * //
61  * g.dispose();
62  * } while (vImg.contentsLost());
63  * }
64  *
65  *
66  * // copying from the image (here, gScreen is the Graphics
67  * // object for the onscreen window)
68  * do {
69  * int returnCode = vImg.validate(getGraphicsConfiguration());
70  * if (returnCode == VolatileImage.IMAGE_RESTORED) {
71  * // Contents need to be restored
72  * renderOffscreen(); // restore contents
73  * } else if (returnCode == VolatileImage.IMAGE_INCOMPATIBLE) {
74  * // old vImg doesn't work with new GraphicsConfig; re-create it
75  * vImg = createVolatileImage(w, h);
76  * renderOffscreen();
77  * }
78  * gScreen.drawImage(vImg, 0, 0, this);
79  * } while (vImg.contentsLost());
80  * </pre>
81  * <P>
82  * Note that this class subclasses from the {@link Image} class, which
83  * includes methods that take an {@link ImageObserver} parameter for
84  * asynchronous notifications as information is received from
85  * a potential {@link ImageProducer}. Since this <code>VolatileImage</code>
86  * is not loaded from an asynchronous source, the various methods that take
87  * an <code>ImageObserver</code> parameter will behave as if the data has
88  * already been obtained from the <code>ImageProducer</code>.
89  * Specifically, this means that the return values from such methods
90  * will never indicate that the information is not yet available and
91  * the <code>ImageObserver</code> used in such methods will never
92  * need to be recorded for an asynchronous callback notification.
93  */
94 public abstract class VolatileImage extends Image JavaDoc implements Transparency JavaDoc
95 {
96
97     // Return codes for validate() method
98
99     /**
100      * Validated image is ready to use as-is.
101      */
102     public static final int IMAGE_OK = 0;
103
104     /**
105      * Validated image has been restored and is now ready to use.
106      * Note that restoration causes contents of the image to be lost.
107      */
108     public static final int IMAGE_RESTORED = 1;
109
110     /**
111      * Validated image is incompatible with supplied
112      * <code>GraphicsConfiguration</code> object and should be
113      * re-created as appropriate. Usage of the image as-is
114      * after receiving this return code from <code>validate</code>
115      * is undefined.
116      */
117     public static final int IMAGE_INCOMPATIBLE = 2;
118
119     /**
120      * Returns a static snapshot image of this object. The
121      * <code>BufferedImage</code> returned is only current with
122      * the <code>VolatileImage</code> at the time of the request
123      * and will not be updated with any future changes to the
124      * <code>VolatileImage</code>.
125      * @return a {@link BufferedImage} representation of this
126      * <code>VolatileImage</code>
127      * @see BufferedImage
128      */
129     public abstract BufferedImage JavaDoc getSnapshot();
130     
131     /**
132      * Returns the width of the <code>VolatileImage</code>.
133      * @return the width of this <code>VolatileImage</code>.
134      */
135     public abstract int getWidth();
136
137     /**
138      * Returns the height of the <code>VolatileImage</code>.
139      * @return the height of this <code>VolatileImage</code>.
140      */
141     public abstract int getHeight();
142
143     // Image overrides
144
145     /**
146      * This returns an ImageProducer for this VolatileImage.
147      * Note that the VolatileImage object is optimized for
148      * rendering operations and blitting to the screen or other
149      * VolatileImage objects, as opposed to reading back the
150      * pixels of the image. Therefore, operations such as
151      * <code>getSource</code> may not perform as fast as
152      * operations that do not rely on reading the pixels.
153      * Note also that the pixel values read from the image are current
154      * with those in the image only at the time that they are
155      * retrieved. This method takes a snapshot
156      * of the image at the time the request is made and the
157      * ImageProducer object returned works with
158      * that static snapshot image, not the original VolatileImage.
159      * Calling getSource()
160      * is equivalent to calling getSnapshot().getSource().
161      * @return an {@link ImageProducer} that can be used to produce the
162      * pixels for a <code>BufferedImage</code> representation of
163      * this Image.
164      * @see ImageProducer
165      * @see #getSnapshot()
166      */
167     public ImageProducer JavaDoc getSource() {
168     // REMIND: Make sure this functionality is in line with the
169 // spec. In particular, we are returning the Source for a
170 // static image (the snapshot), not a changing image (the
171 // VolatileImage). So if the user expects the Source to be
172 // up-to-date with the current contents of the VolatileImage,
173 // they will be disappointed...
174 // REMIND: This assumes that getSnapshot() returns something
175 // valid and not the default null object returned by this class
176 // (so it assumes that the actual VolatileImage object is
177 // subclassed off something that does the right thing
178 // (e.g., SunVolatileImage).
179 return getSnapshot().getSource();
180     }
181
182     // REMIND: if we want any decent performance for getScaledInstance(),
183 // we should override the Image implementation of it...
184
185     /**
186      * Releases system resources currently consumed by this image.
187      * <p>
188      * When a VolatileImage object is created, limited system resources
189      * such as video memory (VRAM) may be allocated in order to
190      * support the image. When a VolatileImage object is no longer
191      * used, it may be garbage-collected and those system resources
192      * will be returned, but this process does
193      * not happen at guaranteed times. Applications that create
194      * many VolatileImage objects (for example, a resizing window
195      * may force recreation of its back buffer as the size
196      * changes) may run out of optimal system
197      * resources for new VolatileImage objects simply because the
198      * old objects have not yet been removed from the system.
199      * (New VolatileImage objects may still be created, but they
200      * may not perform as well as those created in accelerated
201      * memory).
202      * <p>
203      * By calling this flush method, applications can have more control over
204      * the state of the resources taken up by obsolete VolatileImage objects.
205      * <p>
206      * This method will cause the contents of the image to be lost, so
207      * calls to {@link #contentsLost} will return <code>true</code>
208      * and the image must be validated before it can be used again.
209      * @see #contentsLost
210      * @see #validate
211      */
212     public void flush() {
213     }
214
215     /**
216      * This method returns a {@link Graphics2D}, but is here
217      * for backwards compatibility. {@link #createGraphics() createGraphics} is more
218      * convenient, since it is declared to return a
219      * <code>Graphics2D</code>.
220      * @return a <code>Graphics2D</code>, which can be used to draw into
221      * this image.
222      */
223     public Graphics JavaDoc getGraphics() {
224     return createGraphics();
225     }
226
227     /**
228      * Creates a <code>Graphics2D</code>, which can be used to draw into
229      * this <code>VolatileImage</code>.
230      * @return a <code>Graphics2D</code>, used for drawing into this
231      * image.
232      */
233     public abstract Graphics2D JavaDoc createGraphics();
234
235
236     // Volatile management methods
237
238     /**
239      * Attempts to restore the drawing surface of the image if the surface
240      * had been lost since the last <code>validate</code> call. Also
241      * validates this image against the given GraphicsConfiguration
242      * parameter to see whether operations from this image to the
243      * GraphicsConfiguration are compatible. An example of an
244      * incompatible combination might be a situation where a VolatileImage
245      * object was created on one graphics device and then was used
246      * to render to a different graphics device. Since VolatileImage
247      * objects tend to be very device-specific, this operation might
248      * not work as intended, so the return code from this validate
249      * call would note that incompatibility. A null or incorrect
250      * value for gc may cause incorrect values to be returned from
251      * <code>validate</code> and may cause later problems with rendering.
252      *
253      * @param gc a <code>GraphicsConfiguration</code> object for this
254      * image to be validated against. A null gc implies that the
255      * validate method should skip the compatibility test.
256      * @return <code>IMAGE_OK</code> if the image did not need validation<BR>
257      * <code>IMAGE_RESTORED</code> if the image needed restoration.
258      * Restoration implies that the contents of the image may have
259      * been affected and the image may need to be re-rendered.<BR>
260      * <code>IMAGE_INCOMPATIBLE</code> if the image is incompatible
261      * with the <code>GraphicsConfiguration</code> object passed
262      * into the <code>validate</code> method. Incompatibility
263      * implies that the image may need to be recreated with a
264      * new <code>Component</code> or
265      * <code>GraphicsConfiguration</code> in order to get an image
266      * that can be used successfully with this
267      * <code>GraphicsConfiguration</code>.
268      * An incompatible image is not checked for whether restoration
269      * was necessary, so the state of the image is unchanged
270      * after a return value of <code>IMAGE_INCOMPATIBLE</code>
271      * and this return value implies nothing about whether the
272      * image needs to be restored.
273      * @see java.awt.GraphicsConfiguration
274      * @see java.awt.Component
275      * @see #IMAGE_OK
276      * @see #IMAGE_RESTORED
277      * @see #IMAGE_INCOMPATIBLE
278      */
279     public abstract int validate(GraphicsConfiguration JavaDoc gc);
280
281     /**
282      * Returns <code>true</code> if rendering data was lost since last
283      * <code>validate</code> call. This method should be called by the
284      * application at the end of any series of rendering operations to
285      * or from the image to see whether
286      * the image needs to be validated and the rendering redone.
287      * @return <code>true</code> if the drawing surface needs to be restored;
288      * <code>false</code> otherwise.
289      */
290     public abstract boolean contentsLost();
291
292     /**
293      * Returns an ImageCapabilities object which can be
294      * inquired as to the specific capabilities of this
295      * VolatileImage. This would allow programmers to find
296      * out more runtime information on the specific VolatileImage
297      * object that they have created. For example, the user
298      * might create a VolatileImage but the system may have
299      * no video memory left for creating an image of that
300      * size, so although the object is a VolatileImage, it is
301      * not as accelerated as other VolatileImage objects on
302      * this platform might be. The user might want that
303      * information to find other solutions to their problem.
304      * @return an <code>ImageCapabilities</code> object that contains
305      * the capabilities of this <code>VolatileImage</code>.
306      * @since 1.4
307      */
308     public abstract ImageCapabilities JavaDoc getCapabilities();
309
310     /**
311      * The transparency value with which this image was created.
312      * @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int,
313      * int,int)
314      * @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int,
315      * int,ImageCapabilities,int)
316      * @see Transparency
317      * @since 1.5
318      */
319     protected int transparency = TRANSLUCENT;
320     
321     /**
322      * Returns the transparency. Returns either OPAQUE, BITMASK,
323      * or TRANSLUCENT.
324      * @return the transparency of this <code>VolatileImage</code>.
325      * @see Transparency#OPAQUE
326      * @see Transparency#BITMASK
327      * @see Transparency#TRANSLUCENT
328      * @since 1.5
329      */
330     public int getTransparency() {
331     return transparency;
332     }
333 }
334
335
Popular Tags