VolatileImage (Java SE 26 & JDK 26)
Description: declaration: module: java.desktop, package: java.awt.image, class: VolatileImage
Keywords: java.awt.image.VolatileImage class

# Class VolatileImage

java.lang.Object
java.awt.Image
java.awt.image.VolatileImage

All Implemented Interfaces:
  `Transparency`

public abstract class VolatileImage extends Image implements 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.

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.

Since:
  1.4

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `IMAGE_INCOMPATIBLE`
  Validated image is incompatible with supplied `GraphicsConfiguration` object and should be re-created as appropriate.
  `static final int`
  `IMAGE_OK`
  Validated image is ready to use as-is.
  `static final int`
  `IMAGE_RESTORED`
  Validated image has been restored and is now ready to use.
  `protected int`
  `transparency`
  The transparency value with which this image was created.

  ### Fields declared in class Image

  `accelerationPriority, SCALE_AREA_AVERAGING, SCALE_DEFAULT, SCALE_FAST, SCALE_REPLICATE, SCALE_SMOOTH, UndefinedProperty`
  Modifier and Type
  Field
  Description
  `protected float`
  `accelerationPriority`
  Priority for accelerating this image.
  `static final int`
  `SCALE_AREA_AVERAGING`
  Use the Area Averaging image scaling algorithm.
  `static final int`
  `SCALE_DEFAULT`
  Use the default image-scaling algorithm.
  `static final int`
  `SCALE_FAST`
  Choose an image-scaling algorithm that gives higher priority to scaling speed than smoothness of the scaled image.
  `static final int`
  `SCALE_REPLICATE`
  Use the image scaling algorithm embodied in the `ReplicateScaleFilter` class.
  `static final int`
  `SCALE_SMOOTH`
  Choose an image-scaling algorithm that gives higher priority to image smoothness than scaling speed.
  `static final Object`
  `UndefinedProperty`
  The `UndefinedProperty` object should be returned whenever a property which was not defined for a particular image is fetched.

  ### Fields declared in interface Transparency

  `BITMASK, OPAQUE, TRANSLUCENT`
  Modifier and Type
  Field
  Description
  `static final int`
  `BITMASK`
  Represents image data that is guaranteed to be either completely opaque, with an alpha value of 1.0, or completely transparent, with an alpha value of 0.0.
  `static final int`
  `OPAQUE`
  Represents image data that is guaranteed to be completely opaque, meaning that all pixels have an alpha value of 1.0.
  `static final int`
  `TRANSLUCENT`
  Represents image data that contains or might contain arbitrary alpha values between and including 0.0 and 1.0.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `VolatileImage()`
  Constructor for subclasses to call.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract boolean`
  `contentsLost()`
  Returns `true` if rendering data was lost since last `validate` call.
  `abstract Graphics2D`
  `createGraphics()`
  Creates a `Graphics2D`, which can be used to draw into this `VolatileImage`.
  `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 `validate` call.

  ### Methods declared in class Image

  `flush, getAccelerationPriority, getCapabilities, getHeight, getProperty, getScaledInstance, getWidth, setAccelerationPriority`
  Modifier and Type
  Method
  Description
  `void`
  `flush()`
  Flushes all reconstructable resources being used by this Image object.
  `float`
  `getAccelerationPriority()`
  Returns the current value of the acceleration priority hint.
  `ImageCapabilities`
  `getCapabilities(GraphicsConfiguration gc)`
  Returns an ImageCapabilities object which can be inquired as to the capabilities of this Image on the specified GraphicsConfiguration.
  `abstract int`
  `getHeight(ImageObserver observer)`
  Determines the height of the image.
  `abstract Object`
  `getProperty(String name, ImageObserver observer)`
  Gets a property of this image by name.
  `Image`
  `getScaledInstance(int width, int height, int hints)`
  Creates a scaled version of this image.
  `abstract int`
  `getWidth(ImageObserver observer)`
  Determines the width of the image.
  `void`
  `setAccelerationPriority(float priority)`
  Sets a hint for this image about how important acceleration is.

  ### Methods declared in class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`
  Modifier and Type
  Method
  Description
  `protected Object`
  `clone()`
  Creates and returns a copy of this object.
  `boolean`
  `equals(Object obj)`
  Indicates whether some other object is "equal to" this one.
  `protected void`
  `finalize()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Finalization is deprecated and subject to removal in a future release.
  `final Class<?>`
  `getClass()`
  Returns the runtime class of this `Object`.
  `int`
  `hashCode()`
  Returns a hash code value for this object.
  `final void`
  `notify()`
  Wakes up a single thread that is waiting on this object's monitor.
  `final void`
  `notifyAll()`
  Wakes up all threads that are waiting on this object's monitor.
  `String`
  `toString()`
  Returns a string representation of the object.
  `final void`
  `wait()`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
  `final void`
  `wait(long timeoutMillis)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
  `final void`
  `wait(long timeoutMillis, int nanos)`
  Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.

- ## Field Details

  - ### IMAGE_OK

    public static final int IMAGE_OK
    Validated image is ready to use as-is.
    See Also:
      - Constant Field Values

  - ### 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

    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

    protected int transparency
    The transparency value with which this image was created.
    Since:
      1.5
    See Also:
      - `GraphicsConfiguration.createCompatibleVolatileImage(int, int,int)`
      - `GraphicsConfiguration.createCompatibleVolatileImage(int, int,ImageCapabilities,int)`
      - `Transparency`

- ## Constructor Details

  - ### VolatileImage

    protected VolatileImage()
    Constructor for subclasses to call.

- ## Method Details

  - ### getSnapshot

    public abstract 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` representation of this `VolatileImage`
    See Also:
      - `BufferedImage`

  - ### getWidth

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

  - ### getHeight

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

  - ### getSource

    public 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` in class `Image`
    Returns:
      an `ImageProducer` that can be used to produce the pixels for a `BufferedImage` representation of this Image.
    See Also:
      - `ImageProducer`
      - `getSnapshot()`

  - ### getGraphics

    public Graphics getGraphics()
    This method returns a `Graphics2D`, but is here for backwards compatibility. `createGraphics` is more convenient, since it is declared to return a `Graphics2D`.
    Specified by:
      `getGraphics` in class `Image`
    Returns:
      a `Graphics2D`, which can be used to draw into this image.
    See Also:
      - `Graphics`
      - `Component.createImage(int, int)`

  - ### createGraphics

    public abstract Graphics2D createGraphics()
    Creates a `Graphics2D`, which can be used to draw into this `VolatileImage`.
    Returns:
      a `Graphics2D`, used for drawing into this image.

  - ### validate

    public abstract int validate(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`
      - `Component`
      - `IMAGE_OK`
      - `IMAGE_RESTORED`
      - `IMAGE_INCOMPATIBLE`

  - ### 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

    public abstract 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

    public int getTransparency()
    Returns the transparency. Returns either OPAQUE, BITMASK, or TRANSLUCENT.
    Specified by:
      `getTransparency` in interface `Transparency`
    Returns:
      the transparency of this `VolatileImage`.
    Since:
      1.5
    See Also:
      - `Transparency.OPAQUE`
      - `Transparency.BITMASK`
      - `Transparency.TRANSLUCENT`