Toodle

Appearance

@bloopjs/toodle

@bloopjs/toodle / Toodle / Toodle

Class: Toodle ​

Defined in: Toodle.ts:29

Constructors ​

Constructor ​

new Toodle(backend, canvas, resolution, options): Toodle

Defined in: Toodle.ts:77

it's unlikely that you want to use the constructor directly. see Toodle.attach for creating a Toodle instance that draws to a canvas.

Parameters ​

backend ​

IRenderBackend

canvas ​

HTMLCanvasElement

resolution ​

Resolution

options ​

ToodleOptions

Returns ​

Toodle

Properties ​

assets ​

assets: AssetManager

Defined in: Toodle.ts:33

Asset manager. Use toodle.assets.loadTexture to load texture assets.

camera ​

camera: Camera

Defined in: Toodle.ts:56

Camera. This applies a 2d perspective projection matrix to any nodes drawn with toodle.draw

clearColor ​

clearColor: Color

Defined in: Toodle.ts:62

clearColor is the color that will be used to clear the screen at the beginning of each frame you can also think of this as the background color of the canvas

diagnostics ​

diagnostics: object

Defined in: Toodle.ts:39

diagnostics can be used as a rough gauge for performance. besides frames, these stats are reset at the beginning of each frame.

drawCalls ​

drawCalls: number = 0

number of instanced draw calls issued last frame. lower is better

frames ​

frames: number = 0

number of frames rendered

instancesEnqueued ​

instancesEnqueued: number = 0

number of instances enqueued last frame

pipelineSwitches ​

pipelineSwitches: number = 0

number of pipeline switches last frame. lower is better. to reduce pipeline switches, use fewer z-indexes or fewer custom shaders

shapes ​

shapes: object

Defined in: Toodle.ts:532

Circle() ​

Circle: (options) => QuadNode

Parameters ​
options ​

CircleOptions = ...

Returns ​

QuadNode

Line() ​

Line: (options) => QuadNode

Parameters ​
options ​

LineOptions

Returns ​

QuadNode

Rect() ​

Rect: (options) => QuadNode

Parameters ​
options ​

QuadOptions = {}

Returns ​

QuadNode

Accessors ​

backend ​

Get Signature ​

get backend(): WebGPUBackend | WebGLBackend

Defined in: Toodle.ts:742

Get the render backend instance. Cast to WebGPUBackend or WebGLBackend to access backend-specific properties.

Example ​
ts
if (toodle.backend instanceof WebGPUBackend) {
  const device = toodle.backend.device;
}
Returns ​

WebGPUBackend | WebGLBackend

batcher ​

Get Signature ​

get batcher(): Batcher

Defined in: Toodle.ts:218

Returns ​

Batcher

frameCount ​

Get Signature ​

get frameCount(): number

Defined in: Toodle.ts:381

The number of frames rendered since this Toodle instance was created.

Returns ​

number

limits ​

Get Signature ​

get limits(): object

Defined in: Toodle.ts:214

Returns the currently configured Toodle engine limits

See: https://toodle.gg/f849595b3ed13fc956fc1459a5cb5f0228f9d259/limits.html

Example ​
ts
const instanceLimit: number = toodle.limits.instanceCount;
Returns ​
instanceBufferFields ​

instanceBufferFields: number

Maximum number of instance buffer fields - 16 minus the vertex locations used by the engine

instanceBufferSize ​

instanceBufferSize: number

Maximum size of instance buffer

instanceCount ​

instanceCount: number

Maximum number of rendered instances in the scene per frame

maxTextLength ​

maxTextLength: number = 256

Maximum length of a single piece of text

shaderCount ​

shaderCount: number = 32

Maximum number of vfx shaders

textureArrayLayers ​

textureArrayLayers: number = 64

Maximum number of layers in a texture array

textureSize ​

textureSize: number

Maximum dimensions of a single texture

uniformBufferSize ​

uniformBufferSize: number

Maximum size of uniforms buffer

zIndex ​

zIndex: number = 32

Maximum number of unique z-indexes in the scene

maxGpuMemory ​

Get Signature ​

get maxGpuMemory(): number

Defined in: Toodle.ts:237

The maximum amount of GPU memory that will be used by the Toodle instance. This is a rough estimate and may not be exact. This will be allocated up front when calling Toodle.attach, and freed when calling toodle.destroy.

Returns ​

number

maxPixels ​

Get Signature ​

get maxPixels(): number

Defined in: Toodle.ts:225

The maximum number of pixels that can be loaded into texture atlases for this toodle instance.

Returns ​

number

postprocess ​

Get Signature ​

get postprocess(): null | PostProcess

Defined in: Toodle.ts:110

Screen shader is an optional slot for post-processing effects. Note that this will do the main render pass to an offscreen texture, which may impact performance. Currently only supported in WebGPU mode.

Returns ​

null | PostProcess

Set Signature ​

set postprocess(value): void

Defined in: Toodle.ts:115

Parameters ​
value ​

null | PostProcess

Returns ​

void

resolution ​

Get Signature ​

get resolution(): Resolution

Defined in: Toodle.ts:201

The resolution of the canvas in css or logical pixels.

