Back to index...

	/*
	* Copyright (c) 2000, 2006, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/

	package java.awt.image;

	import java.awt.Color;
	import java.awt.Graphics;
	import java.awt.Graphics2D;
	import java.awt.GraphicsConfiguration;
	import java.awt.GraphicsDevice;
	import java.awt.Image;
	import java.awt.ImageCapabilities;
	import java.awt.Toolkit;
	import java.awt.Transparency;

	/**
	* VolatileImage is an image which can lose its
	* contents at any time due to circumstances beyond the control of the
	* application (e.g., situations caused by the operating system or by
	* other applications). Because of the potential for hardware acceleration,
	* a VolatileImage object can have significant performance benefits on
	* some platforms.
	* <p>
	* The drawing surface of an image (the memory where the image contents
	* actually reside) can be lost or invalidated, causing the contents of that
	* memory to go away. The drawing surface thus needs to be restored
	* or recreated and the contents of that surface need to be
	* re-rendered. VolatileImage provides an interface for
	* allowing the user to detect these problems and fix them
	* when they occur.
	* <p>
	* When a VolatileImage object is created, limited system resources
	* such as video memory (VRAM) may be allocated in order to support
	* the image.
	* When a VolatileImage object is no longer used, it may be
	* garbage-collected and those system resources will be returned,
	* but this process does not happen at guaranteed times.
	* Applications that create many VolatileImage objects (for example,
	* a resizing window may force recreation of its back buffer as the
	* size changes) may run out of optimal system resources for new
	* VolatileImage objects simply because the old objects have not
	* yet been removed from the system.
	* (New VolatileImage objects may still be created, but they
	* may not perform as well as those created in accelerated
	* memory).
	* The flush method may be called at any time to proactively release
	* the resources used by a VolatileImage so that it does not prevent
	* subsequent VolatileImage objects from being accelerated.
	* In this way, applications can have more control over the state
	* of the resources taken up by obsolete VolatileImage objects.
	* <p>
	* This image should not be subclassed directly but should be created
	* by using the {@link java.awt.Component#createVolatileImage(int, int)
	* Component.createVolatileImage} or
	* {@link java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int, int)
	* GraphicsConfiguration.createCompatibleVolatileImage(int, int)} methods.
	* <P>
	* An example of using a VolatileImage object follows:
	* <pre>
	* // image creation
	* VolatileImage vImg = createVolatileImage(w, h);
	*
	*
	* // rendering to the image
	* void renderOffscreen() {
	* do {
	* if (vImg.validate(getGraphicsConfiguration()) ==
	* VolatileImage.IMAGE_INCOMPATIBLE)
	* {
	* // old vImg doesn't work with new GraphicsConfig; re-create it
	* vImg = createVolatileImage(w, h);
	* }
	* Graphics2D g = vImg.createGraphics();
	* //
	* // miscellaneous rendering commands...
	* //
	* g.dispose();
	* } while (vImg.contentsLost());
	* }
	*
	*
	* // copying from the image (here, gScreen is the Graphics
	* // object for the onscreen window)
	* do {
	* int returnCode = vImg.validate(getGraphicsConfiguration());
	* if (returnCode == VolatileImage.IMAGE_RESTORED) {
	* // Contents need to be restored
	* renderOffscreen(); // restore contents
	* } else if (returnCode == VolatileImage.IMAGE_INCOMPATIBLE) {
	* // old vImg doesn't work with new GraphicsConfig; re-create it
	* vImg = createVolatileImage(w, h);
	* renderOffscreen();
	* }
	* gScreen.drawImage(vImg, 0, 0, this);
	* } while (vImg.contentsLost());
	* </pre>
	* <P>
	* Note that this class subclasses from the {@link Image} class, which
	* includes methods that take an {@link ImageObserver} parameter for
	* asynchronous notifications as information is received from
	* a potential {@link ImageProducer}. Since this <code>VolatileImage</code>
	* is not loaded from an asynchronous source, the various methods that take
	* an <code>ImageObserver</code> parameter will behave as if the data has
	* already been obtained from the <code>ImageProducer</code>.
	* Specifically, this means that the return values from such methods
	* will never indicate that the information is not yet available and
	* the <code>ImageObserver</code> used in such methods will never
	* need to be recorded for an asynchronous callback notification.
	* @since 1.4
	*/
	public abstract class VolatileImage extends Image implements Transparency
	{

	// Return codes for validate() method

	/**
	* Validated image is ready to use as-is.
	*/
	public static final int IMAGE_OK = 0;

	/**
	* Validated image has been restored and is now ready to use.
	* Note that restoration causes contents of the image to be lost.
	*/
	public static final int IMAGE_RESTORED = 1;

	/**
	* Validated image is incompatible with supplied
	* <code>GraphicsConfiguration</code> object and should be
	* re-created as appropriate. Usage of the image as-is
	* after receiving this return code from <code>validate</code>
	* is undefined.
	*/
	public static final int IMAGE_INCOMPATIBLE = 2;

	/**
	* Returns a static snapshot image of this object. The
	* <code>BufferedImage</code> returned is only current with
	* the <code>VolatileImage</code> at the time of the request
	* and will not be updated with any future changes to the
	* <code>VolatileImage</code>.
	* @return a {@link BufferedImage} representation of this
	* <code>VolatileImage</code>
	* @see BufferedImage
	*/
	public abstract BufferedImage getSnapshot();

	/**
	* Returns the width of the <code>VolatileImage</code>.
	* @return the width of this <code>VolatileImage</code>.
	*/
	public abstract int getWidth();

	/**
	* Returns the height of the <code>VolatileImage</code>.
	* @return the height of this <code>VolatileImage</code>.
	*/
	public abstract int getHeight();

	// Image overrides

	/**
	* This returns an ImageProducer for this VolatileImage.
	* Note that the VolatileImage object is optimized for
	* rendering operations and blitting to the screen or other
	* VolatileImage objects, as opposed to reading back the
	* pixels of the image. Therefore, operations such as
	* <code>getSource</code> may not perform as fast as
	* operations that do not rely on reading the pixels.
	* Note also that the pixel values read from the image are current
	* with those in the image only at the time that they are
	* retrieved. This method takes a snapshot
	* of the image at the time the request is made and the
	* ImageProducer object returned works with
	* that static snapshot image, not the original VolatileImage.
	* Calling getSource()
	* is equivalent to calling getSnapshot().getSource().
	* @return an {@link ImageProducer} that can be used to produce the
	* pixels for a <code>BufferedImage</code> representation of
	* this Image.
	* @see ImageProducer
	* @see #getSnapshot()
	*/
	public ImageProducer getSource() {
	// REMIND: Make sure this functionality is in line with the
	// spec. In particular, we are returning the Source for a
	// static image (the snapshot), not a changing image (the
	// VolatileImage). So if the user expects the Source to be
	// up-to-date with the current contents of the VolatileImage,
	// they will be disappointed...
	// REMIND: This assumes that getSnapshot() returns something
	// valid and not the default null object returned by this class
	// (so it assumes that the actual VolatileImage object is
	// subclassed off something that does the right thing
	// (e.g., SunVolatileImage).
	return getSnapshot().getSource();
	}

	// REMIND: if we want any decent performance for getScaledInstance(),
	// we should override the Image implementation of it...

	/**
	* This method returns a {@link Graphics2D}, but is here
	* for backwards compatibility. {@link #createGraphics() createGraphics} is more
	* convenient, since it is declared to return a
	* <code>Graphics2D</code>.
	* @return a <code>Graphics2D</code>, which can be used to draw into
	* this image.
	*/
	public Graphics getGraphics() {
	return createGraphics();
	}

	/**
	* Creates a <code>Graphics2D</code>, which can be used to draw into
	* this <code>VolatileImage</code>.
	* @return a <code>Graphics2D</code>, used for drawing into this
	* image.
	*/
	public abstract Graphics2D createGraphics();


	// Volatile management methods

	/**
	* Attempts to restore the drawing surface of the image if the surface
	* had been lost since the last <code>validate</code> call. Also
	* validates this image against the given GraphicsConfiguration
	* parameter to see whether operations from this image to the
	* GraphicsConfiguration are compatible. An example of an
	* incompatible combination might be a situation where a VolatileImage
	* object was created on one graphics device and then was used
	* to render to a different graphics device. Since VolatileImage
	* objects tend to be very device-specific, this operation might
	* not work as intended, so the return code from this validate
	* call would note that incompatibility. A null or incorrect
	* value for gc may cause incorrect values to be returned from
	* <code>validate</code> and may cause later problems with rendering.
	*
	* @param gc a <code>GraphicsConfiguration</code> object for this
	* image to be validated against. A null gc implies that the
	* validate method should skip the compatibility test.
	* @return <code>IMAGE_OK</code> if the image did not need validation<BR>
	* <code>IMAGE_RESTORED</code> if the image needed restoration.
	* Restoration implies that the contents of the image may have
	* been affected and the image may need to be re-rendered.<BR>
	* <code>IMAGE_INCOMPATIBLE</code> if the image is incompatible
	* with the <code>GraphicsConfiguration</code> object passed
	* into the <code>validate</code> method. Incompatibility
	* implies that the image may need to be recreated with a
	* new <code>Component</code> or
	* <code>GraphicsConfiguration</code> in order to get an image
	* that can be used successfully with this
	* <code>GraphicsConfiguration</code>.
	* An incompatible image is not checked for whether restoration
	* was necessary, so the state of the image is unchanged
	* after a return value of <code>IMAGE_INCOMPATIBLE</code>
	* and this return value implies nothing about whether the
	* image needs to be restored.
	* @see java.awt.GraphicsConfiguration
	* @see java.awt.Component
	* @see #IMAGE_OK
	* @see #IMAGE_RESTORED
	* @see #IMAGE_INCOMPATIBLE
	*/
	public abstract int validate(GraphicsConfiguration gc);

	/**
	* Returns <code>true</code> if rendering data was lost since last
	* <code>validate</code> call. This method should be called by the
	* application at the end of any series of rendering operations to
	* or from the image to see whether
	* the image needs to be validated and the rendering redone.
	* @return <code>true</code> if the drawing surface needs to be restored;
	* <code>false</code> otherwise.
	*/
	public abstract boolean contentsLost();

	/**
	* Returns an ImageCapabilities object which can be
	* inquired as to the specific capabilities of this
	* VolatileImage. This would allow programmers to find
	* out more runtime information on the specific VolatileImage
	* object that they have created. For example, the user
	* might create a VolatileImage but the system may have
	* no video memory left for creating an image of that
	* size, so although the object is a VolatileImage, it is
	* not as accelerated as other VolatileImage objects on
	* this platform might be. The user might want that
	* information to find other solutions to their problem.
	* @return an <code>ImageCapabilities</code> object that contains
	* the capabilities of this <code>VolatileImage</code>.
	* @since 1.4
	*/
	public abstract ImageCapabilities getCapabilities();

	/**
	* The transparency value with which this image was created.
	* @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int,
	* int,int)
	* @see java.awt.GraphicsConfiguration#createCompatibleVolatileImage(int,
	* int,ImageCapabilities,int)
	* @see Transparency
	* @since 1.5
	*/
	protected int transparency = TRANSLUCENT;

	/**
	* Returns the transparency. Returns either OPAQUE, BITMASK,
	* or TRANSLUCENT.
	* @return the transparency of this <code>VolatileImage</code>.
	* @see Transparency#OPAQUE
	* @see Transparency#BITMASK
	* @see Transparency#TRANSLUCENT
	* @since 1.5
	*/
	public int getTransparency() {
	return transparency;
	}
	}

Back to index...