「MonoGame/クラスライブラリ/RenderTargetUsage列挙体」を編集中

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

== 名前空間 ==
 [[MonoGame/クラスライブラリ/Microsoft.Xna.Framework.Graphics名前空間|Microsoft.Xna.Framework.Graphics名前空間]]

== 構文 ==
 public enum RenderTargetUsage

== フィールド ==
{| class="wikitable"
|+
! 値
! 概要
|-
| DiscardContents
| 常にレンダリングターゲットのデータを削除する。
|-
| PlatformContents
| プラットフォームに応じて扱いを変える。使うな危険。
|-
| PreserveContents
| 常にレンダリングターゲットのデータを保持する。
|}

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

=== DiscardContentsの注意点 ===
DiscardContents設定になっていると「GraphicsDevice.SetRenderTargetするたびに破棄（初期化）される」という特徴がある。この特性があるためレンダリング系APIの呼出順序を間違えると残念なことになる。
<source lang="csharp">
GraphicsDevice.SetRenderTarget(このRenderTargetは初期化される);
</source>

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

このため、たとば以下のコードは正常に動作しない。
<source lang="csharp">
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);
}
</source>

DiscardContentsの場合は以下のような呼出順序で書かなければならない。
<source lang="csharp">
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);
}
</source>

== 関連項目 ==
* [[MonoGame/クラスライブラリ/GraphicsDeviceクラス|GraphicsDeviceクラス]]
** [[MonoGame/クラスライブラリ/GraphicsDeviceクラス/SetRenderTargetメソッド|SetRenderTargetメソッド]]
** [[MonoGame/クラスライブラリ/GraphicsDeviceクラス/SetRenderTargetsメソッド|SetRenderTargetsメソッド]]
** [[MonoGame/クラスライブラリ/GraphicsDeviceクラス/GetRenderTargetsメソッド|GetRenderTargetsメソッド]]
* [[MonoGame/クラスライブラリ/RenderTarget2Dクラス|RenderTarget2Dクラス]]
* [[MonoGame/クラスライブラリ/RenderTargetCubeクラス|RenderTargetCubeクラス]]
* [[MonoGame/クラスライブラリ/CubeMapFace列挙体|CubeMapFace列挙体]]
* [[MonoGame/クラスライブラリ/RenderTargetBinding構造体|RenderTargetBinding構造体]]
* [[MonoGame/クラスライブラリ/RenderTargetUsage列挙体|RenderTargetUsage列挙体]]

[[category: MonoGame]]