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

# RSSetShadingRateImage (XBOX Series 主機)

> ID3D12GraphicsCommandList5::RSSetShadingRateImage 方法 (d3d12.h) 會設定可變速率著色 (VRS) 的螢幕空間著色速率影像。

設定可變速率著色 (VRS) 的螢幕空間著色速率影像。如需詳細資訊，請參閱[可變速率著色 (VRS)](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/vrs)。
此方法需要第 2 層[可變速率著色 (VRS)](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/vrs) 支援。請參閱 [**D3D12\_FEATURE\_DATA\_D3D12\_OPTIONS6**](/zh-TW/reference/graphics/d3d12/structs/d3d12_feature_data_d3d12_options6_public) 與 [**D3D12\_VARIABLE\_SHADING\_RATE\_TIER**](/zh-TW/reference/graphics/d3d12/enums/d3d12_variable_shading_rate_tier_public)。

## 語法

```cpp theme={null}
void RSSetShadingRateImage(
    ID3D12Resource  shadingRateImage
)
```

### 參數

*shadingRateImage*\
類型：ID3D12Resource \*

選擇性的指標，指向代表螢幕空間著色速率影像的 [ID3D12Resource](/zh-TW/reference/graphics/d3d12_xs/interfaces/ID3D12Resource/id3d12resource_xs)。
如果為 **NULL**，效果等同於所有值皆為 1x1 著色速率的著色速率影像。

此紋理必須已套用 [**D3D12\_RESOURCE\_STATE\_SHADING\_RATE\_SOURCE**](/zh-TW/reference/graphics/d3d12_x/enums/d3d12_resource_states) 狀態。

著色速率影像的圖格大小可以透過 [**D3D12\_FEATURE\_DATA\_D3D12\_OPTIONS6**](/zh-TW/reference/graphics/d3d12/structs/d3d12_feature_data_d3d12_options6_public) 判斷。
因此，著色速率影像的大小應為

```
ceil((float)rtWidth / VRSTileSize), ceil((float)rtHeight / VRSTileSize)
```

著色速率影像必須是具有單一 mip 的 2D 紋理，且格式為 [**DXGI\_FORMAT\_R8\_UINT**](https://learn.microsoft.com/en-us/windows/win32/api/dxgiformat/ne-dxgiformat-dxgi_format)。每個紋素都必須是對應 [**D3D12\_SHADING\_RATE**](/zh-TW/reference/graphics/d3d12/enums/d3d12_shading_rate_public) 的值。其配置必須為 [**D3D12\_TEXTURE\_LAYOUT\_UNKNOWN**](/zh-TW/reference/graphics/d3d12_x/enums/d3d12_texture_layout)，且不能是深度樣板、轉譯目標、同時存取或跨介面卡資源。

由於在 DirectX 中 (0, 0) 位於左上角，著色速率影像過小或過大會導致底部或右側沒有著色速率影像區域，或影像延伸超出這些方向。有多餘部分時會予以忽略 (但為合法)；影像過小時，底部與右側所有超出界限的區域都會採用影像的預設著色速率 1x1 (不過，這並不表示那就是最終著色速率。合併器仍會套用至此 1x1 預設值)。

### 傳回值

類型：void

無。

## 備註

若要讓螢幕空間著色速率影像生效，必須已呼叫 [**ID3D12GraphicsCommandList5::RSSetShadingRate**](/zh-TW/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist5/methods/id3d12graphicscommandlist5_rssetshadingrate_public) 來設定著色的合併器。否則，在使用預設合併器 (兩者皆為 [**D3D12\_SHADING\_RATE\_COMBINER\_PASSTHROUGH**](/zh-TW/reference/graphics/d3d12/enums/d3d12_shading_rate_combiner_public)) 的情況下，決定著色細微性時會忽略螢幕空間著色速率影像。

傳遞給 \[**ID3D12GraphicsCommandList5::RSSetShadingRate**] 的第二個合併器會套用至著色速率影像，這會在全域著色速率與個別基本型別著色速率合併之後發生。

最終著色速率的演算法由下列方式決定

```cpp theme={null}
postRasterizerRate = ApplyCombiner(Combiners[0], CommandListShadingRate, Primitive->PrimitiveSpecifiedShadingRate);
finalRate = ApplyCombiner(Combiners[1], postRasterizerRate, ScreenSpaceImage[xy]);
```

其中 `ApplyCombiner` 為

```cpp theme={null}
UINT ApplyCombiner(D3D12_SHADING_RATE_COMBINER combiner, UINT a, UINT b)
{
MaxShadingRate = options6.AdditionalShadingRatesSupported ? 4 : 2;
switch (combiner)
{
case D3D12_SHADING_RATE_COMBINER_PASSTHROUGH: // default
return a;
case D3D12_SHADING_RATE_COMBINER_OVERRIDE:
return b;
case D3D12_SHADING_RATE_COMBINER_MAX:
return max(a, b);
case D3D12_SHADING_RATE_COMBINER_MIN:
return min(a, b);
case D3D12_SHADING_RATE_COMBINER_SUM:
return min(MaxShadingRate, a + b);
case default:
return a;
}
}
```

## 需求

**標頭:** d3d12\_xs.h\
**程式庫:** d3d12\_xs.lib\
**支援的平台**: XBOX Series 主機

## 另請參閱

[可變速率著色 (VRS)](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/vrs)


## Related topics

- [RSSetShadingRateImage (XBOX Series consoles)](/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist5/methods/id3d12graphicscommandlist5_rssetshadingrateimage_public.md)
- [RSSetShadingRateImage (XBOX Series 主机)](/zh-CN/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist5/methods/id3d12graphicscommandlist5_rssetshadingrateimage_public.md)
- [RSSetShadingRateImage (consolas XBOX Series)](/es/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist5/methods/id3d12graphicscommandlist5_rssetshadingrateimage_public.md)
- [RSSetShadingRateImage (XBOX Series 콘솔)](/ko/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist5/methods/id3d12graphicscommandlist5_rssetshadingrateimage_public.md)
- [RSSetShadingRateImage (XBOX Series 本体)](/ja-jp/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist5/methods/id3d12graphicscommandlist5_rssetshadingrateimage_public.md)