Skip to main content

RenderPass

Usage​

To draw to the screen in luma.gl, simply create a RenderPass by calling device.beginRenderPass() and start rendering. When done rendering, call renderPass.end()

  // A renderpass without parameters uses the default framebuffer of the device's default CanvasContext
  const renderPass = device.beginRenderPass();
  model.draw(renderPass);
  renderPass.end();
  device.submit();

device.getDefaultCanvasContext().getCurrentFramebuffer() returns a special framebuffer that lets you render to screen (into the swap chain). This framebuffer is used by default when a device.beginRenderPass() is called without providing a framebuffer, equivalent to:

  const renderPass = device.beginRenderPass({framebuffer: device.getDefaultCanvasContext().getCurrentFramebuffer()});
  ...

Clearing the screen​

Framebuffer attachments are cleared by default when a RenderPass starts. More control is provided via the clearColor parameter, setting this will clear the attachments to the corresponding color. The default clear color is [0, 0, 0, 1]. Set a clear property to boolean false to preserve that attachment.

  const renderPass = device.beginRenderPass({clearColor: [0, 0, 0, 1]});
  model.draw(renderPass);
  renderPass.end();
  device.submit();

Depth and stencil buffers are also cleared to default values:

  const renderPass = device.beginRenderPass({
    clearColor: [0, 0, 0, 1],
    clearDepth: 1,
    clearStencil: 0
  });
  renderPass.end();
  device.submit();

Viewport size​

RenderPassProps.parameters.viewport controls how the rendered graphics is mapped to window pixels / texels (more precisely, the affine transformation of x and y from normalized device coordinates to window coordinates).

If no value for the viewport parameter is provided, the following defaults will be applied.

  • If no framebuffer is specified, the size of the canvas drawing buffer will be used (device.getDefaultCanvasContext().getDrawingBufferSize())
  • If a framebuffer is specified, the width and height of the framebuffer will be used.

Types​

RenderPassProps​

RenderPassProps extends ResourceProps and accepts the following fields.

PropertyTypeDefaultDescription
framebuffer?Framebuffer | nullnullRender target that receives the output of the pass. When omitted, the default canvas framebuffer is used.
parameters?RenderPassParametersundefinedDynamic render-pass parameters such as viewport, scissor rectangle, blend constant and stencil reference.
clearColor?NumberArray4 | TypedArray | false[0, 0, 0, 1]Color used to clear the default color attachment. Set to false to preserve the previous value.
clearColors?(TypedArray | false)[]undefinedPer-attachment clear values for multiple color attachments. Takes precedence over clearColor when provided.
clearDepth?number | false1Depth value used when clearing the depth attachment. Set to false to preserve the previous depth.
clearStencil?number | false0Stencil value used when clearing the stencil attachment. Set to false to preserve the previous stencil.
depthReadOnly?booleanfalseMarks the depth attachment as read-only for the duration of the pass.
stencilReadOnly?booleanfalseMarks the stencil attachment as read-only for the duration of the pass.
discard?booleanfalseDisables rasterization output when set to true.
occlusionQuerySet?QuerySetundefinedQuery set that records occlusion query results generated by the pass.
timestampQuerySet?QuerySetundefinedQuery set that will receive timestamps at the beginning and end of the pass.
beginTimestampIndex?numberundefinedQuery set index that records the timestamp when the pass begins.
endTimestampIndex?numberundefinedQuery set index that records the timestamp when the pass ends.

Members​

  • device: Device - holds a reference to the Device that created this RenderPass.
  • handle: unknown - holds the backend render-pass handle
  • props: RenderPassProps - holds a copy of the RenderPassProps used to create this RenderPass.

Methods​

constructor()​

RenderPass is an abstract class and cannot be instantiated directly. Create with device.beginRenderPass(...).

end(): void​

Ends command encoding for the pass. Submit the encoder to execute WebGPU work; ending a pass does not itself submit it. AnimationLoop submits the default encoder after onRender returns.

setPipeline(pipeline: RenderPipeline): void​

Selects the immutable render pipeline used by subsequent commands.

setBindings(bindings: Bindings | BindingsByGroup): void​

Replaces the complete binding set used by subsequent draws. Call setPipeline() first so luma.gl can resolve binding names against the active shader layout.

setVertexArray(vertexArray: VertexArray): void​

Selects the vertex and index data used by subsequent draws.

draw(options: RenderPassDrawOptions): boolean​

Draws with the active pipeline, bindings, and vertex array. options contains draw counts and offsets such as vertexCount, indexCount, instanceCount, firstVertex, and firstIndex.

For indexed draws, indexCount takes precedence. When it is omitted, the active backend may use vertexCount as the indexed draw count for compatibility. firstIndex is measured in index elements; firstVertex applies to non-indexed draws. WebGL requires an index buffer when indexCount is supplied. A vertex array can be omitted for attribute-less non-indexed draws. WebGL requires isInstanced: true to use instanceCount; WebGPU infers instancing from the count. baseVertex and firstInstance are supported only on WebGPU.

renderPass.setPipeline(pipeline);
renderPass.setBindings({frameUniforms, materialUniforms});
renderPass.setVertexArray(vertexArray);
renderPass.draw({vertexCount: 3});

drawIndirect(indirectBuffer: Buffer, indirectByteOffset?: number): void​

WebGPU supportedWebGL 2 not supported

Draws using four packed uint32 arguments beginning at indirectByteOffset: vertexCount, instanceCount, firstVertex, and firstInstance. The buffer requires Buffer.INDIRECT usage.

drawIndexedIndirect(indirectBuffer: Buffer, indirectByteOffset?: number): void​

Draws indexed geometry using five packed 32-bit arguments: indexCount, instanceCount, firstIndex, signed baseVertex, and firstInstance. The record occupies 20 bytes.

executeBundles(bundles: Iterable<RenderBundle>): void​

From v9.4WebGPU supportedWebGL 2 not supported

Replays previously recorded RenderBundle objects from a RenderBundleEncoder in this render pass.

pushDebugGroup(groupLabel: string): void​

Adds a debug group (implementation dependent).

popDebugGroup(): void​

Removes a debug group (implementation dependent).

insertDebugMarker(markerLabel: string): void​

Adds a debug marker (implementation dependent).

withParameters(parameters: RenderPassParameters, callback: () => T): T​

Runs a synchronous callback with temporary viewport, scissorRect, blendConstant, and/or stencilReference values. Restores prior state in finally, including when parameter setup or the callback throws. Nested scopes are supported. Set state through luma APIs; direct native-handle changes are not tracked. Render bundle encoders reject this operation because dynamic state belongs to the executing pass.

WebGPU tracks copied parameter values, initialized from the attached texture view extent (including its mip level), a blend constant of [0, 0, 0, 0], and stencil reference 0. WebGL uses its existing state tracker, preserving inherited state such as a disabled scissor test.