Draw

LittleJS Drawing System

  • Hybrid system with both Canvas2D and WebGL available
  • Super fast tile sheet rendering with WebGL
  • Can apply rotation, mirror, color and additive color
  • Font rendering system with built in engine font
  • Many useful utility functions

LittleJS uses a hybrid rendering solution with the best of both Canvas2D and WebGL. There are 3 canvas/contexts available to draw to... mainCanvas - 2D background canvas, non WebGL stuff like tile layers are drawn here. glCanvas - Used by the accelerated WebGL batch rendering system. overlayCanvas - Another 2D canvas that appears on top of the other 2 canvases.

The WebGL rendering system is very fast with some caveats...

  • Switching blend modes (additive) or textures causes another draw call which is expensive in excess
  • Group additive rendering together using renderOrder to mitigate this issue

The LittleJS rendering solution is intentionally simple, feel free to adjust it for your needs!

Source

Classes

FontImage
TextureInfo
TileInfo

Members

(static) canvasClearColor :Color

Color to clear the canvas to before render

Type:
  • Color
Source

(static) drawCanvas :HTMLCanvasElement|OffscreenCanvas

The default canvas to use for drawing, usually mainCanvas

Type:
  • HTMLCanvasElement | OffscreenCanvas
Source

(static) drawContext :CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D

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

Type:
  • CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D
Source

(static) drawCount :number

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

Type:
  • number
Source

(static) mainCanvas :HTMLCanvasElement

The primary 2D canvas visible to the user

Type:
  • HTMLCanvasElement
Source

(static) mainCanvasSize :Vector2

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

Type:
  • Vector2
Source

(static) mainContext :CanvasRenderingContext2D

2d context for mainCanvas

Type:
  • CanvasRenderingContext2D
Source

(static) overlayCanvas :HTMLCanvasElement

A canvas that appears on top of everything the same size as mainCanvas

Type:
  • HTMLCanvasElement
Source

(static) overlayContext :CanvasRenderingContext2D

2d context for overlayCanvas

Type:
  • CanvasRenderingContext2D
Source

(static) textureInfos :Array.<TextureInfo>

Array containing texture info for batch rendering system

Type:
  • Array.<TextureInfo>
Source

(static) workCanvas :OffscreenCanvas

Offscreen canvas that can be used for image processing

Type:
  • OffscreenCanvas
Source

(static) workContext :OffscreenCanvasRenderingContext2D

Offscreen canvas that can be used for image processing

Type:
  • OffscreenCanvasRenderingContext2D
Source

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:
NameTypeAttributesDescription
posVector2

Center in world space

sizeVector2<optional>

Size in world space

colorColor<optional>

Color to modulate with

anglenumber<optional>

Angle to rotate by

mirrorboolean<optional>

If true image is flipped along the Y axis

additiveColorColor<optional>

Additive color to be applied if any

screenSpaceboolean<optional>

If true the pos and size are in screen space

contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>

Canvas 2D context to draw to

Source

(static) combineCanvases()

Combines all LittleJS canvases onto the main canvas and clears them This is necessary for things like saving a screenshot

Source

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

Draw directly to a 2d canvas context in world space

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

