Draw

LittleJS Drawing System

  • Hybrid rendering with both Canvas2D and WebGL support
  • Optimized tile sheet sprite rendering using WebGL batching
  • Primitive drawing for polygons, ellipses, and lines
  • Tile-based rendering with TileInfo and TextureInfo classes
  • Text rendering with custom fonts and ImageFont support
  • Color and additive color blending for effects
  • Rotation, mirroring, and scaling transformations
  • Camera system with position, scale, and rotation
  • Multiple canvas support (main, WebGL, work canvases)
  • Gradient fills and outlined shapes
  • Image manipulation and color tinting

Rendering Architecture:

  • glCanvas: WebGL canvas for accelerated sprite batch rendering
  • mainCanvas: Canvas2D overlay for text, UI, and custom drawing
  • All draw functions default to WebGL when enabled, can force Canvas2D with useWebGL parameter

Classes

ImageFont
TextureInfo
TileInfo

Members

(static) drawContext :CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D

The default 2d context to use for drawing, usually mainContext

Type:
  • CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D

(static) drawCount :number

Keeps track of how many draw calls there were each frame for debugging

Type:
  • number

(static) drawEllipseGradientOffset

Draw an ellipse filled with a radial gradient from the center to the rim

  • Best when batched with other untextured polys
  • If drawing mostly textured sprites, bake the gradient into a texture and use drawTile instead
  • Stacking gradients at the exact same position may show a faint vertical artifact

(static) engineImageFont :ImageFont

Engine font image, 8x8 font provided by the engine

Type:
  • ImageFont

(static) mainCanvas :HTMLCanvasElement

The primary 2D canvas visible to the user

Type:
  • HTMLCanvasElement

(static) mainCanvasSize :Vector2

The size of the main canvas (and other secondary canvases)

Type:
  • Vector2

(static) mainContext :CanvasRenderingContext2D

2d context for mainCanvas

Type:
  • CanvasRenderingContext2D

(static) primitiveCount :number

Keeps track of how many primitives were drawn each frame for debugging A single draw call can render many primitives (e.g. a WebGL sprite batch).

Type:
  • number

(static) textureInfos :Array.<TextureInfo>

Array containing texture info for batch rendering system

Type:
  • Array.<TextureInfo>

(static) workCanvas :OffscreenCanvas

Offscreen canvas that can be used for image processing

Type:
  • OffscreenCanvas

(static) workContext :OffscreenCanvasRenderingContext2D

Offscreen canvas that can be used for image processing

Type:
  • OffscreenCanvasRenderingContext2D

(static) workReadCanvas :OffscreenCanvas

Offscreen canvas with willReadFrequently that can be used for image processing

Type:
  • OffscreenCanvas

(static) workReadContext :OffscreenCanvasRenderingContext2D

Offscreen canvas with willReadFrequently that can be used for image processing

Type:
  • OffscreenCanvasRenderingContext2D

Methods

(static) CanvasLayer#draw(pos, sizeopt, coloropt, angleopt, mirroropt, additiveColoropt, screenSpaceopt, contextopt)

Draw this canvas layer centered in world space, with color applied if using WebGL

Parameters:
NameTypeAttributesDefaultDescription
posVector2

Center in world space

sizeVector2<optional>

Size in world space

colorColor<optional>

Color to modulate with

anglenumber<optional>
0

Angle to rotate by

mirrorboolean<optional>
false

If true image is flipped along the Y axis

additiveColorColor<optional>

Additive color to be applied if any

screenSpaceboolean<optional>
false

If true the pos and size are in screen space

contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>

Canvas 2D context to draw to

(static) cameraFit(center, size, worldMarginopt, screenInsetopt) → {number}

Fit the camera to a rectangle in world space by setting cameraPos and cameraScale

  • worldMargin pads the content rectangle in world units, so the gap scales with the content on resize
  • screenInset reserves space in screen pixels on each viewport edge (for example a HUD band) and re-centers the content away from that edge, so the reserved band stays a fixed pixel size on resize
  • worldMargin and screenInset may each be a number for all sides, a Vector2 (x=left/right, y=top/bottom), or an object with any of {top, right, bottom, left}
Parameters:
NameTypeAttributesDescription
centerVector2

Center of the rectangle in world space

sizeVector2

Size of the rectangle in world space

worldMarginnumber | Vector2 | Object<optional>

World space padding added around the content rectangle

screenInsetnumber | Vector2 | Object<optional>

