java.awt.image
Class VolatileImage

java.lang.Object sample code for java.lang.Object definition code for java.lang.Object 
  extended by java.awt.Image sample code for java.awt.Image definition code for java.awt.Image 
      extended by java.awt.image.VolatileImage
All Implemented Interfaces:
Transparency sample code for java.awt.Transparency definition code for java.awt.Transparency

public abstract class VolatileImage
extends Image sample code for java.awt.Image definition code for java.awt.Image
implements Transparency sample code for java.awt.Transparency definition code for 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.

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 Component.createVolatileImage sample code for java.awt.Component.createVolatileImage(int, int) definition code for java.awt.Component.createVolatileImage(int, int) or GraphicsConfiguration.createCompatibleVolatileImage(int, int) sample code for java.awt.GraphicsConfiguration.createCompatibleVolatileImage(int, int) definition code for java.awt.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 sample code for java.awt.Image definition code for java.awt.Image class, which includes methods that take an ImageObserver sample code for java.awt.image.ImageObserver definition code for java.awt.image.ImageObserver parameter for asynchronous notifications as information is received from a potential ImageProducer sample code for java.awt.image.ImageProducer definition code for java.awt.image.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.


Field Summary
static int IMAGE_INCOMPATIBLE sample code for java.awt.image.VolatileImage.IMAGE_INCOMPATIBLE definition code for java.awt.image.VolatileImage.IMAGE_INCOMPATIBLE
          Validated image is incompatible with supplied GraphicsConfiguration object and should be re-created as appropriate.
static int IMAGE_OK sample code for java.awt.image.VolatileImage.IMAGE_OK definition code for java.awt.image.VolatileImage.IMAGE_OK
          Validated image is ready to use as-is.
static int IMAGE_RESTORED sample code for java.awt.image.VolatileImage.IMAGE_RESTORED definition code for java.awt.image.VolatileImage.IMAGE_RESTORED
          Validated image has been restored and is now ready to use.
protected  int transparency sample code for java.awt.image.VolatileImage.transparency definition code for java.awt.image.VolatileImage.transparency
          The transparency value with which this image was created.
 
Fields inherited from class java.awt.Image sample code for java.awt.Image definition code for java.awt.Image
accelerationPriority sample code for java.awt.Image.accelerationPriority definition code for java.awt.Image.accelerationPriority , SCALE_AREA_AVERAGING sample code for java.awt.Image.SCALE_AREA_AVERAGING definition code for java.awt.Image.SCALE_AREA_AVERAGING , SCALE_DEFAULT sample code for java.awt.Image.SCALE_DEFAULT definition code for java.awt.Image.SCALE_DEFAULT , SCALE_FAST sample code for java.awt.Image.SCALE_FAST definition code for java.awt.Image.SCALE_FAST , SCALE_REPLICATE sample code for java.awt.Image.SCALE_REPLICATE definition code for java.awt.Image.SCALE_REPLICATE , SCALE_SMOOTH sample code for java.awt.Image.SCALE_SMOOTH definition code for java.awt.Image.SCALE_SMOOTH , UndefinedProperty sample code for java.awt.Image.UndefinedProperty definition code for java.awt.Image.UndefinedProperty
 
Fields inherited from interface java.awt.Transparency sample code for java.awt.Transparency definition code for java.awt.Transparency
BITMASK sample code for java.awt.Transparency.BITMASK definition code for java.awt.Transparency.BITMASK , OPAQUE sample code for java.awt.Transparency.OPAQUE definition code for java.awt.Transparency.OPAQUE , TRANSLUCENT sample code for java.awt.Transparency.TRANSLUCENT definition code for java.awt.Transparency.TRANSLUCENT
 
Constructor Summary
VolatileImage sample code for java.awt.image.VolatileImage.VolatileImage() definition code for java.awt.image.VolatileImage.VolatileImage() ()
           
 
Method Summary
abstract  boolean contentsLost sample code for java.awt.image.VolatileImage.contentsLost() definition code for java.awt.image.VolatileImage.contentsLost() ()
          Returns true if rendering data was lost since last validate call.
abstract  Graphics2D sample code for java.awt.Graphics2D definition code for java.awt.Graphics2D createGraphics sample code for java.awt.image.VolatileImage.createGraphics() definition code for java.awt.image.VolatileImage.createGraphics() ()
          Creates a Graphics2D, which can be used to draw into this VolatileImage.
 void flush sample code for java.awt.image.VolatileImage.flush() definition code for java.awt.image.VolatileImage.flush() ()
          Releases system resources currently consumed by this image.
