java.awt.image
Class VolatileImage
public abstract
class
VolatileImage
extends Image
implements Transparency
VolatileImage represents a hardware-accelerated graphics buffer.
The native graphics system may free or damage the resources
occupied by a VolatileImage at any time. As such, one must
frequently check the "validity" of the image buffer's resources.
A volatile image's "validity" depends on multiple factors. Its
resources may have become unavailble in which case you must
reallocate them. If you move the image from one output device to
another, you may need to recreate the image's resources if the new
output device's capabilities don't match the old one's. Finally,
if the contents of the image's buffer have been damaged you must
re-render the image.
VolatileImages should always be created using either
Component.createVolatileImage or
GraphicsConfiguration.createCompatibleVolatileImage.
public static final int IMAGE_INCOMPATIBLE
One of validate's possible return values. Indicates that the
image buffer type is unsupported by the current graphics
configuration. The graphics configuration may have changed, for
example if the image moved from one output device to another.
This return value implies that the image buffer's resources
should be re-acquired.
public static final int IMAGE_OK
One of validate's possible return values. Indicates that the
image buffer matches its graphics configuration's capabilities
and that its resources are initialized and ready to be drawn
into. Also implies that any existing image rendered to the
buffer is intact and need not be re-rendered.
public static final int IMAGE_RESTORED
One of validate's possible return values. Indicates that the
image buffer has been restored, meaning that it is valid and
ready-to-use but that its previous contents have been lost. This
return value implies that the image needs to be re-rendered.
protected int transparency
This image's transparency type. One of Transparency.BITMASK,
Transparency.OPAQUE or Transparency.TRANSLUCENT.
Since: 1.5
public VolatileImage()
Default constructor. VolatileImages should not be created
directly. Rather, you should use Component.createVolatileImage
or GraphicsConfiguration.createCompatibleVolatileImage.
public abstract boolean contentsLost()
Returns true if the contents of the image buffer have been
damaged or if the image buffer's resources have been reclaimed by
the graphics system. You should call this method after a series
of rendering operations to or from the image, to see if the image
buffer needs to be revalidated or the image re-rendered.
Returns: true if the validate should be called, false otherwise
Returns a Graphics2D object that can be used to draw onto this
image.
Returns: a Graphics2D object that can be used to draw onto this
image
public void flush()
Releases the system resources taken by this image.
Returns the capabilities of this image buffer.
Returns: the capabilities of this image buffer
Returns a Graphics2D object that can be used to draw onto this
image. This method is present for backwards-compatibility. It
simply returns the result of createGraphics.
Returns: a Graphics2D object that can be used to draw onto this
image
public abstract int getHeight()
Returns the height of this image buffer.
Returns: the height of this VolatileImage
Returns an image representing the current state of the volatile
image buffer. The returned image is static meaning that it is
not updated after being created. It is a snapshot of the
volatile image buffer at the time getSnapshot is called.
This method, which reads pixels from the volatile image buffer,
may be less-performant than methods that write pixels since
VolatileImages are typically optimized for writing.
Returns: a BufferedImage representing this VolatileImage
Calling this method is equivalent to calling
getSnapshot().getSource(). The ImageProducer produces pixels
from the BufferedImage snapshot and not from the VolatileImage
itself. Thus, changes to the VolatileImage that occur after this
ImageProducer has been retrieved will not be reflected in the
produced pixels.
This method, which reads pixels from the volatile image buffer,
may be less-performant than methods that write pixels since
VolatileImages are typically optimized for writing.
Returns: an ImageProducer for a static BufferedImage snapshot of
this image buffer
public int getTransparency()
Returns the transparency type of this image.
Returns: Transparency.OPAQUE, Transparency.BITMASK or
Transparency.TRANSLUCENT
public abstract int getWidth()
Returns the width of this image buffer.
Returns: the width of this VolatileImage
Validates and restores this image. If the image buffer has
become unavailable for further use since the last call to
validate, validate will allocate a new image buffer. The image
is also "validated" against the GraphicsConfiguration parameter.
"Validating" the image means checking that the capabilities it
requires of the output device are indeed supported by the given
output device. If the image's characteristics, which can be
highly output device-specific, are not supported by the graphics
configuration, then IMAGE_INCOMPATIBLE will be returned. This
can happen, for example, if this image was created on one output
device, then validated against a different output device with
different capabilities. Calling validate with a NULL gc argument
causes validate to skip the validation test.
Parameters: gc graphics configuration against which to validate or
NULL
Returns: a code indicating the result of validation. One of:
IMAGE_OK if the image did not need to be
validated and didn't need to be restoredIMAGE_RESTORED if the image may need to be
re-rendered.IMAGE_INCOMPATIBLE if this image's
requirements are not fulfilled by the graphics configuration
parameter. This implies that you need to create a new
VolatileImage for the different GraphicsConfiguration or
Component. This return value implies nothing about whether the
image is valid or needs to be re-rendered.