Transparency
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 | 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. |
accelerationPriority, SCALE_AREA_AVERAGING, SCALE_DEFAULT, SCALE_FAST, SCALE_REPLICATE, SCALE_SMOOTH, UndefinedProperty
BITMASK, OPAQUE, TRANSLUCENT
Modifier | Constructor | Description |
---|---|---|
protected |
Constructor for subclasses to call. |
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 |
Attempts to restore the drawing surface of the image if the surface had been lost since the last validate call. |
flush, getAccelerationPriority, getCapabilities, getHeight, getProperty, getScaledInstance, getWidth, setAccelerationPriority
public 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
protected VolatileImage()
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 VolatileImage
public 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 Image
ImageProducer
that can be used to produce the pixels for a BufferedImage
representation of this Image.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 Image
Graphics2D
, which can be used to draw into this image.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.public 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 Transparency
VolatileImage
.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/java/awt/image/VolatileImage.html