MonoGame/クラスライブラリ/RenderTargetUsage列挙体

RenderTargetUsage列挙体は、グラフィックデバイス（GraphicsDeviceクラス）に新たなレンダリングターゲット（RenderTarget2Dクラス）を設定したとき、そのレンダリングターゲットのデータをどのように処理するかを指定するのに使用する列挙体である。

名前空間

Microsoft.Xna.Framework.Graphics名前空間

構文

public enum RenderTargetUsage

フィールド

値	概要
DiscardContents	常にレンダリングターゲットのデータを削除する。
PlatformContents	プラットフォームに応じて扱いを変える。使うな危険。
PreserveContents	常にレンダリングターゲットのデータを保持する。

備考

PreserveContentsは遅い

PreserveContentsはVRAM容量が少ない環境ではメインメモリへの保存と復元が発生するため絶望的なほど遅くなる。 PCではまず問題になることはないようだが、一部のスマホでは絶望的な速度になるようだ。 なるべくDiscardContentsを使ったほうが良さそうだ。

DiscardContentsの注意点

DiscardContentsは「GraphicsDevice.SetRenderTargetするたびに破棄（初期化）される」という特徴がある。この特性があるためレンダリング系APIの呼出順序を間違えると残念なことになる。

GraphicsDevice.SetRenderTarget(このRenderTargetは初期化される);

ちなみにGraphicsDeviceが最初から持っているレンダリングターゲット（DirectXでいうプライマリサーフェイス、SetRenterTarget(null)）に相当するものはDiscardContentsに設定されている。

このため、たとば以下のコードは正常に動作しない。

protected override void Draw(GameTime gameTime)
{
    var gd = _graphics.GraphicsDevice;

    // （１）プライマリサーフェイスを塗りつぶす
    gd.Clear(Color.CornflowerBlue);

    // （２）レンダリングターゲットを切り替える
    gd.SetRenderTarget(new RenderTarget2D(GraphicsDevice, 128, 128));

    // （３）レンダリングターゲットをプライマリサーフェイスに戻す
    // このときプライマリサーフェイスはDiscardContents設定なので内容がクリアされ（１）の塗りつぶしが無かったことにされる。
    // （２）のレンダーターゲットは影響を受けない。
    gd.SetRenderTarget(null);

    base.Draw(gameTime);
}

DiscardContentsの場合は以下のような呼出順序で書かなければならない。

protected override void Draw(GameTime gameTime)
{
    var gd = _graphics.GraphicsDevice;

    // （１）レンダリングターゲットを切り替える
    gd.SetRenderTarget(new RenderTarget2D(GraphicsDevice, 128, 128));

    // （２）レンダリングターゲットをプライマリサーフェイスに戻す（と同時にまっさらになる）
    // （１）のレンダーターゲットは影響を受けない。
    gd.SetRenderTarget(null);

    // （３）プライマリサーフェイスを塗りつぶす
    gd.Clear(Color.CornflowerBlue);

    base.Draw(gameTime);
}

関連項目

• GraphicsDeviceクラス
  • SetRenderTargetメソッド
  • SetRenderTargetsメソッド
  • GetRenderTargetsメソッド
• RenderTarget2Dクラス
• RenderTargetCubeクラス
• CubeMapFace列挙体
• RenderTargetBinding構造体
• RenderTargetUsage列挙体