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
Members
(static) canvasClearColor :Color
Color to clear the canvas to before render
- Color
- Source
(static) drawCanvas :HTMLCanvasElement|OffscreenCanvas
The default canvas to use for drawing, usually mainCanvas
- HTMLCanvasElement |
OffscreenCanvas
- Source
(static) drawContext :CanvasRenderingContext2D|OffscreenCanvasRenderingContext2D
The default 2d context to use for drawing, usually mainContext
- CanvasRenderingContext2D |
OffscreenCanvasRenderingContext2D
- Source
(static) drawCount :number
Keeps track of how many draw calls there were each frame for debugging
- number
- Source
(static) mainCanvas :HTMLCanvasElement
The primary 2D canvas visible to the user
- HTMLCanvasElement
- Source
(static) mainCanvasSize :Vector2
The size of the main canvas (and other secondary canvases)
- Vector2
- Source
(static) mainContext :CanvasRenderingContext2D
2d context for mainCanvas
- CanvasRenderingContext2D
- Source
(static) overlayCanvas :HTMLCanvasElement
A canvas that appears on top of everything the same size as mainCanvas
- HTMLCanvasElement
- Source
(static) overlayContext :CanvasRenderingContext2D
2d context for overlayCanvas
- CanvasRenderingContext2D
- Source
(static) textureInfos :Array.<TextureInfo>
Array containing texture info for batch rendering system
- Array.<TextureInfo>
- Source
(static) workCanvas :OffscreenCanvas
Offscreen canvas that can be used for image processing
- OffscreenCanvas
- Source
(static) workContext :OffscreenCanvasRenderingContext2D
Offscreen canvas that can be used for image processing
- 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
| Name | Type | Attributes | Description |
|---|---|---|---|
pos | Vector2 | Center in world space | |
size | Vector2 | <optional> | Size in world space |
color | Color | <optional> | Color to modulate with |
angle | number | <optional> | Angle to rotate by |
mirror | boolean | <optional> | If true image is flipped along the Y axis |
additiveColor | Color | <optional> | Additive color to be applied if any |
screenSpace | boolean | <optional> | If true the pos and size are in screen space |
context | CanvasRenderingContext2D | | <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
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
pos | Vector2 | |||
size | Vector2 | |||
angle | number | 0 | ||
mirror | boolean | <optional> | false | |
drawFunction | Canvas2DDrawFunction | <optional> | ||
screenSpace | boolean | <optional> | false | |
context | CanvasRenderingContext2D | | <optional> | drawContext |
- Source
(static) drawCircle(pos, sizeopt, coloropt, lineWidthopt, lineColoropt, useWebGLopt, screenSpaceopt, contextopt)
Draw colored circle using passed in point
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
pos | Vector2 | |||
size | number | <optional> | 1 | Diameter |
color | Color | <optional> | (1,1,1,1) | |
lineWidth | number | <optional> | 0 | |
lineColor | Color | <optional> | (0,0,0,1) | |
useWebGL | boolean | <optional> | glEnable | |
screenSpace | boolean | <optional> | false | |
context | CanvasRenderingContext2D | | <optional> |
- Source
(static) drawEllipse(pos, sizeopt, coloropt, angleopt, lineWidthopt, lineColoropt, useWebGLopt, screenSpaceopt, contextopt)
Draw colored ellipse using passed in point
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
pos | Vector2 | |||
size | Vector2 | <optional> | (1,1) | Width and height diameter |
color | Color | <optional> | (1,1,1,1) | |
angle | number | <optional> | 0 | |
lineWidth | number | <optional> | 0 | |
lineColor | Color | <optional> | (0,0,0,1) | |
useWebGL | boolean | <optional> | glEnable | |
screenSpace | boolean | <optional> | false | |
context | CanvasRenderingContext2D | | <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
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
context | CanvasRenderingContext2D | | |||
image | HTMLImageElement | | |||
sx | number | |||
sy | number | |||
sWidth | number | |||
sHeight | number | |||
dx | number | |||
dy | number | |||
dWidth | number | |||
dHeight | number | |||
color | Color | |||
additiveColor | Color | <optional> | ||
bleedScale | number | <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
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
posA | Vector2 | |||
posB | Vector2 | |||
width | number | <optional> | 0.1 | |
color | Color | <optional> | (1,1,1,1) | |
pos | Vector2 | <optional> | (0,0) | Offset to apply |
angle | number | <optional> | 0 | Angle to rotate by |
useWebGL | boolean | <optional> | glEnable | |
screenSpace | boolean | <optional> | ||
context | CanvasRenderingContext2D | | <optional> |
- Source
(static) drawLineList(points, widthopt, coloropt, wrapopt, posopt, angleopt, useWebGLopt, screenSpaceopt, contextopt)
Draw connected lines between a series of points
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
points | Array.<Vector2> | |||
width | number | <optional> | 0.1 | |
color | Color | <optional> | (1,1,1,1) | |
wrap | boolean | <optional> | false | Should the last point connect to the first? |
pos | Vector2 | <optional> | (0,0) | Offset to apply |
angle | number | <optional> | 0 | Angle to rotate by |
useWebGL | boolean | <optional> | glEnable | |
screenSpace | boolean | <optional> | ||
context | CanvasRenderingContext2D | | <optional> |
- Source
(static) drawPoly(points, coloropt, lineWidthopt, lineColoropt, posopt, angleopt, useWebGLopt, screenSpaceopt, contextopt)
Draw colored polygon using passed in points
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
points | Array.<Vector2> | Array of Vector2 points | ||
color | Color | <optional> | (1,1,1,1) | |
lineWidth | number | <optional> | 0 | |
lineColor | Color | <optional> | (0,0,0,1) | |
pos | Vector2 | <optional> | (0,0) | Offset to apply |
angle | number | <optional> | 0 | Angle to rotate by |
useWebGL | boolean | <optional> | glEnable | |
screenSpace | boolean | <optional> | false | |
context | CanvasRenderingContext2D | | <optional> |
- Source
(static) drawRect(pos, sizeopt, coloropt, angleopt, useWebGLopt, screenSpaceopt, contextopt)
Draw colored rect centered on pos
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
pos | Vector2 | |||
size | Vector2 | <optional> | (1,1) | |
color | Color | <optional> | (1,1,1,1) | |
angle | number | <optional> | ||
useWebGL | boolean | <optional> | glEnable | |
screenSpace | boolean | <optional> | ||
context | CanvasRenderingContext2D | | <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
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
pos | Vector2 | |||
size | Vector2 | <optional> | (1,1) | |
colorTop | Color | <optional> | (1,1,1,1) | |
colorBottom | Color | <optional> | (0,0,0,1) | |
angle | number | <optional> | 0 | |
useWebGL | boolean | <optional> | glEnable | |
screenSpace | boolean | <optional> | false | |
context | CanvasRenderingContext2D | | <optional> |
- Source
(static) drawRegularPoly(pos, sizeopt, sidesopt, coloropt, angleopt, lineWidthopt, lineColoropt, useWebGLopt, screenSpaceopt, contextopt)
Draw colored regular polygon using passed in number of sides
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
pos | Vector2 | |||
size | Vector2 | <optional> | (1,1) | |
sides | number | <optional> | 3 | |
color | Color | <optional> | (1,1,1,1) | |
angle | number | <optional> | 0 | |
lineWidth | number | <optional> | ||
lineColor | Color | <optional> | (0,0,0,1) | |
useWebGL | boolean | <optional> | glEnable | |
screenSpace | boolean | <optional> | ||
context | CanvasRenderingContext2D | | <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
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
text | string | | |||
pos | Vector2 | |||
size | number | <optional> | 1 | |
color | Color | <optional> | (1,1,1,1) | |
lineWidth | number | <optional> | 0 | |
lineColor | Color | <optional> | (0,0,0,1) | |
textAlign | CanvasTextAlign | <optional> | 'center' | |
font | string | <optional> | fontDefault | |
fontStyle | string | <optional> | ||
maxWidth | number | <optional> | ||
angle | number | <optional> | 0 | |
context | CanvasRenderingContext2D | | <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
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
text | string | | |||
pos | Vector2 | |||
size | number | <optional> | 1 | |
color | Color | <optional> | (1,1,1,1) | |
lineWidth | number | <optional> | 0 | |
lineColor | Color | <optional> | (0,0,0,1) | |
textAlign | CanvasTextAlign | <optional> | 'center' | |
font | string | <optional> | fontDefault | |
fontStyle | string | <optional> | ||
maxWidth | number | <optional> | ||
angle | number | <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
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
text | string | | |||
pos | Vector2 | |||
size | number | <optional> | 1 | |
color | Color | <optional> | (1,1,1,1) | |
lineWidth | number | <optional> | 0 | |
lineColor | Color | <optional> | (0,0,0,1) | |
textAlign | CanvasTextAlign | <optional> | center | |
font | string | <optional> | fontDefault | |
fontStyle | string | <optional> | ||
maxWidth | number | <optional> | ||
angle | number | <optional> | 0 | |
context | CanvasRenderingContext2D | | <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
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
pos | Vector2 | Center of the tile in world space | ||
size | Vector2 | <optional> | (1,1) | Size of the tile in world space |
tileInfo | TileInfo | <optional> | Tile info to use, untextured if undefined | |
color | Color | <optional> | (1,1,1,1) | Color to modulate with |
angle | number | <optional> | 0 | Angle to rotate by |
mirror | boolean | <optional> | Is image flipped along the Y axis? | |
additiveColor | Color | <optional> | Additive color to be applied if any | |
useWebGL | boolean | <optional> | glEnable | Use accelerated WebGL rendering? |
screenSpace | boolean | <optional> | false | Are the pos and size are in screen space? |
context | CanvasRenderingContext2D | | <optional> | Canvas 2D context to draw to |
- Source
(static) getCameraSize() → {Vector2}
Get the size of the camera window in world space
- Source
- Type:
- Vector2
(static) isFullscreen() → {boolean}
Returns true if fullscreen mode is active
- Source
- 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
| Name | Type | Default | Description |
|---|---|---|---|
pos | Vector2 | world space position | |
size | Vector2 | | 0 | world space size or diameter |
- Source
- Type:
- boolean
(static) screenToWorld(screenPos) → {Vector2}
Convert from screen to world space coordinates
| Name | Type | Description |
|---|---|---|
screenPos | Vector2 |
- Source
- Type:
- Vector2
(static) screenToWorldDelta(screenDelta) → {Vector2}
Convert from screen to world space coordinates for a directional vector (no translation)
| Name | Type | Description |
|---|---|---|
screenDelta | Vector2 |
- Source
- Type:
- Vector2
(static) screenToWorldTransform(screenPos, screenSize, screenAngleopt)
Convert screen space transform to world space
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
screenPos | Vector2 | |||
screenSize | Vector2 | |||
screenAngle | number | <optional> | 0 |
- Source
(static) setBlendMode(additiveopt, contextopt)
Enable normal or additive blend mode
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
additive | boolean | <optional> | false | |
context | CanvasRenderingContext2D | | <optional> |
- Source
(static) setCursor(cursorStyleopt)
Set the cursor style
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
cursorStyle | string | <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
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
pos | Vector2 | | <optional> | 0 | Position of the tile in pixels, or tile index |
size | Vector2 | | <optional> | tileSizeDefault | Size of tile in pixels |
textureIndex | number | <optional> | 0 | Texture index to use |
padding | number | <optional> | 0 | How many pixels padding around tiles |
- Source
- Type:
- TileInfo
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
| Name | Type | Description |
|---|---|---|
worldPos | Vector2 |
- Source
- Type:
- Vector2
(static) worldToScreenDelta(worldDelta) → {Vector2}
Convert from screen to world space coordinates for a directional vector (no translation)
| Name | Type | Description |
|---|---|---|
worldDelta | Vector2 |
- Source
- Type:
- Vector2
(static) worldToScreenTransform(worldPos, worldSize, worldAngleopt)
Convert world space transform to screen space
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
worldPos | Vector2 | |||
worldSize | Vector2 | |||
worldAngle | number | <optional> | 0 |
- Source
Type Definitions
Canvas2DDrawFunction(context)
| Name | Type | Description |
|---|---|---|
context | CanvasRenderingContext2D | |
- Source
LineTestFunction(pos)
| Name | Type | Description |
|---|---|---|
pos | Vector2 |
- Source