Show:
API

Matter.Render

The Matter.Render module is a lightweight, optional utility which provides a simple canvas based renderer for visualising instances of Matter.Engine. It is intended for development and debugging purposes, but may also be suitable for simple games. It includes a number of drawing options including wireframe, vector with support for sprites and viewports.

Methods

Matter.Render._createCanvas

(width, height)
Object private

Parameters

Returns

canvas

Matter.Render._getPixelRatio

(canvas)
Number private

Gets the pixel ratio of the canvas.

Parameters

Returns

Number

pixel ratio

Matter.Render._getTexture

(render, imagePath)
Image private

Gets the requested texture (an Image) via its path

Parameters

Returns

Image

texture

Matter.Render._mean

(values)
Number private

Returns the mean value of the given numbers.

Parameters

Returns

Number

the mean of given values

Matter.Render._updateTiming

(render, time)
private

Updates render timing.

Parameters

Matter.Render.applyBackground

(render, background)
private

Applies the background to the canvas using CSS.

Parameters

Matter.Render.bodies

(render, bodies, context)
private

Description

Parameters

Matter.Render.bodyAxes

(render, bodies, context)
private

Draws body angle indicators and axes

Parameters

Matter.Render.bodyBounds

(render, bodies, context)
private

Draws body bounds

Parameters

Matter.Render.bodyConvexHulls

(render, bodies, context)
private

Optimised method for drawing body convex hull wireframes in one pass

Parameters

Matter.Render.bodyIds

(render, bodies, context)
private

Draws body ids

Parameters

Matter.Render.bodyPositions

(render, bodies, context)
private

Draws body positions

Parameters

Matter.Render.bodyVelocity

(render, bodies, context)
private

Draws body velocity

Parameters

Matter.Render.bodyWireframes

(render, bodies, context)
private

Optimised method for drawing body wireframes in one pass

Parameters

Matter.Render.collisions

(render, pairs, context)
private

Description

Parameters

Matter.Render.constraints

(constraints, context)
private

Description

Parameters

Matter.Render.create

([options])
Render

Creates a new renderer. The options parameter is an object that specifies any properties you wish to override the defaults. All properties have default values, and many are pre-calculated automatically based on other properties. See the properties section below for detailed information on what you can pass via the options object.

Parameters

Returns

Render

A new renderer

Matter.Render.endViewTransform

(render)

Resets all transforms on the render context.

Parameters

Matter.Render.inspector

(inspector, context)
private

Description

Parameters

Matter.Render.lookAt

(render, objects, [padding], [center=true])

Positions and sizes the viewport around the given object bounds. Objects must have at least one of the following properties:

  • object.bounds
  • object.position
  • object.min and object.max
  • object.x and object.y

Parameters

Matter.Render.mousePosition

(render, mouse, context)
private

Renders mouse position.

Parameters

Matter.Render.performance

(render, context)
private

Renders engine and render performance information.

Parameters

Matter.Render.run

(render)

Continuously updates the render canvas on the requestAnimationFrame event.

Parameters

Matter.Render.separations

(render, pairs, context)
private

Description

Parameters

Matter.Render.setPixelRatio

(render, pixelRatio)

Sets the pixel ratio of the renderer and updates the canvas. To automatically detect the correct ratio, pass the string 'auto' for pixelRatio.

Parameters

Matter.Render.setSize

(render, width, height)

Sets the render width and height.

Updates the canvas accounting for render.options.pixelRatio.

Updates the bottom right render bound render.bounds.max relative to the provided width and height. The top left render bound render.bounds.min isn't changed.

Follow this call with Render.lookAt if you need to change the render bounds.

See also Render.setPixelRatio.

Parameters

  • render Render
  • width Number

    The width (in CSS pixels)

  • height Number

    The height (in CSS pixels)

Matter.Render.startViewTransform

(render)

Applies viewport transforms based on render.bounds to a render context.

Parameters

Matter.Render.stats

(render, context, time)
private

Renders statistics about the engine and world useful for debugging.

Parameters

Matter.Render.status

(context, x, y, width, height, count, label, indicator, plotY)
private

Renders a label, indicator and a chart.

Parameters

Matter.Render.stop

(render)

Ends execution of Render.run on the given render, by canceling the animation frame request event loop.

Parameters

Matter.Render.vertexNumbers

(render, bodies, context)
private

Renders body vertex numbers.

Parameters

Matter.Render.world

(render)

