Java Doc for VolatileImage.java in  » 6.0-JDK-Modules » j2me » java » awt » image » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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.

This image should not be subclassed directly but should be created by using the java.awt.Component.createVolatileImage(intint)Component.createVolatileImage or java.awt.GraphicsConfiguration.createCompatibleVolatileImage(intint)GraphicsConfiguration.createCompatibleVolatileImage(int, int) methods.

An example of using a VolatileImage object follows:

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

Note that this class subclasses from the Image class, which includes methods that take an ImageObserver parameter for asynchronous notifications as information is received from a potential ImageProducer . Since this VolatileImage is not loaded from an asynchronous source, the various methods that take an ImageObserver parameter will behave as if the data has already been obtained from the ImageProducer. Specifically, this means that the return values from such methods will never indicate that the information is not yet available and the ImageObserver used in such methods will never need to be recorded for an asynchronous callback notification.

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 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 VolatileImage.contentsLost will return true and the image must be validated before it can be used again.
See Also:   VolatileImage.contentsLost
See Also:   VolatileImage.validate