java.awt.image

Class VolatileImage

Implemented Interfaces:
Transparency
Known Direct Subclasses:
GtkVolatileImage, QtVolatileImage

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.

Field Summary

static int
IMAGE_INCOMPATIBLE
One of validate's possible return values.
static int
IMAGE_OK
One of validate's possible return values.
static int
IMAGE_RESTORED
One of validate's possible return values.
protected int
transparency
This image's transparency type.

Fields inherited from class java.awt.Image

SCALE_AREA_AVERAGING, SCALE_DEFAULT, SCALE_FAST, SCALE_REPLICATE, SCALE_SMOOTH, UndefinedProperty, accelerationPriority

Fields inherited from interface java.awt.Transparency

BITMASK, OPAQUE, TRANSLUCENT

Constructor Summary

VolatileImage()
Default constructor.

Method Summary

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.
abstract Graphics2D
createGraphics()
Returns a Graphics2D object that can be used to draw onto this image.
void
flush()
Releases the system resources taken by this image.
abstract ImageCapabilities
getCapabilities()
Returns the capabilities of this image buffer.
Graphics
getGraphics()
Returns a Graphics2D object that can be used to draw onto this image.
abstract int
getHeight()
Returns the height of this image buffer.
abstract BufferedImage
getSnapshot()
Returns an image representing the current state of the volatile image buffer.
ImageProducer
getSource()
Calling this method is equivalent to calling getSnapshot().getSource().
int
getTransparency()
Returns the transparency type of this image.
abstract int
getWidth()
Returns the width of this image buffer.
abstract int
validate(GraphicsConfiguration gc)
Validates and restores this image.

Methods inherited from class java.awt.Image

flush, getAccelerationPriority, getGraphics, getHeight, getProperty, getScaledInstance, getSource, getWidth, setAccelerationPriority

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

IMAGE_INCOMPATIBLE

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.
Field Value:
2

IMAGE_OK

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.
Field Value:
0

IMAGE_RESTORED

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.
Field Value:
1

transparency

protected int transparency
This image's transparency type. One of Transparency.BITMASK, Transparency.OPAQUE or Transparency.TRANSLUCENT.
Since:
1.5

Constructor Details

VolatileImage

public VolatileImage()
Default constructor. VolatileImages should not be created directly. Rather, you should use Component.createVolatileImage or GraphicsConfiguration.createCompatibleVolatileImage.

Method Details

contentsLost

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

createGraphics

public abstract Graphics2D createGraphics()
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

flush

public void flush()
Releases the system resources taken by this image.
Overrides:
flush in interface Image

getCapabilities

public abstract ImageCapabilities getCapabilities()
Returns the capabilities of this image buffer.
Returns:
the capabilities of this image buffer

getGraphics

public Graphics getGraphics()
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.
Overrides:
getGraphics in interface Image
Returns:
a Graphics2D object that can be used to draw onto this image

getHeight

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

getSnapshot

public abstract BufferedImage getSnapshot()
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

getSource

public ImageProducer getSource()
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.
Overrides:
getSource in interface Image
Returns:
an ImageProducer for a static BufferedImage snapshot of this image buffer

getTransparency

public int getTransparency()
Returns the transparency type of this image.
Specified by:
getTransparency in interface Transparency
Returns:
Transparency.OPAQUE, Transparency.BITMASK or Transparency.TRANSLUCENT

getWidth

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

validate

public abstract int validate(GraphicsConfiguration gc)
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 restored
  • IMAGE_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.

VolatileImage.java -- a hardware-accelerated image buffer Copyright (C) 2002, 2005 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.