Renders the given engine's Matter.World object. This is the entry point for all rendering and should be called every time the scene changes.

Parameters

Properties / Options

The following properties if specified below are for objects created by Matter.Render.create and may be passed to it as options.

Render.bounds

Bounds

A Bounds object that specifies the drawing view region. Rendering will be automatically transformed and scaled to fit within the canvas size (render.options.width and render.options.height). This allows for creating views that can pan or zoom around the scene. You must also set render.options.hasBounds to true to enable bounded rendering.

The canvas element to render to. If not specified, one will be created if render.element has been specified.

Default: null

The 2d rendering context from the render.canvas element.

deprecated

A back-reference to the Matter.Render module.

A reference to the element where the canvas is to be inserted (if render.canvas has not been specified)

Default: null

Render.engine

Engine

A reference to the Matter.Engine instance to be used.

Render.mouse

Mouse

The mouse to render if render.options.showMousePosition is enabled.

Default: null

Render.options

The configuration options of the renderer.

A CSS background color string to use when render.options.wireframes is disabled. This may be also set to 'transparent' or equivalent.

Default: '#14151f'

A flag to enable or disable rendering entirely.

Default: false

A flag that specifies if render.bounds should be used when rendering.

Default: false

The target height in pixels of the render.canvas to be created. See also the options.pixelRatio property to change render quality.

Default: 600

The pixel ratio to use when rendering.

Default: 1

A flag to enable or disable the body angle debug overlay.

Default: false

A flag to enable or disable the body axes debug overlay.

Default: false

A flag to enable or disable the body bounds debug overlay.

Default: false

deprecated

Deprecated: no longer implemented

A flag to enable or disable the collision broadphase debug overlay.

Default: false

A flag to enable or disable the body collisions debug overlay.

Default: false

A flag to enable or disable the body convex hulls debug overlay.

Default: false

A flag to enable or disable all debug information overlays together.
This includes and has priority over the values of:

  • render.options.showStats
  • render.options.showPerformance

Default: false

A flag to enable or disable the debug information overlay.

Default: false

A flag to enable or disable the body and part ids debug overlay.

Default: false

A flag to enable or disable the body internal edges debug overlay.

Default: false

A flag to enable or disable the mouse position debug overlay.

Default: false

A flag to enable or disable performance charts.
From left to right, the values shown are:

  • average render frequency (e.g. 60 fps)
  • exact engine delta time used for last update (e.g. 16.66ms)
  • average updates per frame (e.g. 1)
  • average engine execution duration (e.g. 5.00ms)
  • average render execution duration (e.g. 0.40ms)
  • average effective play speed (e.g. '1.00x' is 'real-time')

Each value is recorded over a fixed sample of past frames (60 frames).

A chart shown below each value indicates the variance from the average over the sample. The more stable or fixed the value is the flatter the chart will appear.

Default: false

A flag to enable or disable the body positions debug overlay.

Default: false

A flag to enable or disable the collision resolver separations debug overlay.

Default: false

A flag to enable or disable sleeping bodies indicators.

Default: true

A flag to enable or disable the engine stats info overlay.
From left to right, the values shown are:

  • body parts total
  • body total
  • constraints total
  • composites total
  • collision pairs total

Default: false

A flag to enable or disable the body velocity debug overlay.

Default: false

A flag to enable or disable the body vertex numbers debug overlay.

Default: false

The target width in pixels of the render.canvas to be created. See also the options.pixelRatio property to change render quality.

Default: 800

A CSS color string to use for background when render.options.wireframes is enabled. This may be also set to 'transparent' or equivalent.

Default: '#14151f'

A flag to toggle wireframe rendering otherwise solid fill rendering is used.

Default: true

A CSS color string to use for stroke when render.options.wireframes is enabled. This may be also set to 'transparent' or equivalent.

Default: '#bbb'

Render.textures

The sprite texture cache.

Events

The following events are emitted by objects created by Matter.Render.create and received by objects that have subscribed using Matter.Events.on.

Events.on(Render, "afterRender", callback)

Fired after rendering

Callback Parameters

  • event Object

    An event object

    • timestamp Number

      The engine.timing.timestamp of the event

    • source

      The source object of the event

    • name

      The name of the event

Events.on(Render, "beforeRender", callback)

Fired before rendering

Callback Parameters

  • event Object

    An event object

    • timestamp Number

      The engine.timing.timestamp of the event

    • source

      The source object of the event

    • name

      The name of the event