Java Doc for VolatileImage.java in  » 6.0-JDK-Core » AWT » java » awt » image » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Home
Java Source Code / Java Documentation
1.6.0 JDK Core
2.6.0 JDK Modules
3.6.0 JDK Modules com.sun
4.6.0 JDK Modules com.sun.java
5.6.0 JDK Modules sun
6.6.0 JDK Platform
7.Ajax
8.Apache Harmony Java SE
9.Aspect oriented
10.Authentication Authorization
11.Blogger System
12.Build
13.Byte Code
14.Cache
15.Chart
16.Chat
17.Code Analyzer
18.Collaboration
19.Content Management System
20.Database Client
21.Database DBMS
22.Database JDBC Connection Pool
23.Database ORM
24.Development
25.EJB Server
26.ERP CRM Financial
27.ESB
28.Forum
29.Game
30.GIS
31.Graphic 3D
32.Graphic Library
33.Groupware
34.HTML Parser
35.IDE
36.IDE Eclipse
37.IDE Netbeans
38.Installer
39.Internationalization Localization
40.Inversion of Control
41.Issue Tracking
42.J2EE
43.J2ME
44.JBoss
45.JMS
46.JMX
47.Library
48.Mail Clients
49.Music
50.Net
51.Parser
52.PDF
53.Portal
54.Profiler
55.Project Management
56.Report
57.RSS RDF
58.Rule Engine
59.Science
60.Scripting
61.Search Engine
62.Security
63.Sevlet Container
64.Source Control
65.Swing Library
66.Template Engine
67.Test Coverage
68.Testing
69.UML
70.Web Crawler
71.Web Framework
72.Web Mail
73.Web Server
74.Web Services
75.Web Services apache cxf 2.2.6
76.Web Services AXIS2
77.Wiki Engine
78.Workflow Engines
79.XML
80.XML UI
Java Source Code / Java Documentation » 6.0 JDK Core » AWT » java.awt.image 
Source Cross Reference  Class Diagram Java Document (Java Doc) 


java.lang.Object
   java.awt.Image
      java.awt.image.VolatileImage

VolatileImage
abstract public class VolatileImage extends Image implements Transparency(Code)
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 java.awt.Component.createVolatileImage(intint)Component.createVolatileImage or java.awt.GraphicsConfiguration.createCompatibleVolatileImage(intint)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.
since:
   1.4



Field Summary
final public static  intIMAGE_INCOMPATIBLE
     Validated image is incompatible with supplied GraphicsConfiguration object and should be re-created as appropriate.
final public static  intIMAGE_OK
     Validated image is ready to use as-is.
final public static  intIMAGE_RESTORED
     Validated image has been restored and is now ready to use.
protected  inttransparency
     The transparency value with which this image was created.


Method Summary
abstract public  booleancontentsLost()
     Returns true if rendering data was lost since last validate call.
abstract public  Graphics2DcreateGraphics()
     Creates a Graphics2D, which can be used to draw into this VolatileImage. a Graphics2D, used for drawing into thisimage.
abstract public  ImageCapabilitiesgetCapabilities()
     Returns an ImageCapabilities object which can be inquired as to the specific capabilities of this VolatileImage.
public  GraphicsgetGraphics()
     This method returns a Graphics2D , but is here for backwards compatibility.
abstract public  intgetHeight()
     Returns the height of the VolatileImage.
abstract public  BufferedImagegetSnapshot()
     Returns a static snapshot image of this object.
public  ImageProducergetSource()
     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.
public  intgetTransparency()
     Returns the transparency.
abstract public  intgetWidth()
     Returns the width of the VolatileImage.
abstract public  intvalidate(GraphicsConfiguration gc)
     Attempts to restore the drawing surface of the image if the surface had been lost since the last validate call.

Field Detail
IMAGE_INCOMPATIBLE
final public static int IMAGE_INCOMPATIBLE(Code)
Validated image is incompatible with supplied GraphicsConfiguration object and should be re-created as appropriate. Usage of the image as-is after receiving this return code from validate is undefined.



IMAGE_OK
final public static int IMAGE_OK(Code)
Validated image is ready to use as-is.



IMAGE_RESTORED
final public static int IMAGE_RESTORED(Code)
Validated image has been restored and is now ready to use. Note that restoration causes contents of the image to be lost.



transparency
protected int transparency(Code)
The transparency value with which this image was created.
See Also:   java.awt.GraphicsConfiguration.createCompatibleVolatileImage(intintint)
See Also:   java.awt.GraphicsConfiguration.createCompatibleVolatileImage(intintImageCapabilitiesint)
See Also:   Transparency
since:
   1.5





