如何在TypeScript中定义WebGPU采样器绑定布局的过滤类型？

WebGPU 的绑定组布局在描述采样器绑定槽位时，并不直接设置过滤模式，而是通过 GPUSamplerBindingLayout 的 type 字段声明该槽位可能容纳的采样器类别。这个字段的取值有三个：filtering、non-filtering 和 comparison。很多使用者容易把 type 和 GPUSamplerDescriptor 里的 magFilter、minFilter、mipmapFilter 混淆：后者决定采样器自身的纹理过滤行为，前者是绑定布局对采样器能力的要求。如果绑定布局声明为 non-filtering，却在管线中绑定了一个 minFilter 为 linear 的采样器，WebGPU 实现会认为绑定不满足布局约束，从而产生验证错误。理解这两层过滤类型的关系，是正确封装 TypeScript 采样器模块的前提。

一、绑定布局中的 type 字段如何区分过滤能力

在 WebGPU 中，一个绑定组布局由多个 entry 组成，每个 entry 可以是 buffer、texture、sampler 或 storage texture。当 entry 的类型为 sampler 时，其 sampler 属性就是一个 GPUSamplerBindingLayout 字典。这个字典只有一个成员，即 type。它控制该绑定槽位对采样器过滤能力的约束，而不是设置具体的过滤算法。

从类型层面看，GPUSamplerBindingLayout.type 的取值可以建模为 TypeScript 联合类型。最简单的定义如下：

type GPUSamplerBindingType = "filtering" | "non-filtering" | "comparison";

interface GPUSamplerBindingLayout {
  type?: GPUSamplerBindingType;
}

这三个值各有不同的适用范围。filtering 表示该槽位可以绑定启用了线性过滤的采样器，也可以绑定最近邻采样的采样器，是最宽松的一种。它适合颜色纹理、法线贴图等需要平滑采样的场景。与之相反，non-filtering 要求采样器的 magFilter、minFilter 和 mipmapFilter 必须全部为 nearest，否则会在创建或使用绑定组时产生校验错误。comparison 主要用于深度纹理或阴影贴图，这类采样器必须设置 compare 字段，以进行深度比较采样。

从 WebGPU 规范的意图看，这样设计是为了让底层实现能够在管线创建阶段就知道某个采样器会不会使用线性过滤。这样驱动可以提前判断纹理的采样成本，也便于在移动端或其他硬件上优化着色器采样指令。因此，type 不是冗余字段，它参与绑定组的静态校验。

二、采样器描述符的过滤枚举与 non-filtering 约束

GPUSamplerDescriptor 是创建采样器时传入的参数对象。它包含三个与过滤直接相关的字段：magFilter、minFilter 和 mipmapFilter。这三个字段都接受 GPUFilterMode 类型，而 GPUFilterMode 只有 nearest 和 linear 两个取值。

magFilter 控制纹理被放大时的采样方式，例如在屏幕上显示一个低分辨率纹理且纹理坐标变化较慢时，一个 texel 可能覆盖多个像素。minFilter 控制纹理被缩小时的行为，例如远处物体使用高分辨率纹理时，一个像素对应多个 texel。mipmapFilter 则决定在两个 mip 级别之间进行插值的方式。三者在 TypeScript 中可以用以下结构表示：

type GPUFilterMode = "nearest" | "linear";

interface GPUSamplerDescriptor {
  magFilter?: GPUFilterMode;
  minFilter?: GPUFilterMode;
  mipmapFilter?: GPUFilterMode;
  addressModeU?: GPUAddressMode;
  addressModeV?: GPUAddressMode;
  addressModeW?: GPUAddressMode;
  compare?: GPUCompareFunction;
}

当绑定布局的 type 为 non-filtering 时，采样器描述符中的 magFilter、minFilter 和 mipmapFilter 都必须为 nearest。即使只有一个字段被设置为 linear，也会导致绑定组与布局不匹配。需要注意，non-filtering 并不限制 U、V、W 三个轴的 wrap 模式，也不限制是否使用各向异性过滤，因为这些能力与过滤类型无关。

反过来，如果绑定布局的 type 为 filtering，则可以绑定任意过滤组合的采样器。比如可以只把 minFilter 设为 linear 而保持其他字段为 nearest，也可以三个字段全部使用 linear。这种灵活性允许同一个材质或着色器在运行时切换不同采样器，只要它们都属于 filtering 约束范围。

三、TypeScript 中的完整定义与运行时校验

