ID3D12GraphicsCommandList1：：SetSamplePositions 方法 (d3d12.h)

项目
02/29/2024

此方法配置后续绘制、复制、解析和类似操作使用的示例位置。

语法

void SetSamplePositions(
  [in] UINT                  NumSamplesPerPixel,
  [in] UINT                  NumPixels,
  [in] D3D12_SAMPLE_POSITION *pSamplePositions
);

参数

[in] NumSamplesPerPixel

类型： UINT

SAL： In

指定每个像素要拍摄的样本数。此值可以是 1、2、4、8 或 16，否则将删除 SetSamplePosition 调用。样本数必须与绘制时 PSO 中配置的样本计数匹配，否则行为未定义。

[in] NumPixels

类型： UINT

SAL： In

指定要为其指定示例模式的像素数。此值可以是 1 或 4，否则将删除 SetSamplePosition 调用。值 1 将配置单个示例模式用于每个像素;值 4 为 2x2 像素网格中的每个像素配置单独的样本图案，该网格在呈现目标或视区空间上重复，与偶数坐标对齐。

请注意，组合样本的最大数目不能超过 16，否则将丢弃调用。如果 NumPixels 设置为 4，NumSamplesPerPixel 可以指定不超过 4 个样本。

[in] pSamplePositions

类型： D3D12_SAMPLE_POSITION*

SAL： In_reads(NumSamplesPerPixel*NumPixels)

指定D3D12_SAMPLE_POSITION元素的数组。数组的大小为 NumPixels * NumSamplesPerPixel。如果 NumPixels 设置为 4，则第一组样本位置对应于 2x2 像素网格中的左上角像素;下一组样本位置对应于右上像素，下一组对应于左下角像素，最后一组对应于右下像素。

如果在呈现过程中使用质心内插，则每个像素的位置顺序将确定质心采样优先级。也就是说，按指定顺序选择第一个涵盖的样本作为质心样本位置。

返回值

无

备注

示例位置的操作语义由各种绘制、复制、解析和可能发生的其他操作决定。

CommandList： 在 CommandList 中没有对 SetSamplePositions 进行任何先前调用的情况下，示例基于管道状态对象 (PSO) 假定默认位置。默认位置由 PSO 的SAMPLE_DESC部分（如果存在）确定;如果 PSO 的RASTERIZER_DESC部分已将 ForcedSampleCount 设置为大于 0 的值，则由标准样本位置确定。

调用 SetSamplePosition 后，后续绘制调用必须使用 PSO 的 PSO，该 PSO 使用 PSO 的 SAMPLE_DESC 部分指定匹配的样本计数，或者使用 PSO RASTERIZER_DESC 部分中的 ForcedSampleCount。

只能在图形 CommandList 上调用 SetSamplePositions。无法在捆绑包中调用它;捆绑包从调用 CommandList 继承示例位置状态，并且不会对其进行修改。

调用 SetSamplePositions (0、0、NULL) 会将示例位置还原为其默认值。

清除 RenderTarget： 清除呈现器目标时，将忽略示例位置。

Clear DepthStencil： 清除深度模具图面或其任何区域的深度部分时，必须将样本位置设置为将未来呈现的位置与清除的图面或区域相匹配;使用不同样本位置生成的任何未明确区域的内容将变为未定义。

清除深度模具表面或其任何区域的模具部分时，将忽略样本位置。

绘制到 RenderTarget： 绘制到呈现器目标时，即使绘制到与上一个绘图调用重叠的区域，也可以更改每个绘图调用的样本位置。当前样本位置确定每个绘制调用的操作语义，样本取自呈现器目标的存储内容，即使内容是使用不同的样本位置生成的。

使用 DepthStencil 绘制： 当绘制到深度模具图面 (读取或写入) 或其任何区域时，必须将样本位置设置为匹配之前用于清除受影响区域的位置。若要使用不同的示例位置，必须先清除目标区域。清除区域外的像素不受影响。

