> ## 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)。
此方法需要 Tier2 [可变速率着色 (VRS)](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/vrs) 支持。请参阅 [**D3D12\_FEATURE\_DATA\_D3D12\_OPTIONS6**](/reference/graphics/d3d12/structs/d3d12_feature_data_d3d12_options6_public) 和 [**D3D12\_VARIABLE\_SHADING\_RATE\_TIER**](/reference/graphics/d3d12/enums/d3d12_variable_shading_rate_tier_public)。

## 语法

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

### 参数

*shadingRateImage*\
类型：ID3D12Resource \*

一个可选指针，指向表示屏幕空间着色速率图像的 [ID3D12Resource](/reference/graphics/d3d12_xs/interfaces/ID3D12Resource/id3d12resource_xs)。
如果为 **NULL**，则效果等同于拥有一个所有值都是 1x1 着色速率的着色速率图像。

此纹理必须已应用 [**D3D12\_RESOURCE\_STATE\_SHADING\_RATE\_SOURCE**](/reference/graphics/d3d12_x/enums/d3d12_resource_states) 状态。

可以通过 [**D3D12\_FEATURE\_DATA\_D3D12\_OPTIONS6**](/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**](/reference/graphics/d3d12/enums/d3d12_shading_rate_public) 的值。它必须具有布局 [**D3D12\_TEXTURE\_LAYOUT\_UNKNOWN**](/reference/graphics/d3d12_x/enums/d3d12_texture_layout)，并且不能是深度模板、渲染目标、同时访问或跨适配器资源。

由于在 DirectX 中 (0, 0) 是左上角，因此过小或过大的着色速率图像会导致底部或右侧没有着色速率图像区域，或图像在这些方向上延伸。当有多余时，会被忽略（但合法），当图像过小时，底部和右侧的所有超出范围区域将具有来自图像的默认着色速率 1x1（但这并不意味着这是最终的着色速率。组合器仍将应用于此 1x1 默认值）。

### 返回值

类型：void

无。

## 备注

为了让屏幕空间着色速率图像生效，必须已调用 [**ID3D12GraphicsCommandList5::RSSetShadingRate**](/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist5/methods/id3d12graphicscommandlist5_rssetshadingrate_public) 来设置着色组合器。否则，使用默认组合器（两者都是 [**D3D12\_SHADING\_RATE\_COMBINER\_PASSTHROUGH**](/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

- [RSSetShadingRate (XBOX Series 主机)](/zh-CN/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist5/methods/id3d12graphicscommandlist5_rssetshadingrate_public.md)
- [D3D12_SHADING_RATE（XBOX Series 主机）](/zh-CN/reference/graphics/d3d12/enums/d3d12_shading_rate_public.md)
- [D3D12_AXIS_SHADING_RATE (XBOX Series consoles)](/zh-CN/reference/graphics/d3d12/enums/d3d12_axis_shading_rate_public.md)
- [D3D12_SHADING_RATE_COMBINER](/zh-CN/reference/graphics/d3d12/enums/d3d12_shading_rate_combiner_public.md)
- [D3D12_VARIABLE_SHADING_RATE_TIER](/zh-CN/reference/graphics/d3d12/enums/d3d12_variable_shading_rate_tier_public.md)