TypeScript 的类型系统可以表达字段级别的可选值和联合类型，但很难直接表达跨字段约束，例如“当绑定布局类型为 non-filtering 时，采样器描述符的三个过滤字段必须全部为 nearest”。这类约束需要依靠运行时校验函数来完成。在实际项目中，通常会把采样器描述符与绑定布局描述符放在同一个模块中维护，并导出若干工具函数。

下面是一个较为完整的 TypeScript 定义示例，包含 SamplerBindingLayoutType、FilterMode 以及一个校验函数。该函数会检查给定绑定布局类型和采样器描述符是否匹配。

export type SamplerBindingFilterType = "filtering" | "non-filtering" | "comparison";
export type FilterMode = "nearest" | "linear";

export interface SamplerBindingLayoutDeclaration {
  type: SamplerBindingFilterType;
}

export interface SamplerDescriptorDeclaration {
  magFilter?: FilterMode;
  minFilter?: FilterMode;
  mipmapFilter?: FilterMode;
  compare?: GPUCompareFunction;
}

export function isNonFilteringSampler(descriptor: SamplerDescriptorDeclaration): boolean {
  const mag = descriptor.magFilter ?? "nearest";
  const min = descriptor.minFilter ?? "nearest";
  const mip = descriptor.mipmapFilter ?? "nearest";
  if (mag !== "nearest") return false;
  if (min !== "nearest") return false;
  if (mip !== "nearest") return false;
  return true;
}

export function validateSamplerBinding(
  layoutType: SamplerBindingFilterType,
  descriptor: SamplerDescriptorDeclaration
): boolean {
  if (layoutType === "non-filtering") {
    return isNonFilteringSampler(descriptor);
  }
  if (layoutType === "comparison") {
    return typeof descriptor.compare !== "undefined";
  }
  return true;
}

这里的校验逻辑并不复杂，但它的价值在于把 WebGPU 的隐式校验规则转换成显式的 TypeScript 函数，方便在资源加载、材质系统和调试工具中复用。例如在创建采样器之前，可以先调用 validateSamplerBinding，当返回 false 时直接抛出带有详细信息的错误，而不是等浏览器控制台输出模糊的 WebGPU 验证错误。

另一个常见做法是使用 TypeScript 的 satisfies 或 as const 来定义常量对象。比如预置一组过滤采样器和一组非过滤采样器的创建参数，然后通过类型推断保证这些常量不会被误用到不匹配的绑定布局中。

四、创建绑定组时的组合校验与常见错误

在实际创建绑定组布局时，采样器槽位需要显式写上 type。假设片段着色器同时使用一个过滤采样器和一个浮点纹理，绑定组布局可以这样定义：

const bindGroupLayout = device.createBindGroupLayout({
  entries: [
    {
      binding: 0,
      visibility: GPUShaderStage.FRAGMENT,
      sampler: {
        type: "filtering"
      }
    },
    {
      binding: 1,
      visibility: GPUShaderStage.FRAGMENT,
      texture: {
        sampleType: "float"
      }
    }
  ]
});

随后创建采样器和绑定组时，采样器的过滤方式必须与布局中的 type 匹配。例如布局写的是 filtering，那么创建一个线性过滤采样器是允许的：

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

const bindGroup = device.createBindGroup({
  layout: bindGroupLayout,
  entries: [
    { binding: 0, resource: sampler },
    { binding: 1, resource: textureView }
  ]
});

如果布局中的 type 被改成 non-filtering，上面的 createSampler 调用就必须把三个过滤字段全部改为 nearest，否则绑定组要么直接创建失败，要么在后续 createRenderPipeline 或 beginRenderPass 时产生异步校验错误。WebGPU 的错误上报通常通过 pushErrorScope 和 popErrorScope 来捕获，这类错误不会像 JavaScript 异常那样立刻中断执行，因此很容易被忽略。

最常见的错误有三种：一是布局声明为 non-filtering，采样器却使用了 linear；二是布局声明为 comparison，但采样器描述符没有设置 compare 字段；三是在采样器描述符中只设置了 minFilter 为线性过滤，却忘记同步更新绑定布局，导致材质在切换管线时出现不一致。借助前文的 TypeScript 校验函数，可以在开发阶段尽早暴露这些问题。

对于深度阴影贴图，通常需要把采样器绑定类型设为 comparison，同时给采样器描述符传入 compare: "less-equal" 之类的比较函数。这样着色器中调用 textureSampleCompare 时才能得到正确的深度比较结果。此时同样要保证布局类型与实际描述符匹配，而不是简单复制普通颜色纹理的 filtering 配置。

TypeScriptWebGPU采样器绑定修改时间：2026-09-17 18:36:19