如何在TypeScript中定义WebGPU着色器管线绑定的资源类型

WebGPU把着色器资源绑定拆成了两层：布局层用GPUBindGroupLayoutEntry描述“这个槽位放什么类型的资源”，实例层用GPUBindGroupEntry描述“这个槽位具体放哪个资源对象”。这两层在WGSL着色器端还各自有一套@group和@binding标注。三套信息必须严丝合缝地对上，任何一处不一致，createBindGroupLayout或createBindGroup都会直接抛出验证错误。在TypeScript工程里，官方提供的@webgpu/types类型包已经把这套API建模得相当完整，但很多开发者不知道怎么正确组合这些类型，最后写出一堆any。本文就来把这块的类型定义彻底讲清楚。

四种资源绑定类型与对应的TypeScript类型

GPUBindGroupLayoutEntry本身是一个联合类型，它要求你必须且只能提供一个资源视图字段：buffer、sampler、texture或storageTexture四选一。这就是类型系统在强制你遵守WebGPU规范里的互斥规则。四种字段对应的JavaScript资源对象各不相同：buffer绑定接收GPUBufferBinding（包含GPUBuffer加上可选的offset和size），sampler绑定接收GPUSampler，texture和storageTexture绑定接收GPUTextureView。

注意区分资源视图这个概念。同一个GPUTexture可以通过createView()生成不同格式、不同mip层级的视图，绑定时传的永远是视图而不是纹理本身。这在类型定义上体现为GPUBindGroupEntry.resource的类型是联合类型，TypeScript能根据布局定义自动收窄。下面是一个覆盖四种绑定类型的布局定义示例：

const bindGroupLayout = device.createBindGroupLayout({
  entries: [
    {
      binding: 0,
      visibility: GPUShaderStage.VERTEX,
      buffer: { type: 'uniform' },  // 对应WGSL中的var<uniform>
    },
    {
      binding: 1,
      visibility: GPUShaderStage.FRAGMENT,
      sampler: { type: 'filtering' },  // 对应WGSL中的sampler
    },
    {
      binding: 2,
      visibility: GPUShaderStage.FRAGMENT,
      texture: { sampleType: 'float' },  // 对应WGSL中的texture_2d<f32>
    },
    {
      binding: 3,
      visibility: GPUShaderStage.COMPUTE,
      storageTexture: {
        access: 'write-only',
        format: 'rgba8unorm',
      },
    },
  ],
});

每个entry的binding数字必须和WGSL里@binding(n)的数字一致，@group(m)则对应管线布局中GPUBindGroupLayout数组的下标。写类型定义时建议把这些槽位定义提取成常量对象，而不是散落的魔法数字，这样着色器改绑定时TypeScript能第一时间报错。

buffer、texture子类型与visibility的匹配关系

GPUBufferBindingLayout的type字段有四个取值：'uniform'、'storage'、'read-only-storage'以及默认的空值表示只允许顶点阶段的间接索引。这个type必须和WGSL中变量的地址空间一致：var<uniform>对应uniform，var<storage, read>对应read-only-storage，var<storage, read_write>对应storage。如果布局写的是uniform而着色器里声明成了storage，即便字节布局完全一样，验证也会失败。

GPUTextureBindingLayout的sampleType决定着色器中纹理类型的泛型参数：'float'对应texture_2d<f32>，'depth'对应texture_depth_2d，'sint'和'uint'分别对应texture_2d<i32>和texture_2d<u32>。还有一个容易被忽略的字段是viewDimension，默认是'2d'，如果着色器里用的是texture_cube或者纹理数组，这里必须显式写'cube'或'2d-array'，否则采样结果会异常甚至验证失败。

visibility是位掩码，类型为GPUShaderStageFlags。关键限制在于：uniform buffer可以在任意阶段使用，但可写storage buffer在部分实现中不允许出现在顶点阶段；storageTexture的access如果是'write-only'，就只能绑定在渲染管线里做输出，不能在顶点阶段读写。这些规则TypeScript类型本身管不了，属于运行时验证的范畴，所以更要用自定义类型把它们编码进去。比如顶点阶段的绑定，可以用一个条件类型约束storage buffer不允许出现：