Example ​
ts
// devicePixelRatio is 1, resolution is 200x200
<canvas width="200" height="200" style="width: 200px; height: 200px;"></canvas>
// devicePixelRatio is 2, resolution is 100x100
<canvas width="200" height="200" style="width: 100px; height: 100px;"></canvas>
Returns ​

Resolution

Methods ​

convertSpace() ​

convertSpace(point, options): Point

Defined in: Toodle.ts:347

Convert a point from one coordinate space to another.

Parameters ​

point ​

Point

The point to convert.

options ​

The options for the conversion.

from ​

"screen" | "world"

to ​

"screen" | "world"

Returns ​

Point

The converted point.

destroy() ​

destroy(): void

Defined in: Toodle.ts:727

Destroy the toodle instance and release its gpu and cpu resources.

Note that calling any methods on the instance after this result in undefined behavior.

Returns ​

void

draw() ​

draw(node): void

Defined in: Toodle.ts:276

call draw in between start frame and end frame to enqueue an instanced draw call.

Parameters ​

node ​

SceneNode

Returns ​

void

Example ​

ts
toodle.assets.loadTexture("myImage", "assets/image.png");
const quad = toodle.Quad("myImage");

toodle.startFrame();
toodle.draw(quad);
toodle.endFrame();

endFrame() ​

endFrame(): void

Defined in: Toodle.ts:294

call end frame to run through enqueued draw calls and submit them to the GPU.

Returns ​

void

Example ​

ts
toodle.startFrame();
// draw stuff
toodle.endFrame();

JumboQuad() ​

JumboQuad(assetId, options): JumboQuadNode

Defined in: Toodle.ts:460

Create a jumbo quad node. This contains multiple tiles for a single texture.

Parameters ​

assetId ​

string

The ID of the asset to use for the jumbo quad. This must have been loaded with toodle.assets.loadTextures.

options ​

JumboQuadOptions

QuadOptions for Quad creation

Returns ​

JumboQuadNode

Node() ​

Node(nodeOpts?): SceneNode

Defined in: Toodle.ts:522

Create a new container node.

Parameters ​

nodeOpts? ​

NodeOptions

Returns ​

SceneNode

Example ​

ts
const node = toodle.Node();
const child = node.add(toodle.Node());
node.position = [100, 100];
console.log(child.matrix);

Quad() ​

Quad(assetId, options): QuadNode

Defined in: Toodle.ts:430

Create a new quad node.

Parameters ​

assetId ​

string

The ID of the asset to use for the quad. This must have been loaded with toodle.assets.loadBundle.

options ​

QuadOptions = {}

QuadOptions for Quad creation

Returns ​

QuadNode

Example ​

ts
await toodle.assets.loadTextures({
  "myImage": new URL("assets/image.png"),
});
const quad = toodle.Quad("myImage");

toodle.startFrame();
toodle.draw(quad);
toodle.endFrame();

QuadShader() ​

QuadShader(label, instanceCount, userCode, shaderOpts?): IBackendShader

Defined in: Toodle.ts:397

Create a custom shader for quad instances. In some engines, this might be called a material.

Parameters ​

label ​

string

Debug name of the shader

instanceCount ​

number

The maximum number of instances that will be processed by the shader. Note that a worst-case buffer of this many instances will be immediately allocated.

userCode ​

string

The WGSL code to be used for the shader (WebGPU only).

shaderOpts? ​

QuadShaderOpts

Returns ​

IBackendShader

Example ​

ts

resize() ​

resize(resolution): void

Defined in: Toodle.ts:142

call resize when the canvas is resized. this will update the projection matrix and the resolution.

Parameters ​

resolution ​

Resolution

the resolution of the canvas in logical pixels. this should be canvas.clientWidth x canvas.clientHeight and NOT canvas.width * canvas.height

Returns ​

void

Example ​

ts
const canvas = document.querySelector("canvas")!

 const observer = new ResizeObserver((entries) => {
  if (entries.length === 0) return
  toodle.resize({ width: canvas.clientWidth, height: canvas.clientHeight })
 })

 observer.observe(canvas)

startFrame() ​

startFrame(options?): void

Defined in: Toodle.ts:255

call startFrame before drawing anything. this will create a new encoder and render pass.

Parameters ​

options? ​

StartFrameOptions

Returns ​

void

Example ​

ts
toodle.startFrame();
// draw stuff
toodle.endFrame();

Text() ​

Text(fontId, text, textOpts?): TextNode

Defined in: Toodle.ts:526

Parameters ​

fontId ​

string

text ​

string

textOpts? ​

TextOptions

Returns ​

TextNode

attach() ​

static attach(canvas, options?): Promise<Toodle>

Defined in: Toodle.ts:687

Attach toodle to a canvas.

Parameters ​

canvas ​

HTMLCanvasElement

The canvas to attach toodle to.

options? ​

ToodleOptions

ToodleOptions for the creation of the toodle instance

Returns ​

Promise<Toodle>

A promise that resolves to a Toodle instance.

Example ​

ts
const canvas = document.createElement("canvas");

  const toodle = await Toodle.attach(canvas);