Skip to main content
リソース内の指定されたサブリソースへの CPU ポインターを取得しますが、そのポインター値をアプリケーションに開示しない場合があります。Map は、GPU によって加えられた変更が CPU からのこのアドレスへの読み取りに反映されるように、必要に応じて CPU キャッシュも無効化します。

構文

パラメーター

Subresource
型: UINT
サブリソースのインデックス番号を指定します。 pReadRange [in, optional]
型: const D3D12_RANGE *
アクセスするメモリ範囲を記述する D3D12_RANGE 構造体へのポインター。 これは CPU が読み取る可能性のある領域を示し、座標はサブリソース相対です。null ポインターは、CPU がサブリソース全体を読み取る可能性があることを示します。EndBegin 以下となる範囲を渡すことで、CPU がデータを読み取らないことを指定することも有効です。 ppData [out, optional]
型: void **
リソース データへのポインターを受け取るメモリ ブロックへのポインター。 null ポインターも有効であり、WriteToSubresource のようなメソッド用に CPU 仮想アドレス範囲をキャッシュするのに便利です。ppData が NULL でない場合、返されるポインターは pReadRange の値によってオフセットされることはありません。

戻り値

型: HRESULT このメソッドは、Direct3D 12 のリターン コード のいずれかを返します。

解説

Map および Unmap は、複数のスレッドから安全に呼び出せます。ネストされた Map 呼び出しがサポートされ、参照カウントされます。Map への最初の呼び出しでリソースの CPU 仮想アドレス範囲が割り当てられます。Unmap の最後の呼び出しで CPU 仮想アドレス範囲が解放されます。CPU 仮想アドレスは通常アプリケーションに返されます。ただし、レイアウトが不明なテクスチャの内容を操作する場合は、CPU 仮想アドレスを開示することはできません。詳細については WriteToSubresource を参照してください。アプリケーションは、Map が永続的にネストされていない限り、アドレスの一貫性に依存できません。 Map によって返されるポインターは、通常のポインターのすべての機能を持つことは保証されませんが、ほとんどのアプリケーションは通常の使用で違いに気付くことはありません。たとえば、WRITE_COMBINE の動作を持つポインターは、WRITE_BACK の動作に比べて CPU メモリ順序の保証が弱くなります。CPU と GPU の両方からアクセスできるメモリは、PCIe の制限により、CPU が持つ同じアトミック メモリ保証を共有することは保証されていません。同期にはフェンスを使用してください。 Map の使用モデルには、シンプルと高度の 2 つのカテゴリーがあります。シンプルな使用モデルはツールのパフォーマンスを最大化するため、アプリケーションでは、高度モデルが必要であることが判明するまで、シンプル モデルに従うことが推奨されます。

シンプルな使用モデル

アプリケーションは、すべてのアダプター アーキテクチャを合理的にサポートするために、UPLOAD、DEFAULT、READBACK のヒープ タイプ抽象化に従うべきです。
アプリケーションは、たとえ偶然でも、UPLOAD ヒープ上のリソースへのポインターからの CPU 読み取りを避けるべきです。CPU 読み取りは機能しますが、多くの一般的な GPU アーキテクチャでは非常に遅いため、以下を考慮してください。
  • D3D12_HEAP_TYPE_UPLOAD であるか、D3D12_CPU_PAGE_PROPERTY_WRITE_COMBINE を持つヒープに関連付けられたリソースから CPU に読み取らせないでください。
  • pData が指すメモリ領域は PAGE_WRITECOMBINE で割り当てられる可能性があり、アプリはそのようなメモリに関連付けられたすべての制限を守る必要があります。
  • 以下の C++ コードでさえも、次の x86 アセンブリ コードに展開される可能性があるため、メモリから読み取ってパフォーマンス上のペナルティを引き起こす可能性があります。C++ コード:
    x86 アセンブリ コード:
  • このパフォーマンス ペナルティを回避するには、適切な最適化設定と言語構造を使用してください。たとえば、volatile ポインターを使用するか、コード サイズではなくコード速度に対して最適化することで、xor の最適化を回避できます。
アプリケーションは、CPU が変更しない間はリソースをアンマップされたままにし、常に厳密で正確な範囲を使用することが推奨されます。これにより、グラフィックス デバッグ やデバッグ層などのツールで最も高速なモードが有効になります。こうしたツールは、GPU が読み取る可能性のあるメモリに対する CPU のすべての変更を追跡する必要があります。

高度な使用モデル

CPU アクセス可能なヒープ上のリソースは、永続的にマップできます。つまり、リソース作成の直後に Map を一度だけ呼び出すことができます。Unmap を呼び出す必要はありませんが、Map から返されたアドレスは、リソースへの最後の参照が解放された後は使用してはなりません。永続マップを使用する場合、アプリケーションは、GPU がそのメモリを読み書きするコマンド リストを実行する前に、CPU がメモリへのデータの書き込みを完了することを保証する必要があります。一般的なシナリオでは、アプリケーションは ExecuteCommandLists を呼び出す前にメモリに書き込むだけでよいですが、フェンスを使用してコマンド リストの実行を遅らせる方法も機能します。
すべての CPU アクセス可能メモリ タイプは、リソースがマップされてから決してアンマップされない永続マッピング使用をサポートします。ただし、リソースが破棄された後にアプリケーションがポインターにアクセスしないことが条件です。

D3D12Bundles サンプルでは、ID3D12Resource::Map を次のように使用しています。 三角形データを頂点バッファーにコピーします。
定数バッファー用のアップロード ヒープを作成します。
D3D12 リファレンスのサンプル コード を参照してください。

要件

ヘッダー: d3d12_xs.h または d3d12_x.h
ライブラリ: d3d12_xs.lib または d3d12_x.lib
サポートされているプラットフォーム: XBOX Series 本体および XBOX One ファミリ

関連項目

ID3D12Resource サブリソース Unmap
最終更新日 2026年8月24日