首页 / luma.gl / API 文档

Framebuffer

先看结论

离屏渲染目标：把颜色与深度附件组合成一个可绘制的表面，渲染结果留在纹理里，供后续采样或回读。

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

device.createFramebuffer({ width, height, colorAttachments, depthStencilAttachment }) → Framebuffer

创建参数

参数	说明
`width` / `height`	附件尺寸；省略时由附件推算
`colorAttachments`	颜色附件数组，元素可以是 `Texture`、`TextureView` 或格式字符串
`depthStencilAttachment`	深度或深度模板附件，类型同上，也可为 `null`
`id`	调试用标识

传格式字符串时设备会按 width / height 自动创建纹理，但拿不到纹理引用，无法在下一趟渲染中采样。需要复用结果时自己建纹理再传入。

成员

成员	说明
`width` / `height`	所有附件的统一尺寸
`colorAttachments`	`TextureView` 数组，实际参与渲染的视图
`depthStencilAttachment`	深度模板视图，没有时为 `null`
`handle`	底层帧缓冲句柄
`destroyed`	是否已释放

方法

方法	返回	说明
`clone(size?)`	Framebuffer	按相同参数复制附件，可指定新尺寸，不复制内容
`resize(size)`	void	旧接口，会销毁并重建附件，已标记废弃
`destroy()`	void	释放帧缓冲，不自动释放外部传入的纹理

离屏渲染

const color = device.createTexture({
  width: 512,
  height: 512,
  format: 'rgba8unorm',
  usage: Texture.SAMPLE | Texture.RENDER | Texture.COPY_DST,
  sampler: { minFilter: 'linear', magFilter: 'linear' }
});

const depth = device.createTexture({
  width: 512,
  height: 512,
  format: device.preferredDepthFormat,
  usage: Texture.RENDER
});

const fbo = device.createFramebuffer({
  width: 512,
  height: 512,
  colorAttachments: [color],
  depthStencilAttachment: depth
});

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

pass.setPipeline(pipeline);
pass.setVertexArray(vertexArray);
pass.draw({ vertexCount: 3 });
pass.end();
device.submit();

颜色附件要同时带 SAMPLE 与 RENDER：前者允许下一趟把它当纹理采样，后者允许本趟写入。深度格式用 device.preferredDepthFormat，写死格式在部分设备上会创建失败。

结果接着用

const post = device.createRenderPipeline({
  vs: postVS,
  fs: postFS,
  topology: 'triangle-list',
  bufferLayout: [
    { name: 'positions', stepMode: 'vertex', format: 'float32x2' }
  ]
});

const screen = device.beginRenderPass({ clearColor: [0, 0, 0, 1] });
screen.setPipeline(post);
screen.setVertexArray(quadArray);
screen.setBindings({ uScene: color });
screen.draw({ vertexCount: 6 });
screen.end();
device.submit();

离屏纹理作为绑定传入下一趟，键名与片元着色器里的采样器名一致。两个通道各自记录命令，全部结束后再提交一次，顺序由记录先后决定。

尺寸变化

帧缓冲尺寸一旦创建就固定。窗口缩放时用 clone({ width, height }) 建新的帧缓冲与附件，再把旧对象 destroy。直接 resize 已废弃，而且会销毁调用方可能还在引用的纹理。

WebGL 后端不能再建第二个画布。 需要额外渲染目标时只能用帧缓冲。WebGPU 后端支持多画布，但离屏渲染同样走帧缓冲，两者的代码结构可以保持一致。

引用本文

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