myr.js v1.1.6

myr.js

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.

Installation

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.

Initialization

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));

Alternatively, a second parameter can be given to the Myr function, which is a boolean indicating whether anti aliasing should be enabled on this context.

Objects

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.

The next objects accessible through the Myr object itself:

Namespaces

A myr.js context exposes several namespaces which provide access to specific functions:

Global 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.

setClearColor(color)

Sets the clear color of the myr.js object. When clear() is called, the screen will be cleared using this color.

setColor(color)

Sets the global color filter. Every drawn color will be multiplied by this color before rendering.

setAlpha(alpha)

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.

resize(width, height)

Resize the renderer and the canvas used by this Myriad instance.

clear()

Clears the canvas to the currently set clear color.

bind()

Binds the canvas as the current render target.

flush()

This function finishes all previously given draw calls. This function should be called at the very end of the render loop.

free()

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.

getTransform()

Return the transformation which is currently on top of the stack.

push()

Push the current transformation onto the stack, saving the current transformation state.

pop()

Pop the current transformation from the stack, restoring the last pushed transformation.

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. 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.

register(name, ...)

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.

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.

isRegistered(name)

Returns a boolean indicating whether a sprite with the given name has been registered.

unregister(name)

Unregisters a previously registered sprite.

blendEnable()

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.

blendDisable()

Disables blending when drawing. This means that newly drawn pixels will completely overwrite the pixels previously at that location.

transform(transform)

Transform the current transformation by multiplying it with another transformation.

transformSet(transform)

Set the current transformation by overwriting it. Do not call this function when no custom transformation is on the stack; the root transform may never be modified.

translate(x, y)

Translate the current transformation.

rotate(angle)

Rotate the current transformation.

shear(x, y)

Shear the current transformation.

scale(x, y)

Scale the current transformation.

Surface

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.

Functions

Surface(width, height)

Constructs a surface of a specific size.

Surface(width, height, precision, linear, repeat)

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 linear interpolation option can be turned on to enable linear interpolation when reading this surface. Interpolation is nearest neighbor by default. The repeat option can be turned on to enable texture repeating when sampling this surface.

Surface(width, height, pixels)

Constructs a surface of a specific size from an array of pixels. The pixel array has the size width * height * 4, where every color channel has an entry. The range of the pixel channel values is [0, 255].

Surface(width, height, pixels, linear, repeat)

Constructs a surface of a specific size from an array of pixels. The pixel array has the size width * height * 4, where every color channel has an entry. The range of the pixel channel values is [0, 255].

Surface(image)

Constructs a surface from an existing image. The function ready() will return false until the image is loaded.

Surface(image, linear, repeat)

Constructs a surface from an existing image. The function ready() will return false until the image is loaded.

Surface(image, width, height)

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.

Surface(image, width, height, linear, repeat)

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.

bind()

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.

setClearColor(color)

Set the clear color of this surface. When clear() is called, the surface will be cleared using this color.

clear()

Clears the surface to the currently set clear color.

ready()

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.

getWidth()

Returns the width of the surface in pixels.

getHeight()

Returns the height of the surface in pixels.

free()

Frees the surface and all memory allocated by it.

draw(x, y)

Draws this surface on the currently bound target.

drawScaled(x, y, xScale, yScale)

Draws this surface on the currently bound target after applying scaling.

drawSheared(x, y, xShear, yShear)

Draws this surface on the currently bound target after applying shearing.

drawRotated(x, y, angle)

Draws this surface on the currently bound target after applying rotation.

drawScaledRotated(x, y, xScale, yScale, angle)

Draws this surface on the currently bound target after applying both scaling and rotation.

drawTransformed(transform)

Draws this surface on the currently bound target after applying a transformation to it.

drawTransformedAt(x, y, transform)

Draws this surface on the currently bound target at a certain position after applying a transformation to it.

drawPart(x, y, left, top, width, height)

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.

drawPartTransformed(transform, left, top, width, height)

Draws a part of this surface on the currently bound render target.

Sprite

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.

Functions

Sprite(name)

Constructs a sprite from a registered source.

animate(timeStep)

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.

setFrame(frame)

Sets the current frame index of this sprite.

getFrame()

Returns the current frame index.

isFinished()

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.

getFrameCount()

Returns the total number of frames for this sprite.

getWidth()

Returns the width of the sprite in pixels.

getHeight()

Returns the height of the sprite in pixels.

getOriginX()

Returns the X origin of this sprite's current frame.

getOriginY()

Returns the Y origin of this sprite's current frame.

getUvLeft()

Returns the left UV coordinate.

getUvRight()

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 this sprite on the currently bound target.

drawScaled(x, y, xScale, yScale)

Draws this sprite on the currently bound target after applying scaling.

drawSheared(x, y, xShear, yShear)

Draws this sprite on the currently bound target after applying shearing.

drawRotated(x, y, angle)

Draws this sprite on the currently bound target after applying rotation.

drawScaledRotated(x, y, xScale, yScale, angle)

Draws this sprite on the currently bound target after applying both scaling and rotation.

drawTransformed(transform)

Draws this sprite on the currently bound target after applying a transformation to it.

drawTransformedAt(x, y, transform)

Draws this sprite on the currently bound target at a certain position after applying a transformation to it.

