首页 / luma.gl / API 文档

RenderPass

先看结论

一次渲染通道：决定画到哪个附件、用什么清除值、视口多大，并持有绘制所需的管线、绑定与顶点数组。v9 里所有绘制都必须经过它。

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

device.beginRenderPass(props) → RenderPass

创建参数

参数	说明
`framebuffer`	渲染目标，省略或传 `null` 时画到画布
`clearColor`	颜色清除值 `[r, g, b, a]`；传 `false` 保留上一帧内容
`clearColors`	多颜色附件各自的清除值，需用类型化数组
`clearDepth`	深度清除值，默认 `1`；传 `false` 不清除
`clearStencil`	模板清除值，默认 `0`
`parameters`	`viewport`、`scissorRect`、`blendConstant`、`stencilReference`
`depthReadOnly` / `stencilReadOnly`	只读附件，禁止写入深度或模板
`discard`	丢弃光栅化结果，只做深度预写等用途
`occlusionQuerySet`	遮挡查询的结果集合

未给 viewport 时，通道按目标尺寸自动设置：画到帧缓冲用帧缓冲的宽高，画到画布用绘制缓冲的宽高。

方法

方法	说明
`setPipeline(pipeline)`	选择后续绘制使用的管线
`setBindings(bindings)`	整体替换绑定，必须在 `setPipeline` 之后调用
`setVertexArray(vertexArray)`	选择后续绘制使用的顶点数组
`draw(options)`	按当前管线、绑定与顶点数组发起一次绘制，返回布尔值
`setParameters(parameters)`	运行期可改视口、裁剪矩形、混合常量、模板参考值
`drawIndirect(buffer)`	用缓冲里的四个整数参数发起绘制，仅 WebGPU
`drawIndexedIndirect(buffer)`	索引版间接绘制，仅 WebGPU
`executeBundles(bundles)`	回放渲染束，仅 WebGPU
`beginOcclusionQuery(index)` / `endOcclusionQuery()`	遮挡查询的起止
`pushDebugGroup(label)` / `popDebugGroup()`	给命令流打标签，便于在调试工具里定位
`insertDebugMarker(label)`	插入单点标记
`end()`	结束通道并弹出状态栈

完整用法

const pass = device.beginRenderPass({
  framebuffer: fbo,                    // 省略则画到画布
  clearColor: [0.04, 0.06, 0.09, 1],
  clearDepth: 1,
  parameters: { viewport: [0, 0, 256, 256] }
});

pass.setPipeline(pipeline);
pass.setBindings({ uTexture: texture });
pass.setVertexArray(vertexArray);
pass.draw({ vertexCount: 6, instanceCount: 1 });

pass.end();

draw 的选项

选项	说明
`vertexCount`	顶点数量，非索引绘制使用
`indexCount`	索引数量，绑定索引缓冲后使用
`instanceCount`	实例数量
`firstVertex` / `firstIndex`	起始顶点或起始索引
`firstInstance` / `baseVertex`	起始实例与索引绘制时的基准顶点
`isInstanced`	WebGL 需要显式声明是否实例化；WebGPU 由 `instanceCount` 推断
`uniforms`	WebGL 兼容用的 uniform 字典，新代码走绑定

与 Model 的关系

Model.draw(pass) 做的事情就是上面四步：设管线、设绑定、设顶点数组、绘制。通道仍然要自己开、自己关，模型不会替应用决定画到哪里。

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

能力	WebGL 2	WebGPU
间接绘制	抛错	支持
渲染束回放	抛错	支持
多颜色附件	支持	支持
模板参考值	支持	支持

忘记 end() 会留下未结束的状态栈。 通道内部用 pushState 记录进入时的 WebGL 状态，end 时才恢复。漏掉一次，后续所有绘制的视口与清除行为都会跟着错。

引用本文

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