> ## 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 部分或 PSO 的 RASTERIZER\_DESC 部分中的 ForcedSampleCount 指定相符樣本計數的 PSO。

SetSamplePositions 只能在圖形 CommandList 上呼叫，無法在套件組合中呼叫；套件組合會從呼叫端 CommandList 繼承樣本位置狀態，且不會修改它。

呼叫 SetSamplePositions(0, 0, NULL) 會將樣本位置還原為其預設值。

**清除 RenderTarget：** 清除轉譯目標時會忽略樣本位置。

**清除 DepthStencil：** 清除深度樣板表面的深度部分或其任何區域時，樣本位置必須設定為符合未來對已清除表面或區域進行轉譯時所用的位置；使用不同樣本位置所產生的任何未清除區域內容將變成未定義。

清除深度樣板表面的樣板部分或其任何區域時，會忽略樣本位置。

**繪製到 RenderTarget：** 繪製到轉譯目標時，即使繪製到與先前繪製呼叫重疊的區域，也可以針對每個繪製呼叫變更樣本位置。目前的樣本位置會決定每個繪製呼叫的運作語意，且樣本取自轉譯目標的已儲存內容，即使這些內容是使用不同樣本位置所產生的也一樣。

**使用 DepthStencil 繪製：** 繪製到深度樣板表面 (讀取或寫入) 或其任何區域時，樣本位置必須設定為符合先前清除受影響區域時所用的位置。若要使用不同的樣本位置，必須先清除目標區域。清除區域以外的像素不受影響。

硬體可能會將深度樣板表面的深度部分儲存為平面方程式，並在應用程式發出讀取時評估這些方程式以產生深度值。只有點陣化器與輸出合併器需要支援深度樣板表面深度部分的可程式化樣本位置。對於已使用設定的樣本位置轉譯之深度部分，任何其他讀取或寫入都可能忽略這些位置，改為在標準位置取樣。

**解析 RenderTarget：** 解析轉譯目標或其任何區域時，會忽略樣本位置；這些 API 只會對已儲存的色彩值運作。

**解析 DepthStencil：** 解析深度樣板表面的深度部分或其任何區域時，樣本位置必須設定為符合過去對已解析表面或區域進行轉譯時所用的位置。若要使用不同的樣本位置，必須先清除目標區域。

解析深度樣板表面的樣板部分或其任何區域時，會忽略樣本位置；樣板解析只會對已儲存的樣板值運作。

**複製 RenderTarget：** 從轉譯目標複製時，無論是完整或部分複製，都會忽略樣本位置。

**複製 DepthStencil (完整子資源)：** 從深度樣板表面複製完整子資源時，樣本位置必須設定為符合用來產生來源表面的樣本位置。若要使用不同的樣本位置，必須先清除目標區域。

在某些硬體上，來源表面的屬性 (例如為深度值儲存的平面方程式) 會傳輸到目的地。因此，如果後續繪製到目的地表面，就需要對目的地表面使用原本用來產生來源內容的樣本位置。為了保持一致性，API 在所有硬體上都要求這麼做，即使這可能只適用於部分硬體。

**複製 DepthStencil (部分子資源)：** 從深度樣板表面複製部分子資源時，樣本位置必須設定為符合用來產生來源表面的樣本位置，與複製完整子資源類似。不過，如果受影響的目的地子資源內容只有部分被複製涵蓋，則這些子資源中未涵蓋部分的內容將變成未定義，除非這些內容全部都是使用與複製來源相同的樣本位置所產生。若要使用不同的樣本位置，必須先清除目標區域。

從深度樣板表面的樣板部分複製部分子資源時，會忽略樣本位置。用來為目的地緩衝區中未被複製涵蓋之其他區域產生內容的樣本位置並不重要，這些內容仍然有效。

**著色器 SamplePos：** HLSL SamplePos 內建函式無法感知可程式化樣本位置，在以可程式化位置轉譯的表面上呼叫此函式的著色器所傳回的結果是未定義的。如有需要，應用程式必須手動將座標傳入其著色器。同樣地，使用可程式化樣本位置時，依樣本索引評估屬性也是未定義的。

**從 DEPTH\_READ 或 DEPTH\_WRITE 狀態轉換：** 如果處於 DEPTH\_READ 或 DEPTH\_WRITE 狀態的子資源轉換為任何其他狀態 (包括 COPY\_SOURCE 或 RESOLVE\_SOURCE)，某些硬體可能需要將表面解壓縮。因此，必須在命令清單上設定樣本位置，使其符合用來產生來源表面內容的位置。此外，只要表面中仍保留相同的深度資料，對於該表面的任何後續轉換，樣本位置都必須持續符合命令清單上所設定的位置。若要使用不同的樣本位置，必須先清除目標區域。

如果應用程式想要在只需要使用一部分時將解壓縮區域減到最少，或只是想保留壓縮，可以在指定矩形的情況下以 DECOMPRESS 模式呼叫 ResolveSubresourceRegion()。在某些硬體上，這只會將相關區域解壓縮到個別資源，並保持來源不變，但在其他硬體上，連來源區域也會被解壓縮。接著可以將這個個別明確解壓縮的資源轉換為所需的狀態 (例如 SHADER\_RESOURCE)。

**從 RENDER\_TARGET 狀態轉換：** 如果處於 RENDER\_TARGET 狀態的子資源轉換為 COPY\_SOURCE 或 RESOLVE\_SOURCE 以外的任何狀態，某些實作可能需要將表面解壓縮。此解壓縮與樣本位置無關。

如果應用程式想要在只需要使用一部分時將解壓縮區域減到最少，或只是想保留壓縮，可以在指定矩形的情況下以 DECOMPRESS 模式呼叫 ResolveSubresourceRegion()。在某些硬體上，這只會將相關區域解壓縮到個別資源，並保持來源不變，但在其他硬體上，連來源區域也會被解壓縮。接著可以將這個個別明確解壓縮的資源轉換為所需的狀態 (例如 SHADER\_RESOURCE)。

## 需求

**標頭:** d3d12\_xs.h 或 d3d12\_x.h\
**程式庫:** d3d12\_xs.lib 或 d3d12\_x.lib\
**支援的平台**: XBOX Series 主機與 XBOX One 系列

## 另請參閱

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


## Related topics

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