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 はこれらの問題が発生した時にこれを検出し、修正するためのインタフェースを提供します。

VolatileImage オブジェクトが生成される時には、イメージサポートのため、ビデオメモリー (VRAM) などの制限されたシステムリソースが割り当てられます。VolatileImage オブジェクトが使用されなくなった場合にはガベージコレクトされ、割り当てられたシステムリソースが解放されますが、このプロセスの実行タイミングは一定ではありません。たとえばウィンドウサイズを変更すると、変更のたびにバックバッファーが再生成されますが、このように多数の VolatileImage オブジェクトを生成するアプリケーションでは、使用されなくなったオブジェクトがシステム上に残っているという理由だけで、新しい VolatileImage オブジェクトの生成に最適なリソースが不足する可能性があります。この場合、新しい VolatileImage オブジェクトが生成されても、高速なメモリーに生成された場合に比べてパフォーマンスは低下します。flush メソッドはいつでも呼び出して、VolatileImage で使用されるリソースを事前に解放し、以後の VolatileImage オブジェクトの高速化を妨げないようにすることができます。この方法では、無効になった VolatileImage オブジェクトに占有されているリソースの状態をアプリケーションから制御しやすくなります。

このイメージは直接サブクラス化せず、Component.createVolatileImage または GraphicsConfiguration.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());
 

情報は潜在的に ImageProducer から得られるため、このクラスは、非同期通知に ImageObserver パラメータを使用するメソッドを含む Image クラスからサブクラス化してください。この VolatileImage は非同期ソースからロードされないので、ImageObserver パラメータを持つ複数のメソッドが、データが ImageProducer から取得済みであるかのように動作します。ここで重要なことは、このようなメソッドからの戻り値を確認しても、情報が有効かどうかは判断できないということです。 したがって、これらのメソッドで使用されている ImageObserver を、非同期コールバック通知のために記録する必要はありません。

導入されたバージョン:

1.4

フィールドの概要

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() この VolatileImage に描画するために使用できる Graphics2D を生成します。
abstract ImageCapabilities	getCapabilities() この VolatileImage の固有の機能を照会できる ImageCapabilities オブジェクトを返します。
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 から継承されたメソッド

flush, 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 が変更されても更新されません。

戻り値:

この VolatileImage の BufferedImage 表現

関連項目:

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

戻り値:

このイメージの BufferedImage 表現のピクセル生成に使用可能な ImageProducer

関連項目:

ImageProducer, getSnapshot()

getGraphics

public Graphics getGraphics()

このメソッドは Graphics2D を返しますが、ここでは下位互換のために提供されます。Graphics2D を返すように宣言されているため、createGraphics の方が便利です。

定義:

クラス Image 内の getGraphics

戻り値:

このイメージへの描画に使用される Graphics2D

関連項目:

Graphics, Component.createImage(int, int)

createGraphics

public abstract Graphics2D createGraphics()

この VolatileImage に描画するために使用できる Graphics2D を生成します。

戻り値:

このイメージへの描画に使用される Graphics2D

validate

public abstract int validate(GraphicsConfiguration gc)

最後の validate 呼び出し以降にイメージの描画表面が失われている場合、その描画表面を復元します。さらにこのイメージを指定された GraphicsConfiguration パラメータに対して検証し、このイメージから GraphicsConfiguration への操作が互換性を持つかどうかを確認します。互換性を持たない組み合わせが考えられるのは、VolatileImage オブジェクトがあるグラフィックデバイス上で生成され、別のグラフィックデバイス上で描画に使用されるような場合です。VolatileImage オブジェクトはデバイス固有のものとなる傾向が強いので、このような場合では意図したとおりに動作しない可能性があり、この validate 呼び出しの戻り値でこの不整合が通知されます。gc に対する値が null の場合、あるいは不正な場合は、validate から不正な値が返され、あとで描画についての問題が発生する可能性があります。

パラメータ:

gc - このイメージに対して検証される GraphicsConfiguration オブジェクト。gc が null の場合、検証メソッドの互換テストがスキップされる

戻り値:

イメージが検証不要の場合は IMAGE_OK
イメージの復元が必要な場合は IMAGE_RESTORED。イメージの復元を行った場合は、内容に影響しているため、イメージの再描画が必要な可能性がある
イメージが validate メソッドに渡された GraphicsConfiguration オブジェクトと互換性がない場合は IMAGE_INCOMPATIBLE。この場合、この GraphicsConfiguration で正常に使用可能なイメージを得るため、新しい Component または 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()

この VolatileImage の固有の機能を照会できる ImageCapabilities オブジェクトを返します。プログラマが、生成した特定の 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