Merge branch 'decouple-renderer'

README.md

@@ -103,7 +103,6 @@ See how others are using matter.js physics
 - Collision queries (raycasting, region tests)
 - Time scaling (slow-mo, speed-up)
 - Canvas renderer (supports vectors and textures)
-- WebGL renderer (requires [pixi.js](https://github.com/GoodBoyDigital/pixi.js/))
 - [MatterTools](https://github.com/liabru/matter-tools) for creating, testing and debugging worlds
 - World state serialisation (requires [resurrect.js](https://github.com/skeeto/resurrect-js))
 - Cross-browser (Chrome, Firefox, Safari, IE8+)
@@ -173,7 +172,7 @@ The engine uses the following techniques:
 - Constraints solved with the Gauss-Siedel method
 - Semi-variable time step, synced with rendering
 -   A basic sleeping strategy
-- HTML5 Canvas / WebGL renderer
+- HTML5 Canvas rendering
 
 For more information see my post on [Game physics for beginners](http://brm.io/game-physics-for-beginners/).
 

demo/js/Demo.js

@@ -33,7 +33,8 @@
         Events = Matter.Events,
         Mouse = Matter.Mouse,
         MouseConstraint = Matter.MouseConstraint,
-        Runner = Matter.Runner;
+        Runner = Matter.Runner,
+        Render = Matter.Render;
 
     // MatterTools aliases
     if (window.MatterTools) {
@@ -64,12 +65,24 @@
         // run the engine
         demo.runner = Engine.run(demo.engine);
 
+        // create a debug renderer
+        demo.render = Render.create({
+            element: demo.container,
+            engine: demo.engine
+        });
+
+        // run the renderer
+        Render.run(demo.render);
+
         // add a mouse controlled constraint
-        demo.mouseConstraint = MouseConstraint.create(demo.engine);
+        demo.mouseConstraint = MouseConstraint.create(demo.engine, {
+            element: demo.render.canvas
+        });
+        
         World.add(demo.engine.world, demo.mouseConstraint);
 
         // pass mouse to renderer to enable showMousePosition
-        demo.engine.render.mouse = demo.mouseConstraint.mouse;
+        demo.render.mouse = demo.mouseConstraint.mouse;
 
         // get the scene function name from hash
         if (window.location.hash.length !== 0) 
@@ -108,23 +121,21 @@
 
         // create a Matter.Gui
         if (!_isMobile && Gui) {
-            demo.gui = Gui.create(demo.engine, demo.runner);
+            demo.gui = Gui.create(demo.engine, demo.runner, demo.render);
 
             // need to add mouse constraint back in after gui clear or load is pressed
             Events.on(demo.gui, 'clear load', function() {
-                demo.mouseConstraint = MouseConstraint.create(demo.engine);
+                demo.mouseConstraint = MouseConstraint.create(demo.engine, {
-                World.add(demo.engine.world, demo.mouseConstraint);
+                    element: demo.render.canvas
-            });
+                });
 
-            // need to rebind mouse on render change
+                World.add(demo.engine.world, demo.mouseConstraint);
-            Events.on(demo.gui, 'setRenderer', function() {
-                Mouse.setElement(demo.mouseConstraint.mouse, demo.engine.render.canvas);
             });
         }
 
         // create a Matter.Inspector
         if (!_isMobile && Inspector && _useInspector) {
-            demo.inspector = Inspector.create(demo.engine, demo.runner);
+            demo.inspector = Inspector.create(demo.engine, demo.runner, demo.render);
 
             Events.on(demo.inspector, 'import', function() {
                 demo.mouseConstraint = MouseConstraint.create(demo.engine);
@@ -150,7 +161,7 @@
             var body = document.body;
 
             body.className += ' is-mobile';
-            demo.engine.render.canvas.addEventListener('touchstart', Demo.fullscreen);
+            demo.render.canvas.addEventListener('touchstart', Demo.fullscreen);
 
             var fullscreenChange = function() {
                 var fullscreenEnabled = document.fullscreenEnabled || document.mozFullScreenEnabled || document.webkitFullscreenEnabled;
@@ -248,7 +259,7 @@
     };
 
     Demo.fullscreen = function(demo) {
-        var _fullscreenElement = demo.engine.render.canvas;
+        var _fullscreenElement = demo.render.canvas;
         
         if (!document.fullscreenElement && !document.mozFullScreenElement && !document.webkitFullscreenElement) {
             if (_fullscreenElement.requestFullscreen) {
@@ -269,10 +280,10 @@
         Engine.clear(demo.engine);
 
         // clear scene graph (if defined in controller)
-        if (demo.engine.render) {
+        if (demo.render) {
-            var renderController = demo.engine.render.controller;
+            var renderController = demo.render.controller;
             if (renderController && renderController.clear)
-                renderController.clear(demo.engine.render);
+                renderController.clear(demo.render);
         }
 
         // clear all scene events
@@ -296,9 +307,9 @@
                 Events.off(demo.runner, demo.sceneEvents[i]);
         }
 
-        if (demo.engine.render && demo.engine.render.events) {
+        if (demo.render && demo.render.events) {
             for (i = 0; i < demo.sceneEvents.length; i++)
-                Events.off(demo.engine.render, demo.sceneEvents[i]);
+                Events.off(demo.render, demo.sceneEvents[i]);
         }
 
         demo.sceneEvents = [];
@@ -335,8 +346,8 @@
             World.add(world, demo.mouseConstraint);
         }
         
-        if (demo.engine.render) {
+        if (demo.render) {
-            var renderOptions = demo.engine.render.options;
+            var renderOptions = demo.render.options;
             renderOptions.wireframes = true;
             renderOptions.hasBounds = false;
             renderOptions.showDebug = false;

demo/js/lib/matter-tools/matter-tools-dev.js

@@ -1,5 +1,5 @@
 /**
-* matter-tools-dev.min.js 0.5.0-dev 2015-12-05
+* matter-tools-dev.min.js 0.5.0-dev 2016-04-26
 * https://github.com/liabru/matter-tools
 * License: MIT
 */
@@ -10,7 +10,7 @@
   var Gui = {};
   (function() {
     var _isWebkit = "WebkitAppearance" in document.documentElement.style;
-    Gui.create = function(engine, runner, options) {
+    Gui.create = function(engine, runner, render, options) {
       var _datGuiSupported = window.dat && window.localStorage;
       if (!_datGuiSupported) {
         console.log("Could not create GUI. Check dat.gui library is loaded first.");
@@ -20,6 +20,7 @@
       var gui = {
         engine:engine,
         runner:runner,
+        render:render,
         datGui:datGui,
         broadphase:"grid",
         broadphaseCache:{
@@ -116,7 +117,7 @@
           Events.trigger(gui, "load");
         },
         inspect:function() {
-          if (!Inspector.instance) gui.inspector = Inspector.create(gui.engine, gui.runner);
+          if (!Inspector.instance) gui.inspector = Inspector.create(gui.engine, gui.runner, gui.render);
         },
         recordGif:function() {
           if (!gui.isRecording) {
@@ -201,40 +202,24 @@
       physics.add(runner, "enabled");
       physics.open();
       var render = datGui.addFolder("Render");
-      render.add(gui, "renderer", [ "canvas", "webgl" ]).onFinishChange(function(value) {
+      render.add(gui.render.options, "wireframes");
-        _setRenderer(gui, value);
+      render.add(gui.render.options, "showDebug");
-      });
+      render.add(gui.render.options, "showPositions");
-      render.add(engine.render.options, "wireframes");
+      render.add(gui.render.options, "showBroadphase");
-      render.add(engine.render.options, "showDebug");
+      render.add(gui.render.options, "showBounds");
-      render.add(engine.render.options, "showPositions");
+      render.add(gui.render.options, "showVelocity");
-      render.add(engine.render.options, "showBroadphase");
+      render.add(gui.render.options, "showCollisions");
-      render.add(engine.render.options, "showBounds");
+      render.add(gui.render.options, "showSeparations");
-      render.add(engine.render.options, "showVelocity");
+      render.add(gui.render.options, "showAxes");
-      render.add(engine.render.options, "showCollisions");
+      render.add(gui.render.options, "showAngleIndicator");
-      render.add(engine.render.options, "showSeparations");
+      render.add(gui.render.options, "showSleeping");
-      render.add(engine.render.options, "showAxes");
+      render.add(gui.render.options, "showIds");
-      render.add(engine.render.options, "showAngleIndicator");
+      render.add(gui.render.options, "showVertexNumbers");
-      render.add(engine.render.options, "showSleeping");
+      render.add(gui.render.options, "showConvexHulls");
-      render.add(engine.render.options, "showIds");
+      render.add(gui.render.options, "showInternalEdges");
-      render.add(engine.render.options, "showVertexNumbers");
+      render.add(gui.render.options, "enabled");
-      render.add(engine.render.options, "showConvexHulls");
-      render.add(engine.render.options, "showInternalEdges");
-      render.add(engine.render.options, "enabled");
       render.open();
     };
-    var _setRenderer = function(gui, rendererName) {
-      var engine = gui.engine, controller;
-      if (rendererName === "canvas") controller = Render;
-      if (rendererName === "webgl") controller = RenderPixi;
-      engine.render.element.removeChild(engine.render.canvas);
-      var options = engine.render.options;
-      engine.render = controller.create({
-        element:engine.render.element,
-        options:options
-      });
-      engine.render.options = options;
-      Events.trigger(gui, "setRenderer");
-    };
     var _addBody = function(gui) {
       var engine = gui.engine;
       var options = {
@@ -257,8 +242,8 @@
       var engine = gui.engine;
       World.clear(engine.world, true);
       Engine.clear(engine);
-      var renderController = engine.render.controller;
+      var renderController = gui.render.controller;
-      if (renderController.clear) renderController.clear(engine.render);
+      if (renderController.clear) renderController.clear(gui.render);
       Events.trigger(gui, "clear");
     };
     var _initGif = function(gui) {
@@ -268,7 +253,7 @@
       var engine = gui.engine, skipFrame = false;
       Matter.Events.on(gui.runner, "beforeTick", function(event) {
         if (gui.isRecording && !skipFrame) {
-          gui.gif.addFrame(engine.render.context, {
+          gui.gif.addFrame(gui.render.context, {
             copy:true,
             delay:25
           });
@@ -280,14 +265,15 @@
   var Inspector = {};
   (function() {
     var _key, _isWebkit = "WebkitAppearance" in document.documentElement.style, $body;
-    Inspector.create = function(engine, runner, options) {
+    Inspector.create = function(engine, runner, render, options) {
       if (!jQuery || !$.fn.jstree || !window.key) {
         console.log("Could not create inspector. Check keymaster, jQuery, jsTree libraries are loaded first.");
         return;
       }
       var inspector = {
-        engine:engine,
+        engine:null,
-        runner:runner,
+        runner:null,
+        render:null,
         isPaused:false,
         selected:[],
         selectStart:null,
@@ -317,7 +303,10 @@
       };
       inspector = Common.extend(inspector, options);
       Inspector.instance = inspector;
-      inspector.mouse = Mouse.create(engine.render.canvas);
+      inspector.engine = engine;
+      inspector.runner = runner;
+      inspector.render = render;
+      inspector.mouse = Mouse.create(inspector.render.canvas);
       inspector.mouseConstraint = MouseConstraint.create(engine, {
         mouse:inspector.mouse
       });
@@ -670,8 +659,8 @@
           _updateSelectedMouseDownOffset(inspector);
         }
       });
-      Events.on(inspector.engine.render, "afterRender", function() {
+      Events.on(inspector.render, "afterRender", function() {
-        var renderController = engine.render.controller, context = engine.render.context;
+        var renderController = inspector.render.controller, context = inspector.render.context;
         if (renderController.inspector) renderController.inspector(inspector, context);
       });
     };

examples/airFriction.js

@@ -23,7 +23,7 @@ if (!_isBrowser) {
             Bodies.rectangle(600, 100, 60, 60, { frictionAir: 0.1 })
         ]);
 
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showAngleIndicator = false;
         renderOptions.showVelocity = true;
     };

examples/broadphase.js

@@ -27,7 +27,7 @@
         
         World.add(world, stack);
         
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showBroadphase = true;
     };
     

examples/car.js

@@ -21,7 +21,7 @@
             Bodies.rectangle(340, 580, 700, 20, { isStatic: true, angle: Math.PI * 0.04 })
         ]);
         
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showAngleIndicator = true;
         renderOptions.showCollisions = true;
     };

examples/catapult.js

@@ -24,7 +24,7 @@
             Constraint.create({ bodyA: catapult, pointB: { x: 410, y: 580 } })
         ]);
         
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showCollisions = true;
         renderOptions.showVelocity = true;
         renderOptions.showAngleIndicator = true;

examples/collisionFiltering.js

@@ -88,7 +88,7 @@
         // red category objects should not be draggable with the mouse
         mouseConstraint.collisionFilter.mask = defaultCategory | blueCategory | greenCategory;
 
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.wireframes = false;
         renderOptions.background = '#222';
         renderOptions.showAngleIndicator = false;

examples/compositeManipulation.js

@@ -42,7 +42,7 @@
             })
         );
 
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.wireframes = false;
         renderOptions.showAxes = true;
         renderOptions.showCollisions = true;

examples/compound.js

@@ -40,7 +40,7 @@
 
         World.add(world, [compoundBodyA, compoundBodyB, constraint]);
         
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showAxes = true;
         renderOptions.showPositions = true;
         renderOptions.showConvexHulls = true;

examples/concave.js

@@ -27,7 +27,7 @@
 
         World.add(world, stack);
 
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showAngleIndicator = false;
     };
 

examples/engine.js

@@ -11,7 +11,7 @@
             metrics: { extended: true }
         };
 
-        return Engine.create(demo.container, options);
+        return Engine.create(options);
     };
 
 })();

examples/events.js

@@ -92,7 +92,7 @@
             Events.on(mouseConstraint, 'mousedown', function(event) {
                 var mousePosition = event.mouse.position;
                 console.log('mousedown at ' + mousePosition.x + ' ' + mousePosition.y);
-                engine.render.options.background = 'cornsilk';
+                demo.render.options.background = 'cornsilk';
                 shakeScene(engine);
             })
 
@@ -103,7 +103,7 @@
             // an example of using mouse events on a mouse
             Events.on(mouseConstraint, 'mouseup', function(event) {
                 var mousePosition = event.mouse.position;
-                engine.render.options.background = "white";
+                demo.render.options.background = "white";
                 console.log('mouseup at ' + mousePosition.x + ' ' + mousePosition.y);
             })
 
@@ -135,7 +135,7 @@
         
         World.add(world, stack);
 
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.wireframes = false;
 
         var shakeScene = function(engine) {

examples/friction.js

@@ -22,7 +22,7 @@
             Bodies.rectangle(300, 430, 40, 40, { friction: 0 })
         ]);
 
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showAngleIndicator = false;
         renderOptions.showVelocity = true;
     };

examples/manipulation.js

@@ -73,7 +73,7 @@
             })
         );
 
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showAxes = true;
         renderOptions.showCollisions = true;
         renderOptions.showPositions = true;

examples/mixedSolid.js

@@ -27,7 +27,7 @@
         
         World.add(world, stack);
         
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.wireframes = false;
         renderOptions.showAngleIndicator = false;
     };

examples/newtonsCradle.js

@@ -16,7 +16,7 @@
         World.add(world, cradle);
         Body.translate(cradle.bodies[0], { x: -140, y: -100 });
         
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showVelocity = true;
     };
 

examples/raycasting.js

@@ -38,9 +38,9 @@
         World.add(world, [stack, concave]);
 
         sceneEvents.push(
-            Events.on(engine.render, 'afterRender', function() {
+            Events.on(demo.render, 'afterRender', function() {
                 var mouse = mouseConstraint.mouse,
-                    context = engine.render.context,
+                    context = demo.render.context,
                     bodies = Composite.allBodies(engine.world),
                     startPoint = { x: 400, y: 100 },
                     endPoint = mouse.position;

examples/restitution.js

@@ -18,7 +18,7 @@
             Bodies.rectangle(100 + space * 5, 150, 180, 20, { restitution: rest, angle: -Math.PI * 0.5 })
         ]);
         
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showCollisions = true;
         renderOptions.showVelocity = true;
         renderOptions.showAngleIndicator = true;

examples/rounded.js

@@ -41,7 +41,7 @@
             })
         ]);
 
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showAxes = true;
         renderOptions.showCollisions = true;
     };

examples/sensors.js

@@ -62,7 +62,7 @@
             })
         );
 
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.wireframes = false;
         renderOptions.background = '#222';
         renderOptions.showAngleIndicator = false;

examples/slingshot.js

@@ -55,7 +55,7 @@
             }
         });
         
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.wireframes = false;
         renderOptions.showAngleIndicator = false;
         renderOptions.background = './img/background.png';

