首页 / luma.gl / API 文档

RenderPipeline

先看结论

把已编译的着色器、顶点缓冲区布局与固定渲染状态组合成一个可绘制的对象。它接替了 v8 的 Program，差别在于状态也在创建时固定。

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

device.createRenderPipeline(props) → RenderPipeline

创建参数

参数	说明
`vs` / `fs`	`Shader` 对象，由 `device.createShader` 编译得到；片元着色器可为 `null`
`shaderLayout`	着色器暴露的属性与绑定声明，GLSL 下可省略，由管线自行解析
`bufferLayout`	缓冲区内存布局，见 `BufferLayout`
`topology`	`triangle-list`、`triangle-strip`、`line-list`、`line-strip`、`point-list`
`parameters`	深度、混合、面剔除、图元重启等固定状态
`colorAttachmentFormats`	颜色附件格式，WebGPU 必填；WebGL 下可省略
`depthStencilAttachmentFormat`	深度附件格式，写入深度时需要
`varyings` / `bufferMode`	变换反馈的捕获变量与模式，仅 WebGL
`vertexEntryPoint` / `fragmentEntryPoint`	WGSL 的入口函数名，默认 `main`
`disableWarnings`	关闭「多余的属性或绑定」告警

成员

成员	说明
`vs` / `fs`	创建时传入的两个着色器
`shaderLayout`	合并后的属性与绑定声明
`bufferLayout`	实际生效的缓冲区布局数组
`linkStatus`	`pending`、`success`、`error`
`isPending` / `isErrored`	编译或链接是否仍在进行、是否已失败
`hash`	管线内容的哈希，供工厂缓存复用
`destroy()`	释放底层 program 与关联资源

先编译着色器，再建管线

const vs = device.createShader({
  stage: 'vertex',
  source: [
    '#version 300 es',
    'in vec3 positions;',
    'void main() {',
    '  gl_Position = vec4(positions, 1.0);',
    '}'
  ].join('\n')
});

const fs = device.createShader({
  stage: 'fragment',
  source: [
    '#version 300 es',
    'precision highp float;',
    'out vec4 fragColor;',
    'void main() {',
    '  fragColor = vec4(0.35, 0.80, 0.62, 1.0);',
    '}'
  ].join('\n')
});

const pipeline = device.createRenderPipeline({
  vs: vs,
  fs: fs,
  topology: 'triangle-list',
  bufferLayout: [
    { name: 'positions', stepMode: 'vertex', format: 'float32x3' }
  ],
  parameters: {
    depthCompare: 'less-equal',
    depthWriteEnabled: true
  }
});

用渲染通道驱动管线

v9.4 的绘制入口在渲染通道上：先选管线，再给顶点数组，最后 draw。管线自身的 draw 方法仍然存在，但已标记为废弃。

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

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

const pass = device.beginRenderPass({ clearColor: [0.05, 0.07, 0.1, 1] });
pass.setPipeline(pipeline);
pass.setVertexArray(vertexArray);
pass.draw({ vertexCount: 3 });
pass.end();

为什么不直接到处用它

管线是不可变对象：深度状态、混合、附件格式都在创建时固定，改一项就要新建一条。顶点数组、绑定组、通道状态也要手工管理，代码量很快超过一个最小示例的规模。 Model 已经封装了这些事，并且在参数变化时自动换管线；只有实现自定义图层基类、或需要精确控制管线状态时，才值得直接操作它。

设备内置的 PipelineFactory 会按 hash 缓存管线，相同配置重复创建拿到的是同一条，不必自己维护缓存。

链接是异步的。创建后立刻绘制可能拿到 pending。首帧出现空洞时，先查 pipeline.isPending 与 linkStatus，而不是怀疑顶点数据。

引用本文

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