首页 / luma.gl / API 文档

ShaderLayout

先看结论

着色器接口的类型描述：声明顶点属性与各类绑定的名称、位置和维度，让 JavaScript 里的资源能对上 GPU 的槽位。

最后验证 2026-11-03 · luma.gl 9.4 · 更新 2026-10-29 · 引用本文

type ShaderLayout = { attributes, bindings, uniforms?, varyings? }

它是类型而不是类，创建管线时以普通对象传入。

字段

字段	说明
`attributes`	顶点属性声明数组
`bindings`	绑定声明数组，覆盖 uniform 块、存储缓冲、纹理与采样器
`uniforms`	WebGL 下的普通 uniform 声明，可选
`varyings`	阶段间传递变量声明，用于变换反馈等场景

AttributeDeclaration

字段	说明
`name`	属性名，与缓冲区布局里的名称一致
`location`	属性位置编号
`type`	着色器类型，如 `vec3<f32>`
`stepMode`	`vertex` 或 `instance`，默认逐顶点

BindingDeclaration

字段	说明
`name`	绑定名，与着色器里的变量名对应
`group`	绑定组序号，可稀疏
`location`	组内的绑定序号
`type`	`uniform`、`storage`、`texture`、`sampler` 等
`viewDimension`	纹理绑定的维度，如 `2d`
`sampleType`	纹理采样类型，如 `float`
`samplerType`	采样器类型，如 `filtering`

具体可用字段随绑定种类变化。uniform 块用 type: 'uniform'，纹理用 type: 'texture' 并给出维度与采样类型，采样器用 type: 'sampler'。

声明一个布局

const shaderLayout = {
  attributes: [
    { name: 'positions', location: 0, type: 'vec3<f32>' },
    { name: 'instanceOffsets', location: 1, type: 'vec2<f32>', stepMode: 'instance' }
  ],
  bindings: [
    { name: 'frameUniforms', type: 'uniform', group: 0, location: 0 },
    { name: 'materialUniforms', type: 'uniform', group: 3, location: 0 },
    { name: 'baseColorTexture', type: 'texture', group: 3, location: 1,
      viewDimension: '2d', sampleType: 'float' },
    { name: 'baseColorSampler', type: 'sampler', group: 3, location: 2,
      samplerType: 'filtering' }
  ]
};

const pipeline = device.createRenderPipeline({
  vs: vs,
  fs: fs,
  shaderLayout: shaderLayout,
  bufferLayout: [
    { name: 'positions', stepMode: 'vertex', format: 'float32x3' },
    { name: 'instanceOffsets', stepMode: 'instance', format: 'float32x2' }
  ]
});

组可以稀疏

group 不必连续，上面的例子跳过了 1 与 2。 WebGPU 直接按写出的编号创建绑定组；WebGL 没有原生绑定组， luma.gl 仍按逻辑分组管理，绑定时按同样的名字查找。

location 是组内序号，不是全局编号。同一个组内不能重复，不同组之间互不影响。

何时必须手写

场景	是否需要显式布局
GLSL 渲染管线	通常可省略，后端可从源码反射
WGSL 计算管线	需要，WGSL 反射信息有限
跨后端共享代码	建议显式写出，避免两套反射结果不一致
变换反馈	需要，捕获变量必须在 `varyings` 里声明

名称必须与着色器变量逐字一致。 大小写、下划线、拼写任何一处不同，绑定都会静默失败，着色器读到默认值。显式布局的好处是把这类错误提前到创建阶段暴露。

引用本文

经纬志（2026）。《ShaderLayout》。https://www.jingweizhi.com/lumagl/api/shader-layout.html（访问日期 2026-11-03）。