Screen space padding in pixels reserved on each viewport edge

Returns:
  • The new camera scale
Type: 
number

(static) combineCanvases()

Combines LittleJS canvases onto the main canvas This is necessary for things like screenshots and video

(static) drawCanvas2D(pos, size, angle, mirroropt, drawFunctionopt, screenSpaceopt, contextopt)

Draw directly to a 2d canvas context in world space. The Y axis is flipped so world-Y-up coordinates render right-side up (matches the WebGL path). Callers whose drawing depends on Y direction (e.g. linear gradients) should flip their own Y endpoints accordingly.

Parameters:
NameTypeAttributesDefaultDescription
posVector2
sizeVector2
anglenumber0
mirrorboolean<optional>
false
drawFunctionCanvas2DDrawFunction<optional>
screenSpaceboolean<optional>
false
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>
drawContext

(static) drawCircle(pos, sizeopt, coloropt, lineWidthopt, lineColoropt, useWebGLopt, screenSpaceopt, contextopt)

Draw colored circle using passed in point

Parameters:
NameTypeAttributesDefaultDescription
posVector2
sizenumber<optional>
1

Diameter

colorColor<optional>
WHITE
lineWidthnumber<optional>
0
lineColorColor<optional>
BLACK
useWebGLboolean<optional>
glEnable
screenSpaceboolean<optional>
false
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>

(static) drawCircleGradient(pos, sizeopt, colorInneropt, colorOuteropt, useWebGLopt, screenSpaceopt, contextopt)

Draw a circle filled with a radial gradient from the center to the rim

  • Best when batched with other untextured polys
  • If drawing mostly textured sprites, bake the gradient into a texture and use drawTile instead
  • Stacking gradients at the exact same position may show a faint vertical artifact
Parameters:
NameTypeAttributesDefaultDescription
posVector2
sizenumber<optional>
1

Diameter

colorInnerColor<optional>
WHITE
colorOuterColor<optional>
CLEAR_WHITE
useWebGLboolean<optional>
glEnable
screenSpaceboolean<optional>
false
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>

(static) drawEllipse(pos, sizeopt, coloropt, angleopt, lineWidthopt, lineColoropt, useWebGLopt, screenSpaceopt, contextopt)

Draw colored ellipse using passed in point

Parameters:
NameTypeAttributesDefaultDescription
posVector2
sizeVector2<optional>
vec2(1)

Width and height diameter

colorColor<optional>
WHITE
anglenumber<optional>
0
lineWidthnumber<optional>
0
lineColorColor<optional>
BLACK
useWebGLboolean<optional>
glEnable
screenSpaceboolean<optional>
false
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>

(static) drawImageColor(context, image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight, color, additiveColoropt, bleedopt)

Helper function to draw an image with color and additive color applied This is slower then normal drawImage when color is applied

Parameters:
NameTypeAttributesDefaultDescription
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D
imageHTMLImageElement | OffscreenCanvas
sxnumber
synumber
sWidthnumber
sHeightnumber
dxnumber
dynumber
dWidthnumber
dHeightnumber
colorColor
additiveColorColor<optional>
bleednumber<optional>
0

How many pixels to shrink the source, used to fix bleeding

(static) drawLine(posA, posB, widthopt, coloropt, posopt, angleopt, useWebGLopt, screenSpaceopt, contextopt)

Draw colored line between two points

Parameters:
NameTypeAttributesDefaultDescription
posAVector2
posBVector2
widthnumber<optional>
0.1
colorColor<optional>
WHITE
posVector2<optional>
vec2()

Offset to apply

anglenumber<optional>
0

Angle to rotate by

useWebGLboolean<optional>
glEnable
screenSpaceboolean<optional>
false
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>

(static) drawLineList(points, widthopt, coloropt, wrapopt, posopt, angleopt, useWebGLopt, screenSpaceopt, contextopt)

Draw connected lines between a series of points

Parameters:
NameTypeAttributesDefaultDescription
pointsArray.<Vector2>
widthnumber<optional>
0.1
colorColor<optional>
WHITE
wrapboolean<optional>
false

Should the last point connect to the first?

posVector2<optional>
vec2()

Offset to apply

anglenumber<optional>
0

Angle to rotate by

useWebGLboolean<optional>
glEnable
screenSpaceboolean<optional>
false
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>

(static) drawPoly(points, coloropt, lineWidthopt, lineColoropt, posopt, angleopt, useWebGLopt, screenSpaceopt, contextopt)

