File	Doc	Category	Size	Date	Package
VolatileImage.java	API Doc	Java SE 5 API	13748	Fri Aug 26 14:56:54 BST 2005	java.awt.image

VolatileImage

• java.lang.Object
  • java.awt.Image

// 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());

Fields Summary
public static final int	IMAGE_OK Validated image is ready to use as-is.
public static final int	IMAGE_RESTORED 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_INCOMPATIBLE Validated image is incompatible with supplied GraphicsConfiguration object and should be re-created as appropriate. Usage of the image as-is after receiving this return code from validate is undefined.
protected int	transparency The transparency value with which this image was created.

Constructors Summary

Methods Summary
public abstract boolean	contentsLost() Returns true if rendering data was lost since last validate 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 true if the drawing surface needs to be restored; false otherwise.
public abstract java.awt.Graphics2D	createGraphics() Creates a Graphics2D, which can be used to draw into this VolatileImage. return a Graphics2D, used for drawing into this image.
public void	flush() Releases system resources currently consumed by this image. 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). By calling this flush method, applications can have more control over the state of the resources taken up by obsolete VolatileImage objects. This method will cause the contents of the image to be lost, so calls to {@link #contentsLost} will return true and the image must be validated before it can be used again. see #contentsLost see #validate
public abstract java.awt.ImageCapabilities	getCapabilities() 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 ImageCapabilities object that contains the capabilities of this VolatileImage. since 1.4
public java.awt.Graphics	getGraphics() 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 Graphics2D. return a Graphics2D, which can be used to draw into this image. return createGraphics();
public abstract int	getHeight() Returns the height of the VolatileImage. return the height of this VolatileImage.
public abstract java.awt.image.BufferedImage	getSnapshot() Returns a static snapshot image of this object. The BufferedImage returned is only current with the VolatileImage at the time of the request and will not be updated with any future changes to the VolatileImage. return a {@link BufferedImage} representation of this VolatileImage see BufferedImage
public java.awt.image.ImageProducer	getSource() 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 getSource 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 BufferedImage representation of this Image. see ImageProducer see #getSnapshot() // Image overrides // 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();
public int	getTransparency() Returns the transparency. Returns either OPAQUE, BITMASK, or TRANSLUCENT. return the transparency of this VolatileImage. see Transparency#OPAQUE see Transparency#BITMASK see Transparency#TRANSLUCENT since 1.5 return transparency;
public abstract int	getWidth() Returns the width of the VolatileImage. return the width of this VolatileImage.
public abstract int	validate(java.awt.GraphicsConfiguration gc) Attempts to restore the drawing surface of the image if the surface had been lost since the last validate 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 validate and may cause later problems with rendering. param gc a GraphicsConfiguration object for this image to be validated against. A null gc implies that the validate method should skip the compatibility test. return IMAGE_OK if the image did not need validation IMAGE_RESTORED 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. IMAGE_INCOMPATIBLE if the image is incompatible with the GraphicsConfiguration object passed into the validate method. Incompatibility implies that the image may need to be recreated with a new Component or GraphicsConfiguration in order to get an image that can be used successfully with this GraphicsConfiguration. An incompatible image is not checked for whether restoration was necessary, so the state of the image is unchanged after a return value of IMAGE_INCOMPATIBLE 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