TilemapLayer rendering double-copy

- Memory optimization of delta-scroll shifting.
  - The copy canvas is shared between all TilemapLayers
  - The copy is done in segments to reduce the memory usage of the copy
  canvas. Currently this is a 1/4 ratio.

- Device has the feature (by browser) check to see if bitblt works
  - TilemapLayer will automatically enable the double-copy as needed
  - Device.whenReady can be used to override the device value

Author: pnstickne

src/system/Canvas.js

@@ -18,7 +18,7 @@ Phaser.Canvas = {
     * @method Phaser.Canvas.create
     * @param {number} [width=256] - The width of the canvas element.
     * @param {number} [height=256] - The height of the canvas element..
-    * @param {string} [id=''] - If given this will be set as the ID of the canvas element, otherwise no ID will be set.
+    * @param {string} [id=(none)] - If specified, and not the empty string, this will be set as the ID of the canvas element. Otherwise no ID will be set.
     * @return {HTMLCanvasElement} The newly created canvas element.
     */
     create: function (width, height, id) {

src/system/Device.js

@@ -143,6 +143,18 @@ Phaser.Device = function () {
     */
     this.canvas = false;
 
+    /**
+    * @property {?boolean} canvasBitBltShift - True if canvas supports a 'copy' bitblt onto itself when the source and destination regions overlap.
+    * @default
+    */
+    this.canvasBitBltShift = null;
+
+    /**
+    * @property {boolean} webGL - Is webGL available?
+    * @default
+    */
+    this.webGL = false;
+
     /**
     * @property {boolean} file - Is file available?
     * @default
@@ -161,12 +173,6 @@ Phaser.Device = function () {
     */
     this.localStorage = false;
 
-    /**
-    * @property {boolean} webGL - Is webGL available?
-    * @default
-    */
-    this.webGL = false;
-
     /**
     * @property {boolean} worker - Is worker available?
     * @default
@@ -224,7 +230,7 @@ Phaser.Device = function () {
     this.mspointer = false;
 
     /**
-    * @property {string|null} wheelType - The newest type of Wheel/Scroll event supported: 'wheel', 'mousewheel', 'DOMMouseScroll'
+    * @property {?string} wheelType - The newest type of Wheel/Scroll event supported: 'wheel', 'mousewheel', 'DOMMouseScroll'
     * @default
     * @protected
     */
@@ -387,6 +393,8 @@ Phaser.Device = function () {
     */
     this.iPad = false;
 
+    // Device features
+
     /**
     * @property {number} pixelRatio - PixelRatio of the host device?
     * @default
@@ -643,16 +651,9 @@ Phaser.Device._initialize = function () {
 
         device.file = !!window['File'] && !!window['FileReader'] && !!window['FileList'] && !!window['Blob'];
         device.fileSystem = !!window['requestFileSystem'];
-        device.webGL = ( function () { try { var canvas = document.createElement( 'canvas' ); /*Force screencanvas to false*/ canvas.screencanvas = false; return !! window.WebGLRenderingContext && ( canvas.getContext( 'webgl' ) || canvas.getContext( 'experimental-webgl' ) ); } catch( e ) { return false; } } )();
 
-        if (device.webGL === null || device.webGL === false)
-        {
-            device.webGL = false;
-        }
-        else
-        {
-            device.webGL = true;
-        }
+        device.webGL = ( function () { try { var canvas = document.createElement( 'canvas' ); /*Force screencanvas to false*/ canvas.screencanvas = false; return !! window.WebGLRenderingContext && ( canvas.getContext( 'webgl' ) || canvas.getContext( 'experimental-webgl' ) ); } catch( e ) { return false; } } )();
+        device.webGL = !!device.webGL;
 
         device.worker = !!window['Worker'];
 
@@ -662,6 +663,17 @@ Phaser.Device._initialize = function () {
 
         device.getUserMedia = !!(navigator.getUserMedia || navigator.webkitGetUserMedia || navigator.mozGetUserMedia || navigator.msGetUserMedia);
 
+        if (device.ie || device.firefox || device.chrome)
+        {
+            // Believed to work - need verification of Chrome for iOS, or other browsers using UIWebKit.
+            device.canvasBitBltShift = true;
+        }
+        if (device.safari || device.mobileSafari)
+        {
+            // Known not to work
+            device.canvasBitBltShift = false;
+        }
+
     }
 
     /**

src/tilemap/TilemapLayer.js

@@ -8,6 +8,7 @@
 * A TilemapLayer is a Phaser.Image/Sprite that renders a specific TileLayer of a Tilemap.
 *
 * Since a TilemapLayer is a Sprite it can be moved around the display, added to other groups or display objects, etc.
+*
 * By default TilemapLayers have fixedToCamera set to `true`. Changing this will break Camera follow and scrolling behaviour.
 *
 * @class Phaser.TilemapLayer
@@ -61,7 +62,7 @@ Phaser.TilemapLayer = function (game, tilemap, index, width, height) {
     * @property {HTMLCanvasElement} canvas
     * @protected
     */
-    this.canvas = Phaser.Canvas.create(width, height, '', true);
+    this.canvas = Phaser.Canvas.create(width, height);
 
     /**
     * The 2d context of the canvas.
@@ -70,12 +71,6 @@ Phaser.TilemapLayer = function (game, tilemap, index, width, height) {
     */
     this.context = this.canvas.getContext('2d');
 
-    /**
-    * @property {?HTMLCanvasElement} _copyCanvas
-    * @private
-    */
-    this._copyCanvas = Phaser.Canvas.create(width, height, '', true);
-
     /**
     * Required Pixi var.
     * @property {PIXI.BaseTexture} baseTexture
@@ -130,16 +125,24 @@ Phaser.TilemapLayer = function (game, tilemap, index, width, height) {
     /**
     * Settings that control standard (non-diagnostic) rendering.
     *
-    * @public
-    * @property {boolean} enableScrollDelta - When enabled, only new newly exposed areas of the layer are redraw after scrolling. This can greatly improve scrolling rendering performance, especially when there are many small tiles.
+    * @property {boolean} [enableScrollDelta=true] - Delta scroll rendering only draws tiles/edges as them come into view.
+    *     This can greatly improve scrolling rendering performance, especially when there are many small tiles.
+    *     It should only be disabled in rare cases.
+    *
+    * @property {?DOMCanvasElement} [copyCanvas=(auto)] - [Internal] If set, force using a separate (shared) copy canvas.
+    *     Using a canvas bitblt/copy when the source and destinations region overlap produces unexpected behavior
+    *     in some browsers, notably Safari. 
+    *
+    * @property {integer} copySliceCount - [Internal] The number of vertical slices to copy when using a `copyCanvas`.
+    *     This is ratio of the pixel count of the primary canvas to the copy canvas.
+    *
     * @default
     */
     this.renderSettings = {
-
         enableScrollDelta: true,
-
-        overdrawRatio: 0.20
-
+        overdrawRatio: 0.20,
+        copyCanvas: null,
+        copySliceCount: 4
     };
 
     /**
@@ -264,6 +267,35 @@ Phaser.TilemapLayer = function (game, tilemap, index, width, height) {
     */
     this._results = [];
 
+    if (!game.device.canvasBitBltShift)
+    {
+        this.renderSettings.copyCanvas = Phaser.TilemapLayer.ensureSharedCopyCanvas();
+    }
+
+};
+
+/**
+* The shared double-copy canvas, created as needed.
+*
+* @private
+* @static
+*/
+Phaser.TilemapLayer.sharedCopyCanvas = null;
+
+/**
+* Create if needed (and return) a shared copy canvas that is shared across all TilemapLayers.
+*
+* Code that uses the canvas is responsible to ensure the dimensions and save/restore state as appropriate.
+*
+* @protected
+* @static
+*/
+Phaser.TilemapLayer.ensureSharedCopyCanvas = function () {
+    if (!this.sharedCopyCanvas)
+    {
+        this.sharedCopyCanvas = Phaser.Canvas.create(2, 2);
+    }
+    return this.sharedCopyCanvas;
 };
 
 Phaser.TilemapLayer.prototype = Object.create(Phaser.Image.prototype);
