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.
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.
GraphicsConfiguration object and should be
re-created as appropriate. Usage of the image as-is
after receiving this return code from validate
is undefined.ReplicateScaleFilter class.
The Image object is free to substitute a different filter
that performs the same algorithm yet integrates more efficiently
into the imaging infrastructure supplied by the toolkit.UndefinedProperty object should be returned whenever a
property which was not defined for a particular image is fetched.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.Graphics2D, which can be used to draw into
this VolatileImage.
The equals method implements an equivalence relation
on non-null object references:
x, x.equals(x) should return
true.
x and y, x.equals(y)
should return true if and only if
y.equals(x) returns true.
x, y, and z, if
x.equals(y) returns true and
y.equals(z) returns true, then
x.equals(z) should return true.
x and y, multiple invocations of
x.equals(y) consistently return true
or consistently return false, provided no
information used in equals comparisons on the
objects is modified.
x,
x.equals(null) should return false.
The equals method for class Object implements
the most discriminating possible equivalence relation on objects;
that is, for any non-null reference values x and
y, this method returns true if and only
if x and y refer to the same object
(x == y has the value true).
Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.
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).
By calling this flush method, applications can have more control over the state of the resources taken up by obsolete VolatileImage objects.
This method will cause the contents of the image to be lost, so
calls to #contentsLost
will return true
and the image must be validated before it can be used again.
Graphics2D.VolatileImage.-1 and the specified
ImageObserver object is notified later.
Individual property names are defined by the various image
formats. If a property is not defined for a particular image, this
method returns the UndefinedProperty object.
If the properties for this image are not yet known, this method
returns null, and the ImageObserver
object is notified later.
The property name "comment" should be used to store
an optional comment which can be presented to the application as a
description of the image, its source, or its author.
Image object is returned which will render
the image at the specified width and
height by default. The new Image object
may be loaded asynchronously even if the original source image
has already been loaded completely.
If either width
or height is a negative number then a value is
substituted to maintain the aspect ratio of the original image
dimensions. If both width and height
are negative, then the original image dimensions are used.
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.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().Transparency.VolatileImage.-1 and the specified
ImageObserver object is notified later.java.util.Hashtable.
The general contract of hashCode is:
hashCode method on each of
the two objects must produce the same integer result.
As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)
wait methods.
The awakened thread will not be able to proceed until the current thread relinquishes the lock on this object. The awakened thread will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened thread enjoys no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner of this object's monitor. A thread becomes the owner of the object's monitor in one of three ways:
synchronized statement
that synchronizes on the object.
Class, by executing a
synchronized static method of that class.
Only one thread at a time can own an object's monitor.
wait methods.
The awakened threads will not be able to proceed until the current thread relinquishes the lock on this object. The awakened threads will compete in the usual manner with any other threads that might be actively competing to synchronize on this object; for example, the awakened threads enjoy no reliable privilege or disadvantage in being the next thread to lock this object.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
toString method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
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.
The current thread must own this object's monitor. The thread
releases ownership of this monitor and waits until another thread
notifies threads waiting on this object's monitor to wake up
either through a call to the notify method or the
notifyAll method. The thread then waits until it can
re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait();
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.The current thread must own this object's monitor.
This method causes the current thread (call it T) to place itself in the wait set for this object and then to relinquish any and all synchronization claims on this object. Thread T becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:
A thread can also wake up without being notified, interrupted, or timing out, a so-called spurious wakeup. While this will rarely occur in practice, applications must guard against it by testing for the condition that should have caused the thread to be awakened, and continuing to wait if the condition is not satisfied. In other words, waits should always occur in loops, like this one:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout);
... // Perform action appropriate to condition
}
(For more information on this topic, see Section 3.2.3 in Doug Lea's
"Concurrent Programming in Java (Second Edition)" (Addison-Wesley,
2000), or Item 50 in Joshua Bloch's "Effective Java Programming
Language Guide" (Addison-Wesley, 2001).
If the current thread is interrupted by another thread while it is waiting, then an InterruptedException is thrown. This exception is not thrown until the lock status of this object has been restored as described above.
Note that the wait method, as it places the current thread into the wait set for this object, unlocks only this object; any other objects on which the current thread may be synchronized remain locked while the thread waits.
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.
This method is similar to the wait method of one
argument, but it allows finer control over the amount of time to
wait for a notification before giving up. The amount of real time,
measured in nanoseconds, is given by:
1000000*timeout+nanos
In all other respects, this method does the same thing as the method of one argument. In particular, wait(0, 0) means the same thing as wait(0).
The current thread must own this object's monitor. The thread releases ownership of this monitor and waits until either of the following two conditions has occurred:
notify method
or the notifyAll method.
timeout
milliseconds plus nanos nanoseconds arguments, has
elapsed.
The thread then waits until it can re-obtain ownership of the monitor and resumes execution.
As in the one argument version, interrupts and spurious wakeups are possible, and this method should always be used in a loop:
synchronized (obj) {
while (<condition does not hold>)
obj.wait(timeout, nanos);
... // Perform action appropriate to condition
}
This method should only be called by a thread that is the owner
of this object's monitor. See the notify method for a
description of the ways in which a thread can become the owner of
a monitor.