abstract  ImageCapabilities sample code for java.awt.ImageCapabilities definition code for java.awt.ImageCapabilities getCapabilities sample code for java.awt.image.VolatileImage.getCapabilities() definition code for java.awt.image.VolatileImage.getCapabilities() ()
          Returns an ImageCapabilities object which can be inquired as to the specific capabilities of this VolatileImage.
 Graphics sample code for java.awt.Graphics definition code for java.awt.Graphics getGraphics sample code for java.awt.image.VolatileImage.getGraphics() definition code for java.awt.image.VolatileImage.getGraphics() ()
          This method returns a Graphics2D sample code for java.awt.Graphics2D definition code for java.awt.Graphics2D , but is here for backwards compatibility.
abstract  int getHeight sample code for java.awt.image.VolatileImage.getHeight() definition code for java.awt.image.VolatileImage.getHeight() ()
          Returns the height of the VolatileImage.
abstract  BufferedImage sample code for java.awt.image.BufferedImage definition code for java.awt.image.BufferedImage getSnapshot sample code for java.awt.image.VolatileImage.getSnapshot() definition code for java.awt.image.VolatileImage.getSnapshot() ()
          Returns a static snapshot image of this object.
 ImageProducer sample code for java.awt.image.ImageProducer definition code for java.awt.image.ImageProducer getSource sample code for java.awt.image.VolatileImage.getSource() definition code for java.awt.image.VolatileImage.getSource() ()
          This returns an ImageProducer for this VolatileImage.
 int getTransparency sample code for java.awt.image.VolatileImage.getTransparency() definition code for java.awt.image.VolatileImage.getTransparency() ()
          Returns the transparency.
abstract  int getWidth sample code for java.awt.image.VolatileImage.getWidth() definition code for java.awt.image.VolatileImage.getWidth() ()
          Returns the width of the VolatileImage.
abstract  int validate sample code for java.awt.image.VolatileImage.validate(java.awt.GraphicsConfiguration) definition code for java.awt.image.VolatileImage.validate(java.awt.GraphicsConfiguration) (GraphicsConfiguration sample code for java.awt.GraphicsConfiguration definition code for java.awt.GraphicsConfiguration  gc)
          Attempts to restore the drawing surface of the image if the surface had been lost since the last validate call.
 
Methods inherited from class java.awt.Image sample code for java.awt.Image definition code for java.awt.Image
getAccelerationPriority sample code for java.awt.Image.getAccelerationPriority() definition code for java.awt.Image.getAccelerationPriority() , getCapabilities sample code for java.awt.Image.getCapabilities(java.awt.GraphicsConfiguration) definition code for java.awt.Image.getCapabilities(java.awt.GraphicsConfiguration) , getHeight sample code for java.awt.Image.getHeight(java.awt.image.ImageObserver) definition code for java.awt.Image.getHeight(java.awt.image.ImageObserver) , getProperty sample code for java.awt.Image.getProperty(java.lang.String, java.awt.image.ImageObserver) definition code for java.awt.Image.getProperty(java.lang.String, java.awt.image.ImageObserver) , getScaledInstance sample code for java.awt.Image.getScaledInstance(int, int, int) definition code for java.awt.Image.getScaledInstance(int, int, int) , getWidth sample code for java.awt.Image.getWidth(java.awt.image.ImageObserver) definition code for java.awt.Image.getWidth(java.awt.image.ImageObserver) , setAccelerationPriority sample code for java.awt.Image.setAccelerationPriority(float) definition code for java.awt.Image.setAccelerationPriority(float)
 
Methods inherited from class java.lang.Object sample code for java.lang.Object definition code for java.lang.Object
clone sample code for java.lang.Object.clone() definition code for java.lang.Object.clone() , equals sample code for java.lang.Object.equals(java.lang.Object) definition code for java.lang.Object.equals(java.lang.Object) , finalize sample code for java.lang.Object.finalize() definition code for java.lang.Object.finalize() , getClass sample code for java.lang.Object.getClass() definition code for java.lang.Object.getClass() , hashCode sample code for java.lang.Object.hashCode() definition code for java.lang.Object.hashCode() , notify sample code for java.lang.Object.notify() definition code for java.lang.Object.notify() , notifyAll sample code for java.lang.Object.notifyAll() definition code for java.lang.Object.notifyAll() , toString sample code for java.lang.Object.toString() definition code for java.lang.Object.toString() , wait sample code for java.lang.Object.wait() definition code for java.lang.Object.wait() , wait sample code for java.lang.Object.wait(long) definition code for java.lang.Object.wait(long) , wait sample code for java.lang.Object.wait(long, int) definition code for java.lang.Object.wait(long, int)
 

