Documentation / spryte / Draw

Class: Draw

Defined in: draw.ts:52

Immediate-mode drawing in logical units, the same API on WebGL2 and Canvas 2D (ADR 0007). Everything batches automatically; call order is draw order.

Constructors

Constructor

new Draw(backend, smooth): Draw

Defined in: draw.ts:84

Internal

Parameters

backend

Backend

smooth

boolean

Default filtering for images (false for pixel art).

Returns

Draw

Properties

alpha

alpha: number = 1

Defined in: draw.ts:54

Global alpha multiplier for subsequent draws.

---

font

font: string | BitmapFont | (() => string | BitmapFont) = "16px sans-serif"

Defined in: draw.ts:59

Font for text() and measure() when none is given: a CSS font, a BitmapFont, or a function returning one (called on first use, so a font built from a canvas costs nothing until text is drawn).

---

quads

quads: number = 0

Defined in: draw.ts:61

Quads (sprites, rects, glyph runs…) submitted this frame. Reset each frame; for diagnostics.

---

ready

ready: Promise<void>

Defined in: draw.ts:104

Resolves once the backend can draw. Immediate on WebGL2; on the Canvas 2D fallback, once its chunk has loaded (frames before that draw nothing). Rejects if the fallback fails to load.

---

renderScale

renderScale: number = 1

Defined in: draw.ts:522

Internal

---

smooth

smooth: boolean

Defined in: draw.ts:87

Default filtering for images (false for pixel art).

Accessors

contextLost

Get Signature

get contextLost(): boolean

Defined in: draw.ts:510

True while the WebGL context is lost (e.g. a backgrounded mobile tab): frames draw nothing until it's restored.

Returns

boolean

---

drawCalls

Get Signature

get drawCalls(): number

Defined in: draw.ts:96

Draw calls this frame: batched GPU calls on WebGL2, one per quad on Canvas 2D.

Returns

number

---

kind

Get Signature

get kind(): "webgl2" | "2d"

Defined in: draw.ts:91

Which backend is active.

Returns

"webgl2" | "2d"

---

raw

Get Signature

get raw(): RawContext

Defined in: draw.ts:107

Raw WebGL2RenderingContext or CanvasRenderingContext2D. Mixing raw calls with draw calls requires care.

Returns

RawContext

Methods

begin()

begin(clear, width, height, scale): void

Defined in: draw.ts:525

Internal

Parameters

clear

Color

width

number

height

number

scale

number

Returns

void

---

blend()

blend(mode): void

Defined in: draw.ts:216

Parameters

mode

BlendMode

Returns

void

---

circle()

circle(x, y, radius, color): void

Defined in: draw.ts:227

Filled circle (antialiased).

Parameters

x

number

y

number

radius

number

color

Color

Returns

void

---

clip()

clip(x, y, w, h, fn): void

Defined in: draw.ts:157

Run fn with drawing restricted to a rectangle (in current units), then restore. Nested clips intersect. Clips are axis-aligned on screen: under rotation the rectangle's screen bounds are used.

Parameters

x

number

y

number

w

number

h

number

fn

() => void

Returns

void

---

createShader()

createShader(source): Shader

Defined in: draw.ts:486

A custom fragment effect: see Shader. Compiled on first use, so errors surface at the first withShader draw.

Parameters

source

string

Returns

Shader

---

createTarget()

createTarget(width, height): RenderTarget

Defined in: draw.ts:431

An offscreen image of width × height pixels to draw into with into(), then draw like any image.

Parameters

width

number

height

number

Returns

RenderTarget

---

dispose()

dispose(): void

Defined in: draw.ts:558

Release GPU resources and listeners. Using this Draw afterwards throws; disposing again does nothing.

Returns

void

---

disposeTarget()

disposeTarget(target): void

Defined in: draw.ts:505

Free a target's GPU memory. Drawing it afterwards recreates it, blank.

Parameters

target

RenderTarget

Returns

void

---

end()

end(): void

Defined in: draw.ts:553

Internal

Returns

void

---

into()

into(target, fn, clear?): void

Defined in: draw.ts:448

