Unified use of roundPixels, antialias and pixelArt modes

Author: photonstorm

CHANGELOG.md

@@ -26,6 +26,21 @@
 * `CameraManager.getTotal` is a new method that will return the total number of Cameras being managed, with an optional `isVisible` argument, that only counts visible cameras if set.
 * `CameraManager.remove` can now take an array of cameras to be removed from the manager, as well as a single camera.
 * `CameraManager.remove` would previously not allow you to remove a camera if it meant there would be no cameras left in the Camera Manager. This restriction has been removed. A Camera Manager can now run even with zero cameras. Your game obviously won't display anything, but it's still now possible.
+* `CameraManager.remove` will now return the total number of Cameras removed.
+
+### Round Pixels Changes
+
+Before explaining the changes it's worth covering what the three different game config properties do:
+
+`roundPixels` - this will cause the renderer to draw most Game Objects at whole integer positions. Their actual positions can be anything, but the renderer will floor the values to ensure they are integers immediately before drawing. It only works on texture based Game Objects. Graphics objects, for instance, ignore this property.
+
+`antialias` - when set to `true` WebGL textures are created using `gl.LINEAR`, which allows WebGL to try its best to interpolate the texture when rendered at non-texture frame sizes. This can happen if you scale a Game Object, or zoom a Camera. In both cases it will need to interpolate the pixel values to accommodate the new size. If this property is set to `false` then it will use `gl.NEAREST` instead. This uses a nearest neighbor method of interpolation, and is nearly always the better option if you need to keep the textures crisp, such as when using scaled pixel art. Disabling `antialias` invokes nearest-neighbor interpolation on the game canvas itself as well. If you need a mixture of aliased and anti-aliased textures in your game, then you can change them on a per-texture basis by using `Texture.setFilter`.
+
+There is a third game config property called `pixelArt`. If set to `true` it's the same thing as enabling `roundPixels` and disabling `antialias`. This is the optimum setting for pixel art games.
+
+* Both renderers will now check for `pixelArt` OR `antialias` before setting the canvas scale mode. Both values are checked during texture creation as well.
+* If in your game config you have enabled either pixel art mode or roundPixels, then all Cameras will have their `roundPixels` values set to `true` by default. You can toggle this by changing the `CameraManager.roundPixels` property, or change it on a camera-by-camera basis, as needed.
+* `Camera.roundPixels` is now used across all rendering code for both Canvas and WebGL. Previously, it would check the renderer config value, but now all renderer code uses the camera value to decide if it should floor the drawing position or not.
 
 ### New Features
 

src/boot/Config.js