硬件可能会将深度部分或深度模具表面存储为平面公式，并在应用程序发出读取时对其进行评估以生成深度值。只需光栅器和输出合并即可支持深度模具表面深度部分的可编程样本位置。已使用样本位置设置呈现的深度部分的任何其他读取或写入都可能会忽略它们，而是在标准位置采样。

解析 RenderTarget： 解析呈现目标或其任何区域时，将忽略示例位置;这些 API 仅对存储的颜色值运行。

解析 DepthStencil： 解析深度模具图面或其任何区域的深度部分时，必须将样本位置设置为将过去呈现的位置与解析的图面或区域相匹配。若要使用不同的示例位置，必须先清除目标区域。

解析深度模具表面或其任何区域的模具部分时，将忽略样本位置;模具解析仅对存储的模具值进行操作。

复制 RenderTarget： 从呈现器目标复制时，无论样本位置是完整副本还是部分副本，都将被忽略。

复制 DepthStencil (完整的子资源) ： 从深度模具图面复制完整的子资源时，必须将样本位置设置为与用于生成源图面的样本位置相匹配。若要使用不同的示例位置，必须先清除目标区域。

在源图面的某些硬件属性上， (例如深度值的存储平面公式，) 传输到目标。因此，如果随后将目标图面绘制到，则最初用于生成源内容的样本位置需要与目标图面一起使用。 API 要求在所有硬件上执行此操作，以确保一致性，即使它可能仅适用于某些硬件。

复制 DepthStencil (部分子资源) ： 从深度模具图面复制部分子资源时，必须设置样本位置以匹配用于生成源图面的样本位置，类似于复制完整的子资源。但是，如果受影响目标子资源的内容仅部分由副本覆盖，则这些子资源中未发现的部分的内容将变为未定义，除非使用与复制源相同的采样位置生成所有内容。若要使用不同的示例位置，必须先清除目标区域。

从深度模具图面的模具部分复制部分子资源时，将忽略示例柱线。无论使用哪个样本位置为副本未涵盖的目标缓冲区的任何其他区域生成内容，这些内容仍然有效。

着色器示例Pos： HLSL SamplePos 内部函数不知道可编程样本位置，并且返回给着色器的结果在具有可编程位置的呈现的图面上调用此位置是未定义的。如果需要，应用程序必须手动将坐标传递到其着色器中。同样，通过可编程样本位置未定义按样本索引评估属性。

转换出DEPTH_READ或DEPTH_WRITE状态： 如果处于DEPTH_READ或DEPTH_WRITE状态的子资源转换为任何其他状态（包括COPY_SOURCE或RESOLVE_SOURCE），则某些硬件可能需要解压缩表面。因此，必须在命令列表中设置示例位置，以匹配用于在源图面中生成内容的位置。此外，对于图面的任何后续转换，而相同的深度数据保留在其中，样本位置必须继续匹配命令列表中设置的位置。若要使用不同的示例位置，必须先清除目标区域。

如果应用程序希望在只需要使用一部分时最小化解压缩区域，或者只是为了保留压缩，则可以在 DECOMPRESS 模式下调用 ResolveSubresourceRegion () 并指定了 rect。这会仅将相关区域解压缩到单独的资源，使源在某些硬件上保持不变，尽管在其他硬件上甚至源区域也会解压缩。然后，可以将单独的显式解压缩资源转换为所需的状态 (，例如SHADER_RESOURCE) 。

转换出RENDER_TARGET状态： 如果将处于RENDER_TARGET状态的子资源转换为除COPY_SOURCE或RESOLVE_SOURCE以外的任何内容，则某些实现可能需要解压缩图面。此解压缩与样本位置无关。

要求

要求	值
目标平台	Windows
标头	d3d12.h
Library	D3d12.lib
DLL	D3d12.dll

另请参阅

ID3D12GraphicsCommandList1

通过

ID3D12GraphicsCommandList1：：SetSamplePositions 方法 (d3d12.h)

语法

参数

返回值

备注

要求

另请参阅

反馈

其他资源