Field Detail

IMAGE_OK sample code for java.awt.image.VolatileImage.IMAGE_OK

public static final int IMAGE_OK
Validated image is ready to use as-is.

See Also:
Constant Field Values

IMAGE_RESTORED sample code for java.awt.image.VolatileImage.IMAGE_RESTORED

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.

See Also:
Constant Field Values

IMAGE_INCOMPATIBLE sample code for java.awt.image.VolatileImage.IMAGE_INCOMPATIBLE

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.

See Also:
Constant Field Values

transparency sample code for java.awt.image.VolatileImage.transparency

protected int transparency
The transparency value with which this image was created.

Since:
1.5
See Also:
GraphicsConfiguration.createCompatibleVolatileImage(int, int,int) sample code for java.awt.GraphicsConfiguration.createCompatibleVolatileImage(int, int, int) definition code for java.awt.GraphicsConfiguration.createCompatibleVolatileImage(int, int, int) , GraphicsConfiguration.createCompatibleVolatileImage(int, int,ImageCapabilities,int) sample code for java.awt.GraphicsConfiguration.createCompatibleVolatileImage(int, int, java.awt.ImageCapabilities, int) definition code for java.awt.GraphicsConfiguration.createCompatibleVolatileImage(int, int, java.awt.ImageCapabilities, int) , Transparency sample code for java.awt.Transparency definition code for java.awt.Transparency
Constructor Detail

VolatileImage sample code for java.awt.image.VolatileImage() definition code for java.awt.image.VolatileImage()

public VolatileImage()
Method Detail

getSnapshot sample code for java.awt.image.VolatileImage.getSnapshot() definition code for java.awt.image.VolatileImage.getSnapshot()

public abstract BufferedImage sample code for java.awt.image.BufferedImage definition code for 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.

Returns:
a BufferedImage sample code for java.awt.image.BufferedImage definition code for java.awt.image.BufferedImage representation of this VolatileImage
See Also:
BufferedImage sample code for java.awt.image.BufferedImage definition code for java.awt.image.BufferedImage

getWidth sample code for java.awt.image.VolatileImage.getWidth() definition code for java.awt.image.VolatileImage.getWidth()

public abstract int getWidth()
Returns the width of the VolatileImage.

Returns:
the width of this VolatileImage.

getHeight sample code for java.awt.image.VolatileImage.getHeight() definition code for java.awt.image.VolatileImage.getHeight()

public abstract int getHeight()
Returns the height of the VolatileImage.

Returns:
the height of this VolatileImage.

getSource sample code for java.awt.image.VolatileImage.getSource() definition code for java.awt.image.VolatileImage.getSource()

public ImageProducer sample code for java.awt.image.ImageProducer definition code for 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().

Specified by:
getSource sample code for java.awt.Image.getSource() definition code for java.awt.Image.getSource() in class Image sample code for java.awt.Image definition code for java.awt.Image
Returns:
an ImageProducer sample code for java.awt.image.ImageProducer definition code for java.awt.image.ImageProducer that can be used to produce the pixels for a BufferedImage representation of this Image.
See Also:
ImageProducer sample code for java.awt.image.ImageProducer definition code for java.awt.image.ImageProducer , getSnapshot() sample code for java.awt.image.VolatileImage.getSnapshot() definition code for java.awt.image.VolatileImage.getSnapshot()

flush sample code for java.awt.image.VolatileImage.flush() definition code for java.awt.image.VolatileImage.flush()

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 contentsLost() sample code for java.awt.image.VolatileImage.contentsLost() definition code for java.awt.image.VolatileImage.contentsLost() will return true and the image must be validated before it can be used again.

Specified by:
flush sample code for java.awt.Image.flush() definition code for java.awt.Image.flush() in class Image sample code for java.awt.Image definition code for java.awt.Image
See Also:
contentsLost() sample code for java.awt.image.VolatileImage.contentsLost() definition code for java.awt.image.VolatileImage.contentsLost() , validate(java.awt.GraphicsConfiguration) sample code for java.awt.image.VolatileImage.validate(java.awt.GraphicsConfiguration) definition code for java.awt.image.VolatileImage.validate(java.awt.GraphicsConfiguration)