Draw colored polygon using passed in points

Parameters:
NameTypeAttributesDefaultDescription
pointsArray.<Vector2>

Array of Vector2 points

colorColor<optional>
WHITE
lineWidthnumber<optional>
0
lineColorColor<optional>
BLACK
posVector2<optional>
vec2()

Offset to apply

anglenumber<optional>
0

Angle to rotate by

useWebGLboolean<optional>
glEnable
screenSpaceboolean<optional>
false
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>

(static) drawRect(pos, sizeopt, coloropt, angleopt, useWebGLopt, screenSpaceopt, contextopt)

Draw colored rect centered on pos

Parameters:
NameTypeAttributesDefaultDescription
posVector2
sizeVector2<optional>
vec2(1)
colorColor<optional>
WHITE
anglenumber<optional>
useWebGLboolean<optional>
glEnable
screenSpaceboolean<optional>
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>

(static) drawRectGradient(pos, sizeopt, colorTopopt, colorBottomopt, angleopt, useWebGLopt, screenSpaceopt, contextopt)

Draw a rect centered on pos with a gradient from top to bottom

Parameters:
NameTypeAttributesDefaultDescription
posVector2
sizeVector2<optional>
vec2(1)
colorTopColor<optional>
WHITE
colorBottomColor<optional>
CLEAR_WHITE
anglenumber<optional>
0
useWebGLboolean<optional>
glEnable
screenSpaceboolean<optional>
false
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>

(static) drawRegularPoly(pos, sizeopt, sidesopt, coloropt, lineWidthopt, lineColoropt, angleopt, useWebGLopt, screenSpaceopt, contextopt)

Draw colored regular polygon using passed in number of sides

Parameters:
NameTypeAttributesDefaultDescription
posVector2
sizeVector2<optional>
vec2(1)
sidesnumber<optional>
3
colorColor<optional>
WHITE
lineWidthnumber<optional>
0
lineColorColor<optional>
BLACK
anglenumber<optional>
0
useWebGLboolean<optional>
glEnable
screenSpaceboolean<optional>
false
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>

(static) drawText(text, pos, sizeopt, coloropt, lineWidthopt, lineColoropt, textAlignopt, fontopt, fontStyleopt, maxWidthopt, angleopt, contextopt)

Draw text on main canvas in world space Automatically splits new lines into rows

Parameters:
NameTypeAttributesDefaultDescription
textstring | number
posVector2
sizenumber<optional>
1
colorColor<optional>
WHITE
lineWidthnumber<optional>
0
lineColorColor<optional>
BLACK
textAlignCanvasTextAlign<optional>
'center'
fontstring<optional>
fontDefault
fontStylestring<optional>
maxWidthnumber<optional>
anglenumber<optional>
0
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>
drawContext

(static) drawTextScreen(text, pos, size, coloropt, lineWidthopt, lineColoropt, textAlignopt, fontopt, fontStyleopt, maxWidthopt, angleopt, contextopt)

Draw text in screen space Automatically splits new lines into rows

Parameters:
NameTypeAttributesDefaultDescription
textstring | number
posVector2
sizenumber
colorColor<optional>
WHITE
lineWidthnumber<optional>
0
lineColorColor<optional>
BLACK
textAlignCanvasTextAlign<optional>
center
fontstring<optional>
fontDefault
fontStylestring<optional>
maxWidthnumber<optional>
anglenumber<optional>
0
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>
drawContext

(static) drawTextureWrapped(pos, size, wrapCount, textureopt, coloropt, angleopt, additiveColoropt, useWebGLopt, screenSpaceopt, contextopt)

Draw a texture tiled (wrapped) across a rectangle in world space. Useful for backgrounds, repeating patterns, and seamless fills. The whole texture is tiled — sub-region (TileInfo) wrapping is not supported.

Parameters:
NameTypeAttributesDefaultDescription
posVector2

Center of the rect in world space

sizeVector2

Size of the rect in world space

wrapCountVector2

How many times the texture repeats (x, y)

textureTextureInfo | number<optional>
0

TextureInfo or texture index into textureInfos

colorColor<optional>
WHITE

Color to modulate with

anglenumber<optional>
0

Angle to rotate by

additiveColorColor<optional>

Additive color to be applied if any

useWebGLboolean<optional>
glEnable

Use accelerated WebGL rendering?

screenSpaceboolean<optional>
false

Are pos and size in screen space?

contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>

Canvas 2D context to draw to