Method Detail
contentsLost
abstract public boolean contentsLost()(Code)
Returns 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. true if the drawing surface needs to be restored;false otherwise.



createGraphics
abstract public Graphics2D createGraphics()(Code)
Creates a Graphics2D, which can be used to draw into this VolatileImage. a Graphics2D, used for drawing into thisimage.



getCapabilities
abstract public ImageCapabilities getCapabilities()(Code)
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. an ImageCapabilities object that containsthe capabilities of this VolatileImage.
since:
   1.4



getGraphics
public Graphics getGraphics()(Code)
This method returns a Graphics2D , but is here for backwards compatibility. VolatileImage.createGraphics() createGraphics is more convenient, since it is declared to return a Graphics2D. a Graphics2D, which can be used to draw intothis image.



getHeight
abstract public int getHeight()(Code)
Returns the height of the VolatileImage. the height of this VolatileImage.



getSnapshot
abstract public BufferedImage getSnapshot()(Code)
Returns a static snapshot image of this object. The 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. a BufferedImage representation of thisVolatileImage
See Also:   BufferedImage



getSource
public ImageProducer getSource()(Code)
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 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(). an ImageProducer that can be used to produce thepixels for a BufferedImage representation ofthis Image.
See Also:   ImageProducer
See Also:   VolatileImage.getSnapshot()



getTransparency
public int getTransparency()(Code)
Returns the transparency. Returns either OPAQUE, BITMASK, or TRANSLUCENT. the transparency of this VolatileImage.
See Also:   Transparency.OPAQUE
See Also:   Transparency.BITMASK
See Also:   Transparency.TRANSLUCENT
since:
   1.5



getWidth
abstract public int getWidth()(Code)
Returns the width of the VolatileImage. the width of this VolatileImage.



validate
abstract public int validate(GraphicsConfiguration gc)(Code)
Attempts to restore the drawing surface of the image if the surface had been lost since the last 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.
Parameters:
  gc - a GraphicsConfiguration object for thisimage to be validated against. A null gc implies that thevalidate method should skip the compatibility test. 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 incompatiblewith the GraphicsConfiguration object passedinto the validate method. Incompatibilityimplies that the image may need to be recreated with anew Component or GraphicsConfiguration in order to get an imagethat can be used successfully with this GraphicsConfiguration.An incompatible image is not checked for whether restorationwas necessary, so the state of the image is unchanged after a return value of IMAGE_INCOMPATIBLEand this return value implies nothing about whether theimage needs to be restored.
See Also:   java.awt.GraphicsConfiguration
See Also:   java.awt.Component
See Also:   VolatileImage.IMAGE_OK
See Also:   VolatileImage.IMAGE_RESTORED
See Also:   VolatileImage.IMAGE_INCOMPATIBLE



Fields inherited from java.awt.Image
final public static int SCALE_AREA_AVERAGING(Code)(Java Doc)
final public static int SCALE_DEFAULT(Code)(Java Doc)
final public static int SCALE_FAST(Code)(Java Doc)
final public static int SCALE_REPLICATE(Code)(Java Doc)
final public static int SCALE_SMOOTH(Code)(Java Doc)
final public static Object UndefinedProperty(Code)(Java Doc)
protected float accelerationPriority(Code)(Java Doc)

Methods inherited from java.awt.Image
public void flush()(Code)(Java Doc)
public float getAccelerationPriority()(Code)(Java Doc)
public ImageCapabilities getCapabilities(GraphicsConfiguration gc)(Code)(Java Doc)
abstract public Graphics getGraphics()(Code)(Java Doc)
abstract public int getHeight(ImageObserver observer)(Code)(Java Doc)
abstract public Object getProperty(String name, ImageObserver observer)(Code)(Java Doc)
public Image getScaledInstance(int width, int height, int hints)(Code)(Java Doc)
abstract public ImageProducer getSource()(Code)(Java Doc)
abstract public int getWidth(ImageObserver observer)(Code)(Java Doc)
public void setAccelerationPriority(float priority)(Code)(Java Doc)

Methods inherited from java.lang.Object
native protected Object clone() throws CloneNotSupportedException(Code)(Java Doc)
public boolean equals(Object obj)(Code)(Java Doc)
protected void finalize() throws Throwable(Code)(Java Doc)
final native public Class getClass()(Code)(Java Doc)
native public int hashCode()(Code)(Java Doc)
final native public void notify()(Code)(Java Doc)
final native public void notifyAll()(Code)(Java Doc)
public String toString()(Code)(Java Doc)
final native public void wait(long timeout) throws InterruptedException(Code)(Java Doc)
final public void wait(long timeout, int nanos) throws InterruptedException(Code)(Java Doc)
final public void wait() throws InterruptedException(Code)(Java Doc)

www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.