- java.lang.Object
-
- java.awt.Image
-
- java.awt.image.VolatileImage
-
- All Implemented Interfaces:
- Transparency
public abstract class VolatileImage extends Image implements Transparency
VolatileImage is an image which can lose its contents at any time due to circumstances beyond the control of the application (e.g., situations caused by the operating system or by other applications). Because of the potential for hardware acceleration, a VolatileImage object can have significant performance benefits on some platforms.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
orGraphicsConfiguration.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 anImageObserver
parameter for asynchronous notifications as information is received from a potentialImageProducer
. Since thisVolatileImage
is not loaded from an asynchronous source, the various methods that take anImageObserver
parameter will behave as if the data has already been obtained from theImageProducer
. Specifically, this means that the return values from such methods will never indicate that the information is not yet available and theImageObserver
used in such methods will never need to be recorded for an asynchronous callback notification.- Since:
- 1.4
-
-
Field Summary
Fields Modifier and Type Field and Description static int
IMAGE_INCOMPATIBLE
Validated image is incompatible with suppliedGraphicsConfiguration
object and should be re-created as appropriate.static int
IMAGE_OK
Validated image is ready to use as-is.static 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.-
Fields inherited from class java.awt.Image
accelerationPriority, SCALE_AREA_AVERAGING, SCALE_DEFAULT, SCALE_FAST, SCALE_REPLICATE, SCALE_SMOOTH, UndefinedProperty
-
Fields inherited from interface java.awt.Transparency
BITMASK, OPAQUE, TRANSLUCENT
-
-
Constructor Summary
Constructors Constructor and Description VolatileImage()
-
Method Summary
Methods Modifier and Type Method and Description abstract boolean
contentsLost()
Returnstrue
if rendering data was lost since lastvalidate
call.abstract Graphics2D
createGraphics()
Creates aGraphics2D
, which can be used to draw into thisVolatileImage
.abstract ImageCapabilities
getCapabilities()
Returns an ImageCapabilities object which can be inquired as to the specific capabilities of this VolatileImage.Graphics
getGraphics()
This method returns aGraphics2D
, but is here for backwards compatibility.abstract int
getHeight()
Returns the height of theVolatileImage
.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 theVolatileImage
.abstract int
validate(GraphicsConfiguration gc)
Attempts to restore the drawing surface of the image if the surface had been lost since the lastvalidate
call.-
Methods inherited from class java.awt.Image
flush, getAccelerationPriority, getCapabilities, getHeight, getProperty, getScaledInstance, getWidth, setAccelerationPriority
-
-
-
-
Field Detail
-
IMAGE_OK
public static final int IMAGE_OK
Validated image is ready to use as-is.- See Also:
- Constant Field Values
-
IMAGE_RESTORED
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.- See Also:
- Constant Field Values
-
IMAGE_INCOMPATIBLE
public static final int IMAGE_INCOMPATIBLE
Validated image is incompatible with suppliedGraphicsConfiguration
object and should be re-created as appropriate. Usage of the image as-is after receiving this return code fromvalidate
is undefined.- See Also:
- Constant Field Values
-
transparency
protected int transparency
The transparency value with which this image was created.
-
-
Method Detail
-
getSnapshot
public abstract BufferedImage getSnapshot()
Returns a static snapshot image of this object. TheBufferedImage
returned is only current with theVolatileImage
at the time of the request and will not be updated with any future changes to theVolatileImage
.- Returns:
- a
BufferedImage
representation of thisVolatileImage
- See Also:
BufferedImage
-
getWidth
public abstract int getWidth()
Returns the width of theVolatileImage
.- Returns:
- the width of this
VolatileImage
.
-
getHeight
public abstract int getHeight()
Returns the height of theVolatileImage
.- Returns:
- the height of this
VolatileImage
.
-
getSource
public ImageProducer getSource()
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 asgetSource
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().- Specified by:
getSource
in classImage
- Returns:
- an
ImageProducer
that can be used to produce the pixels for aBufferedImage
representation of this Image. - See Also:
ImageProducer
,getSnapshot()
-
getGraphics
public Graphics getGraphics()
This method returns aGraphics2D
, but is here for backwards compatibility.createGraphics
is more convenient, since it is declared to return aGraphics2D
.- Specified by:
getGraphics
in classImage
- Returns:
- a
Graphics2D
, which can be used to draw into this image. - See Also:
Graphics
,Component.createImage(int, int)
-
createGraphics
public abstract Graphics2D createGraphics()
Creates aGraphics2D
, which can be used to draw into thisVolatileImage
.- Returns:
- a
Graphics2D
, used for drawing into this image.
-
validate
public abstract int validate(GraphicsConfiguration gc)
Attempts to restore the drawing surface of the image if the surface had been lost since the lastvalidate
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 fromvalidate
and may cause later problems with rendering.- Parameters:
gc
- aGraphicsConfiguration
object for this image to be validated against. A null gc implies that the validate method should skip the compatibility test.- Returns:
IMAGE_OK
if the image did not need validation
IMAGE_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 theGraphicsConfiguration
object passed into thevalidate
method. Incompatibility implies that the image may need to be recreated with a newComponent
orGraphicsConfiguration
in order to get an image that can be used successfully with thisGraphicsConfiguration
. An incompatible image is not checked for whether restoration was necessary, so the state of the image is unchanged after a return value ofIMAGE_INCOMPATIBLE
and this return value implies nothing about whether the image needs to be restored.- See Also:
GraphicsConfiguration
,Component
,IMAGE_OK
,IMAGE_RESTORED
,IMAGE_INCOMPATIBLE
-
contentsLost
public abstract boolean contentsLost()
Returnstrue
if rendering data was lost since lastvalidate
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.- Returns:
true
if the drawing surface needs to be restored;false
otherwise.
-
getCapabilities
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.- Returns:
- an
ImageCapabilities
object that contains the capabilities of thisVolatileImage
. - Since:
- 1.4
-
getTransparency
public int getTransparency()
Returns the transparency. Returns either OPAQUE, BITMASK, or TRANSLUCENT.- Specified by:
getTransparency
in interfaceTransparency
- Returns:
- the transparency of this
VolatileImage
. - Since:
- 1.5
- See Also:
Transparency.OPAQUE
,Transparency.BITMASK
,Transparency.TRANSLUCENT
-
-
Deutsche Übersetzung
Sie haben gebeten, diese Seite auf Deutsch zu besuchen. Momentan ist nur die Oberfläche übersetzt, aber noch nicht der gesamte Inhalt.Wenn Sie mir bei Übersetzungen helfen wollen, ist Ihr Beitrag willkommen. Alles, was Sie tun müssen, ist, sich auf der Website zu registrieren und mir eine Nachricht zu schicken, in der Sie gebeten werden, Sie der Gruppe der Übersetzer hinzuzufügen, die Ihnen die Möglichkeit gibt, die gewünschten Seiten zu übersetzen. Ein Link am Ende jeder übersetzten Seite zeigt an, dass Sie der Übersetzer sind und einen Link zu Ihrem Profil haben.
Vielen Dank im Voraus.
Dokument erstellt 11/06/2005, zuletzt geändert 04/03/2020
Quelle des gedruckten Dokuments:https://www.gaudry.be/de/java-api-rf-java/awt/image/volatileimage.html/.html/
Die Infobro ist eine persönliche Seite, deren Inhalt in meiner alleinigen Verantwortung liegt. Der Text ist unter der CreativeCommons-Lizenz (BY-NC-SA) verfügbar. Weitere Informationen auf die Nutzungsbedingungen und dem Autor.
Referenzen
Diese Verweise und Links verweisen auf Dokumente, die während des Schreibens dieser Seite konsultiert wurden, oder die zusätzliche Informationen liefern können, aber die Autoren dieser Quellen können nicht für den Inhalt dieser Seite verantwortlich gemacht werden.
Der Autor Diese Website ist allein dafür verantwortlich, wie die verschiedenen Konzepte und Freiheiten, die mit den Nachschlagewerken gemacht werden, hier dargestellt werden. Denken Sie daran, dass Sie mehrere Quellinformationen austauschen müssen, um das Risiko von Fehlern zu reduzieren.