首页 / luma.gl / API 文档

Model

先看结论

luma.gl 的高层绘制单元，把着色器、顶点属性、缓冲区布局与渲染状态合成一个对象。它对应原生 WebGL 里「program + 顶点数组 + 状态设置」的整组操作。

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

new Model(device, props) → Model

构造参数

参数	说明
`vs` / `fs`	顶点与片元着色器源码，GLSL 或 WGSL
`source`	统一着色器源码，WebGPU 使用
`modules`	来自 shadertools 的着色器模块，按顺序拼进最终源码
`defines`	预处理宏，用来开关着色器分支
`attributes`	属性名到缓冲区的映射
`bufferLayout`	缓冲区内存布局：名字、格式、步进模式
`geometry`	CPU 几何体或已上传的 GPU 几何体，可替代手写属性
`vertexCount`	顶点数量，未提供时由几何体或索引推算
`indexBuffer` / `indexCount`	索引缓冲与索引绘制数量
`instanceCount`	实例数量，大于 0 时按实例化绘制
`topology`	`triangle-list`、`triangle-strip`、`line-list`、`line-strip`、`point-list`
`parameters`	深度、混合、面剔除等渲染状态
`bindings`	纹理、采样器、uniform 缓冲等绑定资源
`uniforms`	WebGL 下的初始 uniform 值

属性

属性	说明
`pipeline`	底层渲染管线，参数变化时会重建
`vertexArray`	顶点数组，绑定缓冲区与属性布局
`bufferAttributes`	当前绑定的缓冲区属性
`vertexCount` / `instanceCount`	绘制数量
`topology`	图元类型
`needsRedraw()`	查询是否需要重绘

方法

方法	说明
`draw(renderPass)`	发起一次绘制，返回布尔值表示是否成功执行
`predraw(commandEncoder)`	在渲染通道之前上传 uniform 等数据
`setAttributes(buffers)`	替换或新增属性缓冲区
`setVertexCount(n)`	更新顶点数量
`setInstanceCount(n)`	更新实例数量
`setIndexBuffer(buffer)`	设置索引缓冲
`setGeometry(geometry)`	整体替换几何体
`setBindings(bindings)`	替换纹理与 uniform 缓冲绑定
`setParameters(parameters)`	修改深度、混合等状态，可能触发管线重建
`destroy()`	释放管线与顶点数组

完整构造

const positions = device.createBuffer(new Float32Array([
  -0.6, -0.45, 0,
   0.6, -0.45, 0,
   0.0,  0.55, 0
]));

const colors = device.createBuffer(new Float32Array([
  0.95, 0.36, 0.32,
  0.98, 0.78, 0.35,
  0.35, 0.80, 0.95
]));

const model = new Model(device, {
  topology: 'triangle-list',
  vertexCount: 3,
  attributes: {
    positions: positions,
    colors: colors
  },
  bufferLayout: [
    { name: 'positions', stepMode: 'vertex', format: 'float32x3' },
    { name: 'colors', stepMode: 'vertex', format: 'float32x3' }
  ],
  vs: '#version 300 es\n...',
  fs: '#version 300 es\n...'
});

逐帧绘制

const pass = device.beginRenderPass({ clearColor: [0.04, 0.06, 0.09, 1] });

model.setVertexCount(count);
model.draw(pass);

pass.end();

draw 返回 false 通常意味着资源未就绪、管线编译失败或绑定缺失。排查时先看控制台里的 luma.gl 警告，它们会直接指出缺了哪个布局或绑定。

uniform 怎么更新

v9 的 Model 没有 setUniforms。较新的做法是把需要逐帧变化的值放进 uniform 缓冲区，作为绑定传给模型；使用 shadertools 时，由 shaderInputs 统一生成与更新这些缓冲。 WebGL 下也可以在构造时通过 uniforms 提供初始值，但频繁更新仍应走缓冲区。

实例化

把 instanceCount 设为大于 0，并让实例属性使用 stepMode: 'instance'，就得到实例化绘制。每个实例的偏移、缩放与颜色都放在实例属性缓冲区里，绘制调用仍然只有一次。

布局必须与着色器逐字对应。属性名、分量数、数据类型三者任一不匹配，模型都不会报错，但画面是空的。先用一个最小三角形验证布局，再往上加属性。

引用本文

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