Framebuffer

Proposed luma.gl v9 API. Open for comments.

A Framebuffer holds textures that will be used as render targets for RenderPipelines:

one or more color textures
optionally a depth / stencil buffer

A Framebuffer is "shallowly immutable": the list of attachments cannot be changed after creation, however a Framebuffer can be "resized" causing the attachments to be resized.

The use of framebuffers is described in detail in the Rendering Guide/

Usage

Creating a framebuffer with default color and depth attachments

const framebuffer = device.createFramebuffer({
  width: window.innerWidth,
  height: window.innerHeight,
  colorAttachments: ['rgb8unorm'],
  depthStencilAttachment: 'depth24unorm-stencil8'
});

Resizing a framebuffer to the size of a window by resizing all attachments.

framebuffer.resize(window.innerWidth, window.innerHeight);

Specifying a framebuffer for rendering in each render calls

const offScreenBuffer = device.createFramebuffer(...);

const offScreenRenderPass = device.beginRenderPass({framebuffer: offScreenFramebuffer});
model1.draw({renderPass: offScreenRenderPass});
offScreenRenderPass.endPass();

const screenRenderPass = device.getDefaultRenderPass();
model2.draw({renderPass: screenRenderPass});

Types

`FramebufferProps`

Property	Type	Description
`id?`	`string`	An optional name (id) of the buffer.
`width? = 1`	`number`	The width of the framebuffer.
`height? = 1`	`number`	The height of the framebuffer.
`colorAttachments`	`TextureFormat\|Texture[]`	Array of render target textures.
`depthStencilAttachment?`	`TextureFormat\|Texture[]`	Depth/stencil texture.

Members

device: Device - holds a reference to the Device that created this Framebuffer.
handle: unknown - WebGL: holds the underlying WebGLFramebuffer. No underlying object on WebGPU.
props: BufferProps - holds a copy of the BufferProps used to create this Buffer.

Methods

constructor

Framebuffer is an abstract class and cannot be instantiated directly. Create with device.createFramebuffer(props: FramebufferProps).

An application can render into an (HTML or offscreen) canvas by obtaining a Framebuffer object from a CanvasContext using canvasContext.getDefaultFramebuffer(). Alternatively can create texture based framebuffers for off-screen rendering.

destroy(): void

Free up any GPU resources associated with this buffer immediately (instead of waiting for garbage collection).

TBD - When destroying Framebuffer will also destroy any Texture that was created automatically during Framebuffer creation. Supplied textures will not be destroyed (but will eventually be garbage collected and destroyed).

resize(width: number, height: number): void

Framebuffer.resize(width, height)

Resizes all the Framebuffer's current attachments to the new width and height by calling resize on those attachments.

width - the new width of Framebuffer in pixels
height - the new height of Framebuffer in pixels

Returns itself to enable chaining

Note the framebuffer.resize() method has been designed so that it can be called every frame without performance concerns. While the actual resizing of attachments can be expensive, the resize() methods checks if width or height have changed before actually resizing any attachments.

Remarks

WebGPU: resize() will destroy and recreate textures (meaning the the underlying GPUTexture / GPUTextureView handles are no longer the same after a resize()
WebGL: resize() will erase the current content of any attachments, but not actually create them (The underlyingWebGLTexture / WebGLRenderbuffer handles are not changed).
WebGPU: The Framebuffer class is a pure luma.gl class as this concept does not exist natively in WebGPU (attachment information has to be provided through the GPURenderPassDescriptor colorAttachments and the depthStencilAttachment fields every frame when a render pass is created).`.
WebGL: The Framebuffer class wraps the WebGLFramebuffer object exists, see e.g. Framebuffer and Framebuffer Object in the OpenGL Wiki.

4.6 KiB Raw Blame History