(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>
(1,1,1,1)
lineWidthnumber<optional>
0
lineColorColor<optional>
(0,0,0,1)
useWebGLboolean<optional>
glEnable
screenSpaceboolean<optional>
false
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>
Source

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

Draw colored ellipse using passed in point

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

Width and height diameter

colorColor<optional>
(1,1,1,1)
anglenumber<optional>
0
lineWidthnumber<optional>
0
lineColorColor<optional>
(0,0,0,1)
useWebGLboolean<optional>
glEnable
screenSpaceboolean<optional>
false
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>
Source

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

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>
bleedScalenumber<optional>
0

How much to shrink the source, used to fix bleeding

Source

(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>
(1,1,1,1)
posVector2<optional>
(0,0)

Offset to apply

anglenumber<optional>
0

Angle to rotate by

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

(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>
(1,1,1,1)
wrapboolean<optional>
false

Should the last point connect to the first?

posVector2<optional>
(0,0)

Offset to apply

anglenumber<optional>
0

Angle to rotate by

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

(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>
(1,1,1,1)
lineWidthnumber<optional>
0
lineColorColor<optional>
(0,0,0,1)
posVector2<optional>
(0,0)

Offset to apply

anglenumber<optional>
0

Angle to rotate by

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

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

Draw colored rect centered on pos

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

(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>
(1,1)
colorTopColor<optional>
(1,1,1,1)
colorBottomColor<optional>
(0,0,0,1)
anglenumber<optional>
0
useWebGLboolean<optional>
glEnable
screenSpaceboolean<optional>
false
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>
Source

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

Draw colored regular polygon using passed in number of sides

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

(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>
(1,1,1,1)
lineWidthnumber<optional>
0
lineColorColor<optional>
(0,0,0,1)
textAlignCanvasTextAlign<optional>
'center'
fontstring<optional>
fontDefault
fontStylestring<optional>
maxWidthnumber<optional>
anglenumber<optional>
0
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>
drawContext
Source

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

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

Parameters:
NameTypeAttributesDefaultDescription
textstring | number
posVector2
sizenumber<optional>
1
colorColor<optional>
(1,1,1,1)
lineWidthnumber<optional>
0
lineColorColor<optional>
(0,0,0,1)
textAlignCanvasTextAlign<optional>
'center'
fontstring<optional>
fontDefault
fontStylestring<optional>
maxWidthnumber<optional>
anglenumber<optional>
0
Source

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

Draw text on overlay canvas in screen space Automatically splits new lines into rows

Parameters:
NameTypeAttributesDefaultDescription
textstring | number
posVector2
sizenumber<optional>
1
colorColor<optional>
(1,1,1,1)
lineWidthnumber<optional>
0
lineColorColor<optional>
(0,0,0,1)
textAlignCanvasTextAlign<optional>
center
fontstring<optional>
fontDefault
fontStylestring<optional>
maxWidthnumber<optional>
anglenumber<optional>
0
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>
overlayContext
Source

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

Draw textured tile centered in world space, with color applied if using WebGL

Parameters:
NameTypeAttributesDefaultDescription
posVector2

Center of the tile in world space

sizeVector2<optional>
(1,1)

Size of the tile in world space

tileInfoTileInfo<optional>

Tile info to use, untextured if undefined

colorColor<optional>
(1,1,1,1)

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

Source

(static) getCameraSize() → {Vector2}

Get the size of the camera window in world space

Source
Returns:
Type: 
Vector2

(static) isFullscreen() → {boolean}

Returns true if fullscreen mode is active

Source
Returns:
Type: 
boolean

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

Check if a point or circle is on screen If size is a Vector2, uses the largest dimension 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

Source
Returns:
Type: 
boolean

(static) screenToWorld(screenPos) → {Vector2}

Convert from screen to world space coordinates

Parameters:
NameTypeDescription
screenPosVector2
Source
Returns:
Type: 
Vector2

(static) screenToWorldDelta(screenDelta) → {Vector2}

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

Parameters:
NameTypeDescription
screenDeltaVector2
Source
Returns:
Type: 
Vector2

(static) screenToWorldTransform(screenPos, screenSize, screenAngleopt)

Convert screen space transform to world space

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

(static) setBlendMode(additiveopt, contextopt)

Enable normal or additive blend mode

Parameters:
NameTypeAttributesDefaultDescription
additiveboolean<optional>
false
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D<optional>
Source

(static) setCursor(cursorStyleopt)

Set the cursor style

Parameters:
NameTypeAttributesDefaultDescription
cursorStylestring<optional>
auto

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

Source

(static) tile(posopt, sizeopt, textureIndexopt, paddingopt) → {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
posVector2 | number<optional>
0

Position of the tile in pixels, or tile index

sizeVector2 | number<optional>
tileSizeDefault

Size of tile in pixels

textureIndexnumber<optional>
0

Texture index to use

paddingnumber<optional>
0

How many pixels padding around tiles

Source
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

Source

(static) worldToScreen(worldPos) → {Vector2}

Convert from world to screen space coordinates

Parameters:
NameTypeDescription
worldPosVector2
Source
Returns:
Type: 
Vector2

(static) worldToScreenDelta(worldDelta) → {Vector2}

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

Parameters:
NameTypeDescription
worldDeltaVector2
Source
Returns:
Type: 
Vector2

(static) worldToScreenTransform(worldPos, worldSize, worldAngleopt)

Convert world space transform to screen space

Parameters:
NameTypeAttributesDefaultDescription
worldPosVector2
worldSizeVector2
worldAnglenumber<optional>
0
Source
Returns:

Type Definitions

Canvas2DDrawFunction(context)

Parameters:
NameTypeDescription
contextCanvasRenderingContext2D | OffscreenCanvasRenderingContext2D
Source

LineTestFunction(pos)

Parameters:
NameTypeDescription
posVector2
Source