The renderer parameters
Number of active Light2d instances uploaded to the lit batcher
for the current frame. Set by setLightUniforms. The WebGL
renderer's drawImage reads this to decide between the unlit
fast-path batcher (default) and the lit batcher (only when
lights AND a normal map are both in play).
ReadonlyadapterThe WebGPU adapter, set once WebGPURenderer#init resolves.
The background color used to clear the main framebuffer. Note: alpha value will be set based on the transparent property of the renderer settings.
The WebGPU canvas context
The normal-map texture associated with the next drawImage call,
if any. Set by Sprite.draw (and any other normal-map-aware
renderable) just before calling drawImage, then cleared back
to null after. The WebGL renderer reads this state and routes
lit quads through the shader's lighting path; the Canvas
renderer ignores it entirely.
the requested video size ratio
ReadonlydeviceThe WebGPU device, set once WebGPURenderer#init resolves.
The GPU device identifier string (set by GPU renderers — WebGL today, WebGPU once it lands; undefined for Canvas).
true if the current rendering context is valid
The thickness of lines for shape drawing operations like
Renderer#strokeRect, Renderer#strokeEllipse
and Renderer#strokeLine. Subclasses override the
storage — CanvasRenderer proxies it to the underlying 2D
context via a getter/setter, while WebGLRenderer treats it
as a regular field consumed by its shape-stroke routines.
The Application this renderer belongs to, set by
Application.init() — engine code holding a renderer reference
must use this rather than the global game instance.
The Path2D instance used by the renderer to draw primitives
ReadonlypreferredThe preferred canvas texture format reported by the platform, set once WebGPURenderer#init resolves.
The renderer state container (color, tint, transform, scissor, blend mode) with a zero-allocation save/restore stack.
The renderer renderTarget
the scaling ratio to be applied to the main canvas
The given constructor options
The source language this backend accepts for user-supplied shaders,
or null when it has no programmable pipeline at all (the Canvas
backend). "glsl" on the WebGL backend, "wgsl" on the WebGPU
backend.
Consumers that need a specific language — ShaderEffect and the
loader's {vertex, fragment} shader assets both hand GLSL source
straight to the driver — must compare against the language rather
than test for a GPU backend, or they would accept a backend that
cannot read what they are about to give it.
Whether this backend has a depth buffer, and with it the 3D
projection and mesh paths a depth-sorted scene needs (Camera3d
and any camera declaring defaultSortOn = "depth"). false here
on the base/Canvas renderer.
Whether this renderer backend can draw one geometry many times in a
single call from per-instance data — what InstancedMesh
needs. false here on the base/Canvas renderer, which falls back to
drawing each instance individually.
Whether this renderer backend can keep mesh geometry resident on the
GPU, letting a mesh supply a model matrix instead of vertices it has
already positioned itself. false here on the base/Canvas renderer.
Whether this renderer backend can draw TMX tile layers through a
GPU shader path (see the gpuTilemap application setting).
false here on the base/Canvas renderer; GPU backends flip it.
A capability flag rather than a version/class check so future
backends advertise support without consumers growing type checks.
The renderer backend identity — the built-in renderers report
"CANVAS", "WebGL2" and "WebGPU". Use it for identity
checks (code coupled to one backend's machinery); prefer the
capability flags (shaderLanguage, supportsDepthBuffer,
supportsRetainedMesh, supportsShaderTileLayers) when the
requirement is a capability rather than a specific backend.
(override this property with a specific value when implementing
a custom renderer)
Static_Current per-renderable depth value. The GPU batchers (WebGL and
WebGPU) push it into the vertex stream as the z
component of each vertex — a no-op under the default orthographic
projection, used by perspective (Camera3d) to
scale and parallax sprites by distance. Mirrors renderable.depth,
set automatically by Renderable.preDraw via Renderer#setDepth.
return the height of the canvas which this renderer draws to
height of the system Canvas
return the width of the canvas which this renderer draws to
width of the system Canvas
Add a batcher to this renderer.
a batcher instance
Optionalname: string = "default"
the batcher name
Optionalactivate: boolean = false
true to set this batcher as the active one
Adds a circular arc to the current sub-path, using the given control points and radius.
the x-axis coordinate of the first control point
the y-axis coordinate of the first control point
the x-axis coordinate of the second control point
the y-axis coordinate of the second control point
the arc's radius; must be non-negative
starts a new path by emptying the list of sub-paths
Adds a cubic Bezier curve to the current sub-path.
the x-axis coordinate of the first control point
the y-axis coordinate of the first control point
the x-axis coordinate of the second control point
the y-axis coordinate of the second control point
the x-axis coordinate of the end point
the y-axis coordinate of the end point
Draw a pooled render target through an effect's pipeline as a screen-space quad — the compositing primitive of the post-effect chain. Blending is disabled for camera blits (the target is fully composited) and kept for per-sprite blits (transparent texels must not overwrite the scene).
the target to sample
destination x
destination y
destination width
destination height
the effect to composite with
OptionalkeepBlend: boolean = false
keep the current blend mode
Begin the frame: reset the per-frame allocators, acquire the canvas
texture, and open the frame's command encoder and render pass with a
clear load — the WebGPU realization of gl.clearColor + gl.clear.
Called by Application.draw() at the top of every frame.
Clear the current clip region with the given color — a full-viewport triangle clipped by the active scissor, drawn with blending replaced (WebGPU has no scissored clear operation). Used mid-frame by ColorLayer and Container backgrounds.
Deliberate divergence from the GL backend: because this is a draw,
it honors an active stencil mask (GL's gl.clear ignores stencil and
clears the whole scissor region) — under a mask, the clear fills the
mask window only, which is the behavior masks actually promise.
Optionalcolor: string | Color = "#000000"
css color
Optionalopaque: boolean = false
allow transparency or not
Erase the pixels in the given rectangular area by setting them to transparent black (rgba(0,0,0,0)).
x axis of the coordinate for the rectangle starting point.
y axis of the coordinate for the rectangle starting point.
The rectangle's width.
The rectangle's height.
Clear the current render target with transparent black — the offscreen-target analogue of a frame clear, realized as this backend's pass-level clear (the next pass on the target loads cleared content instead of recording a clearing draw).
clip the given region from the canvas — all future drawing is
limited to it. The clip is a transform-derived screen-space AABB
applied through the pass scissor (WebGPU's setScissorRect is
top-left-origin, so the stored coords apply without the GL y-flip;
it validates containment, so the box is clamped to the canvas).
x axis of the upper-left corner of the region
y axis of the upper-left corner of the region
the width of the region
the height of the region
add a straight line from the current point to the start of the current sub-path
Create and return a new Canvas element, sized as requested.
The instance form of Renderer.createCanvas. app.renderer is
the renderer entry point, and a static is not reachable through an
instance — so this is what user code actually calls.
width in pixels
height in pixels
OptionalreturnOffscreenCanvas: boolean = false
return an OffscreenCanvas where supported
the new canvas
Create a linear gradient that can be used with Renderer#setColor.
x-axis coordinate of the start point
y-axis coordinate of the start point
x-axis coordinate of the end point
y-axis coordinate of the end point
a Gradient object
Create a pattern with the specified repetition
source image
Optionalrepeat: string = "no-repeat"
one of "repeat" / "repeat-x" / "repeat-y" / "no-repeat"
the patterned texture created
Create a radial gradient that can be used with Renderer#setColor.
x-axis coordinate of the start circle
y-axis coordinate of the start circle
radius of the start circle
x-axis coordinate of the end circle
y-axis coordinate of the end circle
radius of the end circle
a Gradient object
Release any retained geometry held for the given mesh (called from
Mesh.onDeactivateEvent / Mesh.destroy).
the mesh whose GPU geometry should be freed
Release the GPU device, unconfigure the canvas context, and tear down every GPU-facing cache. Called by Application#destroy.
disable the scissor test — pass-model realization of the GL call (pending vertices drain, the open pass widens back to the target)
Draw an image onto the frame (Canvas-compatible 3/5/9-argument forms).
the source image
source x (or destination x in the 3/5-arg forms)
source y (or destination y in the 3/5-arg forms)
Optionalsw: number
source width
Optionalsh: number
source height
Optionaldx: number
destination x
Optionaldy: number
destination y
Optionaldw: number
destination width
Optionaldh: number
destination height
Draw a Light2d glow quad through the radial-gradient effect's single-effect fast path — the light's color and intensity ride the per-vertex tint, so back-to-back lights share the same pipeline.
the light to draw
Draw a textured triangle mesh.
The mesh object must provide: vertices (Float32Array, x/y/z triplets),
uvs (Float32Array, u/v pairs), indices (Uint16Array, triangle indices),
texture (TextureAtlas), vertexCount (number), and optionally
cullBackFaces (boolean, default true).
On the GPU backends (WebGL and WebGPU — hardware depth testing),
passing a modelMatrix selects the retained path: the mesh's
model-space geometry stays resident on the GPU and the matrix
places it, so redrawing never re-uploads vertices (see
Renderer#supportsRetainedMesh). Without a matrix the
vertices are taken as already CPU-projected (the 2D-camera path —
the only path the Canvas renderer supports, using painter's
algorithm). Mesh.draw selects the right form automatically.
a Mesh renderable or compatible object
the mesh's placement, for the retained path (GPU backends)
Draw a pattern within the given rectangle.
pattern object returned by WebGPURenderer#createPattern
x position where to draw the pattern
y position where to draw the pattern
width of the pattern
height of the pattern
Draw a TMX tile layer: WGSL-eligible layers (renderMode === "shader") draw through the GPU tile path — one quad per tileset,
GID lookup in a per-layer index texture; everything else falls
through to the base per-tile loop.
the TMXLayer to draw
the visible region in world coords
Enable the scissor test with the given rectangle (transformed by the current transform, like the WebGL renderer). Unlike WebGPURenderer#clipRect a full-canvas rectangle still enables the scissor rather than reading as "no clip".
x coordinate of the scissor rectangle
y coordinate of the scissor rectangle
width of the scissor rectangle
height of the scissor rectangle
fill the given shape or the current defined path
Optionalshape: any
a shape object to fill
Fill an arc at the specified coordinates with given radius, start and end points
arc center point x-axis
arc center point y-axis
arc radius
start angle in radians
end angle in radians
OptionalantiClockwise: boolean = false
draw arc anti-clockwise
Fill an ellipse at the specified coordinates with given radius
ellipse center point x-axis
ellipse center point y-axis
horizontal radius of the ellipse
vertical radius of the ellipse
Fill a line between the given two points
the start x coordinate
the start y coordinate
the end x coordinate
the end y coordinate
Draw a point at the specified coordinates
x axis of the coordinate for the point
y axis of the coordinate for the point
Fill a Polygon on the screen
the shape to draw
Draw a filled rectangle at the specified coordinates
x axis of the coordinate for the rectangle starting point
y axis of the coordinate for the rectangle starting point
the rectangle's width
the rectangle's height
Draw a rounded filled rectangle at the specified coordinates
x axis of the coordinate for the rounded rectangle starting point
y axis of the coordinate for the rounded rectangle starting point
the rounded rectangle's width
the rounded rectangle's height
the rounded corner's radius
end the open pass and submit the frame's command buffer
Draw every ground shadow queued since the last drain, then empty the queue (#1515). Called when the renderer leaves mesh mode, and once more at end of frame for a scene made only of meshes, which never switches away from mesh mode on its own.
Inert on a backend that never queues — the Canvas renderer has no depth buffer and so no ground shadows at all.
returns the current blend mode for this renderer
blend mode
return a reference to the current render target corresponding canvas which this renderer draws to
Returns the WebGPU canvas context
the WebGPU canvas context
Resolve the default texture filter mode for this renderer, decoupled
from Renderer#setAntiAlias (which controls polygon-edge MSAA on GPU
backends). Honors the textureFilter setting ("nearest" / "linear"),
falling back to the antiAlias setting when it's "auto" (the default).
Backend-neutral on purpose: it returns the mode as a string so each GPU
backend maps it to its own enum (WebGL gl.LINEAR / gl.NEAREST, a future
WebGPU renderer GPUFilterMode). The Canvas renderer has no per-texture
filtering, so this is informational there.
the resolved default filter mode
Return the global alpha
global alpha value
Get the current line dash pattern.
the current dash pattern
The compressed-texture families this device supports, in the same shape as the GL backend (one key per family; supported families hold an object of WebGL format constants — the values the loader parsers emit — unsupported ones are null, so the shared hasSupportedCompressedFormats works unchanged). PVRTC has no WebGPU equivalent and stays null.
one key per extension family
return the current global alpha
return true if the given compressed texture format is supported
a WebGL compressed texture format constant
Negotiate the GPU adapter and device, configure the canvas context, and build the GPU-facing infrastructure (pipeline cache, buffer arenas, depth-stencil attachment). Awaited by Application#init right after construction — a WebGPU device cannot be acquired synchronously, which is what this hook exists for.
resolves once the device is configured
adds a straight line to the current sub-path
the x axis of the point
the y axis of the point
begins a new sub-path at the point specified by the given (x, y) coordinates
the x axis of the point
the y axis of the point
Adds a quadratic Bezier curve to the current sub-path.
the x-axis coordinate of the control point
the y-axis coordinate of the control point
the x-axis coordinate of the end point
the y-axis coordinate of the end point
creates a rectangular path whose starting point is at (x, y)
the x axis of the coordinate for the rectangle starting point
the y axis of the coordinate for the rectangle starting point
the rectangle's width
the rectangle's height
Reset the renderer state
Reset the transform to identity
resizes the system canvas
new width of the canvas
new height of the canvas
restores the most recently saved renderer state
adds a rotation to the transformation matrix
the rotation angle, clockwise in radians
adds a rounded rectangle to the current path
the x axis of the coordinate for the rectangle starting point
the y axis of the coordinate for the rectangle starting point
the rectangle's width
the rectangle's height
the corner radius
saves the entire state of the renderer onto the state stack
adds a scaling transformation to the renderer units
horizontal scaling factor
vertical scaling factor
Enable/disable anti-aliasing — under WebGPU this only drives the default sampler filter: textures stay resident and every (texture, sampler) bind-group pairing is rebuilt on next draw.
Optionalenable: boolean = false
whether to enable anti-aliasing
Set the active batcher for this renderer — flush + unbind the outgoing one, bind the incoming. Unlike the GL backend there is no projection re-sync: the projection lives in the shared frame-globals bind group, not in per-program uniforms.
Optionalname: string = "default"
a batcher name
the now-active batcher
Enable or disable blending — blend state is pipeline state on this backend, so this maps onto the blend-mode axis: disabling stashes the current mode and switches to "none" (source replaces destination), enabling restores the stashed mode.
whether blending should be enabled
Set the blend mode for subsequent draws. Under WebGPU blending is pipeline state: the change is recorded (after draining vertices queued under the previous mode) and the next batcher flush picks the matching pipeline variant.
Optionalmode: string = "normal"
blend mode ("normal", "multiply", "additive"/"lighter", "screen", "darken", "lighten", "none")
OptionalpremultipliedAlpha: boolean = true
whether textures use premultiplied alpha (affects the source blend factor)
the blend mode actually applied
Set the current per-renderable depth value. GPU batchers (WebGL
today, WebGPU once it lands) push it into the vertex stream as the
z component of each vertex — a no-op under the default
orthographic projection, used by perspective (Camera3d) to scale
and parallax sprites by distance.
Typically called automatically by Renderable.preDraw from the
renderable's depth property. User code only needs to call this
directly when emitting draw calls outside of a Renderable.draw()
— e.g. from a custom Container.draw() override.
Honored by the save/restore stack like setTint / setColor.
the depth value to set
Multiply the global alpha
global alpha value (0..1)
Pack the active 2D lights and hand the std140 block to the lit batcher — the WebGPU realization of the backend-neutral lighting contract (Camera2d calls this once per camera per frame).
active lights
the ambient lighting floor
OptionaltranslateX: number = 0
camera translate x
OptionaltranslateY: number = 0
camera translate y
Set the line dash pattern for stroke operations.
an array of numbers specifying distances to alternately draw a line and a gap. An empty array clears the dash pattern (solid lines).
A mask limits rendering elements to the shape and position of the given mask object — realized on the stencil half of the pass's depth-stencil attachment, exactly like the GL backend: a write phase increments the stencil under the mask shape (color writes off), then the render phase only passes fragments where the stencil equals the current mask level (or 0 when inverted).
Entering the first mask level clears the stencil, which WebGPU can
only do at a pass boundary — the frame's pass is broken and
restarted with stencilLoadOp: "clear" (color preserved).
(Note: masks are not preserved through save/restore and need to be
manually cleared, same as the other backends.)
Optionalmask: any
the shape defining the mask to be applied
Optionalinvert: boolean = false
either the given shape should define what is visible (default) or the opposite
Set the projection matrix — pushes a fresh frame-globals slot so draws already recorded keep the projection they were queued under (floating containers swap the projection mid-frame).
the new projection matrix
Set the default texture filter at runtime, decoupled from WebGPURenderer#setAntiAlias — same re-pairing mechanism.
Optionalmode: "auto" | "linear" | "nearest" = "auto"
"auto" follows antiAlias
set a coloring tint for sprite based renderables
the tint color
Optionalalpha: number = tint.alpha
an alpha value to be applied to the tint
Reset then multiply the transformation matrix
a matrix, or the a component
Optionalb: number
the b component
Optionalc: number
the c component
Optionald: number
the d component
Optionale: number
the e component
Optionalf: number
the f component
Restrict rendering to a sub-rectangle of the canvas — the split-screen
camera surface (Camera2d/Camera3d._setupNonDefaultProjection).
Callers pass GL-convention rects with a BOTTOM-left origin (the flip is
baked into the camera code, which the GL backend depends on); WebGPU
viewports are top-left, so it is un-flipped here. The rect applies to
canvas passes only — offscreen post-effect targets always render full
size, like the GL pool path re-viewporting per target.
viewport x (pixels)
viewport y, bottom-left origin (pixels)
viewport width (pixels)
viewport height (pixels)
stroke the given shape or the current defined path
Optionalshape: any
a shape object to stroke
Optionalfill: boolean
fill the shape with the current color if true
Stroke an arc at the specified coordinates with given radius, start and end points
arc center point x-axis
arc center point y-axis
arc radius
start angle in radians
end angle in radians
OptionalantiClockwise: boolean = false
draw arc anti-clockwise
Optionalfill: boolean = false
also fill the shape with the current color if true
Stroke an ellipse at the specified coordinates with given radius
ellipse center point x-axis
ellipse center point y-axis
horizontal radius of the ellipse
vertical radius of the ellipse
Optionalfill: boolean = false
also fill the shape with the current color if true
Stroke a line between the given two points
the start x coordinate
the start y coordinate
the end x coordinate
the end y coordinate
Stroke a Point at the specified coordinates
x axis of the coordinate for the point
y axis of the coordinate for the point
Stroke a Polygon on the screen with the current color
the shape to draw
Optionalfill: boolean = false
also fill the shape with the current color if true
Draw a stroke rectangle at the specified coordinates
x axis of the coordinate for the rectangle starting point
y axis of the coordinate for the rectangle starting point
the rectangle's width
the rectangle's height
Optionalfill: boolean = false
also fill the shape with the current color if true
Stroke a rounded rectangle at the specified coordinates
x axis of the coordinate for the rounded rectangle starting point
y axis of the coordinate for the rounded rectangle starting point
the rounded rectangle's width
the rounded rectangle's height
the rounded corner's radius
Optionalfill: boolean = false
also fill the shape with the current color if true
tint the given image or canvas using the given color
the source image to be tinted
the color that will be used to tint the image
Optionalmode: string = "multiply"
the composition mode used to tint the image
a new canvas or offscreencanvas (if supported) element representing the tinted image
creates a Blob object representing the last rendered frame
Optionaltype: string = "image/png"
A string indicating the image format
Optionalquality: number
A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
A Promise returning a Blob object representing the last rendered frame
returns a data URL containing a representation of the last frame rendered
Optionaltype: string = "image/png"
A string indicating the image format
Optionalquality: number
A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
A Promise returning a string containing the requested data URL.
Capture the current frame — everything drawn to the active target so
far — into a Texture2d, entirely on the GPU (an encoder-ordered
copyTextureToTexture; no readback round-trip). Same contract as the
WebGL backend's toFrameTexture: a shared, renderer-owned slot by
default, target: null for a fresh caller-owned capture, or a prior
capture as target to refresh it in place; options.region captures
a sub-region (framebuffer pixels, bottom-left origin — converted to
this backend's top-left copy origin internally).
Two documented divergences from the GL capture:
screen_uv),
where the GL capture is bottom-up — GLSL bodies sampling a capture
flip with 1.0 - uv.y; their WGSL twins must not.Optionaloptions: {Optionalregion?: Bounds | { height: number; width: number; x: number; y: number }capture only this sub-region; defaults to the whole frame
Optionaltarget?: anyomit for the shared renderer
slot; a prior capture to refresh it in place; null to mint a fresh,
caller-owned capture (destroy() it yourself when done)
a GPU-resident texture holding the captured frame, or null when no device is available
creates an ImageBitmap object of the last frame rendered (not supported by standard Canvas)
Optionaltype: string = "image/png"
A string indicating the image format
Optionalquality: number
A Number between 0 and 1 indicating the image quality to be used when creating images using file formats that support lossy compression (such as image/jpeg or image/webp). A user agent will use its default quality value if this option is not specified, or if the number is outside the allowed range.
A Promise returning an ImageBitmap.
Multiply the given matrix (or 2D affine components) into the current transformation matrix
a matrix, or the a component
Optionalb: number
the b component
Optionalc: number
the c component
Optionald: number
the d component
Optionale: number
the e component
Optionalf: number
the f component
adds a translation transformation to the current matrix
distance to move in the horizontal direction
distance to move in the vertical direction
StaticcreateCreate and return a new Canvas element (or OffscreenCanvas when
supported and returnOffscreenCanvas is true). Centralized
renderer-side allocator so every scratch / fallback / render-
target canvas in the engine routes through the same
OffscreenCanvas-aware path, instead of duplicating
document.createElement calls that throw in worker contexts.
canvas width in pixels
canvas height in pixels
OptionalreturnOffscreenCanvas: boolean = false
return an
OffscreenCanvas if the platform supports it
a new canvas of the given size
StaticgetShared 1×1 fully-white canvas used as a no-op texture fallback.
Renderers and renderables that need a "blank" texture binding
(e.g. to satisfy a shader's sampler input when there's no real
image — Kd-only Mesh materials, solid-color quad fills, etc.)
should use this rather than allocating their own.
Lazily created on first call; shared across every caller; uses
OffscreenCanvas where supported (worker-safe). Static so it's
accessible without a renderer instance (e.g. from a Mesh
constructor that runs before the active renderer is set).
the shared 1×1 white canvas
The experimental WebGPU renderer.
The asynchronous bootstrap —
getContext("webgpu")at construction, then adapter/device negotiation and canvas configuration in WebGPURenderer#init (the reason Application#init is asynchronous at all) — plus the core 2D frame pipeline: one command encoder and one render pass per frame, opened by WebGPURenderer#clear and submitted by WebGPURenderer#flush, with adepth24plus-stencil8attachment carried from day one (the stencil half serves masks; the depth half is reserved for the mesh path).It is opt-in only:
renderer: video.WEBGPU(or the#webgpuURI fragment).video.AUTOnever selects it, and will not until it reaches feature parity with the WebGL backend.