GPUDevice: createSampler() 方法

语法

createSampler()
createSampler(descriptor)

参数

descriptor 可选

包含以下属性的对象：

addressModeU 可选

一个枚举值，指定当采样足迹宽度超出纹理宽度时采样器的行为。可能的值有：

• "clamp-to-edge"：纹理坐标将被钳制在 0.0 和 1.0 之间（包含边界）。
• "repeat"：纹理坐标将环绕到纹理的另一侧。
• "mirror-repeat"：纹理坐标将环绕到纹理的另一侧，但当坐标的整数部分为奇数时，纹理会翻转。

如果省略，addressModeU 默认值为 "clamp-to-edge"。

addressModeV 可选

一个枚举值，指定当采样足迹高度超出纹理高度时采样器的行为。可能的值和默认值与 addressModeU 相同。

addressModeW 可选

一个枚举值，指定当采样足迹深度超出纹理深度时采样器的行为。可能的值和默认值与 addressModeU 相同。

compare 可选

如果指定，则该采样器将是指定类型的比较采样器。可能（枚举）值为：

• "never"：比较测试永远不会通过。
• "less"：如果提供的数值小于采样值，则该比较测试通过。
• "equal"：如果提供的数值等于采样值，则该比较测试通过。
• "less-equal"：如果提供的数值小于或等于采样值，则该比较测试通过。
• "greater"：如果提供的数值大于采样值，则该比较测试通过。
• "not-equal"：如果提供的数值不等于采样值，则该比较测试通过。
• "greater-equal"：如果提供的数值大于或等于采样值，则该比较测试通过。
• "always"：比较测试总是通过。

比较采样器可能使用过滤，但采样结果将取决于具体实现，并且可能与常规过滤规则不同。

label 可选

一个字符串，提供可用于识别对象的标签，例如在 GPUError 消息或控制台警告中。

lodMinClamp 可选

一个数值，指定在采样纹理时内部使用的最小细节级别。如果省略，lodMinClamp 默认为 0。

lodMaxClamp 可选

一个数值，指定在采样纹理时内部使用的最大细节级别。如果省略，lodMaxClamp 默认为 32。

maxAnisotropy 可选

指定采样器使用的最大各向异性值钳制。如果省略，maxAnisotropy 默认为 1。

大多数实现支持 1 到 16（包含）之间的 maxAnisotropy 值。实际使用的值将被钳制在底层平台支持的最大值。

magFilter 可选

一个枚举值，指定当采样足迹小于或等于一个纹理单元（texel）时采样行为。可能的值有：

• "nearest"：返回最接近纹理坐标的纹理单元的值。
• "linear"：在每个维度上选择两个纹理单元，并返回它们值之间的线性插值。

如果省略，magFilter 默认为 "nearest"。

注意： 为了使 r32float、rg32float 和 rgba32float format 的 GPUTexture 可过滤，需要启用 float32-filterable 功能。

minFilter 可选

一个枚举值，指定当采样足迹大于一个纹理单元时采样行为。可能的值和默认值与 magFilter 相同。

mipmapFilter 可选

一个枚举值，指定在采样不同 Mipmap 级别时的行为。可能的值和默认值与 magFilter 相同。

返回值

一个 GPUSampler 对象实例。

验证

调用 createSampler() 时必须满足以下条件，否则将生成 GPUValidationError 并返回一个无效的 GPUSampler 对象。

• lodMinClamp 大于或等于 0。
• lodMaxClamp 大于或等于 lodMinClamp。
• maxAnisotropy 大于或等于 1。
• 如果 maxAnisotropy 大于 1，则 magFilter、minFilter 和 mipmapFilter 必须为 "linear"。

示例

以下代码片段创建了一个执行三线性过滤并重复纹理坐标的 GPUSampler。

// …

const sampler = device.createSampler({
  addressModeU: "repeat",
  addressModeV: "repeat",
  magFilter: "linear",
  minFilter: "linear",
  mipmapFilter: "linear",
});

WebGPU 示例中的 阴影贴图示例 使用比较采样器从深度纹理进行采样以渲染阴影。

规范

浏览器兼容性

另见

• WebGPU API