> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SetSamplePositions

> このメソッドは、後続の描画、コピー、解決、および同様の操作で使用されるサンプル位置を設定します。

このメソッドは、後続の描画、コピー、解決、および同様の操作で使用されるサンプル位置を設定します。

## 構文

```cpp theme={null}
void SetSamplePositions(
    UINT NumSamplesPerPixel,
    UINT NumPixels,
    D3D12_SAMPLE_POSITION  pSamplePositions
)
```

### パラメーター

*NumSamplesPerPixel \[in]*\
型: UINT

[SAL](https://learn.microsoft.com/en-us/visualstudio/code-quality/annotating-function-parameters-and-return-values): <code>*In*</code>

ピクセルごとに取得するサンプル数を指定します。この値は 1、2、4、8、または 16 のいずれかであり、それ以外の場合、SetSamplePosition の呼び出しは破棄されます。サンプル数は、描画時に PSO で設定されているサンプル カウントと一致する必要があります。それ以外の場合、動作は未定義です。

*NumPixels \[in]*\
型: UINT

[SAL](https://learn.microsoft.com/en-us/visualstudio/code-quality/annotating-function-parameters-and-return-values): <code>*In*</code>

サンプル パターンを指定するピクセル数を指定します。この値は 1 または 4 のいずれかであり、それ以外の場合、SetSamplePosition の呼び出しは破棄されます。値 1 は、各ピクセルに単一のサンプル パターンが使用されるように構成します。値 4 は、レンダー ターゲットまたはビューポート空間全体にわたって偶数座標に整列されて繰り返される 2x2 ピクセル グリッド内の各ピクセルに対して個別のサンプル パターンを構成します。

結合されたサンプルの最大数は 16 を超えることはできず、超える場合、呼び出しは破棄されることに注意してください。NumPixels が 4 に設定されている場合、NumSamplesPerPixel は 4 サンプル以下しか指定できません。

*pSamplePositions \[in]*\
型: D3D12\_SAMPLE\_POSITION \*

[SAL](https://learn.microsoft.com/en-us/visualstudio/code-quality/annotating-function-parameters-and-return-values): <code>*In\_reads*(NumSamplesPerPixel\*NumPixels)</code>

D3D12\_SAMPLE\_POSITION 要素の配列を指定します。配列のサイズは NumPixels \* NumSamplesPerPixel です。NumPixels が 4 に設定されている場合、サンプル位置の最初のグループは 2x2 ピクセル グリッド内の左上のピクセルに対応し、次のグループは右上、次のグループは左下、最後のグループは右下に対応します。

レンダリング中にセントロイド補間を使用する場合、各ピクセルの位置の順序がセントロイド サンプリング優先度を決定します。つまり、指定された順序内で最初に被覆されたサンプルがセントロイド サンプル位置として選択されます。

### 戻り値

型: void

なし。

## 解説

サンプル位置の操作セマンティクスは、発生する可能性のあるさまざまな描画、コピー、解決、およびその他の操作によって決定されます。

**CommandList:** CommandList 内で SetSamplePositions が事前に呼び出されていない場合、サンプルはパイプライン ステート オブジェクト (PSO) に基づく既定の位置を想定します。既定の位置は、PSO の SAMPLE\_DESC 部分が存在する場合はそれによって、または PSO の RASTERIZER\_DESC 部分の ForcedSampleCount が 0 より大きい値に設定されている場合は標準のサンプル位置によって決定されます。

SetSamplePosition が呼び出された後の後続の描画呼び出しでは、PSO の SAMPLE\_DESC 部分または RASTERIZER\_DESC 部分の ForcedSampleCount を使用して一致するサンプル カウントを指定する PSO を使用する必要があります。

SetSamplePositions は、グラフィックス CommandList でのみ呼び出せます。バンドルでは呼び出せません。バンドルは呼び出し元の CommandList からサンプル位置ステートを継承し、それを変更しません。

SetSamplePositions(0, 0, NULL) を呼び出すと、サンプル位置は既定値に戻ります。

**Clear RenderTarget:** レンダー ターゲットをクリアする場合、サンプル位置は無視されます。

**Clear DepthStencil:** 深度ステンシル サーフェスの深度部分またはその任意の領域をクリアする場合、サンプル位置はクリアされたサーフェスまたは領域への将来のレンダリングと一致するように設定する必要があります。異なるサンプル位置を使用して生成された未クリア領域の内容は未定義になります。

深度ステンシル サーフェスのステンシル部分またはその任意の領域をクリアする場合、サンプル位置は無視されます。

**Draw to RenderTarget:** レンダー ターゲットに描画する場合、以前の描画呼び出しと重なる領域に描画する場合でも、描画呼び出しごとにサンプル位置を変更できます。現在のサンプル位置が各描画呼び出しの操作セマンティクスを決定し、サンプルは異なるサンプル位置を使用して生成された内容であっても、レンダー ターゲットの格納された内容から取得されます。

**Draw using DepthStencil:** 深度ステンシル サーフェス (読み取りまたは書き込み) またはその任意の領域に描画する場合、サンプル位置は以前に影響を受けた領域をクリアするために使用されたものと一致するように設定する必要があります。別のサンプル位置を使用するには、対象領域を最初にクリアする必要があります。クリア領域外のピクセルは影響を受けません。

ハードウェアは深度ステンシル サーフェスの深度部分を平面方程式として格納し、アプリケーションが読み取りを発行した際にそれらを評価して深度値を生成する場合があります。ラスタライザーと出力マージのみが、深度ステンシル サーフェスの深度部分のプログラム可能なサンプル位置をサポートする必要があります。サンプル位置を設定した状態でレンダリングされた深度部分のその他の読み取りや書き込みは、それらを無視して標準位置でサンプリングする場合があります。

**Resolve RenderTarget:** レンダー ターゲットまたはその任意の領域を解決する場合、サンプル位置は無視されます。これらの API は格納された色の値のみに対して動作します。

**Resolve DepthStencil:** 深度ステンシル サーフェスの深度部分またはその任意の領域を解決する場合、サンプル位置は解決されたサーフェスまたは領域への過去のレンダリングと一致するように設定する必要があります。別のサンプル位置を使用するには、対象領域を最初にクリアする必要があります。

深度ステンシル サーフェスのステンシル部分またはその任意の領域を解決する場合、サンプル位置は無視されます。ステンシル解決は、格納されたステンシル値のみに対して動作します。

**Copy RenderTarget:** レンダー ターゲットからコピーする場合、フル コピーか部分コピーかにかかわらず、サンプル位置は無視されます。

**Copy DepthStencil (フル サブリソース):** 深度ステンシル サーフェスからフル サブリソースをコピーする場合、サンプル位置はソース サーフェスの生成に使用されたサンプル位置と一致するように設定する必要があります。別のサンプル位置を使用するには、対象領域を最初にクリアする必要があります。

一部のハードウェアでは、ソース サーフェスのプロパティ (深度値用に格納された平面方程式など) が宛先に転送されます。したがって、宛先サーフェスがその後描画される場合、ソース コンテンツの生成に元々使用されたサンプル位置を宛先サーフェスで使用する必要があります。この API は一貫性のため、一部のハードウェアにしか適用されない場合でもすべてのハードウェアでこれを要求します。

**Copy DepthStencil (部分サブリソース):** 深度ステンシル サーフェスから部分サブリソースをコピーする場合、サンプル位置はソース サーフェスの生成に使用されたサンプル位置と一致するように設定する必要があります (フル サブリソースのコピーと同様)。ただし、影響を受ける宛先サブリソースの内容がコピーによって部分的にしか被覆されない場合、それらのサブリソース内の被覆されなかった部分の内容は、全体がコピー ソースと同じサンプル位置を使用して生成されていない限り、未定義になります。別のサンプル位置を使用するには、対象領域を最初にクリアする必要があります。

深度ステンシル サーフェスのステンシル部分から部分サブリソースをコピーする場合、サンプル位置は無視されます。コピーで被覆されていない宛先バッファーの他の領域のコンテンツ生成に、どのサンプル位置が使用されたかは問題ではなく、それらの内容は有効なままです。

**Shader SamplePos:** HLSL SamplePos 組み込み関数はプログラム可能なサンプル位置を認識しません。プログラム可能な位置でレンダリングされたサーフェスに対してこれを呼び出したシェーダーに返される結果は未定義です。必要に応じて、アプリケーションは座標を手動でシェーダーに渡す必要があります。同様に、プログラム可能なサンプル位置でサンプル インデックスによって属性を評価することも未定義です。

**DEPTH\_READ または DEPTH\_WRITE 状態からの遷移:** DEPTH\_READ または DEPTH\_WRITE 状態のサブリソースが COPY\_SOURCE や RESOLVE\_SOURCE を含む他の状態に遷移する場合、一部のハードウェアではサーフェスを展開する必要があります。したがって、ソース サーフェスのコンテンツ生成に使用されたサンプル位置と一致するように、コマンド リストにサンプル位置を設定する必要があります。さらに、同じ深度データがサーフェスに残っている間の後続の遷移についても、サンプル位置はコマンド リストに設定されているものと一致し続ける必要があります。別のサンプル位置を使用するには、対象領域を最初にクリアする必要があります。

一部のみを使用する必要がある場合や、圧縮を保持するために展開領域を最小化したい場合、ResolveSubresourceRegion() を DECOMPRESS モードで矩形を指定して呼び出せます。これにより、関連する領域のみが別のリソースに展開され、一部のハードウェアではソースがそのまま残ります。ただし、他のハードウェアではソース領域も展開されます。明示的に展開された別のリソースは、その後、目的の状態 (SHADER\_RESOURCE など) に遷移できます。

**RENDER\_TARGET 状態からの遷移:** RENDER\_TARGET 状態のサブリソースが COPY\_SOURCE または RESOLVE\_SOURCE 以外に遷移する場合、一部の実装ではサーフェスを展開する必要があるかもしれません。この展開はサンプル位置に依存しません。

一部のみを使用する必要がある場合や、圧縮を保持するために展開領域を最小化したい場合、ResolveSubresourceRegion() を DECOMPRESS モードで矩形を指定して呼び出せます。これにより、関連する領域のみが別のリソースに展開され、一部のハードウェアではソースがそのまま残ります。ただし、他のハードウェアではソース領域も展開されます。明示的に展開された別のリソースは、その後、目的の状態 (SHADER\_RESOURCE など) に遷移できます。

## 要件

**ヘッダー:** d3d12\_xs.h または d3d12\_x.h\
**ライブラリ:** d3d12\_xs.lib または d3d12\_x.lib\
**サポートされるプラットフォーム**: XBOX Series 本体および XBOX One ファミリ

## 関連項目

[ID3D12GraphicsCommandList1](/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist1/id3d12graphicscommandlist1_public)


## Related topics

- [D3D12_PROGRAMMABLE_SAMPLE_POSITIONS_TIER](/ja-jp/reference/graphics/d3d12/enums/d3d12_programmable_sample_positions_tier_public.md)
- [GetXmaDecodePositionForSample](/ja-jp/reference/audio/xma2defs/functions/getxmadecodepositionforsample.md)
- [D3D12_SAMPLE_POSITION](/ja-jp/reference/graphics/d3d12/structs/d3d12_sample_position_public.md)
- [XSpeechToTextSetPositionHint](/ja-jp/reference/system/xaccessibility/functions/xspeechtotextsetpositionhint.md)
- [XGameUiSetNotificationPositionHint](/ja-jp/reference/system/xgameui/functions/xgameuisetnotificationpositionhint.md)