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.
or
GraphicsConfiguration.
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 |
---|---|
public static final int | IMAGE_INCOMPATIBLE
Validated image is incompatible with supplied
|
public static final int | IMAGE_OK
Validated image is ready to use as-is. |
public 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. |
Access | Constructor and Description |
---|---|
protected |
Modifier and Type | Method and Description |
---|---|
public abstract boolean | Returns: true if the drawing surface needs to be restored;
false otherwise.Returns |
public abstract Graphics2D | Returns: aGraphics2D , used for drawing into this
image.Creates a |
public abstract ImageCapabilities | Returns: anImageCapabilities object that contains
the capabilities of this VolatileImage .Returns an ImageCapabilities object which can be inquired as to the specific capabilities of this VolatileImage. |
public Graphics | Returns: aGraphics2D , which can be used to draw into
this image.Implements abstract java. Graphics2D , but is here
for backwards compatibility.
|
public abstract int | |
public abstract BufferedImage | |
public ImageProducer | Returns: anImageProducer that can be used to produce the
pixels for a BufferedImage representation of
this Image.Implements abstract java. |
public int | Returns: the transparency of thisVolatileImage .Implements java. |
public abstract int | |
public abstract int | Returns: 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.a gc)GraphicsConfiguration object for this
image to be validated against. A null gc implies that the
validate method should skip the compatibility test.Attempts to restore the drawing surface of the image if the surface
had been lost since the last |
IMAGE_INCOMPATIBLE | back to summary |
---|---|
public static final int IMAGE_INCOMPATIBLE Validated image is incompatible with supplied
|
IMAGE_OK | back to summary |
---|---|
public static final int IMAGE_OK Validated image is ready to use as-is. |
IMAGE_RESTORED | back to summary |
---|---|
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. |
transparency | back to summary |
---|---|
protected int transparency The transparency value with which this image was created. |
VolatileImage | back to summary |
---|---|
protected VolatileImage() Constructor for subclasses to call. |
contentsLost | back to summary |
---|---|
public abstract boolean contentsLost() Returns
|
createGraphics | back to summary |
---|---|
public abstract Graphics2D createGraphics() Creates a
|
getCapabilities | back to summary |
---|---|
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.
|
getGraphics | back to summary |
---|---|
public Graphics getGraphics() Implements abstract java. This method returns a
|
getHeight | back to summary |
---|---|
public abstract int getHeight() Returns the height of the
|
getSnapshot | back to summary |
---|---|
public abstract BufferedImage getSnapshot() Returns a static snapshot image of this object. The
|
getSource | back to summary |
---|---|
public ImageProducer getSource() Implements abstract java. 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
|
getTransparency | back to summary |
---|---|
public int getTransparency() Implements java. Returns the transparency. Returns either OPAQUE, BITMASK, or TRANSLUCENT.
|
getWidth | back to summary |
---|---|
public abstract int getWidth() Returns the width of the
|
validate | back to summary |
---|---|
public abstract int validate(GraphicsConfiguration gc) Attempts to restore the drawing surface of the image if the surface
had been lost since the last
|