Added Pointer.prevPosition and getInterpolatedPosition method

Author: photonstorm

CHANGELOG.md

@@ -45,21 +45,24 @@ There is a third game config property called `pixelArt`. If set to `true` it's t
 
 ### Texture Tint Pipeline - New Features, Updates and Fixes
 
-The Texture Tint Pipeline has been rewritten to tidy up hundreds of lines of duplicate code and to move the responsibility of drawing to the Game Objects themselves. Previously, had you excluded say Tilemaps from your build of Phaser, the renderer would still include masses of code dealing with the drawing of them. Now, this task has been moved to the Game Objects and the pipeline just provides a set of clean utility functions for batching, flushing and drawing.
+The Texture Tint Pipeline has been rewritten to tidy up hundreds of lines of duplicate code and to move the responsibility of drawing to the Game Objects themselves. Previously, had you excluded say Tilemaps from your build of Phaser, the renderer would still include masses of code dealing with the drawing of them. This task has been moved to the Game Objects and the pipeline just provides a set of clean utility functions for batching, flushing and drawing.
+
+The decision to make this change was not taken lightly. However, I felt that none of the pipelines actually lived up to their name. You could never actually pass objects through one pipeline to another as they didn't have entry and exit points and were instead just glorified singular batches. Although you could change the pipeline being used on a Game Object this action meant that every pipeline had to be responsible for every single type of Game Object, both now and in the future, and they were full of redundant stub functions as a result. The payload size was also considerable.
 
 * You can now set the WebGL batch size in the Game Config via the property `batchSize`. The default is 2000 before the batch will flush, which is a happy average between desktop and mobile. If targeting desktop specifically, you may wish to increase this value to reduce draw calls.
 * There is a new method `batchVertices` which will add a vertices block to the current batch. This is now used internally by nearly all render functions.
-* All of the rendering functions now use the `TransformMatrix` class far more than before. This allows the matrix operations to be run-time compiled and cut down on masses of code.
-* The `batchTileSprite` method has been removed from the `TextureTintPipeline` class, because it is now handled in the TileSprite WebGL Render function.
-* The `drawStaticTilemapLayer` method has been removed from the `TextureTintPipeline` class, because it is now handled in the Static Tilemap Layer WebGL Render function.
-* The `batchText` method has been removed from the `TextureTintPipeline` class, because it is now handled in the Static Text WebGL Render function.
-* The `batchDynamicTilemapLayer` method has been removed from the `TextureTintPipeline` class, because it is now handled in the Dynamic Tilemap Layer WebGL Render function.
-* The `batchMesh` method has been removed from the `TextureTintPipeline` class, because it is now handled in the Mesh WebGL Render function.
-* The `batchBitmapText` method has been removed from the `TextureTintPipeline` class, because it is now handled in the BitmapText WebGL Render function.
-* The `batchDynamicBitmapText` method has been removed from the `TextureTintPipeline` class, because it is now handled in the DynamicBitmapText WebGL Render function.
-* The `batchBlitter` method has been removed from the `TextureTintPipeline` class, because it is now handled in the Blitter WebGL Render function.
 * The shader has a new attribute: `tintEffect`. This is a single FLOAT.
 * The vertex size has increased by 1 FLOAT to account for the extra shader attribute.
+* All of the rendering functions now use the `TransformMatrix` class far more than before. This allows the matrix operations to be run-time compiled and cut down on masses of code.
+* The `drawTexture` method has been removed. It has been replaced by `drawTextureFrame` which has a new and more concise signature. See the API docs for details.
+* The `batchTileSprite` method has been removed. It is now handled in the TileSprite WebGL Render function.
+* The `drawStaticTilemapLayer` method has been removed. It is now handled in the Static Tilemap Layer WebGL Render function.
+* The `batchText` method has been removed. It is now handled in the Static Text WebGL Render function.
+* The `batchDynamicTilemapLayer` method has been removed. It is now handled in the Dynamic Tilemap Layer WebGL Render function.
+* The `batchMesh` method has been removed. It is now handled in the Mesh WebGL Render function.
+* The `batchBitmapText` method has been removed. It is now handled in the BitmapText WebGL Render function.
+* The `batchDynamicBitmapText` method has been removed. It is now handled in the DynamicBitmapText WebGL Render function.
+* The `batchBlitter` method has been removed. It is now handled in the Blitter WebGL Render function.
 
 Due to the changes in the Texture Tint Pipeline the `Textures.Frame` class has also been updated. The following changes concern the Frame UV data:
 