@@ -597,7 +629,8 @@ Object.defineProperty(Phaser.TilemapLayer.prototype, "wrap", {
 });
 
 /**
-* Returns the appropriate tileset for the index, updating the internal cache as required. This should only be called if `tilesets[index]` evaluates to undefined.
+* Returns the appropriate tileset for the index, updating the internal cache as required.
+* This should only be called if `tilesets[index]` evaluates to undefined.
 *
 * @method Phaser.TilemapLayer#resolveTileset
 * @private
@@ -631,7 +664,9 @@ Phaser.TilemapLayer.prototype.resolveTileset = function (tileIndex)
 };
 
 /**
-* The TilemapLayer caches tileset look-ups. Call this method of clear the cache if tilesets have been added or updated after the layer has been rendered.
+* The TilemapLayer caches tileset look-ups.
+*
+* Call this method of clear the cache if tilesets have been added or updated after the layer has been rendered.
 *
 * @method Phaser.TilemapLayer#resetTilesetCache
 * @public
@@ -648,15 +683,19 @@ Phaser.TilemapLayer.prototype.resetTilesetCache = function ()
 
 /**
 * Shifts the contents of the canvas - does extra math so that different browsers agree on the result.
+*
 * The specified (x/y) will be shifted to (0,0) after the copy and the newly exposed canvas area will need to be filled in.
 *
+* If `copyCanvas` is specified it will be used as an intermediate copy buffer and may be resized.
+*
 * @method Phaser.TilemapLayer#shiftCanvas
 * @private
 * @param {CanvasRenderingContext2D} context - The context to shift
 * @param {integer} x
 * @param {integer} y
+* @param {DOMCanvasElement} [copyCanvas=(none)] - If specified this canvas will be used as an intermediate copy buffer.
 */
