JavaTM 2 Platform
Standard Ed. 5.0

java.awt.image
类 VolatileImage

java.lang.Object
  继承者 java.awt.Image
      继承者 java.awt.image.VolatileImage
所有已实现的接口:
Transparency

public abstract class VolatileImage
extends Image
implements Transparency

VolatileImage 是一种图像,它可以根据不受应用程序控制的情形(例如,由操作系统或其他应用程序引起的情况)随时丢失其内容。由于存在硬件加速的潜力,VolatileImage 对象在某些平台上能够获得显著的性能受益。

图像的绘图表面(图像内容实际驻留的内存)可以丢失或失效,从而引起该内存的内容丢失。因此,绘图表面需要恢复或重新创建,该表面的内容需要重新呈现。VolatileImage 提供了一个接口,此接口允许用户检测这些问题,并在出现这些问题时修复它们。

不能直接为此图像创建子类,而应该使用 Component.createVolatileImageGraphicsConfiguration.createCompatibleVolatileImage(int, int) 方法来创建。

以下是一个使用 VolatileImage 对象的例子:

 // 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());
 

注意,此类是从 Image 类创建的子类,Image 类包含带有一个 ImageObserver 参数的方法,用于从潜在 ImageProducer 收到信息时的异步通知。由于此 VolatileImage 不是从异步源加载的,因此带有 ImageObserver 参数的不同方法的行为就好像已经从 ImageProducer 中获得了数据。明确地说,这意味着这些方法的返回值永远不会指示信息还不是可用的,并且永远不需要为了异步回调通知而记录这些方法中使用的 ImageObserver


字段摘要
static int IMAGE_INCOMPATIBLE
          经验证的图像与提供的 GraphicsConfiguration 对象不兼容,应该重新创建适当的图像。
static int IMAGE_OK
          经验证的图像准备按原样使用。
static int IMAGE_RESTORED
          经验证的图像已经被恢复并准备使用。
protected  int transparency
          创建此图像所使用的透明度值。
 
从类 java.awt.Image 继承的字段
accelerationPriority, SCALE_AREA_AVERAGING, SCALE_DEFAULT, SCALE_FAST, SCALE_REPLICATE, SCALE_SMOOTH, UndefinedProperty
 
从接口 java.awt.Transparency 继承的字段
BITMASK, OPAQUE, TRANSLUCENT
 
构造方法摘要
VolatileImage()
           
 
方法摘要
abstract  boolean contentsLost()
          如果由于最后一次调用 validate 导致呈现数据丢失,则返回 true
abstract  Graphics2D createGraphics()
          创建一个 Graphics2D,可以将它绘制到此 VolatileImage 中。
 void flush()
          释放此图像当前占用的系统资源。
abstract  ImageCapabilities getCapabilities()
          返回 ImageCapabilities 对象,查询此对象即可了解此 VolatileImage 的特定功能。
 Graphics getGraphics()
          此方法返回 Graphics2D,但此处是出于向后兼容性的考虑。
abstract  int getHeight()
          返回此 VolatileImage 的高度。
abstract  BufferedImage getSnapshot()
          返回此对象的静态快照图像。
 ImageProducer getSource()
          此方法返回此 VolatileImage 的 ImageProducer。
 int getTransparency()
          返回透明度。
abstract  int getWidth()
          返回 VolatileImage 的宽度。
abstract  int validate(GraphicsConfiguration gc)
          如果由于最后一次调用 validate 以来绘图表面丢失,则试图恢复图像的绘图表面。
 
从类 java.awt.Image 继承的方法
getAccelerationPriority, getCapabilities, getHeight, getProperty, getScaledInstance, getWidth, setAccelerationPriority
 
从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

字段详细信息

IMAGE_OK

public static final int IMAGE_OK
经验证的图像准备按原样使用。

另请参见:
常量字段值

IMAGE_RESTORED

public static final int IMAGE_RESTORED
经验证的图像已经被恢复并准备使用。注意,恢复引起图像内容的丢失。

另请参见:
常量字段值

IMAGE_INCOMPATIBLE

public static final int IMAGE_INCOMPATIBLE
经验证的图像与提供的 GraphicsConfiguration 对象不兼容,应该重新创建适当的图像。从 validate 收到此返回代码后按原样使用图像是不明确的。

另请参见:
常量字段值

transparency

protected int transparency
创建此图像所使用的透明度值。

从以下版本开始:
1.5
另请参见:
GraphicsConfiguration.createCompatibleVolatileImage(int, int,int), GraphicsConfiguration.createCompatibleVolatileImage(int, int,ImageCapabilities,int), Transparency
构造方法详细信息

VolatileImage

public VolatileImage()
方法详细信息

getSnapshot

public abstract BufferedImage getSnapshot()
返回此对象的静态快照图像。返回的 BufferedImage 仅与请求时刻的 VolatileImage 保持一致,不随 VolatileImage 未来的更改而更新。

返回:
VolatileImageBufferedImage 表示形式
另请参见:
BufferedImage

getWidth

public abstract int getWidth()
返回 VolatileImage 的宽度。

返回:
VolatileImage 的宽度。

getHeight

public abstract int getHeight()
返回此 VolatileImage 的高度。

返回:
VolatileImage 的高度。

getSource