(static) drawTile(pos, sizeopt, tileInfoopt, coloropt, angleopt, mirroropt, additiveColoropt, useWebGLopt, screenSpaceopt, contextopt)

Draw textured tile centered in world space

Parameters:
NameTypeAttributesDefaultDescription
posVector2

Center of the tile in world space

sizeVector2<optional>
vec2(1)

Size of the tile in world space

tileInfoTileInfo<optional>

Tile info to use, untextured if undefined

colorColor<optional>
WHITE

Color to modulate with

anglenumber<optional>
0

Angle to rotate by

mirrorboolean<optional>

Is image flipped along the Y axis?

additiveColorColor<optional>

Additive color to be applied if any

useWebGLboolean<optional>
glEnable

Use accelerated WebGL rendering?

screenSpaceboolean<optional>
false

Are the pos and size are in screen space?

contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>

Canvas 2D context to draw to

(static) getCameraSize() → {Vector2}

Get the size of the camera window in world space

Returns:
Type: 
Vector2

(static) isFullscreen() → {boolean}

Returns true if fullscreen mode is active

Returns:
Type: 
boolean

(static) isOnScreen(pos, size) → {boolean}

Check if a box, point, or circle is on screen with a circle test If size is a Vector2, uses the length as diameter This can be used to cull offscreen objects from render or update

Parameters:
NameTypeDefaultDescription
posVector2

world space position

sizeVector2 | number0

world space size or diameter

Returns:
Type: 
boolean

(async, static) loadTexture(textureIndex, srcopt) → {Promise}

Load a texture at a specific index

Parameters:
NameTypeAttributesDescription
textureIndexnumber

Index to store the texture at

srcstring<optional>

Image source path

Returns:

Promise that resolves when texture is loaded

Type: 
Promise

(static) screenToWorld(screenPos) → {Vector2}

Convert from screen to world space coordinates

Parameters:
NameTypeDescription
screenPosVector2
Returns:
Type: 
Vector2

(static) screenToWorldDelta(screenDelta) → {Vector2}

Convert from screen to world space coordinates for a directional vector (no translation)

Parameters:
NameTypeDescription
screenDeltaVector2
Returns:
Type: 
Vector2

(static) screenToWorldTransform(screenPos, screenSize, screenAngleopt)

Convert screen space transform to world space

Parameters:
NameTypeAttributesDefaultDescription
screenPosVector2
screenSizeVector2
screenAnglenumber<optional>
0
Returns:

(static) setAdditiveBlendMode(additiveopt)

Enable additive blending

Parameters:
NameTypeAttributesDefaultDescription
additiveboolean<optional>
true

(static) setCursor(cursorStyleopt)

Set the cursor style

Parameters:
NameTypeAttributesDefaultDescription
cursorStylestring<optional>
auto

CSS cursor style (auto, none, crosshair, etc)

(static) tile(indexopt, sizeopt, textureopt, paddingopt, bleedopt) → {TileInfo}

Create a tile info object using a grid based system

  • This can take vecs or floats for easier use and conversion
  • If an index is passed in, the tile size and index will determine the position
Parameters:
NameTypeAttributesDefaultDescription
indexVector2 | number<optional>
0

Index of the tile in 1d or 2d form

sizeVector2 | number<optional>

Size of tile in pixels

textureTextureInfo | number<optional>
0

Texture index or info to use

paddingnumber<optional>

How many pixels padding around tiles

bleednumber<optional>

How many pixels smaller to draw tiles

Returns:
Type: 
TileInfo
Example
tile(2)                       // a tile at index 2 using the default tile size of 16
tile(5, 8)                    // a tile at index 5 using a tile size of 8
tile(1, 16, 3)                // a tile at index 1 of size 16 on texture 3
tile(vec2(4,8), vec2(30,10))  // a tile at index (4,8) with a size of (30,10)

(static) toggleFullscreen()

Toggle fullscreen mode

(static) worldToScreen(worldPos) → {Vector2}

Convert from world to screen space coordinates

Parameters:
NameTypeDescription
worldPosVector2
Returns:
Type: 
Vector2

(static) worldToScreenDelta(worldDelta) → {Vector2}

Convert from screen to world space coordinates for a directional vector (no translation)

Parameters:
NameTypeDescription
worldDeltaVector2
Returns:
Type: 
Vector2

Type Definitions

Canvas2DDrawFunction(context)

Parameters:
NameTypeDescription
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D

LineTestFunction(pos)

Parameters:
NameTypeDescription
posVector2