GPUCanvas

A GPU canvas — a 1× presentation target, same role as a WebGPU surface texture. Use .image with renderer:drawImage() to composite the result. Render to it via canvas:beginRenderPass({ color = {{ loadOp = 'clear', storeOp = 'store', ... }} }) — the color attachment’s view defaults to this canvas’s own colorView when omitted. MSAA requires a user-allocated GPUTexture.new({ sampleCount = N, renderTarget = true }) as the explicit color view, with the canvas’s colorView() as resolveTarget.

Fields

image

Backing image for renderer:drawImage().

width

Width in pixels.

height

Height in pixels.

format

Pixel format of the canvas backing texture, always ‘rgba8unorm’. A deferred canvas reports this before its texture is allocated. MSAA resolve requires source and target to have identical formats — always derive GPUTexture and pipeline formats from this value:

  local fmt = canvas.format
  GPUPipeline.new({ colorTargets = {{ format = fmt }}, sampleCount = 4 })

Methods

resize

resize(width: number, height: number) -> ()

Resize the canvas. Recreates the 1× backing texture. Any user-allocated MSAA / depth textures must be recreated by the script to match the new dimensions.

colorView

colorView() -> GPUTextureView

View of the canvas backing texture. Use as a color attachment, an MSAA resolve target, or a sampler input in a subsequent pass.

beginRenderPass

beginRenderPass(desc: RenderPassDesc) -> GPURenderPass

Open a GPU render pass targeting this canvas. The descriptor must include at least one color attachment or a depthStencil attachment. Color attachment views default to this canvas’s colorView when omitted; provide them explicitly when rendering to a different target (e.g. MSAA). The pass’s sampleCount is derived from the attachments (WebGPU rule: all attachments share one sampleCount). Must be called inside a drawCanvas phase. Issue draw calls on the returned pass, then call :finish().