2362N/A * Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved. 0N/A * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 0N/A * This code is free software; you can redistribute it and/or modify it 0N/A * under the terms of the GNU General Public License version 2 only, as 2362N/A * published by the Free Software Foundation. Oracle designates this 0N/A * particular file as subject to the "Classpath" exception as provided 2362N/A * by Oracle in the LICENSE file that accompanied this code. 0N/A * This code is distributed in the hope that it will be useful, but WITHOUT 0N/A * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 0N/A * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 0N/A * version 2 for more details (a copy is included in the LICENSE file that 0N/A * accompanied this code). 0N/A * You should have received a copy of the GNU General Public License version 0N/A * 2 along with this work; if not, write to the Free Software Foundation, 0N/A * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2362N/A * or visit www.oracle.com if you need additional information or have any 0N/A * VolatileImage is an image which can lose its 0N/A * contents at any time due to circumstances beyond the control of the 0N/A * application (e.g., situations caused by the operating system or by 0N/A * other applications). Because of the potential for hardware acceleration, 0N/A * a VolatileImage object can have significant performance benefits on 0N/A * The drawing surface of an image (the memory where the image contents 0N/A * actually reside) can be lost or invalidated, causing the contents of that 0N/A * memory to go away. The drawing surface thus needs to be restored 0N/A * or recreated and the contents of that surface need to be 0N/A * re-rendered. VolatileImage provides an interface for 0N/A * allowing the user to detect these problems and fix them 0N/A * When a VolatileImage object is created, limited system resources 0N/A * such as video memory (VRAM) may be allocated in order to support 0N/A * When a VolatileImage object is no longer used, it may be 0N/A * garbage-collected and those system resources will be returned, 0N/A * but this process does not happen at guaranteed times. 0N/A * Applications that create many VolatileImage objects (for example, 0N/A * a resizing window may force recreation of its back buffer as the 0N/A * size changes) may run out of optimal system resources for new 0N/A * VolatileImage objects simply because the old objects have not 0N/A * yet been removed from the system. 0N/A * (New VolatileImage objects may still be created, but they 0N/A * may not perform as well as those created in accelerated 0N/A * The flush method may be called at any time to proactively release 0N/A * the resources used by a VolatileImage so that it does not prevent 0N/A * subsequent VolatileImage objects from being accelerated. 0N/A * In this way, applications can have more control over the state 0N/A * of the resources taken up by obsolete VolatileImage objects. 0N/A * This image should not be subclassed directly but should be created 0N/A * by using the {@link java.awt.Component#createVolatileImage(int, int) 0N/A * Component.createVolatileImage} or 0N/A * {@link java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int, int) 0N/A * GraphicsConfiguration.createCompatibleVolatileImage(int, int)} methods. 0N/A * An example of using a VolatileImage object follows: 0N/A * VolatileImage vImg = createVolatileImage(w, h); 0N/A * // rendering to the image 0N/A * void renderOffscreen() { 0N/A * if (vImg.validate(getGraphicsConfiguration()) == 0N/A * VolatileImage.IMAGE_INCOMPATIBLE) 0N/A * // old vImg doesn't work with new GraphicsConfig; re-create it 0N/A * vImg = createVolatileImage(w, h); 0N/A * Graphics2D g = vImg.createGraphics(); 0N/A * // miscellaneous rendering commands... 0N/A * } while (vImg.contentsLost()); 0N/A * // copying from the image (here, gScreen is the Graphics 0N/A * // object for the onscreen window) 0N/A * int returnCode = vImg.validate(getGraphicsConfiguration()); 0N/A * if (returnCode == VolatileImage.IMAGE_RESTORED) { 0N/A * // Contents need to be restored 0N/A * renderOffscreen(); // restore contents 0N/A * } else if (returnCode == VolatileImage.IMAGE_INCOMPATIBLE) { 0N/A * // old vImg doesn't work with new GraphicsConfig; re-create it 0N/A * vImg = createVolatileImage(w, h); 0N/A * renderOffscreen(); 0N/A * gScreen.drawImage(vImg, 0, 0, this); 0N/A * } while (vImg.contentsLost()); 0N/A * Note that this class subclasses from the {@link Image} class, which 0N/A * includes methods that take an {@link ImageObserver} parameter for 0N/A * asynchronous notifications as information is received from 0N/A * a potential {@link ImageProducer}. Since this <code>VolatileImage</code> 0N/A * is not loaded from an asynchronous source, the various methods that take 0N/A * an <code>ImageObserver</code> parameter will behave as if the data has 0N/A * already been obtained from the <code>ImageProducer</code>. 0N/A * Specifically, this means that the return values from such methods 0N/A * will never indicate that the information is not yet available and 0N/A * the <code>ImageObserver</code> used in such methods will never 0N/A * need to be recorded for an asynchronous callback notification. 0N/A // Return codes for validate() method 0N/A * Validated image is ready to use as-is. 0N/A * Validated image has been restored and is now ready to use. 0N/A * Note that restoration causes contents of the image to be lost. 0N/A * Validated image is incompatible with supplied 0N/A * <code>GraphicsConfiguration</code> object and should be 0N/A * re-created as appropriate. Usage of the image as-is 0N/A * after receiving this return code from <code>validate</code> 0N/A * Returns a static snapshot image of this object. The 0N/A * <code>BufferedImage</code> returned is only current with 0N/A * the <code>VolatileImage</code> at the time of the request 0N/A * and will not be updated with any future changes to the 0N/A * <code>VolatileImage</code>. 0N/A * @return a {@link BufferedImage} representation of this 0N/A * <code>VolatileImage</code> 0N/A * @see BufferedImage 0N/A * Returns the width of the <code>VolatileImage</code>. 0N/A * @return the width of this <code>VolatileImage</code>. 0N/A * Returns the height of the <code>VolatileImage</code>. 0N/A * @return the height of this <code>VolatileImage</code>. 0N/A * This returns an ImageProducer for this VolatileImage. 0N/A * Note that the VolatileImage object is optimized for 0N/A * rendering operations and blitting to the screen or other 0N/A * VolatileImage objects, as opposed to reading back the 0N/A * pixels of the image. Therefore, operations such as 0N/A * <code>getSource</code> may not perform as fast as 0N/A * operations that do not rely on reading the pixels. 0N/A * Note also that the pixel values read from the image are current 0N/A * with those in the image only at the time that they are 0N/A * retrieved. This method takes a snapshot 0N/A * of the image at the time the request is made and the 0N/A * ImageProducer object returned works with 0N/A * that static snapshot image, not the original VolatileImage. 0N/A * Calling getSource() 0N/A * is equivalent to calling getSnapshot().getSource(). 0N/A * @return an {@link ImageProducer} that can be used to produce the 0N/A * pixels for a <code>BufferedImage</code> representation of 0N/A * @see ImageProducer 0N/A * @see #getSnapshot() 0N/A // REMIND: Make sure this functionality is in line with the 0N/A // spec. In particular, we are returning the Source for a 0N/A // static image (the snapshot), not a changing image (the 0N/A // VolatileImage). So if the user expects the Source to be 0N/A // up-to-date with the current contents of the VolatileImage, 0N/A // they will be disappointed... 0N/A // REMIND: This assumes that getSnapshot() returns something 0N/A // valid and not the default null object returned by this class 0N/A // (so it assumes that the actual VolatileImage object is 0N/A // subclassed off something that does the right thing 0N/A // (e.g., SunVolatileImage). 0N/A // REMIND: if we want any decent performance for getScaledInstance(), 0N/A // we should override the Image implementation of it... 0N/A * This method returns a {@link Graphics2D}, but is here 0N/A * for backwards compatibility. {@link #createGraphics() createGraphics} is more 0N/A * convenient, since it is declared to return a 0N/A * <code>Graphics2D</code>. 0N/A * @return a <code>Graphics2D</code>, which can be used to draw into 0N/A * Creates a <code>Graphics2D</code>, which can be used to draw into 0N/A * this <code>VolatileImage</code>. 0N/A * @return a <code>Graphics2D</code>, used for drawing into this 0N/A // Volatile management methods 0N/A * Attempts to restore the drawing surface of the image if the surface 0N/A * had been lost since the last <code>validate</code> call. Also 0N/A * validates this image against the given GraphicsConfiguration 0N/A * parameter to see whether operations from this image to the 0N/A * GraphicsConfiguration are compatible. An example of an 0N/A * incompatible combination might be a situation where a VolatileImage 0N/A * object was created on one graphics device and then was used 0N/A * to render to a different graphics device. Since VolatileImage 0N/A * objects tend to be very device-specific, this operation might 0N/A * not work as intended, so the return code from this validate 0N/A * call would note that incompatibility. A null or incorrect 0N/A * value for gc may cause incorrect values to be returned from 0N/A * <code>validate</code> and may cause later problems with rendering. 0N/A * @param gc a <code>GraphicsConfiguration</code> object for this 0N/A * image to be validated against. A null gc implies that the 0N/A * validate method should skip the compatibility test. 0N/A * @return <code>IMAGE_OK</code> if the image did not need validation<BR> 0N/A * <code>IMAGE_RESTORED</code> if the image needed restoration. 0N/A * Restoration implies that the contents of the image may have 0N/A * been affected and the image may need to be re-rendered.<BR> 0N/A * <code>IMAGE_INCOMPATIBLE</code> if the image is incompatible 0N/A * with the <code>GraphicsConfiguration</code> object passed 0N/A * into the <code>validate</code> method. Incompatibility 0N/A * implies that the image may need to be recreated with a 0N/A * new <code>Component</code> or 0N/A * <code>GraphicsConfiguration</code> in order to get an image 0N/A * that can be used successfully with this 0N/A * <code>GraphicsConfiguration</code>. 0N/A * An incompatible image is not checked for whether restoration 0N/A * was necessary, so the state of the image is unchanged 0N/A * after a return value of <code>IMAGE_INCOMPATIBLE</code> 0N/A * and this return value implies nothing about whether the 0N/A * image needs to be restored. 0N/A * @see java.awt.GraphicsConfiguration 0N/A * @see java.awt.Component 0N/A * @see #IMAGE_RESTORED 0N/A * @see #IMAGE_INCOMPATIBLE 0N/A * Returns <code>true</code> if rendering data was lost since last 0N/A * <code>validate</code> call. This method should be called by the 0N/A * application at the end of any series of rendering operations to 0N/A * or from the image to see whether 0N/A * the image needs to be validated and the rendering redone. 0N/A * @return <code>true</code> if the drawing surface needs to be restored; 0N/A * <code>false</code> otherwise. 0N/A * Returns an ImageCapabilities object which can be 0N/A * inquired as to the specific capabilities of this 0N/A * VolatileImage. This would allow programmers to find 0N/A * out more runtime information on the specific VolatileImage 0N/A * object that they have created. For example, the user 0N/A * might create a VolatileImage but the system may have 0N/A * no video memory left for creating an image of that 0N/A * size, so although the object is a VolatileImage, it is 0N/A * not as accelerated as other VolatileImage objects on 0N/A * this platform might be. The user might want that 0N/A * information to find other solutions to their problem. 0N/A * @return an <code>ImageCapabilities</code> object that contains 0N/A * the capabilities of this <code>VolatileImage</code>. 0N/A * The transparency value with which this image was created. 0N/A * @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int, 0N/A * @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int, 0N/A * int,ImageCapabilities,int) 0N/A * Returns the transparency. Returns either OPAQUE, BITMASK, 0N/A * @return the transparency of this <code>VolatileImage</code>. 0N/A * @see Transparency#OPAQUE 0N/A * @see Transparency#BITMASK 0N/A * @see Transparency#TRANSLUCENT