getGraphics sample code for java.awt.image.VolatileImage.getGraphics() definition code for java.awt.image.VolatileImage.getGraphics()

public Graphics sample code for java.awt.Graphics definition code for java.awt.Graphics  getGraphics()
This method returns a Graphics2D sample code for java.awt.Graphics2D definition code for java.awt.Graphics2D , but is here for backwards compatibility. createGraphics sample code for java.awt.image.VolatileImage.createGraphics() definition code for java.awt.image.VolatileImage.createGraphics() is more convenient, since it is declared to return a Graphics2D.

Specified by:
getGraphics sample code for java.awt.Image.getGraphics() definition code for java.awt.Image.getGraphics() in class Image sample code for java.awt.Image definition code for java.awt.Image
Returns:
a Graphics2D, which can be used to draw into this image.
See Also:
Graphics sample code for java.awt.Graphics definition code for java.awt.Graphics , Component.createImage(int, int) sample code for java.awt.Component.createImage(int, int) definition code for java.awt.Component.createImage(int, int)

createGraphics sample code for java.awt.image.VolatileImage.createGraphics() definition code for java.awt.image.VolatileImage.createGraphics()

public abstract Graphics2D sample code for java.awt.Graphics2D definition code for java.awt.Graphics2D  createGraphics()
Creates a Graphics2D, which can be used to draw into this VolatileImage.

Returns:
a Graphics2D, used for drawing into this image.

validate sample code for java.awt.image.VolatileImage.validate(java.awt.GraphicsConfiguration) definition code for java.awt.image.VolatileImage.validate(java.awt.GraphicsConfiguration)

public abstract int validate(GraphicsConfiguration sample code for java.awt.GraphicsConfiguration definition code for 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.

Parameters:
gc - a GraphicsConfiguration object for this image to be validated against. A null gc implies that the validate method should skip the compatibility test.
Returns:
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 Also:
GraphicsConfiguration sample code for java.awt.GraphicsConfiguration definition code for java.awt.GraphicsConfiguration , Component sample code for java.awt.Component definition code for java.awt.Component , IMAGE_OK sample code for java.awt.image.VolatileImage.IMAGE_OK definition code for java.awt.image.VolatileImage.IMAGE_OK , IMAGE_RESTORED sample code for java.awt.image.VolatileImage.IMAGE_RESTORED definition code for java.awt.image.VolatileImage.IMAGE_RESTORED , IMAGE_INCOMPATIBLE sample code for java.awt.image.VolatileImage.IMAGE_INCOMPATIBLE definition code for java.awt.image.VolatileImage.IMAGE_INCOMPATIBLE

contentsLost sample code for java.awt.image.VolatileImage.contentsLost() definition code for java.awt.image.VolatileImage.contentsLost()

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.

Returns:
true if the drawing surface needs to be restored; false otherwise.

getCapabilities sample code for java.awt.image.VolatileImage.getCapabilities() definition code for java.awt.image.VolatileImage.getCapabilities()

public abstract ImageCapabilities sample code for java.awt.ImageCapabilities definition code for 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.

Returns:
an ImageCapabilities object that contains the capabilities of this VolatileImage.
Since:
1.4

getTransparency sample code for java.awt.image.VolatileImage.getTransparency() definition code for java.awt.image.VolatileImage.getTransparency()

public int getTransparency()
Returns the transparency. Returns either OPAQUE, BITMASK, or TRANSLUCENT.

Specified by:
getTransparency sample code for java.awt.Transparency.getTransparency() definition code for java.awt.Transparency.getTransparency() in interface Transparency sample code for java.awt.Transparency definition code for java.awt.Transparency
Returns:
the transparency of this VolatileImage.
Since:
1.5
See Also:
Transparency.OPAQUE sample code for java.awt.Transparency.OPAQUE definition code for java.awt.Transparency.OPAQUE , Transparency.BITMASK sample code for java.awt.Transparency.BITMASK definition code for java.awt.Transparency.BITMASK , Transparency.TRANSLUCENT sample code for java.awt.Transparency.TRANSLUCENT definition code for java.awt.Transparency.TRANSLUCENT