Allow for custom canvas and context game config options. Game.context now set in WebGL mode. Allows WebGL2 contexts to be passed in. Fix phaserjs#3653

Author: photonstorm

CHANGELOG.md

@@ -10,6 +10,8 @@
 * WebGLRenderer.config has a new property `maxTextureSize` which is derived from `gl.MAX_TEXTURE_SIZE`, you can get it via the new method `getMaxTextureSize()`
 * WebGLRenderer has a new property `compression` which holds the browser / devices compressed texture support gl extensions, which is populated during `init`.
 * Optimized TextureTintPipeline.drawBlitter so it skips bobs that have alpha of zero and only calls `setTexture2D` if the bob sourceIndex has changed, previously it called it for every single bob.
+* You can pass in your own `canvas` and `context` elements in your Game Config and Phaser will use those to render with instead of creating its own. This also allows you to pass in a WebGL 2 context. Fix #3653 (thanks @tgrajewski)
+* Game.context used to be undefined if running in WebGL. It is now set to be the `WebGLRenderingContext` during WebGLRenderer.init. If you provided your own custom context, it is set to this instead.
 
 ### Bug Fixes
 
@@ -21,7 +23,7 @@
 
 My thanks to the following for helping with the Phaser 3 Examples, Docs and TypeScript definitions, either by reporting errors, fixing them or helping author the docs:
 
-
+@samme @mzguimaraes @NaNdreas @Matthew-Herman @melissaelopez
 
 
 ## Version 3.7.1 - Sinon - 8th May 2018

src/boot/Config.js

@@ -57,8 +57,9 @@ var ValueToColor = require('../display/color/ValueToColor');
  * @property {number} [resolution=1] - [description]
  * @property {number} [type=CONST.AUTO] - [description]
  * @property {*} [parent=null] - [description]
- * @property {HTMLCanvasElement} [canvas=null] - [description]
+ * @property {HTMLCanvasElement} [canvas=null] - Provide your own Canvas element for Phaser to use instead of creating one.
  * @property {string} [canvasStyle=null] - [description]
+ * @property {CanvasRenderingContext2D} [context] - Provide your own Canvas Context for Phaser to use, instead of creating one.
  * @property {object} [scene=null] - [description]
  * @property {string[]} [seed] - [description]
  * @property {string} [title=''] - [description]