Run fn with drawing going into target instead of the canvas, then switch back. Inside, units are the target's pixels from its top-left; the transform, clips and global alpha start fresh and are restored afterwards. clear fills the target first (default transparent); pass null to draw over what's there, for trails and accumulation. Nests.

const glow = draw.createTarget(160, 90);
draw.into(glow, () => draw.sprites(spark, sparks, n, { tint: "#ffd36b" }));
draw.blend("add");
draw.sprite(glow, 160, 90, { scaleX: 2, scaleY: 2, smooth: true });

Parameters

target

RenderTarget

fn

() => void

clear?

Color | null = 0

Returns

void

---

invalidate()

invalidate(src): void

Defined in: draw.ts:515

Re-upload a source whose pixels changed (e.g. a canvas you draw into).

Parameters

src

TextureSource

Returns

void

---

line()

line(x1, y1, x2, y2, width, color): void

Defined in: draw.ts:234

Parameters

x1

number

y1

number

x2

number

y2

number

width

number

color

Color

Returns

void

---

measure()

measure(text, font?): object

Defined in: draw.ts:399

The logical box text() fills for this string and font, so layouts can align and centre without guessing. Same cache as text(), so measuring then drawing rasterises once.

Parameters

text

string

font?

string | BitmapFont = ...

Returns

object

h

h: number

w

w: number

---

pop()

pop(): void

Defined in: draw.ts:123

Returns

void

---

push()

push(): void

Defined in: draw.ts:113

Returns

void

---

rect()

rect(x, y, w, h, color): void

Defined in: draw.ts:220

Parameters

x

number

y

number

w

number

h

number

color

Color

Returns

void

---

reset()

reset(): void

Defined in: draw.ts:541

Internal

Reset transform and blend between scene and afterRender hooks.

Returns

void

---

resize()

resize(w, h): void

Defined in: draw.ts:564

Internal

Parameters

w

number

h

number

Returns

void

---

rotate()

rotate(radians): void

Defined in: draw.ts:143

Parameters

radians

number

Returns

void

---

scale()

scale(x, y?): void

Defined in: draw.ts:135

Parameters

x

number

y?

number = x

Returns

void

---

setBackend()

setBackend(backend): void

Defined in: draw.ts:571

Internal

Switch to a backend that finished loading (the Canvas 2D fallback), at the current size.

Parameters

backend

Backend

Returns

void

---

sprite()

sprite(frame, x, y, o?): void

Defined in: draw.ts:247

Draw an image frame (or a whole image) at x, y, anchored by origin. Allocation-free hot path.

Parameters

frame

TextureSource | Frame

x

number

y

number

o?

SpriteDrawOptions = NO_OPTIONS

Returns

void

---

sprites()

sprites(frame, positions, count?, o?, each?): void

Defined in: draw.ts:273

Draw one image frame at many positions in a single call: particles, bullets, swarms, starfields. positions holds x, y pairs (a Float32Array you reuse is ideal); count defaults to all of them. Every copy shares options (rotation, scale, tint, alpha…), so per-copy work is just the position. Much faster than calling sprite() in a loop, with no per-sprite allocation.

const pos = new Float32Array(2 * MAX);
// ...update pos...
draw.sprites(spark, pos, live, { tint: "#ffd36b", alpha: 0.8 });

Parameters

frame

TextureSource | Frame

positions

ArrayLike<number>

count?

number = ...

o?

SpriteDrawOptions = NO_OPTIONS

each?

SpritesEach

Returns

void

---

text()

text(text, x, y, o?): void

Defined in: draw.ts:379

Text, rasterised once and cached as a texture (crisp at the current render scale).

Parameters

text

string

x

number

y

number

o?

TextDrawOptions = {}

Returns

void

---

translate()

translate(x, y): void

Defined in: draw.ts:129

Parameters

x

number

y

number

Returns

void

---

withCamera()

withCamera(camera, fn): void

Defined in: draw.ts:196

Run fn with the camera's view applied, then restore.

Parameters

camera

view

() => Matrix

fn

() => void

Returns

void

---

withShader()

withShader(shader, fn): void

Defined in: draw.ts:491

Run fn with everything drawn through shader, then restore the previous one. Nests. WebGL2 only (see Shader).

Parameters

shader

Shader

fn

() => void

Returns

void