> ## 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：** 在命令列表中之前未调用过 SetSamplePositions 的情况下，采样采用基于管线状态对象 (PSO) 的默认位置。默认位置由 PSO 的 SAMPLE\_DESC 部分（如果存在）确定，或者如果 PSO 的 RASTERIZER\_DESC 部分将 ForcedSampleCount 设置为大于 0 的值，则由标准采样位置确定。

调用 SetSamplePosition 后，后续绘制调用必须使用一个 PSO，该 PSO 通过 PSO 的 SAMPLE\_DESC 部分或 RASTERIZER\_DESC 部分中的 ForcedSampleCount 指定匹配的采样计数。

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），某些硬件可能需要解压缩表面。因此，必须在命令列表上设置采样位置以匹配用于生成源表面内容的采样位置。此外，在同一深度数据保持在表面中时的任何后续状态转换中，采样位置必须继续与命令列表上设置的位置匹配。要使用不同的采样位置，必须先清除目标区域。

如果应用程序希望在仅需要使用部分区域时尽量减少解压缩区域，或者仅仅是为了保留压缩，可以使用指定的矩形以 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](/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist1/id3d12graphicscommandlist1_public)


## Related topics

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