myr.js is a WebGL 2 based 2D graphics renderer. The engine is optimized for rendering large amounts of sprites, and it also supports render targets, primitives, shaders and advanced transformations. There are no external dependencies. myr.js has been licensed under the MIT license. All source code is contained in the myr.js file.
The myr.js file can be included in any ES6 compatible javascript project. No external dependencies are required.
Alternatively, myr.js can be installed as an NPM package using npm install myr.js
.
myr.js can be initialized by calling the Myr
function, which requires a canvas element as an argument. All global functions and objects are members of the returned object. I call this object a myr.js context. The provided canvas must support WebGL 2.
Initialization would typically look like this:
// Create a myr.js context
let myr = new Myr(document.getElementById("some-canvas-id"));
// Access myr.js functions and classes from here on
myr.setClearColor(new Myr.Color(0.2, 0.5, 0.7));
Two types of myr.js objects exist. There are objects that are exposed through a myr.js context. These objects can only be used for that context. They can be initialized as follows:
// Create a Myriad context
let myr = new Myr(document.getElementById("some-canvas-id"));
// Create a surface to be used in the previously created context
let surface = new myr.Surface(800, 600);
The other type of objects can be accessed directly through the Myr
object, and can be shared by multiple contexts. The example below shows using the Color
object which is not linked to a specific context:
// Create a Myriad context
let myr = new Myr(document.getElementById("some-canvas-id"));
// Create a color object
let color = new Myr.Color(0.3, 0.5, 0.7);
// Set the created color object as the clear color for the context
myr.setClearColor(color);
The following objects are exposed by a myr.js context.
Object | Description |
---|---|
Surface |
A render target which can be rendered to, which may be initialized to an existing image |
Sprite |
A renderable sprite consisting of one or more frames |
Shader |
A shader |
The next objects accessible through the Myr
object itself:
Object | Description |
---|---|
Transform |
A 2D transformation |
Color |
A color containing a red, green, blue and alpha channel |
Vector |
A 2D vector |
A myr.js context exposes several namespaces which provide access to specific functions:
Namespace | Description |
---|---|
primitives |
Exposes primitive rendering functions |
mesh |
Exposes mesh rendering functions |
utils |
Exposes utility functions |
Global functions are members of the object returned by the Myr
function. One of the most important tasks of the global functions is maintaining the transform stack. Everything that is rendered is transformed by the Transform
on top of this stack. Before applying transformations, it is useful to first save the current transform state using the push()
function. The pop()
function can be called after the transformations are done to get back to the original state.
Function | Description |
---|---|
setClearColor(color) |
Sets the clear color |
setColor(color) |
Sets the global color filter |
setAlpha(alpha) |
Sets the global transparency |
resize(width, height) |
Resize this renderer |
clear() |
Clears the current target |
bind() |
Binds the default render target |
flush() |
Flush the draw calls |
free() |
Frees myr.js object |
getTransform() |
Get the current transformation |
push() |
Push the transform stack |
pop() |
Pop the transform stack |
getWidth() |
Returns the width of the default render target |
getHeight() |
Returns the height of the default render target |
makeSpriteFrame(surface, x, y, width, height, xOrigin, yOrigin, time) |
Returns a sprite frame |
register(name, ...) |
Register a sprite |
isRegistered(name) |
Check if a sprite is registered |
unregister(name) |
Unregister a sprite |
blendEnable() |
Enable blending |
blendDisable() |
Disable blending |
transform(transform) |
Transform |
translate(x, y) |
Translate |
rotate(angle) |
Rotate |
shear(x, y) |
Shear |
scale(x, y) |
Scale |
Sets the clear color of the myr.js object. When clear()
is called, the screen will be cleared using this color.
Parameter | Type | Description |
---|---|---|
color | Color |
A color which the canvas will be cleared to when clear() is called |
Sets the global color filter. Every drawn color will be multiplied by this color before rendering.
Parameter | Type | Description |
---|---|---|
color | Color |
A color |
Sets the global alpha (transparency). Every drawn color will be multiplied by this transparency before rendering. Note that this function sets the alpha component of the current clear color set by setColor
.
Parameter | Type | Description |
---|---|---|
alpha | Number |
A transparency in the range [0, 1] |
Resize the renderer and the canvas used by this Myriad instance.
Parameter | Type | Description |
---|---|---|
width | Number |
The width in pixels |
height | Number |
The height in pixels |
Clears the canvas to the currently set clear color.
Binds the canvas as the current render target.
This function finishes all previously given draw calls. This function should be called at the very end of the render loop.
Frees the myr.js object and the OpenGL objects it maintains. Note that this function does not free objects like surfaces, these must be freed individually.
Return the transformation which is currently on top of the stack.
Push the current transformation onto the stack, saving the current transformation state.
Pop the current transformation from the stack, restoring the last pushed transformation.
Returns the width of the default render target
Returns the height of the default render target
Returns a sprite frame. The result of this function should only be passed to the register
function. If the time parameter is less than zero, sprite animation will stop at this frame.
Parameter | Type | Description |
---|---|---|
surface | Surface |
A surface containing the frame |
x | Number |
The x position of the frame on the surface in pixels |
y | Number |
The y position of the frame on the surface in pixels |
width | Number |
The width of the frame in pixels |
height | Number |
The height of the frame in pixels |
xOrigin | Number |
The frame x origin in pixels |
yOrigin | Number |
The frame y origin in pixels |
time | Number |
The duration of this frame in seconds |
Registers a new sprite under a name. Once a sprite has been registered, its name can be used to instatiate sprites. When the sprite has been registered previously, the new frames overwrite the old ones.
While the first argument must be the sprite name, the number of following parameters depends on the number of frames. All frames must be passed as arguments after the sprite name. A frame is created using the makeSpriteFrame
function.
Parameter | Type | Description |
---|---|---|
name | String |
The name of the sprite to register |
Registering sprites usually happens when loading a sprite sheet. This sheet is first loaded onto a surface, after which all sprites on the sheet are registered to make them available for use. This will usually look like this:
// Load a sprite sheet
sheet = new myr.Surface("source.png");
// Load information about the sprites in this sheet
// This could be loaded from JSon exported by a sprite sheet tool
sprites = loadSprites();
// Register every sprite
for(let i = 0; i < sprites.length; ++i)
myr.register(
sprites[i].name,
myr.makeSpriteFrame(
sheet,
sprites[i].x,
sprites[i].y,
sprites[i].width,
sprites[i].height,
sprites[i].xOrigin,
sprites[i].yOrigin,
sprites[i].frameTime));
Note that sprites
can be any kind of data, the member names may differ for other formats; it is only necessary that all required information about a sprite is passed. If animated sprites exist, any number of sprite frames can be passed to the register
function.
Returns a boolean indicating whether a sprite with the given name has been registered.
Parameter | Type | Description |
---|---|---|
name | String |
The name of the sprite |
Unregisters a previously registered sprite.
Parameter | Type | Description |
---|---|---|
name | String |
The name of the sprite to unregister |
Enables blending when drawing. This means that new drawings will not simply overwrite the existing pixels, but blending will be applied depending on the sprite's alpha values. Blending is enabled by default.
Disables blending when drawing. This means that newly drawn pixels will completely overwrite the pixels previously at that location.
Transform the current transformation by multiplying it with another transformation.
Parameter | Type | Description |
---|---|---|
transform | Transform |
A transform to multiply the current transformation with |
Translate the current transformation.
Parameter | Type | Description |
---|---|---|
x | Number |
Horizontal movement |
y | Number |
Vertical movement |
Rotate the current transformation.
Parameter | Type | Description |
---|---|---|
angle | Number |
Angle in radians |
Shear the current transformation.
Parameter | Type | Description |
---|---|---|
x | Number |
Horizontal shearing |
y | Number |
Vertical shearing |
Scale the current transformation.
Parameter | Type | Description |
---|---|---|
x | Number |
Horizontal scaling |
y | Number |
Vertical scaling |
A surface in myr.js can be a render target. After binding it using its member function bind()
, all render calls render to this surface. The surface itself can also be rendered. Additionally, the surface may be constructed from images, making surfaces useful for large image or background rendering since large images don't fit well on sprite sheets. Note that surfaces can only render to other targets, never to themselves.
Function | Description |
---|---|
Surface(width, height) |
Construct from size |
Surface(width, height, precision) |
Construct from size and precision |
Surface(image) |
Construct from image |
Surface(image, width, height) |
Construct from image and size |
bind() |
Bind the surface |
setClearColor(color) |
Set clear color |
clear() |
Clear the surface |
ready() |
Verify whether the surface is renderable |
getWidth() |
Returns the surface width |
getHeight() |
Returns the surface height |
free() |
Frees all resources used by this surface |
draw(x, y) |
Draws the surface |
drawScaled(x, y, xScale, yScale) |
Draws the surface |
drawSheared(x, y, xShear, yShear) |
Draws the surface |
drawRotated(x, y, angle) |
Draws the surface |
drawScaledRotated(x, y, xScale, yScale, angle) |
Draws the surface |
drawTransformed(transform) |
Draws the surface |
drawTransformedAt(x, y, transform) |
Draws the surface |
drawPart(x, y, left, top, width, height) |
Draws the surface |
drawPartTransformed(transform, left, top, width, height) |
Draws the surface |
Constructs a surface of a specific size.
Parameter | Type | Description |
---|---|---|
width | Number |
Width in pixels |
height | Number |
Height in pixels |
Constructs a surface of a specific size with a certain color channel precision. Precision determines the number of bits that are used to describe one color channel. By default, each channel takes 8 bits, so a single pixel will take up 32 bits (RGBA). Increasing this value may be useful when a surface is used to store data instead of an image. The following values are allowed for this parameter:
Value | Bits per channel |
---|---|
0 | 8 (default) |
1 | 16 |
2 | 32 |
Parameter | Type | Description |
---|---|---|
width | Number |
Width in pixels |
height | Number |
Height in pixels |
precision | Number |
The color channel precision |
Constructs a surface from an existing image. The function ready()
will return false
until the image is loaded.
Parameter | Type | Description |
---|---|---|
image | String or Image |
A URL or Image object referring to a valid image file |
Construct a surface from an existing image. The width and height will be set from the beginning instead of after the image has been loaded.
Parameter | Type | Description |
---|---|---|
image | String |
A URL or Image object referring to a valid image file |
width | Number |
Width in pixels |
height | Number |
Height in pixels |
Binds the surface, making it the current render target until another one is bound. After binding, an empty transform is pushed onto the transformation stack.
Set the clear color of this surface. When clear()
is called, the surface will be cleared using this color.
Parameter | Type | Description |
---|---|---|
color | Color |
A color which the surface will be cleared to when clear() is called |
Clears the surface to the currently set clear color.
Returns a Boolean
indicating whether the surface is ready for use. Surfaces constructed from an image will be ready once the image is loaded. Surfaces that don't require an image are always immediately ready.
Returns the width of the surface in pixels.
Returns the height of the surface in pixels.
Frees the surface and all memory allocated by it.
Draws this surface on the currently bound target.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
Draws this surface on the currently bound target after applying scaling.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
xScale | Number |
The horizontal scale factor |
yScale | Number |
The vertical scale factor |
Draws this surface on the currently bound target after applying shearing.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
xShear | Number |
Horizontal shearing |
yShear | Number |
Vertical shearing |
Draws this surface on the currently bound target after applying rotation.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
angle | Number |
The rotation in radians |
Draws this surface on the currently bound target after applying both scaling and rotation.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
xScale | Number |
The horizontal scale factor |
yScale | Number |
The vertical scale factor |
angle | Number |
The rotation in radians |
Draws this surface on the currently bound target after applying a transformation to it.
Parameter | Type | Description |
---|---|---|
transform | Transform |
A transformation to apply to this surface |
Draws this surface on the currently bound target at a certain position after applying a transformation to it.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
transform | Transform |
A transformation to apply to this surface |
Draws a part of this surface on the currently bound render target. Make sure the specified region is part of the surface; rendering parts that fall outside this surface results in undefined behavior.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
left | Number |
The X position on the surface to draw from |
top | Number |
The Y position on the surface to draw from |
width | Number |
The width of the region to draw |
height | Number |
The height of the region to draw |
Draws a part of this surface on the currently bound render target.
Parameter | Type | Description |
---|---|---|
transform | Transform |
A transformation to apply to this surface |
left | Number |
The X position on the surface to draw from |
top | Number |
The Y position on the surface to draw from |
width | Number |
The width of the region to draw |
height | Number |
The height of the region to draw |
A sprite in myr.js is a renderable image consisting of one or more frames. Sprite sources must be registered using register
before they can be instantiated. Sprites are constructed by referencing these sources.
Typically, one big surface should contain all sprites (it will be a sprite atlas). In this way, sprite rendering is much more efficient than surface rendering.
Function | Description |
---|---|
Sprite(name) |
Constructs a sprite |
animate(timeStep) |
Animates the sprite |
setFrame(frame) |
Set the current frame |
getFrame() |
Returns the current frame |
isFinished() |
Returns whether the animation is finished |
getFrameCount() |
Returns the number of frames |
getWidth() |
Returns the sprite width |
getHeight() |
Returns the sprite height |
getOriginX() |
Returns the X origin |
getOriginY() |
Returns the Y origin |
getUvLeft() |
Returns the left UV coordinate. |
getUvTop() |
Returns the top UV coordinate. |
getUvWidth() |
Returns the width of the sprite in UV space. |
getUvHeight() |
Returns the height of the sprite in UV space |
draw(x, y) |
Draws the sprite |
drawScaled(x, y, xScale, yScale) |
Draws the sprite |
drawSheared(x, y, xShear, yShear) |
Draws the sprite |
drawRotated(x, y, angle) |
Draws the sprite |
drawScaledRotated(x, y, xScale, yScale, angle) |
Draws the sprite |
drawTransformed(transform) |
Draws the sprite |
drawTransformedAt(x, y, transform) |
Draws the sprite |
drawPart(x, y, left, top, width, height) |
Draws the sprite |
drawPartTransformed(transform, left, top, width, height) |
Draws the sprite |
Constructs a sprite from a registered source.
Parameter | Type | Description |
---|---|---|
name | String |
The sprite source |
Advances the animation frame of this sprite according to its frame times. When the maximum frame has been reached, the animation rewinds. If a sprite only has one frame, this method does nothing. Note that the animation stops at any frame with a time value below zero.
Parameter | Type | Description |
---|---|---|
timeStep | Number |
The current time step, which is the time the current animation frame takes |
Sets the current frame index of this sprite.
Parameter | Type | Description |
---|---|---|
frame | Number |
The frame index this sprite should be at, starting at zero |
Returns the current frame index.
Returns a boolean indicating whether the animation is finished. A sprite animation is finished when any frame with a time value below zero is reached. If the frame is set to another frame using setFrame
after this, the animation will continue again.
Returns the total number of frames for this sprite.
Returns the width of the sprite in pixels.
Returns the height of the sprite in pixels.
Returns the X origin of this sprite's current frame.
Returns the Y origin of this sprite's current frame.
Returns the left UV coordinate.
Returns the top UV coordinate.
Returns the width of the sprite in UV space.
Returns the height of the sprite in UV space
Draws this sprite on the currently bound target.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
Draws this sprite on the currently bound target after applying scaling.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
xScale | Number |
The horizontal scale factor |
yScale | Number |
The vertical scale factor |
Draws this sprite on the currently bound target after applying shearing.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
xShear | Number |
Horizontal shearing |
yShear | Number |
Vertical shearing |
Draws this sprite on the currently bound target after applying rotation.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
angle | Number |
The rotation in radians |
Draws this sprite on the currently bound target after applying both scaling and rotation.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
xScale | Number |
The horizontal scale factor |
yScale | Number |
The vertical scale factor |
angle | Number |
The rotation in radians |
Draws this sprite on the currently bound target after applying a transformation to it.
Parameter | Type | Description |
---|---|---|
transform | Transform |
A transformation to apply to this sprite |
Draws this sprite on the currently bound target at a certain position after applying a transformation to it.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
transform | Transform |
A transformation to apply to this sprite |
Draws a part of this sprite on the currently bound render target. Make sure the specified region is part of the sprite; rendering parts that fall outside this sprite results in undefined behavior.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
left | Number |
The X position on the sprite to draw from |
top | Number |
The Y position on the sprite to draw from |
width | Number |
The width of the region to draw |
height | Number |
The height of the region to draw |
Draws a part of this sprite on the currently bound render target.
Parameter | Type | Description |
---|---|---|
transform | Transform |
A transformation to apply to this surface |
left | Number |
The X position on the sprite to draw from |
top | Number |
The Y position on the sprite to draw from |
width | Number |
The width of the region to draw |
height | Number |
The height of the region to draw |
A shader in myr.js is a renderable image that is rendered using a custom pixel shader written by the user. Shaders can be provided with one or more surfaces to read from, and one or more variables can be provided to the shader. Pixel shaders must be written in WebGL 2 compliant GLSL.
The size of the rendered result is equal to the size of the first surface provided to it, or alternatively (or when no surfaces are provided) to a size set by the user.
Function | Description |
---|---|
Shader(shader, surfaces, variables) |
Constructs a shader |
getWidth() |
Returns the shader width |
getHeight() |
Returns the shader height |
setVariable(name, value) |
Set one of the variables' values |
setSurface(name, surface) |
Set one of the input surfaces' surface |
setSize(width, height) |
Set the size of this shader |
free() |
Free this shader |
draw(x, y) |
Draws the shader |
drawScaled(x, y, xScale, yScale) |
Draws the shader |
drawSheared(x, y, xShear, yShear) |
Draws the shader |
drawRotated(x, y, angle) |
Draws the shader |
drawScaledRotated(x, y, xScale, yScale, angle) |
Draws the shader |
drawTransformed(transform) |
Draws the shader |
drawTransformedAt(x, y, transform) |
Draws the shader |
drawPart(x, y, left, top, width, height) |
Draws the shader |
drawPartTransformed(transform, left, top, width, height) |
Draws the shader |
Constructs a shader using WebGL 2 compliant GLSL code, and optionally, surface and variable inputs. The surfaces
and variables
arrays are arrays of strings. Inside the shader code, their values are accessible by these strings as names. To assign surfaces and values to these, the functions setSurface()
and setVariable()
are used.
Parameter | Type | Description |
---|---|---|
shader | String |
The GLSL code to execute when this shader runs |
surfaces | Array |
An array of names for surface inputs |
variables | Array |
An array of variables to create in this shader |
The GLSL code to provide is not the entire shader. A simple complete GLSL pixel shader that renders red pixels could look like this:
layout(location = 0) out lowp vec4 color;
void main() {
color = vec4(1, 0, 0, 1);
}
The GLSL code that should be provided to the custom shader is the main
function of the shader, preceeded by any custom functions. However, uniforms and uniform blocks are already predefined, they should not be included.
void main() {
color = vec4(1, 0, 0, 1);
}
Inside the GLSL code, several variables are accessible for the user besides the surfaces
and variables
. These are:
uv
, amediump vec2
representing the UV coordinates of the current pixel inside the drawing area of this shader.pixel
, amediump vec2
representing the pixel of the source currently being shaded. This variable ranges from[0, 0]
in the left top of the image to[width, height]
, wherewidth
andheight
are the source's width and height in pixels.pixelSize
, amediump vec2
containing the UV size of one pixel. Sampling a pixel to the right for example can be done usingtexture(source, vec2(uv.x + pixelSize.x, uv.y))
.colorFilter
, alowp vec4
containing the current color filter (set bysetColor
).color
, alowp vec4
where the output pixel color should be written to.
Before drawing a shader, ensure that all variables and surfaces have been set using the setSurface()
and setVariable()
functions. Not doing this may and probably will result in undefined behavior.
Returns the width of the shader in pixels. If setSurface()
was called on the first surface in this shader's surfaces
array, the width will be equal to that surface's width. Otherwise, the width will be equal to the width given to this shader by the setSize()
function.
Returns the height of the shader in pixels. If setSurface()
was called on the first surface in this shader's surfaces
array, the height will be equal to that surface's height. Otherwise, the height will be equal to the height given to this shader by the setSize()
function.
Set the value of one of this shader's variables. The variable name should have been declared by passing it to the variables
array when the shader was created. The value must be a number, and will be accessible inside the GLSL code under its name with the mediump float
type.
Parameter | Type | Description |
---|---|---|
name | String |
The variable name |
value | Number |
The value |
Set the surface of one of this shader's surfaces. The surface name should have been declared by passing it to the surfaces
array when the shader was created. The value must be a Surface
, and will be accessible inside the GLSL code under its name with the sampler2D
type.
Parameter | Type | Description |
---|---|---|
name | String |
The surface name |
surface | Surface |
The surface |
Sets the size of this shader. This should not be used when the the surfaces
list was not empty when constructing this shader; in that case, the shader size will be equal to the size of its first surface. If no surfaces are provided, the shader size should be set using this function.
Free all resources occupied by this shader. When the shader is no longer used, this function should be called to ensure the occupied memory is freed.
Draws this shader on the currently bound target.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
Draws this shader on the currently bound target after applying scaling.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
xScale | Number |
The horizontal scale factor |
yScale | Number |
The vertical scale factor |
Draws this shader on the currently bound target after applying shearing.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
xShear | Number |
Horizontal shearing |
yShear | Number |
Vertical shearing |
Draws this shader on the currently bound target after applying rotation.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
angle | Number |
The rotation in radians |
Draws this shader on the currently bound target after applying both scaling and rotation.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
xScale | Number |
The horizontal scale factor |
yScale | Number |
The vertical scale factor |
angle | Number |
The rotation in radians |
Draws this shader on the currently bound target after applying a transformation to it.
Parameter | Type | Description |
---|---|---|
transform | Transform |
A transformation to apply to this shader |
Draws this shader on the currently bound target at a certain position after applying a transformation to it.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
transform | Transform |
A transformation to apply to this shader |
Draws a part of this shader on the currently bound render target. Make sure the specified region is part of the shader; rendering parts that fall outside this shader results in undefined behavior.
Parameter | Type | Description |
---|---|---|
x | Number |
The X position to draw to |
y | Number |
The Y position to draw to |
left | Number |
The X position on the shader to draw from |
top | Number |
The Y position on the shader to draw from |
width | Number |
The width of the region to draw |
height | Number |
The height of the region to draw |
Draws a part of this shader on the currently bound render target.
Parameter | Type | Description |
---|---|---|
transform | Transform |
A transformation to apply to this shader |
left | Number |
The X position on the shader to draw from |
top | Number |
The Y position on the shader to draw from |
width | Number |
The width of the region to draw |
height | Number |
The height of the region to draw |
The transform object wraps a homogeneous 2D transformation matrix. Several different transform functions are provided, but the matrix can also be filled by hand. Transform objects are used in the global transformation stack to transform everything that is being rendered.
Function | Description |
---|---|
Transform() |
Constructs as identity transform |
Transform(_00, _10, _20, _01, _11, _21) |
Constructs from matrix values |
apply(vector) |
Apply to a vector |
copy() |
Returns a copy |
identity() |
Set to identity |
set(transform) |
Make equal to another transform |
multiply(transform) |
Multiply with another transform |
rotate(angle) |
Rotate |
shear(x, y) |
Shear |
translate(x, y) |
Translate |
scale(x, y) |
Scale |
invert() |
Invert |
Constructs a Transform
object, which is initialized as the identity matrix (no transform).
Constructs a Transform
object with custom values. Note that only the top two rows of the matrix can be entered, since the bottom row for 2D transformations will always be [0, 0, 1]
.
Parameter | Type | Description |
---|---|---|
_00 | Number |
Value [0, 0] of the matrix |
_10 | Number |
Value [1, 0] of the matrix |
_20 | Number |
Value [2, 0] of the matrix |
_01 | Number |
Value [0, 1] of the matrix |
_11 | Number |
Value [1, 1] of the matrix |
_21 | Number |
Value [2, 1] of the matrix |
Multiplies the given vector by this transformation matrix. This function may prove useful when a coordinate instead of a rendering call must be transformed.
Parameter | Type | Description |
---|---|---|
vector | Vector |
A vector object to transform |
Returns a copy of this transform object.
Sets the transformation to the identity matrix.
Sets the transformation to another transformation.
Parameter | Type | Description |
---|---|---|
transform | Transform |
A transform object |
Multiplies this transformation with another transformation by matrix multiplication. This is useful for combining different transforms together.
Parameter | Type | Description |
---|---|---|
transform | Transform |
A transform object |
Rotate by a number of radians.
Parameter | Type | Description |
---|---|---|
angle | Number |
The number of radians to rotate by |
Shear this transformation.
Parameter | Type | Description |
---|---|---|
x | Number |
Horizontal shear |
y | Number |
Vertical shear |
Translate this transformation.
Parameter | Type | Description |
---|---|---|
x | Number |
Horizontal translation |
y | Number |
Vertical translation |
Scale this transformation.
Parameter | Type | Description |
---|---|---|
x | Number |
Horizontal scale |
y | Number |
Vertical scale |
Invert this transformation.
This object represents a color with a red, green, blue and alpha component.
Function | Description |
---|---|
Color(r, g, b) |
Construct from RGB |
Color(r, g, b, a) |
Construct from RGBA |
toHSV() |
Convert to HSV values |
toHex() |
Convert to hexadecimal string |
copy() |
Copy this color |
add(color) |
Adds another color to itself |
multiply(color) |
Multiplies with another color |
Function | Description |
---|---|
fromHSV(h, s, v) |
Constructs a color from hue, saturation and value |
fromHex(hex) |
Constructs a color from a hexadecimal string |
Constant | Description |
---|---|
BLACK |
Black |
BLUE |
Blue |
GREEN |
Green |
CYAN |
Cyan |
RED |
Red |
MAGENTA |
Magenta |
YELLOW |
Yellow |
WHITE |
White |
Constructs a color object from red, green and blue. The values must lie in the range [0, 1]. The color will have an alpha value of 1.0
.
Parameter | Type | Description |
---|---|---|
r | Number |
Red value in the range [0, 1] |
g | Number |
Green value in the range [0, 1] |
b | Number |
Blue value in the range [0, 1] |
Constructs a color object from red, green, blue and alpha. The values must lie in the range [0, 1].
Parameter | Type | Description |
---|---|---|
r | Number |
Red value in the range [0, 1] |
g | Number |
Green value in the range [0, 1] |
b | Number |
Blue value in the range [0, 1] |
a | Number |
Alpha value in the range [0, 1] |
Returns an object with the members h
, s
and v
, representing this color's hue, saturation and value.
Returns a hexadecimal string representing this color. Note that hexadecimal color representations don't include an alpha channel, so this information is lost after converting the color.
Returns a copy of this color.
Adds another color to itself.
Parameter | Type | Description |
---|---|---|
color | Color |
A color object |
Multiplies this color with another color.
Parameter | Type | Description |
---|---|---|
color | Color |
A color object |
Constructs a color from hue, saturation and value.
Parameter | Type | Description |
---|---|---|
h | Number |
Hue value in the range [0, 1] |
s | Number |
Saturation value in the range [0, 1] |
v | Number |
Value value in the range [0, 1] |
Constructs a color from a hexadecimal string. The string must not contain a prefix like 0x
or #
. If the string has six characters, the red, green and blue components will be read from it. If the string has eight characters, the alpha channel will also be read.
This object represents a vector in 2D space. Several useful vector operation functions are provided.
Function | Description |
---|---|
Vector(x, y) |
Construct from x and y |
copy() |
Returns a copy |
add(vector) |
Add |
subtract(vector) |
Subtract |
negate() |
Negate |
dot(vector) |
Dot product |
length() |
Length |
multiply(scalar) |
Multiply |
divide(scalar) |
Divide |
normalize() |
Normalize |
rotate(angle) |
Rotate |
angle() |
Returns the angle |
equals(vector) |
Checks for equality |
Constructs a vector object.
Parameter | Type | Description |
---|---|---|
x | Number |
X value |
y | Number |
Y value |
Returns a copy of this vector object.
Add another vector to this one.
Parameter | Type | Description |
---|---|---|
vector | Vector |
A vector object |
Subtract another vector from this one.
Parameter | Type | Description |
---|---|---|
vector | Vector |
A vector object |
Negate the vector values.
Returns the dot product of this vector and another one.
Parameter | Type | Description |
---|---|---|
vector | Vector |
A vector object |
Returns the length of the vector.
Multiplies the vector by a scalar.
Parameter | Type | Description |
---|---|---|
scalar | Number |
A number |
Divides the vector by a scalar.
Parameter | Type | Description |
---|---|---|
scalar | Number |
A number |
Normalizes the vector.
Rotates this vector by a given angle.
Parameter | Type | Description |
---|---|---|
angle | Number |
An angle in radians. |
Returns the angle this vector is pointing towards.
Returns a boolean indicating whether the vector is equal to another vector.
Parameter | Type | Description |
---|---|---|
vector | Vector |
A vector object |
The primitives namespace exposes several functions which can be used for primitive rendering.
Function | Description |
---|---|
drawPoint(color, x, y) |
Draws a colored point |
drawLine(color, x1, y1, x2, y2) |
Draws a line segment |
drawLineGradient(color1, x1, y1, color2, x2, y2) |
Draws a gradient line segment |
drawRectangle(color, x, y, width, height) |
Draws a rectangle |
drawCircle(color, x, y, radius) |
Draws a circle |
drawTriangle(color, x1, y1, x2, y2, x3, y3) |
Draws a colored triangle |
drawTriangleGradient(color1, x1, y1, color2, x2, y2, color3, x3, y3) |
Draws a gradient triangle |
fillRectangle(color, x, y, width, height) |
Draws a colored rectangle |
fillRectangleGradient(color1, color2, color3, color4, x, y, width, height) |
Draws a gradient rectangle |
fillCircle(color, x, y, radius) |
Draws a colored circle |
fillCircleGradient(colorStart, colorEnd, x, y, radius) |
Draws a gradient circle |
Draws a colored pixel at the specified coordinates.
Parameter | Type | Description |
---|---|---|
color | Color |
The point color |
x | Number |
The x coordinate |
y | Number |
The y coordinate |
Draws a single line segment with a color.
Parameter | Type | Description |
---|---|---|
color | Color |
The line color |
x1 | Number |
The start point x coordinate |
y1 | Number |
The start point y coordinate |
x2 | Number |
The end point x coordinate |
y2 | Number |
The end point y coordinate |
Draws a single line segment with a color gradient.
Parameter | Type | Description |
---|---|---|
color1 | Color |
The line color at the start point |
x1 | Number |
The start point x coordinate |
y1 | Number |
The start point y coordinate |
color2 | Color |
The line color at the end point |
x2 | Number |
The end point x coordinate |
y2 | Number |
The end point y coordinate |
Draws a rectangle.
Parameter | Type | Description |
---|---|---|
color | Color |
The line color |
x | Number |
The left top x coordinate |
y | Number |
The left top y coordinate |
width | Number |
The rectangle width |
height | Number |
The rectangle height |
Draws a circle with a radius around an origin.
Parameter | Type | Description |
---|---|---|
color | Color |
The line color |
x | Number |
The center's x coordinate |
y | Number |
The center's y coordinate |
radius | Number |
The circle radius |
Draws a colored triangle.
Parameter | Type | Description |
---|---|---|
color | Color |
The fill color |
x1 | Number |
The first point's x coordinate |
y1 | Number |
The first point's y coordinate |
x2 | Number |
The second point's x coordinate |
y2 | Number |
The second point's y coordinate |
x3 | Number |
The third point's x coordinate |
y3 | Number |
The third point's y coordinate |
Draws a triangle with a gradient fill. Each point has a color, and the colors are interpolated along the triangle.
Parameter | Type | Description |
---|---|---|
color1 | Color |
The first point's color |
x1 | Number |
The first point's x coordinate |
y1 | Number |
The first point's y coordinate |
color2 | Color |
The second point's color |
x2 | Number |
The second point's x coordinate |
y2 | Number |
The second point's y coordinate |
color3 | Color |
The third point's color |
x3 | Number |
The third point's x coordinate |
y3 | Number |
The third point's y coordinate |
Draws a colored rectangle.
Parameter | Type | Description |
---|---|---|
color | Color |
The fill color |
x | Number |
The left top x coordinate |
y | Number |
The left top y coordinate |
width | Number |
The rectangle width |
height | Number |
The rectangle height |
Draws a rectangle with a gradient fill. Each point has a color, and the colors are interpolated along the rectangle.
Parameter | Type | Description |
---|---|---|
color1 | Color |
The left top color |
color2 | Color |
The right top color |
color3 | Color |
The left bottom color |
color4 | Color |
The right bottom color |
x | Number |
The left top x coordinate |
y | Number |
The left top y coordinate |
width | Number |
The rectangle width |
height | Number |
The rectangle height |
Draws a colored circle with a radius around an origin.
Parameter | Type | Description |
---|---|---|
color | Color |
The fill color |
x | Number |
The center's x coordinate |
y | Number |
The center's y coordinate |
radius | Number |
The circle radius |
Draws a gradient circle with a radius around an origin.
Parameter | Type | Description |
---|---|---|
colorStart | Color |
The color at the center |
colorEnd | Color |
The color at the edge |
x | Number |
The center's x coordinate |
y | Number |
The center's y coordinate |
radius | Number |
The circle radius |
The mesh namespace exposes several functions which can be used for mesh rendering. Meshes consist of textured triangles; both surfaces and sprites can be used as a source texture.
Function | Description |
---|---|
drawTriangle(source, x1, y1, u1, v1, x2, y2, u2, v2, x3, y3, u3, v3) |
Draws a textured triangle |
Draws a textured triangle. The source can be either a surface or a sprite. If a sprite is used as the source, the current frame of the sprite is used. Note that texture coordinates range from 0 to 1.
Parameter | Type | Description |
---|---|---|
source | Surface or Sprite |
The image to draw a part of |
x1 | Number |
The first point's x coordinate |
y1 | Number |
The first point's y coordinate |
u1 | Number |
The first point's texture x coordinate |
v1 | Number |
The first point's texture y coordinate |
x2 | Number |
The second point's x coordinate |
y2 | Number |
The second point's y coordinate |
u2 | Number |
The second point's texture x coordinate |
v2 | Number |
The second point's texture y coordinate |
x3 | Number |
The third point's x coordinate |
y3 | Number |
The third point's y coordinate |
u3 | Number |
The third point's texture x coordinate |
v3 | Number |
The third point's texture y coordinate |
Function | Description |
---|---|
loop(update) |
Calls the function update on every vertical sync |
After calling this function, the provided update function is called for every vertical synchronization. This usually means the function is called sixty frames per second. The argument timeStep is passed to the function, which is the portion of a second the current frame takes; this will be 1/60 when the browser updates at 60 frames per second. When rendering at this frequency, screen tearing is usually prevented.
The update function should return a boolean. As long as true
is returned, the function keeps being called; when false
is returned, the loop stops.
Parameter | Type | Description |
---|---|---|
update | Function |
A function that is called for every update |