Show:
API

Matter.Render

Defined in: src/render/Render.js:1

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

src/render/Render.js:1474 · Usages · Examples

Matter.Render._getPixelRatio

(canvas)
→ Number private

Gets the pixel ratio of the canvas.

Parameters

Returns

Number

pixel ratio

src/render/Render.js:1490 · Usages · Examples

Matter.Render._getTexture

(render, imagePath)
→ Image private

Gets the requested texture (an Image) via its path

Parameters

Returns

Image

texture

src/render/Render.js:1507 · Usages · Examples

Matter.Render._mean

(values)
→ Number private

Returns the mean value of the given numbers.

Parameters

Returns

Number

the mean of given values

src/render/Render.js:1459 · Usages · Examples

Matter.Render._updateTiming

(render, time)
private

Updates render timing.

Parameters

src/render/Render.js:1421 · Usages · Examples

Matter.Render.applyBackground

(render, background)
private

Applies the background to the canvas using CSS.

Parameters

src/render/Render.js:1527 · Usages · Examples

Matter.Render.bodies

(render, bodies, context)
private

Description

Parameters

src/render/Render.js:749 · Usages · Examples

Matter.Render.bodyAxes

(render, bodies, context)
private

Draws body angle indicators and axes

Parameters

src/render/Render.js:1021 · Usages · Examples

Matter.Render.bodyBounds

(render, bodies, context)
private

Draws body bounds

Parameters

src/render/Render.js:984 · Usages · Examples

Matter.Render.bodyConvexHulls

(render, bodies, context)
private

Optimised method for drawing body convex hull wireframes in one pass

Parameters

src/render/Render.js:905 · Usages · Examples

Matter.Render.bodyIds

(render, bodies, context)
private

Draws body ids

Parameters

src/render/Render.js:1169 · Usages · Examples

Matter.Render.bodyPositions

(render, bodies, context)
private

Draws body positions

Parameters

src/render/Render.js:1083 · Usages · Examples

Matter.Render.bodyVelocity

(render, bodies, context)
private

Draws body velocity

Parameters

src/render/Render.js:1139 · Usages · Examples

Matter.Render.bodyWireframes

(render, bodies, context)
private

Optimised method for drawing body wireframes in one pass

Parameters

src/render/Render.js:852 · Usages · Examples

Matter.Render.collisions

(render, pairs, context)
private

Description

Parameters

src/render/Render.js:1196 · Usages · Examples

Matter.Render.constraints

(constraints, context)
private

Description

Parameters

src/render/Render.js:672 · Usages · Examples

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

src/render/Render.js:38 · Usages · Examples

Matter.Render.endViewTransform

(render)

Resets all transforms on the render context.

Parameters

src/render/Render.js:341 · Usages · Examples

Matter.Render.inspector

(inspector, context)
private

Description

Parameters

src/render/Render.js:1336 · Usages · Examples

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

src/render/Render.js:224 · Usages · Examples

Matter.Render.mousePosition

(render, mouse, context)
private

Renders mouse position.

Parameters

src/render/Render.js:970 · Usages · Examples

Matter.Render.performance

(render, context)
private

Renders engine and render performance information.

Parameters

src/render/Render.js:542 · Usages · Examples

Matter.Render.run

(render)

Continuously updates the render canvas on the requestAnimationFrame event.

Parameters

src/render/Render.js:135 · Usages · Examples

Matter.Render.separations

(render, pairs, context)
private

Description

Parameters

src/render/Render.js:1279 · Usages · Examples

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

src/render/Render.js:171 · Usages · Examples

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)

src/render/Render.js:194 · Usages · Examples

Matter.Render.startViewTransform

(render)

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

Parameters

src/render/Render.js:322 · Usages · Examples

Matter.Render.stats

(render, context, time)
private

Renders statistics about the engine and world useful for debugging.

Parameters

src/render/Render.js:487 · Usages · Examples

Matter.Render.status

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

Renders a label, indicator and a chart.

Parameters

src/render/Render.js:631 · Usages · Examples

Matter.Render.stop

(render)

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

Parameters

src/render/Render.js:162 · Usages · Examples

Matter.Render.vertexNumbers

(render, bodies, context)
private

Renders body vertex numbers.

