VolatileImage (Java Platform SE 7)

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

コンストラクタ
コンストラクタと説明
`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() を呼び出した場合と同じ結果が得られます。
    
    定義:
    
    getSource、クラス: Image
    
    戻り値:
    このイメージの BufferedImage 表現のピクセル生成に使用可能な ImageProducer。
    関連項目:
    ImageProducer、getSnapshot()
  - getGraphics
```
public Graphics getGraphics()
```
    このメソッドは Graphics2D を返しますが、ここでは下位互換のために提供されます。Graphics2D を返すように宣言されているため、createGraphics の方が便利です。
    
    定義:
    
    getGraphics、クラス: Image
    
    戻り値:
    このイメージへの描画に使用できる 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 のいずれかを返します。
    
    定義:
    
    getTransparency、インタフェース: Transparency
    
    戻り値:
    この VolatileImage の透明度。
    導入されたバージョン:
    
    1.5
    
    関連項目:
    Transparency.OPAQUE, Transparency.BITMASK, Transparency.TRANSLUCENT

バグまたは機能を送信
詳細な API リファレンスおよび開発者ドキュメントについては、Java SE のドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.

クラス VolatileImage

フィールドのサマリー

クラス java.awt.Image から継承されたフィールド

インタフェース java.awt.Transparency から継承されたフィールド

コンストラクタのサマリー

メソッドのサマリー

クラス java.awt.Image から継承されたメソッド

クラス java.lang.Object から継承されたメソッド

フィールドの詳細

IMAGE_OK

IMAGE_RESTORED

IMAGE_INCOMPATIBLE

transparency

コンストラクタの詳細

VolatileImage

メソッドの詳細

getSnapshot

getWidth

getHeight

getSource

getGraphics

createGraphics

validate

contentsLost

getCapabilities

getTransparency