-Phaser.TilemapLayer.prototype.shiftCanvas = function (context, x, y)
+Phaser.TilemapLayer.prototype.shiftCanvas = function (context, x, y, copyCanvas)
 {
 
     var canvas = context.canvas;
@@ -681,25 +720,52 @@ Phaser.TilemapLayer.prototype.shiftCanvas = function (context, x, y)
         sy = 0;
     }
 
-    if (!this._copyCanvas)
+    if (copyCanvas)
     {
-        // Flickers in Safari / Safari Mobile
+        // Copying happens in slices to minimize copy canvas size overhead
+        var sliceCount = this.renderSettings.copySliceCount;
+        var sH = Math.ceil(copyH / sliceCount);
+        // Ensure copy canvas is large enough
+        if (copyCanvas.width < copyW) { copyCanvas.width = copyW; }
+        if (copyCanvas.height < sH) { copyCanvas.height = sH; }
+
+        var vShift;
+        if (dy >= sy)
+        {
+            // move old region up, or don't change vertically - copy top to bottom
+            vShift = sH;
+        }
+        else
+        {
+            // move old region down - copy segments from bottom to top
+            vShift = -sH;
+            dy += (sH * (sliceCount - 1));
+            sy += (sH * (sliceCount - 1));
+        }
+
+        var copyContext = copyCanvas.getContext('2d');
+        while (sliceCount--)
+        {
+            copyContext.clearRect(0, 0, copyW, sH);
+            copyContext.drawImage(canvas, dx, dy, copyW, sH, 0, 0, copyW, sH);
+            // clear allows default 'source-over' semantics
+            context.clearRect(sx, sy, copyW, sH);
+            context.drawImage(copyCanvas, 0, 0, copyW, sH, sx, sy, copyW, sH);
+
+            dy += vShift;
+            sy += vShift;
+        }
+
+    }
+    else
+    {
+        // Avoids a second copy but flickers in Safari / Safari Mobile
         // Ref. https://github.com/photonstorm/phaser/issues/1439
         context.save();
         context.globalCompositionOperation = 'copy';
         context.drawImage(canvas, dx, dy, copyW, copyH, sx, sy, copyW, copyH);
         context.restore();
     }
-    else
-    {
-        var cpCanvas = this._copyCanvas;
-        var cpContext = cpCanvas.getContext('2d');
-        cpContext.clearRect(0, 0, copyW, copyH);
-        cpContext.drawImage(canvas, dx, dy, copyW, copyH, 0, 0, copyW, copyH);
-        // clear allows default 'source-over' semantics
-        context.clearRect(sx, sy, copyW, copyH);
-        context.drawImage(cpCanvas, 0, 0, copyW, copyH, sx, sy, copyW, copyH);
-    }
 };
 
 /**
@@ -862,7 +928,7 @@ Phaser.TilemapLayer.prototype.renderDeltaScroll = function (shiftX, shiftY) {
         bottom = shiftY;
     }
 
-    this.shiftCanvas(this.context, shiftX, shiftY);
+    this.shiftCanvas(this.context, shiftX, shiftY, this.renderSettings.copyCanvas);
 
     // Transform into tile-space
     left = Math.floor((left + scrollX) / tw);