Parameters

src/render/Render.js:944 · Usages · Examples

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

src/render/Render.js:350 · Usages · Examples

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.

src/render/Render.js:1608 · Usages · Examples

Render.canvas

HTMLCanvasElement

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

Default: null

src/render/Render.js:1600 · Usages · Examples

Render.context

CanvasRenderingContext2D

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

src/render/Render.js:1618 · Usages · Examples

Render.controller

Render
deprecated

A back-reference to the Matter.Render module.

src/render/Render.js:1577 · Usages · Examples

Render.element

HTMLElement

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

Default: null

src/render/Render.js:1592 · Usages · Examples

Render.engine

Engine

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

src/render/Render.js:1585 · Usages · Examples

Render.mouse

Mouse

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

Default: null

src/render/Render.js:1632 · Usages · Examples

Render.options

The configuration options of the renderer.

src/render/Render.js:1640 · Usages · Examples

Render.options.background

String

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

Default: '#14151f'

src/render/Render.js:1673 · Usages · Examples

Render.options.enabled

Boolean

A flag to enable or disable rendering entirely.

Default: false

src/render/Render.js:1756 · Usages · Examples

Render.options.hasBounds

Boolean

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

Default: false

src/render/Render.js:1700 · Usages · Examples

Render.options.height

Number

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

Default: 600

src/render/Render.js:1656 · Usages · Examples

Render.options.pixelRatio

Number

The pixel ratio to use when rendering.

Default: 1

src/render/Render.js:1665 · Usages · Examples

Render.options.showAngleIndicator

Boolean

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

Default: false

src/render/Render.js:1845 · Usages · Examples

Render.options.showAxes

Boolean

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

Default: false

src/render/Render.js:1829 · Usages · Examples

Render.options.showBounds

Boolean

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

Default: false

src/render/Render.js:1797 · Usages · Examples

Render.options.showBroadphase

Boolean
deprecated

Deprecated: no longer implemented

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

Default: false

src/render/Render.js:1788 · Usages · Examples

Render.options.showCollisions

Boolean

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

Default: false

src/render/Render.js:1813 · Usages · Examples

Render.options.showConvexHulls

Boolean

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

Default: false

src/render/Render.js:1869 · Usages · Examples

Render.options.showDebug

Boolean

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

src/render/Render.js:1708 · Usages · Examples

Render.options.showDebug

Boolean

A flag to enable or disable the debug information overlay.

Default: false

src/render/Render.js:1780 · Usages · Examples

Render.options.showIds

Boolean

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

Default: false

src/render/Render.js:1853 · Usages · Examples

Render.options.showInternalEdges

Boolean

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

Default: false

src/render/Render.js:1877 · Usages · Examples

Render.options.showMousePosition

Boolean

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

Default: false

src/render/Render.js:1885 · Usages · Examples

Render.options.showPerformance

Boolean

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

src/render/Render.js:1735 · Usages · Examples

Render.options.showPositions

Boolean

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

Default: false

src/render/Render.js:1837 · Usages · Examples

Render.options.showSeparations

Boolean

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

Default: false

src/render/Render.js:1821 · Usages · Examples

Render.options.showSleeping

Boolean

A flag to enable or disable sleeping bodies indicators.

Default: true

src/render/Render.js:1772 · Usages · Examples

Render.options.showStats

Boolean

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

src/render/Render.js:1720 · Usages · Examples

Render.options.showVelocity

Boolean

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

Default: false

src/render/Render.js:1805 · Usages · Examples

Render.options.showVertexNumbers

Boolean

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

Default: false

src/render/Render.js:1861 · Usages · Examples

Render.options.width

Number

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

Default: 800

src/render/Render.js:1647 · Usages · Examples

Render.options.wireframeBackground

String

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'

src/render/Render.js:1682 · Usages · Examples

Render.options.wireframes

Boolean

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

Default: true

src/render/Render.js:1764 · Usages · Examples

Render.options.wireframeStrokeStyle

String

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'

src/render/Render.js:1691 · Usages · Examples

Render.textures

The sprite texture cache.

src/render/Render.js:1625 · Usages · Examples

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

src/render/Render.js:1561 · Usages · Examples

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

src/render/Render.js:1551 · Usages · Examples