examples/softBody.js

@@ -19,7 +19,7 @@
             Composites.softBody(250, 400, 4, 4, 0, 0, true, 15, particleOptions)
         ]);
 
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showAngleIndicator = false;
     };
 

examples/sprites.js

@@ -53,7 +53,7 @@
 
         World.add(world, stack);
 
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.background = './img/wall-bg.jpg';
         renderOptions.showAngleIndicator = false;
         renderOptions.wireframes = false;

examples/staticFriction.js

@@ -41,7 +41,7 @@
             })
         );
 
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showAngleIndicator = false;
         renderOptions.showVelocity = true;
     };

examples/stress.js

@@ -14,7 +14,7 @@
         
         World.add(world, stack);
 
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showAngleIndicator = false;
     };
 

examples/stress2.js

@@ -14,7 +14,7 @@
         
         World.add(world, stack);
         
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showAngleIndicator = false;
     };
 

examples/svg.js

@@ -54,7 +54,7 @@
             }, true));
         });
 
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showAngleIndicator = false;
     };
 

examples/terrain.js

@@ -46,7 +46,7 @@
             }));
         });
 
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.showAngleIndicator = false;
         renderOptions.showVelocity = true;
     };

examples/views.js

@@ -36,8 +36,8 @@
 
         // get the centre of the viewport
         var viewportCentre = {
-            x: engine.render.options.width * 0.5,
+            x: demo.render.options.width * 0.5,
-            y: engine.render.options.height * 0.5
+            y: demo.render.options.height * 0.5
         };
 
         // make the world bounds a little bigger than the render bounds
