首页 / luma.gl / API 文档

VertexArray

先看结论

属性绑定的容器：把缓冲区按槽位接到着色器输入上。管线可以复用，顶点数据通过顶点数组切换。

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

device.createVertexArray({ shaderLayout, bufferLayout }) → VertexArray

创建参数

参数	说明
`shaderLayout`	着色器侧的属性声明，通常直接取管线的 `shaderLayout`
`bufferLayout`	缓冲区内存布局数组，描述名称、步进模式与格式
`id`	调试用标识

成员

成员	说明
`attributes`	按后端槽位索引的缓冲区或常量数组
`indexBuffer`	索引缓冲，未设置时为 `null`
`maxVertexAttributes`	该后端支持的属性数量上限
`handle`	底层顶点数组对象句柄
`destroyed`	是否已释放

方法

方法	返回	说明
`getBufferSlot(bufferName)`	number \| null	按逻辑名称取后端槽位，未知名称返回 `null`
`setBuffer(bufferSlot, buffer)`	void	绑定一个缓冲区，传 `null` 解除
`setIndexBuffer(indices)`	void	设置索引缓冲作为索引绘制来源
`getDrawValidationError()`	string \| null	检查是否能安全绘制，通过时返回 `null`
`destroy()`	void	释放顶点数组，不释放外部缓冲区

绑定顶点数据

const positions = device.createBuffer({
  data: new Float32Array([
    -0.5, -0.5,
     0.5, -0.5,
     0.0,  0.5
  ]),
  usage: Buffer.VERTEX
});

const vertexArray = device.createVertexArray({
  shaderLayout: pipeline.shaderLayout,
  bufferLayout: pipeline.bufferLayout
});

const slot = vertexArray.getBufferSlot('positions');

if (slot !== null) {
  vertexArray.setBuffer(slot, positions);
}

console.log(vertexArray.getDrawValidationError());   // null 表示可以绘制

槽位号由后端决定，不能假设属性名对应 0、1、2。一律通过 getBufferSlot 查询，WebGL 与 WebGPU 的代码才能通用。

索引绘制

const indices = device.createBuffer({
  data: new Uint32Array([0, 1, 2]),
  usage: Buffer.INDEX,
  indexType: 'uint32'
});

vertexArray.setIndexBuffer(indices);

pass.setPipeline(pipeline);
pass.setVertexArray(vertexArray);
pass.draw({ indexCount: 3 });

设置索引缓冲后绘制用 indexCount 而不是 vertexCount。 indexType 必须与数据数组类型一致，否则会读出错误的顶点。

复用管线

顶点数组与管线是多对一关系：同一管线可以配多个顶点数组，分别绑定不同的缓冲区，逐次绘制而不用重建管线。批量绘制同结构几何时，这是最直接的优化点。

绘制前的校验不要省。 忘记绑定某个属性时，getDrawValidationError 会给出缺失的属性名；直接绘制则什么都不显示，控制台也不一定报错。首次搭建管线时把它放在绘制前，能省掉大量排查时间。

引用本文

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