public abstract class VolatileImage extends Image implements Transparency
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.
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.
 This image should not be subclassed directly but should be created
 by using the Component.createVolatileImage or
 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.
| Modifier and Type | Field and Description | 
|---|---|
| static int | IMAGE_INCOMPATIBLEValidated image is incompatible with supplied
  GraphicsConfigurationobject and should be
 re-created as appropriate. | 
| static int | IMAGE_OKValidated image is ready to use as-is. | 
| static int | IMAGE_RESTOREDValidated image has been restored and is now ready to use. | 
| protected int | transparencyThe transparency value with which this image was created. | 
accelerationPriority, SCALE_AREA_AVERAGING, SCALE_DEFAULT, SCALE_FAST, SCALE_REPLICATE, SCALE_SMOOTH, UndefinedPropertyBITMASK, OPAQUE, TRANSLUCENT| Constructor and Description | 
|---|
| VolatileImage() | 
| Modifier and Type | Method and Description | 
|---|---|
| abstract boolean | contentsLost()Returns  trueif rendering data was lost since lastvalidatecall. | 
| abstract Graphics2D | createGraphics()Creates a  Graphics2D, which can be used to draw into
 thisVolatileImage. | 
| abstract ImageCapabilities | getCapabilities()Returns an ImageCapabilities object which can be
 inquired as to the specific capabilities of this
 VolatileImage. | 
| Graphics | getGraphics()This method returns a  Graphics2D, but is here
 for backwards compatibility. | 
| abstract int | getHeight()Returns the height of the  VolatileImage. | 
| abstract BufferedImage | getSnapshot()Returns a static snapshot image of this object. | 
| ImageProducer | getSource()This returns an ImageProducer for this VolatileImage. | 
| int | getTransparency()Returns the transparency. | 
| abstract int | getWidth()Returns the width of the  VolatileImage. | 
| abstract int | validate(GraphicsConfiguration gc)Attempts to restore the drawing surface of the image if the surface
 had been lost since the last  validatecall. | 
flush, getAccelerationPriority, getCapabilities, getHeight, getProperty, getScaledInstance, getWidth, setAccelerationPrioritypublic static final int IMAGE_OK
public static final int IMAGE_RESTORED
public static final int IMAGE_INCOMPATIBLE
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
public abstract BufferedImage getSnapshot()
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.BufferedImage representation of this
          VolatileImageBufferedImagepublic abstract int getWidth()
VolatileImage.VolatileImage.public abstract int getHeight()
VolatileImage.VolatileImage.public ImageProducer getSource()
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().getSource in class ImageImageProducer that can be used to produce the
 pixels for a BufferedImage representation of
 this Image.ImageProducer, 
getSnapshot()public Graphics getGraphics()
Graphics2D, but is here
 for backwards compatibility.  createGraphics is more
 convenient, since it is declared to return a
 Graphics2D.getGraphics in class ImageGraphics2D, which can be used to draw into
          this image.Graphics, 
Component.createImage(int, int)public abstract Graphics2D createGraphics()
Graphics2D, which can be used to draw into
 this VolatileImage.Graphics2D, used for drawing into this
          image.public abstract int validate(GraphicsConfiguration gc)
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.gc - a GraphicsConfiguration object for this
          image to be validated against.  A null gc implies that the
          validate method should skip the compatibility test.IMAGE_OK if the image did not need validationIMAGE_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.GraphicsConfiguration, 
Component, 
IMAGE_OK, 
IMAGE_RESTORED, 
IMAGE_INCOMPATIBLEpublic abstract boolean contentsLost()
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.true if the drawing surface needs to be restored;
 false otherwise.public abstract ImageCapabilities getCapabilities()
ImageCapabilities object that contains
         the capabilities of this VolatileImage.public int getTransparency()
getTransparency in interface TransparencyVolatileImage.Transparency.OPAQUE, 
Transparency.BITMASK, 
Transparency.TRANSLUCENT Submit a bug or feature 
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
 Copyright © 1993, 2025, Oracle and/or its affiliates.  All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.