public ImageProducer getSource()
此方法返回此 VolatileImage 的 ImageProducer。注意,用于呈现操作和位图传输到屏幕或其他 VolatileImage 对象时,VolatileImage 对象很理想,但用于读回图像的像素时则相反。因此,诸如 getSource 这类操作的执行速度可能不如不依赖读取像素的操作。同样要注意,从图像读取的像素值只与检索时图像里的像素值保持一致。此方法在作出请求时拍下图像的快照,返回的 ImageProducer 对象使用该静态快照,而不是原始的 VolatileImage 进行工作。调用 getSource() 等效于调用 getSnapshot().getSource()。

指定者:
Image 中的 getSource
返回:
ImageProducer,它可以为此 Image 的 BufferedImage 表示形式生成像素。
另请参见:
ImageProducer, getSnapshot()

flush

public void flush()
释放此图像当前占用的系统资源。

当创建 VolatileImage 对象时,可能为支持图像而分配了诸如显存 (VRAM) 之类的有限系统资源。当不再使用 VolatileImage 对象时,可以将它作为垃圾回收,并返还其占用的系统资源,但此过程无法在保证的时间内发生。创建许多 VolatileImage 对象的应用程序(例如,在窗口大小改变时可以强行重建其后台缓冲区的可调整大小窗口)可能会为新的 VolatileImage 对象用光最优系统资源,因为原有对象还没有从系统中移除。(仍然可以创建新的 VolatileImage 对象,但它们执行起来可能不如那些在加速内存中创建的对象)。

通过调用此 flush 方法,应用程序可以对过时的 VolatileImage 对象所占用的资源状态拥有更多的控制权。

此方法将导致图像内容丢失,因此调用 contentsLost() 将返回 true 并且图像能再次使用前必须经过验证。

指定者:
Image 中的 flush
另请参见:
contentsLost(), validate(java.awt.GraphicsConfiguration)

getGraphics

public Graphics getGraphics()
此方法返回 Graphics2D,但此处是出于向后兼容性的考虑。createGraphics 更为方便,因为它被声明为返回 Graphics2D

指定者:
Image 中的 getGraphics
返回:
Graphics2D,可以将它绘制到此图像中。
另请参见:
Graphics, Component.createImage(int, int)

createGraphics

public abstract Graphics2D createGraphics()
创建一个 Graphics2D,可以将它绘制到此 VolatileImage 中。

返回:
Graphics2D,用于绘制到此图像中。

validate

public abstract int validate(GraphicsConfiguration gc)
如果由于最后一次调用 validate 以来绘图表面丢失,则试图恢复图像的绘图表面。还要依靠给定的 GraphicsConfiguration 参数验证此图像:查看从此图像到 GraphicsConfiguration 的操作是否是兼容的。以下这种情形就是一个不兼容组合的例子:VolatileImage 对象在一个图形设备上创建,然后在另一个不同的图形设备上呈现。由于 VolatileImage 对象与设备特别相关,此操作可能不会按预期进行,因此调用此 validate 返回的代码将记录这种不兼容性。null 或不正确的 gc 值可能引起 validate 返回不正确的值,随后可能引起呈现问题。

参数:
gc - 一个 GraphicsConfiguration 对象,图像依靠此对象进行验证。gc 为 null 意味着 validate 方法应该跳过兼容性测试。
返回:
如果图像不需要验证,则返回 IMAGE_OK
如果图像需要恢复,则返回 IMAGE_RESTORED。恢复意味着图像内容可能已受到影响,并且图像可能需要重新呈现。
如果图像与传递给 validate 方法的 GraphicsConfiguration 对象不兼容,则返回 IMAGE_INCOMPATIBLE。不兼容意味着图像可能需要用新的 ComponentGraphicsConfiguration 重新创建,以获得一个能够用此 GraphicsConfiguration 成功使用的图像。不兼容的图像不会检查是否需要恢复,因此在 IMAGE_INCOMPATIBLE 的值返回后,图像的状态不变,这个返回值与图像是否需要恢复无关。
另请参见:
GraphicsConfiguration, Component, IMAGE_OK, IMAGE_RESTORED, IMAGE_INCOMPATIBLE

contentsLost

public abstract boolean contentsLost()
如果由于最后一次调用 validate 导致呈现数据丢失,则返回 true。在对图像进行的任何系列呈现操作的结尾,应用程序应该调用此方法,以查看图像是否需要验证和重新呈现。

返回:
如果绘图表面需要恢复,则返回 true,否则返回 false

getCapabilities

public abstract ImageCapabilities getCapabilities()
返回 ImageCapabilities 对象,查询此对象即可了解此 VolatileImage 的特定功能。这允许程序员查找关于他们已经创建的特定 VolatileImage 对象的更多运行时信息。例如,用户可能要创建一个 VolatileImage,但系统剩余的显存可能不足以创建该尺寸的图像,因此尽管该对象是 VolatileImage,但它可能不会像此平台上其他 VolatileImage 对象一样被加速。用户可能需要该信息来寻找解决问题的其他方案。

返回:
包含此 VolatileImage 的功能的 ImageCapabilities 对象。
从以下版本开始:
1.4

getTransparency

public int getTransparency()
返回透明度。返回 OPAQUE、BITMASK 或 TRANSLUCENT 中的一种。

指定者:
接口 Transparency 中的 getTransparency
返回:
VolatileImage 的透明度。
从以下版本开始:
1.5
另请参见:
Transparency.OPAQUE, Transparency.BITMASK, Transparency.TRANSLUCENT

JavaTM 2 Platform
Standard Ed. 5.0

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策