@@ -117,6 +120,8 @@ There is a new Game Object Component called `TextureCrop`. It replaces the Textu
 * `TransformMatrix.copyFrom` is a new method that will copy the given matrix into the values of the current one.
 * `TransformMatrix.multiplyWithOffset` is a new method that will multiply the given matrix with the current one, factoring in an additional offset to the results. This is used internally by the renderer code in various places.
 * `Rectangle.Intersection` will take two Rectangle objects and return the area of intersection between them. If there is no intersection, an empty Rectangle is returned.
+* `Pointer.prevPosition` is a new Vector2 that stores the previous position of the Pointer, prior to the most recent DOM event. You can use this when performing calculations between the old and current positions, such as for tracking the pointer speed.
+* `Pointer.getInterpolatedPosition` is a new method that will return an array of smoothly interpolated values between the old and previous position of the Pointer. You can configure how many interpolation steps should take place (the default is 10) and provide an output array to store them in. This method is handy if you've got an object tracking a pointer and you want to ensure it has smooth movement (as the DOM will often process pointer events at a faster rate than the game loop can update).
 
 ### Updates
 

src/input/InputManager.js

@@ -1250,6 +1250,11 @@ var InputManager = new Class({
      */
     transformPointer: function (pointer, pageX, pageY)
     {
+        //  Store the previous position
+        pointer.prevPosition.x = pointer.x;
+        pointer.prevPosition.y = pointer.y;
+
+        //  Set the new position
         pointer.x = (pageX - this.bounds.left) * this.scale.x;
         pointer.y = (pageY - this.bounds.top) * this.scale.y;
     },

src/input/Pointer.js

@@ -5,8 +5,10 @@
  */
 
 var Class = require('../utils/Class');
+var SmoothStepInterpolation = require('../math/interpolation/SmoothStepInterpolation');
 var Vector2 = require('../math/Vector2');
 
+
 /**
  * @classdesc
  * A Pointer object encapsulates both mouse and touch input within Phaser.
@@ -104,6 +106,20 @@ var Pointer = new Class({
          */
         this.position = new Vector2();
 
+        /**
+         * The previous position of the Pointer in screen space.
+         * 
+         * The old x and y values are stored in here during the InputManager.transformPointer call.
+         * 
+         * You can use it to track how fast the pointer is moving, or to smoothly interpolate between the old and current position.
+         * See the `Pointer.getInterpolatedPosition` method to assist in this.
+         *
+         * @name Phaser.Input.Pointer#prevPosition
+         * @type {Phaser.Math.Vector2}
+         * @since 3.11.0
+         */
+        this.prevPosition = new Vector2();
+
         /**
          * The x position of this Pointer, translated into the coordinate space of the most recent Camera it interacted with.
          *
@@ -646,6 +662,57 @@ var Pointer = new Class({
         return (this.buttons & 16);
     },
 
+    /**
+     * Takes the previous and current Pointer positions and then generates an array of interpolated values between
+     * the two. The array will be populated up to the size of the `steps` argument.
+     * 
+     * ```javaScript
+     * var points = pointer.getInterpolatedPosition(4);
+     * 
+     * // points[0] = { x: 0, y: 0 }
+     * // points[1] = { x: 2, y: 1 }
+     * // points[2] = { x: 3, y: 2 }
+     * // points[3] = { x: 6, y: 3 }
+     * ```
+     * 
+     * Use this if you need to get smoothed values between the previous and current pointer positions. DOM pointer
+     * events can often fire faster than the main browser loop, and this will help you avoid janky movement
+     * especially if you have an object following a Pointer.
+     * 
+     * Note that if you provide an output array it will only be populated up to the number of steps provided.
+     * It will not clear any previous data that may have existed beyond the range of the steps count.
+     * 
+     * Internally it uses the Smooth Step interpolation calculation.
+     *
+     * @method Phaser.Input.Pointer#getInterpolatedPosition
+     * @since 3.11.0
+     * 
+     * @param {integer} [steps=10] - The number of interpolation steps to use.
+     * @param {array} [out] - An array to store the results in. If not provided a new one will be created.
+     * 
+     * @return {array} An array of interpolated values.
+     */
+    getInterpolatedPosition: function (steps, out)
+    {
+        if (steps === undefined) { steps = 10; }
+        if (out === undefined) { out = []; }
+
+        var prevX = this.prevPosition.x;
+        var prevY = this.prevPosition.y;
+
+        var curX = this.position.x;
+        var curY = this.position.y;
+
+        for (var i = 0; i < steps; i++)
+        {
+            var t = (1 / steps) * i;
+
+            out[i] = { x: SmoothStepInterpolation(t, prevX, curX), y: SmoothStepInterpolation(t, prevY, curY) };
+        }
+
+        return out;
+    },
+
     /**
      * Destroys this Pointer instance and resets its external references.
      *