@@ -341,7 +341,7 @@ var Config = new Class({
         /**
          * @const {boolean} Phaser.Boot.Config#roundPixels - [description]
          */
-        this.roundPixels = GetValue(renderConfig, 'roundPixels', false);
+        this.roundPixels = GetValue(renderConfig, 'roundPixels', this.pixelArt);
 
         /**
          * @const {boolean} Phaser.Boot.Config#transparent - [description]

src/boot/CreateRenderer.js

@@ -48,7 +48,7 @@ var CreateRenderer = function (game)
     }
 
     //  Pixel Art mode?
-    if (config.pixelArt)
+    if (config.pixelArt || !config.antialias)
     {
         CanvasPool.disableSmoothing();
     }
@@ -70,7 +70,7 @@ var CreateRenderer = function (game)
     }
 
     //  Pixel Art mode?
-    if (config.pixelArt)
+    if (config.pixelArt || !config.antialias)
     {
         CanvasInterpolation.setCrisp(game.canvas);
     }

src/cameras/2d/Camera.js

@@ -1462,8 +1462,9 @@ var Camera = new Class({
     },
 
     /**
-     * Should the Camera round pixel values to whole integers when scrolling?
-     * In some types of game this is required to prevent sub-pixel aliasing.
+     * Should the Camera round pixel values to whole integers when rendering Game Objects?
+     * 
+     * In some types of game, especially with pixel art, this is required to prevent sub-pixel aliasing.
      *
      * @method Phaser.Cameras.Scene2D.Camera#setRoundPixels
      * @since 3.0.0

src/cameras/2d/CameraManager.js

@@ -93,6 +93,18 @@ var CameraManager = new Class({
          */
         this.systems = scene.sys;
 
+        /**
+         * All Cameras created by, or added to, this Camera Manager, will have their `roundPixels`
+         * property set to match this value. By default it is set to match the value set in the
+         * game configuration, but can be changed at any point. Equally, individual cameras can
+         * also be changed as needed.
+         *
+         * @name Phaser.Cameras.Scene2D.CameraManager#roundPixels
+         * @type {boolean}
+         * @since 3.11.0
+         */
+        this.roundPixels = scene.sys.game.config.roundPixels;
+
         /**
          * An Array of the Camera objects being managed by this Camera Manager.
          * The Cameras are updated and rendered in the same order in which they appear in this array.
@@ -197,6 +209,10 @@ var CameraManager = new Class({
      * By default Cameras are transparent and will render anything that they can see based on their `scrollX`
      * and `scrollY` values. Game Objects can be set to be ignored by a Camera by using the `Camera.ignore` method.
      * 
+     * Please note that it will have its `roundPixels` propery set to whatever is set on the game and renderer
+     * configuration. So if you've got a game config with `pixelArt: true` in it, then `roundPixels` will always
+     * be set to `true` on the new Camera.
+     * 
      * See the Camera class documentation for more details.
      *
      * @method Phaser.Cameras.Scene2D.CameraManager#add
@@ -224,6 +240,7 @@ var CameraManager = new Class({
 
         camera.setName(name);
         camera.setScene(this.scene);
+        camera.setRoundPixels(this.roundPixels);
 
         camera.id = this.getNextID();
 
@@ -242,6 +259,10 @@ var CameraManager = new Class({
      * 
      * The Camera should either be a `Phaser.Cameras.Scene2D.Camera` instance, or a class that extends from it.
      * 
+     * Please note that it will have its `roundPixels` propery set to whatever is set on the game and renderer
+     * configuration. So if you've got a game config with `pixelArt: true` in it, then `roundPixels` will always
+     * be set to `true` on the Camera added to this Camera Manager.
+     * 
      * The Camera will be assigned an ID, which is used for Game Object exclusion and then added to the
      * manager. As long as it doesn't already exist in the manager it will be added then returned.
      * 
@@ -265,6 +286,8 @@ var CameraManager = new Class({
         {
             camera.id = this.getNextID();
 
+            camera.setRoundPixels(this.roundPixels);
+
             this.cameras.push(camera);
 
             if (makeMain)

src/gameobjects/bitmaptext/dynamic/DynamicBitmapTextCanvasRenderer.js

@@ -127,8 +127,6 @@ var DynamicBitmapTextCanvasRenderer = function (renderer, src, interpolationPerc
         ctx.clip();
     }
 
-    var roundPixels = renderer.config.roundPixels;
-
     for (var index = 0; index < textLength; ++index)
     {
         //  Reset the scale (in case the callback changed it)
@@ -186,7 +184,7 @@ var DynamicBitmapTextCanvasRenderer = function (renderer, src, interpolationPerc
         x -= cameraScrollX;
         y -= cameraScrollY;
 
-        if (roundPixels)
+        if (camera.roundPixels)
         {
             x |= 0;
             y |= 0;

src/gameobjects/bitmaptext/static/BitmapTextCanvasRenderer.js

@@ -91,12 +91,10 @@ var BitmapTextCanvasRenderer = function (renderer, src, interpolationPercentage,
         renderer.currentScaleMode = src.scaleMode;
     }
 
-    var roundPixels = renderer.config.roundPixels;
-
     var tx = (src.x - camera.scrollX * src.scrollFactorX) + src.frame.x;
     var ty = (src.y - camera.scrollY * src.scrollFactorY) + src.frame.y;
 
-    if (roundPixels)
+    if (camera.roundPixels)
     {
         tx |= 0;
         ty |= 0;
@@ -167,7 +165,7 @@ var BitmapTextCanvasRenderer = function (renderer, src, interpolationPercentage,
             continue;
         }
 
-        if (roundPixels)
+        if (camera.roundPixels)
         {
             x |= 0;
             y |= 0;

src/gameobjects/particles/ParticleManagerCanvasRenderer.js

@@ -64,8 +64,6 @@ var ParticleManagerCanvasRenderer = function (renderer, emitterManager, interpol
             ctx.globalCompositeOperation = renderer.blendModes[emitter.blendMode];
         }
 
-        var roundPixels = renderer.config.roundPixels;
-
         for (var index = 0; index < length; ++index)
         {
             var particle = particles[index];
@@ -90,7 +88,7 @@ var ParticleManagerCanvasRenderer = function (renderer, emitterManager, interpol
             var tx = particle.x - cameraScrollX;
             var ty = particle.y - cameraScrollY;
 
-            if (roundPixels)
+            if (camera.roundPixels)
             {
                 tx |= 0;
                 ty |= 0;

src/gameobjects/text/static/TextCanvasRenderer.js

@@ -73,7 +73,7 @@ var TextCanvasRenderer = function (renderer, src, interpolationPercentage, camer
     var tx = src.x - camera.scrollX * src.scrollFactorX;
     var ty = src.y - camera.scrollY * src.scrollFactorY;
 
-    if (renderer.config.roundPixels)
+    if (camera.roundPixels)
     {
         tx |= 0;
         ty |= 0;

src/gameobjects/tilesprite/TileSpriteCanvasRenderer.js

@@ -86,7 +86,7 @@ var TileSpriteCanvasRenderer = function (renderer, src, interpolationPercentage,
         dy += src.height;
     }
 
-    if (renderer.config.roundPixels)
+    if (camera.roundPixels)
     {
         dx |= 0;
         dy |= 0;