@@ -145,49 +146,48 @@ var Config = new Class({
          */
         this.zoom = GetValue(config, 'zoom', 1);
 
-
         /**
          * @const {number} Phaser.Boot.Config#resolution - [description]
          */
         this.resolution = GetValue(config, 'resolution', 1);
 
-
         /**
          * @const {number} Phaser.Boot.Config#renderType - [description]
          */
         this.renderType = GetValue(config, 'type', CONST.AUTO);
 
-
         /**
          * @const {?*} Phaser.Boot.Config#parent - [description]
          */
         this.parent = GetValue(config, 'parent', null);
 
         /**
-         * @const {?HTMLCanvasElement} Phaser.Boot.Config#canvas - [description]
+         * @const {?HTMLCanvasElement} Phaser.Boot.Config#canvas - Force Phaser to use your own Canvas element instead of creating one.
          */
         this.canvas = GetValue(config, 'canvas', null);
 
+        /**
+         * @const {?(CanvasRenderingContext2D|WebGLRenderingContext)} Phaser.Boot.Config#context - Force Phaser to use your own Canvas context instead of creating one.
+         */
+        this.context = GetValue(renderConfig, 'context', null);
+
         /**
          * @const {?string} Phaser.Boot.Config#canvasStyle - [description]
          */
         this.canvasStyle = GetValue(config, 'canvasStyle', null);
 
-
         /**
          * @const {?object} Phaser.Boot.Config#sceneConfig - [description]
          */
         this.sceneConfig = GetValue(config, 'scene', null);
 
-
         /**
          * @const {string[]} Phaser.Boot.Config#seed - [description]
          */
         this.seed = GetValue(config, 'seed', [ (Date.now() * Math.random()).toString() ]);
 
         MATH.RND.init(this.seed);
 
-
         /**
          * @const {string} Phaser.Boot.Config#gameTitle - [description]
          */
@@ -203,8 +203,8 @@ var Config = new Class({
          */
         this.gameVersion = GetValue(config, 'version', '');
 
-
         //  Input
+
         /**
          * @const {boolean} Phaser.Boot.Config#inputKeyboard - [description]
          */
@@ -215,7 +215,6 @@ var Config = new Class({
          */
         this.inputKeyboardEventTarget = GetValue(config, 'input.keyboard.target', window);
 
-
         /**
          * @const {(boolean|object)} Phaser.Boot.Config#inputMouse - [description]
          */
@@ -231,7 +230,6 @@ var Config = new Class({
          */
         this.inputMouseCapture = GetValue(config, 'input.mouse.capture', true);
 
-
         /**
          * @const {boolean} Phaser.Boot.Config#inputTouch - [description]
          */
@@ -247,32 +245,28 @@ var Config = new Class({
          */
         this.inputTouchCapture = GetValue(config, 'input.touch.capture', true);
 
-
         /**
          * @const {boolean} Phaser.Boot.Config#inputGamepad - [description]
          */
         this.inputGamepad = GetValue(config, 'input.gamepad', false);
 
-
         /**
          * @const {boolean} Phaser.Boot.Config#disableContextMenu - [description]
          */
         this.disableContextMenu = GetValue(config, 'disableContextMenu', false);
 
-
         /**
          * @const {any} Phaser.Boot.Config#audio - [description]
          */
         this.audio = GetValue(config, 'audio');
 
-
         //  If you do: { banner: false } it won't display any banner at all
+
         /**
          * @const {boolean} Phaser.Boot.Config#hideBanner - [description]
          */
         this.hideBanner = (GetValue(config, 'banner', null) === false);
 
-
         /**
          * @const {boolean} Phaser.Boot.Config#hidePhaser - [description]
          */
@@ -361,7 +355,6 @@ var Config = new Class({
          */
         this.powerPreference = GetValue(renderConfig, 'powerPreference', 'default');
 
-
         var bgc = GetValue(config, 'backgroundColor', 0);
 
         /**
@@ -374,7 +367,6 @@ var Config = new Class({
             this.backgroundColor.alpha = 0;
         }
 
-
         //  Callbacks
         /**
          * @const {BootCallback} Phaser.Boot.Config#preBoot - [description]
@@ -386,7 +378,6 @@ var Config = new Class({
          */
         this.postBoot = GetValue(config, 'callbacks.postBoot', NOOP);
 
-
         //  Physics
         //  physics: {
         //      system: 'impact',
@@ -405,8 +396,8 @@ var Config = new Class({
          */
         this.defaultPhysicsSystem = GetValue(this.physics, 'default', false);
 
-
         //  Loader Defaults
+
         /**
          * @const {string} Phaser.Boot.Config#loaderBaseURL - [description]
          */
@@ -452,14 +443,13 @@ var Config = new Class({
          */
         this.loaderTimeout = GetValue(config, 'loader.timeout', 0);
 
-
         //  Scene Plugins
+
         /**
          * @const {any} Phaser.Boot.Config#defaultPlugins - [description]
          */
         this.defaultPlugins = GetValue(config, 'plugins', Plugins.DefaultScene);
 
-
         //  Default / Missing Images
         var pngPrefix = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAg';
 

src/boot/CreateRenderer.js

@@ -96,10 +96,12 @@ var CreateRenderer = function (game)
         CanvasRenderer = require('../renderer/canvas/CanvasRenderer');
         WebGLRenderer = require('../renderer/webgl/WebGLRenderer');
 
-        //  Let the config pick the renderer type, both are included
+        //  Let the config pick the renderer type, as both are included
         if (config.renderType === CONST.WEBGL)
         {
             game.renderer = new WebGLRenderer(game);
+
+            //  The WebGL Renderer sets this value during its init, not on construction
             game.context = null;
         }
         else
@@ -115,7 +117,10 @@ var CreateRenderer = function (game)
 
         //  Force the type to WebGL, regardless what was requested
         config.renderType = CONST.WEBGL;
+
         game.renderer = new WebGLRenderer(game);
+
+        //  The WebGL Renderer sets this value during its init, not on construction
         game.context = null;
     }
 
@@ -125,7 +130,9 @@ var CreateRenderer = function (game)
 
         //  Force the type to Canvas, regardless what was requested
         config.renderType = CONST.CANVAS;
+
         game.renderer = new CanvasRenderer(game);
+
         game.context = game.renderer.gameContext;
     }
 };

src/boot/Game.js

@@ -74,7 +74,9 @@ var Game = new Class({
         this.renderer = null;
 
         /**
-         * A reference to the HTML Canvas Element on which the renderer is drawing.
+         * A reference to the HTML Canvas Element that Phaser uses to render the game.
+         * This is created automatically by Phaser unless you provide a `canvas` property
+         * in your Game Config.
          *
          * @name Phaser.Game#canvas
          * @type {HTMLCanvasElement}
@@ -83,10 +85,14 @@ var Game = new Class({
         this.canvas = null;
 
         /**
-         * A reference to the Canvas Rendering Context belonging to the Canvas Element this game is rendering to.
+         * A reference to the Rendering Context belonging to the Canvas Element this game is rendering to.
+         * If the game is running under Canvas it will be a 2d Canvas Rendering Context.
+         * If the game is running under WebGL it will be a WebGL Rendering Context.
+         * This context is created automatically by Phaser unless you provide a `context` property
+         * in your Game Config.
          *
          * @name Phaser.Game#context
-         * @type {CanvasRenderingContext2D}
+         * @type {(CanvasRenderingContext2D|WebGLRenderingContext)}
          * @since 3.0.0
          */
         this.context = null;

src/renderer/canvas/CanvasRenderer.js

@@ -118,7 +118,7 @@ var CanvasRenderer = new Class({
          * @type {CanvasRenderingContext2D}
          * @since 3.0.0
          */
-        this.gameContext = this.gameCanvas.getContext('2d');
+        this.gameContext = (this.game.config.context) ? this.game.config.context : this.gameCanvas.getContext('2d');
 
         /**
          * [description]

src/renderer/webgl/WebGLRenderer.js

@@ -419,18 +419,32 @@ var WebGLRenderer = new Class({
      */
     init: function (config)
     {
+        var gl;
         var canvas = this.canvas;
         var clearColor = config.backgroundColor;
-        var gl = canvas.getContext('webgl', config.contextCreation) || canvas.getContext('experimental-webgl', config.contextCreation);
+
+        //  Did they provide their own context?
+        if (this.game.config.context)
+        {
+            gl = this.game.config.context;
+        }
+        else
+        {
+            gl = canvas.getContext('webgl', config.contextCreation) || canvas.getContext('experimental-webgl', config.contextCreation);
+        }
 
         if (!gl || gl.isContextLost())
         {
             this.contextLost = true;
+
             throw new Error('This browser does not support WebGL. Try using the Canvas pipeline.');
         }
 
         this.gl = gl;
 
+        //  Set it back into the Game, so devs can access it from there too
+        this.game.context = gl;
+
         for (var i = 0; i <= 16; i++)
         {
             this.blendModes.push({ func: [ gl.ONE, gl.ONE_MINUS_SRC_ALPHA ], equation: gl.FUNC_ADD });