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