type VertexStageEntry = Omit<GPUBindGroupLayoutEntry, 'visibility'> & {
  visibility: GPUShaderStage.VERTEX;
  // 顶点阶段不推荐可写storage，可在此层做额外收窄
};

上面代码块的语言标记应为typescript，修正写法如下：

type VertexStageEntry = Omit<GPUBindGroupLayoutEntry, 'visibility'> & {
  visibility: GPUShaderStage.VERTEX;
};

// 约束顶点阶段只能用只读storage
function vertexSafe(entry: VertexStageEntry): entry is VertexStageEntry & {
  buffer?: { type?: 'read-only-storage' | 'uniform' };
} {
  return !entry.buffer || entry.buffer.type !== 'storage';
}

用TypeScript封装一套类型安全的绑定描述

实际项目中，更实用的做法是定义一个中间层描述结构，让业务代码只声明语义意图，由封装层生成布局和绑定组。这样着色器WGSL的绑定约定、布局定义、绑定实例三处信息可以共享同一份类型化描述，编译期就能查出口径不一致的问题。下面给出一个精简但可用的实现：

interface BindSlotDesc {
  binding: number;
  visibility: number;
  kind:
    | { res: 'uniform' }
    | { res: 'storage'; readOnly?: boolean }
    | { res: 'sampler'; type?: GPUSamplerBindingLayout['type'] }
    | { res: 'texture'; sampleType?: GPUTextureBindingLayout['sampleType'] }
    | { res: 'storageTexture'; format: GPUTextureFormat };
}

function toLayoutEntry(desc: BindSlotDesc): GPUBindGroupLayoutEntry {
  const base = { binding: desc.binding, visibility: desc.visibility };
  switch (desc.kind.res) {
    case 'uniform':
      return { ...base, buffer: { type: 'uniform' } };
    case 'storage':
      return {
        ...base,
        buffer: {
          type: desc.kind.readOnly ? 'read-only-storage' : 'storage',
        },
      };
    case 'sampler':
      return { ...base, sampler: { type: desc.kind.type ?? 'filtering' } };
    case 'texture':
      return {
        ...base,
        texture: { sampleType: desc.kind.sampleType ?? 'float' },
      };
    case 'storageTexture':
      return {
        ...base,
        storageTexture: {
          access: 'write-only',
          format: desc.kind.format,
        },
      };
  }
}

这个BindSlotDesc用可辨识联合把五种资源形态区分开，调用方写{ res: 'sampler', type: 'comparison' }时，TypeScript会阻止同对象里再出现sampleType之类的无关字段，这比直接裸写原生类型更能防手滑。接着再写一个对应的实例化函数，根据描述类型自动选择传buffer、sampler还是textureView：

function toBindGroupEntry(
  desc: BindSlotDesc,
  resources: Record<number, GPUBuffer | GPUSampler | GPUTextureView>,
): GPUBindGroupEntry {
  const res = resources[desc.binding];
  if (res instanceof GPUBuffer) {
    return { binding: desc.binding, resource: { buffer: res } };
  }
  return { binding: desc.binding, resource: res };
}

最后一点实践建议：把@group编号也纳入类型体系，比如用Record<'camera' | 'material' | 'lights', GPUBindGroupLayout>这样的映射来管理多个绑定组，渲染循环里按语义名取用绑定组，而不是记数字下标。配合着色器代码生成或WGSL常量提取，可以让“着色器改了绑定槽位但TS这边没改”这类问题在编译阶段就暴露，而不是等到浏览器控制台里看到validation error再去排查。这套思路在three.js等库的WebGPU后端源码里也有类似体现，值得借鉴到自己的渲染层设计中。

WebGPUTypeScript着色器管线修改时间：2026-09-08 01:26:38