drawPart(x, y, left, top, width, height)

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.

drawPartTransformed(transform, left, top, width, height)

Draws a part of this sprite on the currently bound render target.

Shader

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.

Functions

Shader(shader, surfaces, variables)

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.

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, a mediump vec2 representing the UV coordinates of the current pixel inside the drawing area of this shader.
• pixel, a mediump 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], where width and height are the source's width and height in pixels.
• pixelSize, a mediump vec2 containing the UV size of one pixel. Sampling a pixel to the right for example can be done using texture(source, vec2(uv.x + pixelSize.x, uv.y)).
• colorFilter, a lowp vec4 containing the current color filter (set by setColor).
• color, a lowp 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.

getWidth()

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.

getHeight()

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.

setVariable(name, value)

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.

setSurface(name, surface)

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.

setSize(width, height)

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()

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.

draw(x, y)

Draws this shader on the currently bound target.

drawScaled(x, y, xScale, yScale)

Draws this shader on the currently bound target after applying scaling.

drawSheared(x, y, xShear, yShear)

Draws this shader on the currently bound target after applying shearing.

drawRotated(x, y, angle)

Draws this shader on the currently bound target after applying rotation.

drawScaledRotated(x, y, xScale, yScale, angle)

Draws this shader on the currently bound target after applying both scaling and rotation.

drawTransformed(transform)

Draws this shader on the currently bound target after applying a transformation to it.

drawTransformedAt(x, y, transform)

Draws this shader on the currently bound target at a certain position after applying a transformation to it.

drawPart(x, y, left, top, width, height)

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.

drawPartTransformed(transform, left, top, width, height)

Draws a part of this shader on the currently bound render target.

Transform

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.

Functions

Transform()

Constructs a Transform object, which is initialized as the identity matrix (no transform).

Transform(_00, _10, _20, _01, _11, _21)

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].

apply(vector)

Multiplies the given vector by this transformation matrix. This function may prove useful when a coordinate instead of a rendering call must be transformed.

copy()

Returns a copy of this transform object.

identity()

Sets the transformation to the identity matrix.

set(transform)

Sets the transformation to another transformation.

multiply(transform)

Multiplies this transformation with another transformation by matrix multiplication. This is useful for combining different transforms together.

rotate(angle)

Rotate by a number of radians.

shear(x, y)

Shear this transformation.

translate(x, y)

Translate this transformation.

scale(x, y)

Scale this transformation.

invert()

Invert this transformation.

Color

This object represents a color with a red, green, blue and alpha component.

Functions

Global functions

Constants

Color(r, g, b)

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.

Color(r, g, b, a)

Constructs a color object from red, green, blue and alpha. The values must lie in the range 0, 1.

toHSV()

Returns an object with the members h, s and v, representing this color's hue, saturation and value.

toHex()

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.

copy()

Returns a copy of this color.

add(color)

Adds another color to itself.

multiply(color)

Multiplies this color with another color.

fromHSV(h, s, v)

Constructs a color from hue, saturation and value.

fromHex(hex)

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.

Vector

This object represents a vector in 2D space. Several useful vector operation functions are provided.

Functions

Vector(x, y)

Constructs a vector object.

copy()

Returns a copy of this vector object.

add(vector)

Add another vector to this one.

subtract(vector)

Subtract another vector from this one.

negate()

Negate the vector values.

dot(vector)

Returns the dot product of this vector and another one.

length()

Returns the length of the vector.

multiply(scalar)

Multiplies the vector by a scalar.

divide(scalar)

Divides the vector by a scalar.

normalize()

Normalizes the vector.

rotate(angle)

Rotates this vector by a given angle.

angle()

Returns the angle this vector is pointing towards.

reflect(vector)

Reflects the vector against the given normal vector.

equals(vector)

Returns a boolean indicating whether the vector is equal to another vector.

Primitives

The primitives namespace exposes several functions which can be used for primitive rendering.

Functions

drawPoint(color, x, y)

Draws a colored pixel at the specified coordinates.

drawLine(color, x1, y1, x2, y2)

Draws a single line segment with a color.

drawLineGradient(color1, x1, y1, color2, x2, y2)

Draws a single line segment with a color gradient.

drawRectangle(color, x, y, width, height)

Draws a rectangle.

drawCircle(color, x, y, radius)

Draws a circle with a radius around an origin.

drawTriangle(color, x1, y1, x2, y2, x3, y3)

Draws a colored triangle.

drawTriangleGradient(color1, x1, y1, color2, x2, y2, color3, x3, y3)

Draws a triangle with a gradient fill. Each point has a color, and the colors are interpolated along the triangle.

fillRectangle(color, x, y, width, height)

Draws a colored rectangle.

fillRectangleGradient(color1, color2, color3, color4, x, y, width, height)

Draws a rectangle with a gradient fill. Each point has a color, and the colors are interpolated along the rectangle.

fillCircle(color, x, y, radius)

Draws a colored circle with a radius around an origin.

fillCircleGradient(colorStart, colorEnd, x, y, radius)

Draws a gradient circle with a radius around an origin.

Mesh

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.

Functions

drawTriangle(source, x1, y1, u1, v1, x2, y2, u2, v2, x3, y3, u3, v3)

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.

Utils

Functions

loop(update)

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.