[#1139] allows specifying a custom renderer

Author: obiot

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [14.3.0] (melonJS 2) - _2022-12-XX_
 
+### Added
+- Core: its now possible to specify a custom renderer (that extends the default Renderer class)
+
 ### Changed
 - General: further code revamping to make melonJS more modular and allow instantiation of different app/games
 - Physic: new `Detector` class instantiated by each physic world instance to detect and solve collisions

src/application/application.js

@@ -39,14 +39,15 @@ const AUTO = 2;
      * @param {number} height - The height of the canvas viewport
      * @param {object} [options] - The optional video/renderer parameters.<br> (see Renderer(s) documentation for further specific options)
      * @param {string|HTMLElement} [options.parent=document.body] - the DOM parent element to hold the canvas in the HTML file
-     * @param {number} [options.renderer=video.AUTO] - renderer to use (me.video.CANVAS, me.video.WEBGL, me.video.AUTO)
+     * @param {number|Renderer} [options.renderer=video.AUTO] - renderer to use (me.video.CANVAS, me.video.WEBGL, me.video.AUTO), or a custom renderer class
      * @param {number|string} [options.scale=1.0] - enable scaling of the canvas ('auto' for automatic scaling)
      * @param {string} [options.scaleMethod="fit"] - screen scaling modes ('fit','fill-min','fill-max','flex','flex-width','flex-height','stretch')
      * @param {boolean} [options.preferWebGL1=false] - if true the renderer will only use WebGL 1
      * @param {string} [options.powerPreference="default"] - a hint to the user agent indicating what configuration of GPU is suitable for the WebGL context ("default", "high-performance", "low-power"). To be noted that Safari and Chrome (since version 80) both default to "low-power" to save battery life and improve the user experience on these dual-GPU machines.
      * @param {boolean} [options.transparent=false] - whether to allow transparent pixels in the front buffer (screen).
      * @param {boolean} [options.antiAlias=false] - whether to enable or not video scaling interpolation
      * @param {boolean} [options.consoleHeader=true] - whether to display melonJS version and basic device information in the console
+     * @throws Will throw an exception if it fails to instantiate a renderer
      */
     constructor(width, height, options) {
 
@@ -183,7 +184,7 @@ const AUTO = 2;
         this.settings.zoomX = width * this.settings.scale;
         this.settings.zoomY = height * this.settings.scale;
 
-        try {
+        if (typeof this.settings.renderer === "number") {
             switch (this.settings.renderer) {
                 case AUTO:
                 case WEBGL:
@@ -193,10 +194,10 @@ const AUTO = 2;
                     this.renderer = new CanvasRenderer(this.settings);
                     break;
             }
-        } catch (e) {
-            console(e.message);
-            // me.video.init() returns false if failing at creating/using a HTML5 canvas
-            return false;
+        } else {
+            var CustomRenderer = this.settings.renderer;
+            // a renderer class
+            this.renderer = new CustomRenderer(this.settings);
         }
 
         // register to the channel
@@ -228,7 +229,7 @@ const AUTO = 2;
         }
 
         if (this.settings.consoleHeader !== false) {
-            var renderType = (this.renderer instanceof CanvasRenderer) ? "CANVAS" : "WebGL" + this.renderer.WebGLVersion;
+            var renderType = typeof this.settings.renderer === "number" ? (this.renderer instanceof CanvasRenderer ? "CANVAS" : "WebGL" + this.renderer.WebGLVersion) : "Custom";
             var audioType = device.hasWebAudio ? "Web Audio" : "HTML5 Audio";
             var gpu_renderer = (typeof this.renderer.GPURenderer === "string") ? " (" + this.renderer.GPURenderer + ")" : "";
             // output video information in the console

src/video/video.js

@@ -57,7 +57,7 @@ export let renderer = null;
  * @param {number} height - The height of the canvas viewport
  * @param {object} [options] - The optional video/renderer parameters.<br> (see Renderer(s) documentation for further specific options)
  * @param {string|HTMLElement} [options.parent=document.body] - the DOM parent element to hold the canvas in the HTML file
- * @param {number} [options.renderer=video.AUTO] - renderer to use (me.video.CANVAS, me.video.WEBGL, me.video.AUTO)
+ * @param {number|Renderer} [options.renderer=video.AUTO] - renderer to use (me.video.CANVAS, me.video.WEBGL, me.video.AUTO), or a custom renderer class
  * @param {number|string} [options.scale=1.0] - enable scaling of the canvas ('auto' for automatic scaling)
  * @param {string} [options.scaleMethod="fit"] - screen scaling modes ('fit','fill-min','fill-max','flex','flex-width','flex-height','stretch')
  * @param {boolean} [options.preferWebGL1=false] - if true the renderer will only use WebGL 1
@@ -81,8 +81,14 @@ export function init(width, height, options) {
         throw new Error("me.video.init() called before engine initialization.");
     }
 
-    // initialize the default game Application with the given options
-    game.init(width, height, options);
+    try {
+         // initialize the default game Application with the given options
+        game.init(width, height, options);
+    } catch (e) {
+        console(e.message);
+        // me.video.init() historically returns false if failing at creating/using a HTML5 canvas
+        return false;
+    }
 
     // assign the default renderer
     renderer = game.renderer;

tests/browser/public/renderer_test.html

@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Puppeteer Mocha</title>
+</head>
+<body>
+    <!-- Canvas placeholder -->
+    <div id="screen"></div>
+    <script type="module">
+      import * as me from './lib/melonjs.module.js';
+
+      // a custom renderer extending the default canvas one with one `isCustom` property
+      class CustomRenderer extends me.CanvasRenderer {
+        constructor(options) {
+          super(options);
+          this.isCustom = true;
+        }
+      }
+
+      me.boot();
+      me.video.init(800, 600, {parent : "screen", scale : "auto", renderer : CustomRenderer});
+
+      // a global reference that we can check later in the corresponding test
+      globalThis.isCustomRenderer = me.game.renderer.isCustom;
+  </script>
+</body>
+</html>

tests/browser/spec/renderer-spec.js

@@ -0,0 +1,17 @@
+import { expect } from "expect";
+
+describe("Renderer test", function () {
+    var page;
+
+    before(async () => {
+        page = await browser.newPage();
+        await page.goto("http://localhost:8042/renderer_test.html", {'waitUntil':'load'});
+        
+    });
+
+    describe("Custom Renderer", async () => {
+        it("should create a custom renderer", async () => {
+            expect(await page.evaluate(() => globalThis.isCustomRenderer)).toEqual(true);
+        });
+    });
+});