@@ -58,7 +58,7 @@
             Events.on(engine, 'beforeTick', function() {
                 var world = engine.world,
                     mouse = mouseConstraint.mouse,
-                    render = engine.render,
+                    render = demo.render,
                     translate;
 
                 // mouse wheel controls zoom
@@ -128,7 +128,7 @@
         );
 
         // must enable renderOptions.hasBounds for views to work
-        var renderOptions = engine.render.options;
+        var renderOptions = demo.render.options;
         renderOptions.hasBounds = true;
     };
 

src/constraint/MouseConstraint.js

@@ -38,9 +38,11 @@ var Bounds = require('../geometry/Bounds');
         if (!mouse) {
             if (engine && engine.render && engine.render.canvas) {
                 mouse = Mouse.create(engine.render.canvas);
+            } else if (options && options.element) {
+                mouse = Mouse.create(options.element);
             } else {
                 mouse = Mouse.create();
-                Common.log('MouseConstraint.create: options.mouse was undefined, engine.render.canvas was undefined, may not function as expected', 'warn');
+                Common.log('MouseConstraint.create: options.mouse was undefined, options.element was undefined, may not function as expected', 'warn');
             }
         }
 
@@ -60,6 +62,7 @@ var Bounds = require('../geometry/Bounds');
         var defaults = {
             type: 'mouseConstraint',
             mouse: mouse,
+            element: null,
             body: null,
             constraint: constraint,
             collisionFilter: {

src/core/Engine.js

@@ -32,7 +32,6 @@ var Body = require('../body/Body');
      * 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.
      * @method create
-     * @param {HTMLElement} [element]
      * @param {object} [options]
      * @return {engine} engine
      */
@@ -40,9 +39,12 @@ var Body = require('../body/Body');
         // options may be passed as the first (and only) argument
         options = Common.isElement(element) ? options : element;
         element = Common.isElement(element) ? element : null;
-        
         options = options || {};
 
+        if (element || options.render) {
+            Common.log('Engine.create: engine.render is deprecated (see docs)', 'warn');
+        }
+
         var defaults = {
             positionIterations: 6,
             velocityIterations: 4,
@@ -60,6 +62,7 @@ var Body = require('../body/Body');
 
         var engine = Common.extend(defaults, options);
 
+        // @deprecated
         if (element || engine.render) {
             var renderDefaults = {
                 element: element,
@@ -69,10 +72,16 @@ var Body = require('../body/Body');
             engine.render = Common.extend(renderDefaults, engine.render);
         }
 
+        // @deprecated
         if (engine.render && engine.render.controller) {
             engine.render = engine.render.controller.create(engine.render);
         }
 
+        // @deprecated
+        if (engine.render) {
+            engine.render.engine = engine;
+        }
+
         engine.world = options.world || World.create(engine.world);
         engine.pairs = Pairs.create();
         engine.broadphase = engine.broadphase.controller.create(engine.broadphase);
@@ -462,6 +471,7 @@ var Body = require('../body/Body');
      *
      * @property render
      * @type render
+     * @deprecated see Demo.js for an example of creating a renderer
      * @default a Matter.Render instance
      */
 

src/core/Runner.js

@@ -1,10 +1,9 @@
 /**
 * The `Matter.Runner` module is an optional utility which provides a game loop, 
-* that handles updating and rendering a `Matter.Engine` for you within a browser.
+* that handles continuously updating a `Matter.Engine` for you within a browser.
-* It is intended for demo and testing purposes, but may be adequate for simple games.
+* It is intended for development and debugging purposes, but may also be suitable for simple games.
 * If you are using your own game loop instead, then you do not need the `Matter.Runner` module.
 * Instead just call `Engine.update(engine, delta)` in your own loop.
-* Note that the method `Engine.run` is an alias for `Runner.run`.
 *
 * See the included usage [examples](https://github.com/liabru/matter-js/tree/master/examples).
 *
@@ -168,11 +167,12 @@ var Common = require('./Common');
         Events.trigger(runner, 'afterUpdate', event);
 
         // render
+        // @deprecated
         if (engine.render && engine.render.controller) {
             Events.trigger(runner, 'beforeRender', event);
             Events.trigger(engine, 'beforeRender', event); // @deprecated
 
-            engine.render.controller.world(engine);
+            engine.render.controller.world(engine.render);
 
             Events.trigger(runner, 'afterRender', event);
             Events.trigger(engine, 'afterRender', event); // @deprecated
@@ -266,6 +266,7 @@ var Common = require('./Common');
     * @param {number} event.timestamp The engine.timing.timestamp of the event
     * @param {} event.source The source object of the event
     * @param {} event.name The name of the event
+    * @deprecated
     */
 
     /**
@@ -276,6 +277,7 @@ var Common = require('./Common');
     * @param {number} event.timestamp The engine.timing.timestamp of the event
     * @param {} event.source The source object of the event
     * @param {} event.name The name of the event
+    * @deprecated
     */
 
     /*

src/render/Render.js

@@ -1,11 +1,7 @@
 /**
-* The `Matter.Render` module is the default `render.controller` used by a `Matter.Engine`.
+* The `Matter.Render` module is a simple HTML5 canvas based renderer for visualising instances of `Matter.Engine`.
-* This renderer is HTML5 canvas based and supports a number of drawing options including sprites and viewports.
+* 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.
-* It is possible develop a custom renderer module based on `Matter.Render` and pass an instance of it to `Engine.create` via `options.render`.
-* A minimal custom renderer object must define at least three functions: `create`, `clear` and `world` (see `Matter.Render`).
-*
-* See also `Matter.RenderPixi` for an alternate WebGL, scene-graph based renderer.
 *
 * @class Render
 */
@@ -23,6 +19,18 @@ var Vector = require('../geometry/Vector');
 
 (function() {
     
+    var _requestAnimationFrame,
+        _cancelAnimationFrame;
+
+    if (typeof window !== 'undefined') {
+        _requestAnimationFrame = window.requestAnimationFrame || window.webkitRequestAnimationFrame
+                                      || window.mozRequestAnimationFrame || window.msRequestAnimationFrame 
+                                      || function(callback){ window.setTimeout(function() { callback(Common.now()); }, 1000 / 60); };
+   
+        _cancelAnimationFrame = window.cancelAnimationFrame || window.mozCancelAnimationFrame 
+                                      || window.webkitCancelAnimationFrame || window.msCancelAnimationFrame;
+    }
+
     /**
      * 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.
@@ -34,9 +42,11 @@ var Vector = require('../geometry/Vector');
     Render.create = function(options) {
         var defaults = {
             controller: Render,
+            engine: null,
             element: null,
             canvas: null,
             mouse: null,
+            frameRequestId: null,
             options: {
                 width: 800,
                 height: 600,
@@ -72,6 +82,8 @@ var Vector = require('../geometry/Vector');
             render.canvas.height = render.options.height || render.canvas.height;
         }
 
+        render.mouse = options.mouse;
+        render.engine = options.engine;
         render.canvas = render.canvas || _createCanvas(render.options.width, render.options.height);
         render.context = render.canvas.getContext('2d');
         render.textures = {};
@@ -100,6 +112,27 @@ var Vector = require('../geometry/Vector');
         return render;
     };
 
+    /**
+     * Continuously updates the render canvas on the `requestAnimationFrame` event.
+     * @method run
+     * @param {render} render
+     */
+    Render.run = function(render) {
+        (function loop(time){
+            render.frameRequestId = _requestAnimationFrame(loop);
+            Render.world(render);
+        })();
+    };
+
+    /**
+     * Ends execution of `Render.run` on the given `render`, by canceling the animation frame request event loop.
+     * @method stop
+     * @param {render} render
+     */
+    Render.stop = function(render) {
+        _cancelAnimationFrame(render.frameRequestId);
+    };
+
     /**
      * Sets the pixel ratio of the renderer and updates the canvas.
      * To automatically detect the correct ratio, pass the string `'auto'` for `pixelRatio`.
@@ -128,10 +161,10 @@ var Vector = require('../geometry/Vector');
      * 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.
      * @method world
-     * @param {engine} engine
+     * @param {render} render
      */
-    Render.world = function(engine) {
+    Render.world = function(render) {
-        var render = engine.render,
+        var engine = render.engine,
             world = engine.world,
             canvas = render.canvas,
             context = render.context,
@@ -201,49 +234,49 @@ var Vector = require('../geometry/Vector');
 
         if (!options.wireframes || (engine.enableSleeping && options.showSleeping)) {
             // fully featured rendering of bodies
-            Render.bodies(engine, bodies, context);
+            Render.bodies(render, bodies, context);
         } else {
             if (options.showConvexHulls)
-                Render.bodyConvexHulls(engine, bodies, context);
+                Render.bodyConvexHulls(render, bodies, context);
 
             // optimised method for wireframes only
-            Render.bodyWireframes(engine, bodies, context);
+            Render.bodyWireframes(render, bodies, context);
         }
 
         if (options.showBounds)
-            Render.bodyBounds(engine, bodies, context);
+            Render.bodyBounds(render, bodies, context);
 
         if (options.showAxes || options.showAngleIndicator)
-            Render.bodyAxes(engine, bodies, context);
+            Render.bodyAxes(render, bodies, context);
         
         if (options.showPositions)
-            Render.bodyPositions(engine, bodies, context);
+            Render.bodyPositions(render, bodies, context);
 
         if (options.showVelocity)
-            Render.bodyVelocity(engine, bodies, context);
+            Render.bodyVelocity(render, bodies, context);
 
         if (options.showIds)
-            Render.bodyIds(engine, bodies, context);
+            Render.bodyIds(render, bodies, context);
 
         if (options.showSeparations)
-            Render.separations(engine, engine.pairs.list, context);
+            Render.separations(render, engine.pairs.list, context);
 
         if (options.showCollisions)
-            Render.collisions(engine, engine.pairs.list, context);
+            Render.collisions(render, engine.pairs.list, context);
 
         if (options.showVertexNumbers)
-            Render.vertexNumbers(engine, bodies, context);
+            Render.vertexNumbers(render, bodies, context);
 
         if (options.showMousePosition)
-            Render.mousePosition(engine, render.mouse, context);
+            Render.mousePosition(render, render.mouse, context);
 
         Render.constraints(constraints, context);
 
         if (options.showBroadphase && engine.broadphase.controller === Grid)
-            Render.grid(engine, engine.broadphase, context);
+            Render.grid(render, engine.broadphase, context);
 
         if (options.showDebug)
-            Render.debug(engine, context);
+            Render.debug(render, context);
 
         if (options.hasBounds) {
             // revert view transforms
@@ -257,13 +290,13 @@ var Vector = require('../geometry/Vector');
      * Description
      * @private
      * @method debug
-     * @param {engine} engine
+     * @param {render} render
      * @param {RenderingContext} context
      */
-    Render.debug = function(engine, context) {
+    Render.debug = function(render, context) {
         var c = context,
+            engine = render.engine,
             world = engine.world,
-            render = engine.render,
             metrics = engine.metrics,
             options = render.options,
             bodies = Composite.allBodies(world),
@@ -362,13 +395,13 @@ var Vector = require('../geometry/Vector');
      * Description
      * @private
      * @method bodyShadows
-     * @param {engine} engine
+     * @param {render} render
      * @param {body[]} bodies
      * @param {RenderingContext} context
      */
-    Render.bodyShadows = function(engine, bodies, context) {
+    Render.bodyShadows = function(render, bodies, context) {
         var c = context,
-            render = engine.render;
+            engine = render.engine;
 
         for (var i = 0; i < bodies.length; i++) {
             var body = bodies[i];
@@ -411,13 +444,13 @@ var Vector = require('../geometry/Vector');
      * Description
      * @private
      * @method bodies
-     * @param {engine} engine
+     * @param {render} render
      * @param {body[]} bodies
      * @param {RenderingContext} context
      */
-    Render.bodies = function(engine, bodies, context) {
+    Render.bodies = function(render, bodies, context) {
         var c = context,
-            render = engine.render,
+            engine = render.engine,
             options = render.options,
             showInternalEdges = options.showInternalEdges || !options.wireframes,
             body,
@@ -510,13 +543,13 @@ var Vector = require('../geometry/Vector');
      * Optimised method for drawing body wireframes in one pass
      * @private
      * @method bodyWireframes
-     * @param {engine} engine
+     * @param {render} render
      * @param {body[]} bodies
      * @param {RenderingContext} context
      */
-    Render.bodyWireframes = function(engine, bodies, context) {
+    Render.bodyWireframes = function(render, bodies, context) {
         var c = context,
-            showInternalEdges = engine.render.options.showInternalEdges,
+            showInternalEdges = render.options.showInternalEdges,
             body,
             part,
             i,
@@ -563,11 +596,11 @@ var Vector = require('../geometry/Vector');
      * Optimised method for drawing body convex hull wireframes in one pass
      * @private
      * @method bodyConvexHulls
-     * @param {engine} engine
+     * @param {render} render
      * @param {body[]} bodies
      * @param {RenderingContext} context
      */
-    Render.bodyConvexHulls = function(engine, bodies, context) {
+    Render.bodyConvexHulls = function(render, bodies, context) {
         var c = context,
             body,
             part,
@@ -602,11 +635,11 @@ var Vector = require('../geometry/Vector');
      * Renders body vertex numbers.
      * @private
      * @method vertexNumbers
-     * @param {engine} engine
+     * @param {render} render
      * @param {body[]} bodies
      * @param {RenderingContext} context
      */
-    Render.vertexNumbers = function(engine, bodies, context) {
+    Render.vertexNumbers = function(render, bodies, context) {
         var c = context,
             i,
             j,
@@ -628,11 +661,11 @@ var Vector = require('../geometry/Vector');
      * Renders mouse position.
      * @private
      * @method mousePosition
-     * @param {engine} engine
+     * @param {render} render
      * @param {mouse} mouse
      * @param {RenderingContext} context
      */
-    Render.mousePosition = function(engine, mouse, context) {
+    Render.mousePosition = function(render, mouse, context) {
         var c = context;
         c.fillStyle = 'rgba(255,255,255,0.8)';
         c.fillText(mouse.position.x + '  ' + mouse.position.y, mouse.position.x + 5, mouse.position.y - 5);
@@ -642,13 +675,13 @@ var Vector = require('../geometry/Vector');
      * Draws body bounds
      * @private
      * @method bodyBounds
-     * @param {engine} engine
+     * @param {render} render
      * @param {body[]} bodies
      * @param {RenderingContext} context
      */
-    Render.bodyBounds = function(engine, bodies, context) {
+    Render.bodyBounds = function(render, bodies, context) {
         var c = context,
-            render = engine.render,
+            engine = render.engine,
             options = render.options;
 
         c.beginPath();
@@ -679,13 +712,13 @@ var Vector = require('../geometry/Vector');
      * Draws body angle indicators and axes
      * @private
      * @method bodyAxes
-     * @param {engine} engine
+     * @param {render} render
      * @param {body[]} bodies
      * @param {RenderingContext} context
      */
-    Render.bodyAxes = function(engine, bodies, context) {
+    Render.bodyAxes = function(render, bodies, context) {
         var c = context,
-            render = engine.render,
+            engine = render.engine,
             options = render.options,
             part,
             i,
@@ -740,13 +773,13 @@ var Vector = require('../geometry/Vector');
      * Draws body positions
      * @private
      * @method bodyPositions
-     * @param {engine} engine
+     * @param {render} render
      * @param {body[]} bodies
      * @param {RenderingContext} context
      */
-    Render.bodyPositions = function(engine, bodies, context) {
+    Render.bodyPositions = function(render, bodies, context) {
         var c = context,
-            render = engine.render,
+            engine = render.engine,
             options = render.options,
             body,
             part,
@@ -796,11 +829,11 @@ var Vector = require('../geometry/Vector');
      * Draws body velocity
      * @private
      * @method bodyVelocity
-     * @param {engine} engine
+     * @param {render} render
      * @param {body[]} bodies
      * @param {RenderingContext} context
      */
-    Render.bodyVelocity = function(engine, bodies, context) {
+    Render.bodyVelocity = function(render, bodies, context) {
         var c = context;
 
         c.beginPath();
@@ -824,11 +857,11 @@ var Vector = require('../geometry/Vector');
      * Draws body ids
      * @private
      * @method bodyIds
-     * @param {engine} engine
+     * @param {render} render
      * @param {body[]} bodies
      * @param {RenderingContext} context
      */
-    Render.bodyIds = function(engine, bodies, context) {
+    Render.bodyIds = function(render, bodies, context) {
         var c = context,
             i,
             j;
@@ -851,13 +884,13 @@ var Vector = require('../geometry/Vector');
      * Description
      * @private
      * @method collisions
-     * @param {engine} engine
+     * @param {render} render
      * @param {pair[]} pairs
      * @param {RenderingContext} context
      */
-    Render.collisions = function(engine, pairs, context) {
+    Render.collisions = function(render, pairs, context) {
         var c = context,
-            options = engine.render.options,
+            options = render.options,
             pair,
             collision,
             corrected,
@@ -934,13 +967,13 @@ var Vector = require('../geometry/Vector');
      * Description
      * @private
      * @method separations
-     * @param {engine} engine
+     * @param {render} render
      * @param {pair[]} pairs
      * @param {RenderingContext} context
      */
-    Render.separations = function(engine, pairs, context) {
+    Render.separations = function(render, pairs, context) {
         var c = context,
-            options = engine.render.options,
+            options = render.options,
             pair,
             collision,
             corrected,
@@ -991,13 +1024,13 @@ var Vector = require('../geometry/Vector');
      * Description
      * @private
      * @method grid
-     * @param {engine} engine
+     * @param {render} render
      * @param {grid} grid
      * @param {RenderingContext} context
      */
-    Render.grid = function(engine, grid, context) {
+    Render.grid = function(render, grid, context) {
         var c = context,
-            options = engine.render.options;
+            options = render.options;
 
         if (options.wireframes) {
             c.strokeStyle = 'rgba(255,180,0,0.1)';
@@ -1036,7 +1069,7 @@ var Vector = require('../geometry/Vector');
     Render.inspector = function(inspector, context) {
         var engine = inspector.engine,
             selected = inspector.selected,
-            render = engine.render,
+            render = inspector.render,
             options = render.options,
             bounds;
 
@@ -1222,6 +1255,13 @@ var Vector = require('../geometry/Vector');
      * @type render
      */
 
+    /**
+     * A reference to the `Matter.Engine` instance to be used.
+     *
+     * @property engine
+     * @type engine
+     */
+
     /**
      * A reference to the element where the canvas is to be inserted (if `render.canvas` has not been specified)
      *

src/render/RenderPixi.js

@@ -3,6 +3,8 @@
 * See also `Matter.Render` for a canvas based renderer.
 *
 * @class RenderPixi
+* @deprecated the Matter.RenderPixi module will soon be removed from the Matter.js core.
+* It will likely be moved to its own repository (but maintenance will be limited).
 */
 
 var RenderPixi = {};
@@ -13,17 +15,34 @@ var Composite = require('../body/Composite');
 var Common = require('../core/Common');
 
 (function() {
+
+    var _requestAnimationFrame,
+        _cancelAnimationFrame;
+
+    if (typeof window !== 'undefined') {
+        _requestAnimationFrame = window.requestAnimationFrame || window.webkitRequestAnimationFrame
+                                      || window.mozRequestAnimationFrame || window.msRequestAnimationFrame 
+                                      || function(callback){ window.setTimeout(function() { callback(Common.now()); }, 1000 / 60); };
+   
+        _cancelAnimationFrame = window.cancelAnimationFrame || window.mozCancelAnimationFrame 
+                                      || window.webkitCancelAnimationFrame || window.msCancelAnimationFrame;
+    }
     
     /**
      * Creates a new Pixi.js WebGL renderer
      * @method create
      * @param {object} options
      * @return {RenderPixi} A new renderer
+     * @deprecated
      */
     RenderPixi.create = function(options) {
+        Common.log('RenderPixi.create: Matter.RenderPixi is deprecated (see docs)', 'warn');
+
         var defaults = {
             controller: RenderPixi,
+            engine: null,
             element: null,
+            frameRequestId: null,
             canvas: null,
             renderer: null,
             container: null,
@@ -62,6 +81,8 @@ var Common = require('../core/Common');
             backgroundColor: options.background
         };
 
+        render.mouse = options.mouse;
+        render.engine = options.engine;
         render.renderer = render.renderer || new PIXI.WebGLRenderer(render.options.width, render.options.height, render.pixiOptions);
         render.container = render.container || new PIXI.Container();
         render.spriteContainer = render.spriteContainer || new PIXI.Container();
@@ -99,10 +120,34 @@ var Common = require('../core/Common');
         return render;
     };
 
+    /**
+     * Continuously updates the render canvas on the `requestAnimationFrame` event.
+     * @method run
+     * @param {render} render
+     * @deprecated
+     */
+    RenderPixi.run = function(render) {
+        (function loop(time){
+            render.frameRequestId = _requestAnimationFrame(loop);
+            RenderPixi.world(render);
+        })();
+    };
+
+    /**
+     * Ends execution of `Render.run` on the given `render`, by canceling the animation frame request event loop.
+     * @method stop
+     * @param {render} render
+     * @deprecated
+     */
+    RenderPixi.stop = function(render) {
+        _cancelAnimationFrame(render.frameRequestId);
+    };
+
     /**
      * Clears the scene graph
      * @method clear
      * @param {RenderPixi} render
+     * @deprecated
      */
     RenderPixi.clear = function(render) {
         var container = render.container,
@@ -146,6 +191,7 @@ var Common = require('../core/Common');
      * @method setBackground
      * @param {RenderPixi} render
      * @param {string} background
+     * @deprecated
      */
     RenderPixi.setBackground = function(render, background) {
         if (render.currentBackground !== background) {
@@ -180,9 +226,10 @@ var Common = require('../core/Common');
      * Description
      * @method world
      * @param {engine} engine
+     * @deprecated
      */
-    RenderPixi.world = function(engine) {
+    RenderPixi.world = function(render) {
-        var render = engine.render,
+        var engine = render.engine,
             world = engine.world,
             renderer = render.renderer,
             container = render.container,
@@ -237,10 +284,10 @@ var Common = require('../core/Common');
         }
 
         for (i = 0; i < bodies.length; i++)
-            RenderPixi.body(engine, bodies[i]);
+            RenderPixi.body(render, bodies[i]);
 
         for (i = 0; i < constraints.length; i++)
-            RenderPixi.constraint(engine, constraints[i]);
+            RenderPixi.constraint(render, constraints[i]);
 
         renderer.render(container);
     };
@@ -251,9 +298,10 @@ var Common = require('../core/Common');
      * @method constraint
      * @param {engine} engine
      * @param {constraint} constraint
+     * @deprecated
      */
-    RenderPixi.constraint = function(engine, constraint) {
+    RenderPixi.constraint = function(render, constraint) {
-        var render = engine.render,
+        var engine = render.engine,
             bodyA = constraint.bodyA,
             bodyB = constraint.bodyB,
             pointA = constraint.pointA,
@@ -302,9 +350,10 @@ var Common = require('../core/Common');
      * @method body
      * @param {engine} engine
      * @param {body} body
+     * @deprecated
      */
-    RenderPixi.body = function(engine, body) {
+    RenderPixi.body = function(render, body) {
-        var render = engine.render,
+        var engine = render.engine,
             bodyRender = body.render;
 
         if (!bodyRender.visible)
@@ -358,6 +407,7 @@ var Common = require('../core/Common');
      * @param {RenderPixi} render
      * @param {body} body
      * @return {PIXI.Sprite} sprite
+     * @deprecated
      */
     var _createBodySprite = function(render, body) {
         var bodyRender = body.render,
@@ -378,6 +428,7 @@ var Common = require('../core/Common');
      * @param {RenderPixi} render
      * @param {body} body
      * @return {PIXI.Graphics} graphics
+     * @deprecated
      */
     var _createBodyPrimitive = function(render, body) {
         var bodyRender = body.render,
@@ -442,6 +493,7 @@ var Common = require('../core/Common');
      * @param {RenderPixi} render
      * @param {string} imagePath
      * @return {PIXI.Texture} texture
+     * @deprecated
      */
     var _getTexture = function(render, imagePath) {
         var texture = render.textures[imagePath];

test/browser/TestDemo.js

@@ -64,6 +64,7 @@ var test = function(status) {
             _demo.engine.render = {};
             _demo.engine.render.options = {};
             _demo.runner = runner;
+            _demo.render = { options: {} };
             _demo.mouseConstraint = Matter.MouseConstraint.create(engine);
 
             Matter.Demo.reset(_demo);

test/node/TestDemo.js

@@ -50,6 +50,7 @@ var test = function() {
         _demo.engine.render = {};
         _demo.engine.render.options = {};
         _demo.runner = runner;
+        _demo.render = { options: {} };
 
         if (!(demo in Matter.Example)) {
             throw '\'' + demo + '\' is not defined in Matter.Example';