> ## 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.

# 可變速率著色 Direct3D 12 API

> 可變速率著色 Direct3D 12 API

本主題是根據[可變速率著色規格](https://github.com/microsoft/DirectX-Specs/blob/master/d3d/VariableRateShading.md)建立，並已針對 XBOX Series X|S 硬體更新。

## API

下一節說明應用程式如何透過 Direct3D 12 存取可變速率著色 (VRS)。

### 查詢功能

```text theme={null}
enum D3D12_SHADING_RATE_TIER
{
    D3D12_SHADING_RATE_TIER_NOT_SUPPORTED,
    D3D12_SHADING_RATE_TIER_1,
    D3D12_SHADING_RATE_TIER_2,
};

struct D3D12_FEATURE_DATA_D3D12_OPTIONS6
{
    BOOL AdditionalShadingRatesSupported; 
    BOOL PerPrimitiveShadingRateIndependentOfViewportUse;
    D3D12_SHADING_RATE_TIER ShadingRateTier;
    UINT ShadingRateImageTileSize;
};

enum D3D12_FEATURE
{
    // ...
    D3D12_FEATURE_D3D12_OPTIONS6
};
```

若要查詢第 1 層功能，應用程式可以如下所示操作，例如：

```text theme={null}
// Check that Tier 1 is supported.
D3D12_FEATURE_DATA_D3D12_OPTIONS6 options;
return 
    SUCCEEDED(m_device->CheckFeatureSupport(
        D3D12_FEATURE_D3D12_OPTIONS6, 
        &options, 
        sizeof(options))) && 
    options.ShadingRateTier == D3D12_SHADING_RATE_TIER_1;
```

### 著色速率

```text theme={null}
enum D3D12_SHADING_RATE
{
    D3D12_SHADING_RATE_1X1 = 0x0, // No change to shading rate.
    D3D12_SHADING_RATE_1X2 = 0x1, // Reduces vertical resolution 2x.
    D3D12_SHADING_RATE_2X1 = 0x4, // Reduces horizontal resolution 2x.
    D3D12_SHADING_RATE_2X2 = 0x5, // Reduces both axes by 2x.
    D3D12_SHADING_RATE_2X4 = 0x6, // Reduce horizontal resolution 2x, vertical by 4x.
    D3D12_SHADING_RATE_4X2 = 0x9, // Reduce horizontal resolution 4x, vertical by 2x.
    D3D12_SHADING_RATE_4X4 = 0xA, // Reduces both axes by 4x.
};
```

這些值經過組織，讓著色速率可以輕鬆分解成兩個軸，每個軸的值都以對數空間精簡表示。

```text theme={null}
enum D3D12_AXIS_SHADING_RATE
{
    D3D12_AXIS_SHADING_RATE_1X = 0x0,
    D3D12_AXIS_SHADING_RATE_2X = 0x1, 
    D3D12_AXIS_SHADING_RATE_4X = 0x2
};
```

例如，可以這樣使用：

```text theme={null}
#define D3D12_MAKE_COARSE_SHADING_RATE(x,y) ((x) << 2 | (y))
D3D12_MAKE_COARSE_SHADING_RATE(
    D3D12_AXIS_SHADING_RATE_2X, 
    D3D12_AXIS_SHADING_RATE_1X)
```

為了方便起見，可以使用下列方式來剖析和理解 SV\_ShadingRate：

```text theme={null}
#define D3D12_GET_COARSE_SHADING_RATE_X_AXIS(x) ((x) >> 2 )
#define D3D12_GET_COARSE_SHADING_RATE_Y_AXIS(y) ((y) & 3 )
```

#### 備註

此資料解譯方式主要是用來描述可由著色器操作的螢幕空間遮罩。不過，沒有理由不在所有地方使用一致的粗略像素大小定義，包括設定命令層級著色速率時。

### 設定命令層級著色速率與合併器

著色速率以及選擇性的合併器，是透過命令清單方法來指定。

```text theme={null}
enum D3D12_SHADING_RATE_COMBINER
{
    D3D12_SHADING_RATE_COMBINER_PASSTHROUGH,
    D3D12_SHADING_RATE_COMBINER_OVERRIDE,
    D3D12_SHADING_RATE_COMBINER_MIN,
    D3D12_SHADING_RATE_COMBINER_MAX,
    D3D12_SHADING_RATE_COMBINER_SUM,
};

class ID3D12GraphicsCommandList5: public ID3D12GraphicsCommandList4
{
public:
    // ...
    virtual void RSSetShadingRate(
        D3D12_SHADING_RATE baseShadingRate, 
        _In_reads_opt_(2) D3D12_SHADING_RATE_COMBINER* combiners) = 0;
};
```

### 準備螢幕空間影像

指定可用著色速率影像的唯讀資源狀態定義如下。

```text theme={null}
enum D3D12_RESOURCE_STATES
{
    // ...
    D3D12_RESOURCE_STATE_SHADING_RATE_SOURCE
};
```

### 設定螢幕空間影像

螢幕空間影像是透過命令清單方法來指定。

```text theme={null}
class ID3D12GraphicsCommandList3: public ID3D12GraphicsCommandList2
{
public:
    // ...
    virtual void RSSetShadingRateImage(ID3D12Resource* image) = 0;
};
```

例如：

```text theme={null}
m_commandList->RSSetShadingRateImage(screenSpaceImage);
```

<Info>
  在 XBOX Series X|S 上，您必須在設定著色速率影像之前 (在 GPU 時間軸上)，將其轉換為可讀取狀態。
</Info>

### 查詢圖格大小

圖格大小是從功能中查詢。

```text theme={null}
D3D12_FEATURE_DATA_D3D12_OPTIONS6 options;
return 
    SUCCEEDED(m_device->CheckFeatureSupport(
        D3D12_FEATURE_D3D12_OPTIONS6, 
        &options, 
        sizeof(options))) && 
    UINT tileSize = options.ShadingRateImageTileSize;
```

只會擷取一個維度，因為水平和垂直維度永遠相同。如果系統的功能為 D3D12\_SHADING\_RATE\_TIER\_NOT\_SUPPORTED，傳回的圖格大小為 0。

## 另請參閱

[可變速率著色概觀](/zh-TW/build/core-features/graphics/newfeatures/vrs/vrs-overview)

[可變速率著色功能設計](/zh-TW/build/core-features/graphics/newfeatures/vrs/vrs-feature)

[為什麼要使用可變速率著色？](/zh-TW/build/core-features/graphics/newfeatures/vrs/why-vrs)


## Related topics

- [GDK 範例](/zh-TW/home/setup-install/samples.md)
- [NDA 主題目錄 - Microsoft Learn 線上連結](/zh-TW/nda/nda-topic-directory.md)
- [Direct3D 12 程式設計指南](/zh-TW/build/gdk-and-engines/guides/directx-12-programming-guide.md)
- [Advanced Shader Delivery](/zh-TW/build/gdk-and-engines/guides/advanced-shader-delivery.md)
- [XBOX Series X|S 上的可变速率着色 (VRS)](/zh-CN/build/core-features/graphics/newfeatures/vrs/index.md)