001: /*
002: * @(#)VolatileImage.java 1.5 %E
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program 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 version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package java.awt.image;
028:
029: import java.awt.Color;
030: import java.awt.Graphics;
031: import java.awt.Graphics2D;
032: import java.awt.GraphicsConfiguration;
033: import java.awt.GraphicsDevice;
034: import java.awt.Image;
035: import java.awt.ImageCapabilities;
036: import java.awt.Toolkit;
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: * This image should not be subclassed directly but should be created
055: * by using the {@link java.awt.Component#createVolatileImage(int, int)
056: * Component.createVolatileImage} or
057: * {@link java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int, int)
058: * GraphicsConfiguration.createCompatibleVolatileImage(int, int)} methods.
059: * <P>
060: * An example of using a VolatileImage object follows:
061: * <pre>
062: * // image creation
063: * VolatileImage vImg = createVolatileImage(w, h);
064: *
065: *
066: * // rendering to the image
067: * void renderOffscreen() {
068: * do {
069: * if (vImg.validate(getGraphicsConfiguration()) ==
070: * VolatileImage.IMAGE_INCOMPATIBLE)
071: * {
072: * // old vImg doesn't work with new GraphicsConfig; re-create it
073: * vImg = createVolatileImage(w, h);
074: * }
075: * Graphics2D g = vImg.createGraphics();
076: * //
077: * // miscellaneous rendering commands...
078: * //
079: * g.dispose();
080: * } while (vImg.contentsLost());
081: * }
082: *
083: *
084: * // copying from the image (here, gScreen is the Graphics
085: * // object for the onscreen window)
086: * do {
087: * int returnCode = vImg.validate(getGraphicsConfiguration());
088: * if (returnCode == VolatileImage.IMAGE_RESTORED) {
089: * // Contents need to be restored
090: * renderOffscreen(); // restore contents
091: * } else if (returnCode == VolatileImage.IMAGE_INCOMPATIBLE) {
092: * // old vImg doesn't work with new GraphicsConfig; re-create it
093: * vImg = createVolatileImage(w, h);
094: * renderOffscreen();
095: * }
096: * gScreen.drawImage(vImg, 0, 0, this);
097: * } while (vImg.contentsLost());
098: * </pre>
099: * <P>
100: * Note that this class subclasses from the {@link Image} class, which
101: * includes methods that take an {@link ImageObserver} parameter for
102: * asynchronous notifications as information is received from
103: * a potential {@link ImageProducer}. Since this <code>VolatileImage</code>
104: * is not loaded from an asynchronous source, the various methods that take
105: * an <code>ImageObserver</code> parameter will behave as if the data has
106: * already been obtained from the <code>ImageProducer</code>.
107: * Specifically, this means that the return values from such methods
108: * will never indicate that the information is not yet available and
109: * the <code>ImageObserver</code> used in such methods will never
110: * need to be recorded for an asynchronous callback notification.
111: */
112: public abstract class VolatileImage extends Image {
113:
114: // Return codes for validate() method
115:
116: /**
117: * Validated image is ready to use as-is.
118: */
119: public static final int IMAGE_OK = 0;
120:
121: /**
122: * Validated image has been restored and is now ready to use.
123: * Note that restoration causes contents of the image to be lost.
124: */
125: public static final int IMAGE_RESTORED = 1;
126:
127: /**
128: * Validated image is incompatible with supplied
129: * <code>GraphicsConfiguration</code> object and should be
130: * re-created as appropriate. Usage of the image as-is
131: * after receiving this return code from <code>validate</code>
132: * is undefined.
133: */
134: public static final int IMAGE_INCOMPATIBLE = 2;
135:
136: /**
137: * Returns a static snapshot image of this object. The
138: * <code>BufferedImage</code> returned is only current with
139: * the <code>VolatileImage</code> at the time of the request
140: * and will not be updated with any future changes to the
141: * <code>VolatileImage</code>.
142: * @return a {@link BufferedImage} representation of this
143: * <code>VolatileImage</code>
144: * @see BufferedImage
145: */
146: public abstract BufferedImage getSnapshot();
147:
148: /**
149: * Returns the width of the <code>VolatileImage</code>.
150: * @return the width of this <code>VolatileImage</code>.
151: */
152: public abstract int getWidth();
153:
154: /**
155: * Returns the height of the <code>VolatileImage</code>.
156: * @return the height of this <code>VolatileImage</code>.
157: */
158: public abstract int getHeight();
159:
160: // Image overrides
161:
162: /**
163: * This returns an ImageProducer for this VolatileImage.
164: * Note that the VolatileImage object is optimized for
165: * rendering operations and blitting to the screen or other
166: * VolatileImage objects, as opposed to reading back the
167: * pixels of the image. Therefore, operations such as
168: * <code>getSource</code> may not perform as fast as
169: * operations that do not rely on reading the pixels.
170: * Note also that the pixel values read from the image are current
171: * with those in the image only at the time that they are
172: * retrieved. This method takes a snapshot
173: * of the image at the time the request is made and the
174: * ImageProducer object returned works with
175: * that static snapshot image, not the original VolatileImage.
176: * Calling getSource()
177: * is equivalent to calling getSnapshot().getSource().
178: * @return an {@link ImageProducer} that can be used to produce the
179: * pixels for a <code>BufferedImage</code> representation of
180: * this Image.
181: * @see ImageProducer
182: * @see #getSnapshot()
183: */
184: public ImageProducer getSource() {
185: // NOTE: Make sure this functionality is in line with the
186: // spec. In particular, we are returning the Source for a
187: // static image (the snapshot), not a changing image (the
188: // VolatileImage). So if the user expects the Source to be
189: // up-to-date with the current contents of the VolatileImage,
190: // they will be disappointed...
191: // NOTE: This assumes that getSnapshot() returns something
192: // valid and not the default null object returned by this class
193: // (so it assumes that the actual VolatileImage object is
194: // subclassed off something that does the right thing
195: // (e.g., SunVolatileImage).
196: return getSnapshot().getSource();
197: }
198:
199: // NOTE: if we want any decent performance for getScaledInstance(),
200: // we should override the Image implementation of it...
201:
202: /**
203: * Releases system resources currently consumed by this image.
204: * <p>
205: * When a VolatileImage object is created, limited system resources
206: * such as video memory (VRAM) may be allocated in order to
207: * support the image. When a VolatileImage object is no longer
208: * used, it may be garbage-collected and those system resources
209: * will be returned, but this process does
210: * not happen at guaranteed times. Applications that create
211: * many VolatileImage objects (for example, a resizing window
212: * may force recreation of its back buffer as the size
213: * changes) may run out of optimal system
214: * resources for new VolatileImage objects simply because the
215: * old objects have not yet been removed from the system.
216: * (New VolatileImage objects may still be created, but they
217: * may not perform as well as those created in accelerated
218: * memory).
219: * <p>
220: * By calling this flush method, applications can have more control over
221: * the state of the resources taken up by obsolete VolatileImage objects.
222: * <p>
223: * This method will cause the contents of the image to be lost, so
224: * calls to {@link #contentsLost} will return <code>true</code>
225: * and the image must be validated before it can be used again.
226: * @see #contentsLost
227: * @see #validate
228: */
229: public void flush() {
230: }
231:
232: /**
233: * This method returns a {@link Graphics2D}, but is here
234: * for backwards compatibility. {@link #createGraphics() createGraphics} is more
235: * convenient, since it is declared to return a
236: * <code>Graphics2D</code>.
237: * @return a <code>Graphics2D</code>, which can be used to draw into
238: * this image.
239: */
240: public Graphics getGraphics() {
241: return createGraphics();
242: }
243:
244: /**
245: * Creates a <code>Graphics2D</code>, which can be used to draw into
246: * this <code>VolatileImage</code>.
247: * @return a <code>Graphics2D</code>, used for drawing into this
248: * image.
249: */
250: public abstract Graphics2D createGraphics();
251:
252: // Volatile management methods
253:
254: /**
255: * Attempts to restore the drawing surface of the image if the surface
256: * had been lost since the last <code>validate</code> call. Also
257: * validates this image against the given GraphicsConfiguration
258: * parameter to see whether operations from this image to the
259: * GraphicsConfiguration are compatible. An example of an
260: * incompatible combination might be a situation where a VolatileImage
261: * object was created on one graphics device and then was used
262: * to render to a different graphics device. Since VolatileImage
263: * objects tend to be very device-specific, this operation might
264: * not work as intended, so the return code from this validate
265: * call would note that incompatibility. A null or incorrect
266: * value for gc may cause incorrect values to be returned from
267: * <code>validate</code> and may cause later problems with rendering.
268: *
269: * @param gc a <code>GraphicsConfiguration</code> object for this
270: * image to be validated against. A null gc implies that the
271: * validate method should skip the compatibility test.
272: * @return <code>IMAGE_OK</code> if the image did not need validation<BR>
273: * <code>IMAGE_RESTORED</code> if the image needed restoration.
274: * Restoration implies that the contents of the image may have
275: * been affected and the image may need to be re-rendered.<BR>
276: * <code>IMAGE_INCOMPATIBLE</code> if the image is incompatible
277: * with the <code>GraphicsConfiguration</code> object passed
278: * into the <code>validate</code> method. Incompatibility
279: * implies that the image may need to be recreated with a
280: * new <code>Component</code> or
281: * <code>GraphicsConfiguration</code> in order to get an image
282: * that can be used successfully with this
283: * <code>GraphicsConfiguration</code>.
284: * An incompatible image is not checked for whether restoration
285: * was necessary, so the state of the image is unchanged
286: * after a return value of <code>IMAGE_INCOMPATIBLE</code>
287: * and this return value implies nothing about whether the
288: * image needs to be restored.
289: * @see java.awt.GraphicsConfiguration
290: * @see java.awt.Component
291: * @see #IMAGE_OK
292: * @see #IMAGE_RESTORED
293: * @see #IMAGE_INCOMPATIBLE
294: */
295: public abstract int validate(GraphicsConfiguration gc);
296:
297: /**
298: * Returns <code>true</code> if rendering data was lost since last
299: * <code>validate</code> call. This method should be called by the
300: * application at the end of any series of rendering operations to
301: * or from the image to see whether
302: * the image needs to be validated and the rendering redone.
303: * @return <code>true</code> if the drawing surface needs to be restored;
304: * <code>false</code> otherwise.
305: */
306: public abstract boolean contentsLost();
307:
308: /**
309: * Returns an ImageCapabilities object which can be
310: * inquired as to the specific capabilities of this
311: * VolatileImage. This would allow programmers to find
312: * out more runtime information on the specific VolatileImage
313: * object that they have created. For example, the user
314: * might create a VolatileImage but the system may have
315: * no video memory left for creating an image of that
316: * size, so although the object is a VolatileImage, it is
317: * not as accelerated as other VolatileImage objects on
318: * this platform might be. The user might want that
319: * information to find other solutions to their problem.
320: * @return an <code>ImageCapabilities</code> object that contains
321: * the capabilities of this <code>VolatileImage</code>.
322: * @since 1.4
323: */
324: public abstract ImageCapabilities getCapabilities();
325:
326: }
|