Started documenting top-level Phaser.Math functions and classes.

This commit is contained in:
Chris Andrew 2018-05-23 10:46:16 +01:00
parent 5f3767f43d
commit dca9f11f0f
21 changed files with 100 additions and 92 deletions

View file

@ -5,14 +5,14 @@
*/
/**
* [description]
* Calculate the mean average of the given values.
*
* @function Phaser.Math.Average
* @since 3.0.0
*
* @param {number[]} values - [description]
* @param {number[]} values - The values to average.
*
* @return {number} [description]
* @return {number} The average value.
*/
var Average = function (values)
{

View file

@ -5,15 +5,15 @@
*/
/**
* [description]
* Compute a random integer between the `min` and `max` values, inclusive.
*
* @function Phaser.Math.Between
* @since 3.0.0
*
* @param {integer} min - [description]
* @param {integer} max - [description]
* @param {integer} min - The minimum value.
* @param {integer} max - The maximum value.
*
* @return {integer} [description]
* @return {integer} The random integer.
*/
var Between = function (min, max)
{

View file

@ -13,10 +13,10 @@ var Clamp = require('./Clamp');
* @since 3.0.0
*
* @param {float} percent - A value between 0 and 1 representing the percentage.
* @param {number} min - [description]
* @param {number} [max] - [description]
* @param {number} min - The minimum value.
* @param {number} [max] - The maximum value.
*
* @return {number} [description]
* @return {number} The value that is `percent` percent between `min` and `max`.
*/
var FromPercent = function (percent, min, max)
{

View file

@ -5,7 +5,7 @@
*/
/**
* [description]
* Calculate the speed required to cover a distance in the time given.
*
* @function Phaser.Math.GetSpeed
* @since 3.0.0

View file

@ -5,14 +5,14 @@
*/
/**
* [description]
* Check if a given value is an even number using a strict type check.
*
* @function Phaser.Math.IsEvenStrict
* @since 3.0.0
*
* @param {number} value - [description]
* @param {number} value - The number to perform the check with.
*
* @return {boolean} [description]
* @return {boolean} Whether the number is even or not.
*/
var IsEvenStrict = function (value)
{

View file

@ -10,11 +10,11 @@
* @function Phaser.Math.Linear
* @since 3.0.0
*
* @param {number} p0 - The first point
* @param {number} p1 - The second point
* @param {float} t -The percentage between p0 and p1 to return represented as a number between 0 and 1.
* @param {number} p0 - The first point.
* @param {number} p1 - The second point.
* @param {float} t - The percentage between p0 and p1 to return, represented as a number between 0 and 1.
*
* @return {number} The step t% of the way between p0 and p1
* @return {number} The step t% of the way between p0 and p1.
*/
var Linear = function (p0, p1, t)
{

View file

@ -5,16 +5,16 @@
*/
/**
* [description]
* Add an `amount` to a `value`, limiting the maximum result to `max`.
*
* @function Phaser.Math.MaxAdd
* @since 3.0.0
*
* @param {number} value - [description]
* @param {number} amount - [description]
* @param {number} max - [description]
* @param {number} value - The value to add to.
* @param {number} amount - The amount to add.
* @param {number} max - The maximum value to return.
*
* @return {number} [description]
* @return {number} The resulting value.
*/
var MaxAdd = function (value, amount, max)
{

View file

@ -5,16 +5,16 @@
*/
/**
* [description]
* Subtract an `amount` from `value`, limiting the minimum result to `min`.
*
* @function Phaser.Math.MinSub
* @since 3.0.0
*
* @param {number} value - [description]
* @param {number} amount - [description]
* @param {number} min - [description]
* @param {number} value - The value to subtract from.
* @param {number} amount - The amount to subtract.
* @param {number} min - The minimum value to return.
*
* @return {number} [description]
* @return {number} The resulting value.
*/
var MinSub = function (value, amount, min)
{

View file

@ -13,10 +13,10 @@
* @function Phaser.Math.Percent
* @since 3.0.0
*
* @param {number} value - [description]
* @param {number} min - [description]
* @param {number} [max] - [description]
* @param {number} [upperMax] - [description]
* @param {number} value - The value to determine the percentage of.
* @param {number} min - The minimum value.
* @param {number} [max] - The maximum value.
* @param {number} [upperMax] - The mid-way point in the range that represents 100%.
*
* @return {float} A value between 0 and 1 representing the percentage.
*/

View file

@ -5,15 +5,19 @@
*/
/**
* [description]
* Compute a random unit vector.
*
* Computes random values for the given vector between -1 and 1 that can be used to represent a direction.
*
* Optionally accepts a scale value to scale the resulting vector by.
*
* @function Phaser.Math.RandomXY
* @since 3.0.0
*
* @param {Phaser.Math.Vector2} vector - [description]
* @param {float} scale - [description]
* @param {Phaser.Math.Vector2} vector - The Vector to compute random values for.
* @param {float} [scale=1] - The scale of the random values.
*
* @return {Phaser.Math.Vector2} [description]
* @return {Phaser.Math.Vector2} The given Vector.
*/
var RandomXY = function (vector, scale)
{

View file

@ -4,17 +4,16 @@
* @license {@link https://github.com/photonstorm/phaser/blob/master/license.txt|MIT License}
*/
// Position Vector randomly in a spherical area defined by the given radius
/**
* [description]
* Compute a random position vector in a spherical area, optionally defined by the given radius.
*
* @function Phaser.Math.RandomXYZ
* @since 3.0.0
*
* @param {Phaser.Math.Vector3} vec3 - [description]
* @param {number} [radius=1] - [description]
* @param {Phaser.Math.Vector3} vec3 - The Vector to compute random values for.
* @param {number} [radius=1] - The radius.
*
* @return {Phaser.Math.Vector3} [description]
* @return {Phaser.Math.Vector3} The given Vector.
*/
var RandomXYZ = function (vec3, radius)
{
@ -23,7 +22,7 @@ var RandomXYZ = function (vec3, radius)
var r = Math.random() * 2 * Math.PI;
var z = (Math.random() * 2) - 1;
var zScale = Math.sqrt(1 - z * z) * radius;
vec3.x = Math.cos(r) * zScale;
vec3.y = Math.sin(r) * zScale;
vec3.z = z * radius;

View file

@ -5,21 +5,21 @@
*/
/**
* [description]
* Compute a random four-dimensional vector.
*
* @function Phaser.Math.RandomXYZW
* @since 3.0.0
*
* @param {Phaser.Math.Vector4} vec4 - [description]
* @param {float} [scale=1] - [description]
* @param {Phaser.Math.Vector4} vec4 - The Vector to compute random values for.
* @param {float} [scale=1] - The scale of the random values.
*
* @return {Phaser.Math.Vector4} [description]
* @return {Phaser.Math.Vector4} The given Vector.
*/
var RandomXYZW = function (vec4, scale)
{
if (scale === undefined) { scale = 1; }
// Not spherical; should fix this for more uniform distribution
// TODO: Not spherical; should fix this for more uniform distribution
vec4.x = (Math.random() * 2 - 1) * scale;
vec4.y = (Math.random() * 2 - 1) * scale;
vec4.z = (Math.random() * 2 - 1) * scale;

View file

@ -5,17 +5,17 @@
*/
/**
* [description]
* Rotate a `point` around `x` and `y` by the given `angle`.
*
* @function Phaser.Math.RotateAround
* @since 3.0.0
*
* @param {(Phaser.Geom.Point|object)} point - [description]
* @param {number} x - [description]
* @param {number} y - [description]
* @param {number} angle - [description]
* @param {(Phaser.Geom.Point|object)} point - The point to be rotated.
* @param {number} x - The horizontal coordinate to rotate around.
* @param {number} y - The vertical coordinate to rotate around.
* @param {number} angle - The angle of rotation in radians.
*
* @return {Phaser.Geom.Point} [description]
* @return {Phaser.Geom.Point} The given point, rotated by the given angle around the given coordinates.
*/
var RotateAround = function (point, x, y, angle)
{

View file

@ -10,13 +10,13 @@
* @function Phaser.Math.RotateAroundDistance
* @since 3.0.0
*
* @param {(Phaser.Geom.Point|object)} point - The Point to be rotated.
* @param {(Phaser.Geom.Point|object)} point - The point to be rotated.
* @param {number} x - The horizontal coordinate to rotate around.
* @param {number} y - The vertical coordinate to rotate around.
* @param {number} angle - The angle of rotation in radians.
* @param {number} distance - [description]
*
* @return {Phaser.Geom.Point} [description]
* @return {Phaser.Geom.Point} The given point.
*/
var RotateAroundDistance = function (point, x, y, angle, distance)
{

View file

@ -15,17 +15,17 @@ var tmpVec3 = new Vector3();
/**
* Rotates a vector in place by axis angle.
*
* This is the same as transforming a point by an
* This is the same as transforming a point by an
* axis-angle quaternion, but it has higher precision.
*
* @function Phaser.Math.RotateVec3
* @since 3.0.0
*
* @param {Phaser.Math.Vector3} vec - [description]
* @param {Phaser.Math.Vector3} axis - [description]
* @param {float} radians - [description]
* @param {Phaser.Math.Vector3} vec - The vector to be rotated.
* @param {Phaser.Math.Vector3} axis - The axis to rotate around.
* @param {float} radians - The angle of rotation in radians.
*
* @return {Phaser.Math.Vector3} [description]
* @return {Phaser.Math.Vector3} The given vector.
*/
var RotateVec3 = function (vec, axis, radians)
{

View file

@ -5,16 +5,16 @@
*/
/**
* [description]
* Round a value to a given decimal place.
*
* @function Phaser.Math.RoundTo
* @since 3.0.0
*
* @param {number} value - [description]
* @param {integer} [place=0] - [description]
* @param {number} value - The value to be rounded.
* @param {integer} [place=0] - The decimal place to round to.
* @param {integer} [base=10] - [description]
*
* @return {number} [description]
* @return {number} The rounded value.
*/
var RoundTo = function (value, place, base)
{

View file

@ -5,16 +5,18 @@
*/
/**
* [description]
* Smoothly interpolate between two values.
*
* Computes a smooth step interpolation between `min` and `max` by `x`.
*
* @function Phaser.Math.SmoothStep
* @since 3.0.0
*
* @param {number} x - [description]
* @param {number} min - [description]
* @param {number} max - [description]
* @param {number} x - The percentage of interpolation, between 0 and 1.
* @param {number} min - The minimum value.
* @param {number} max - The maximum value.
*
* @return {number} [description]
* @return {number} The smoothly interpolated value.
*/
var SmoothStep = function (x, min, max)
{

View file

@ -5,16 +5,20 @@
*/
/**
* [description]
* Smoothly interpolate between two values.
*
* Computes a smooth step interpolation between `min` and `max` by `x`.
*
* Produces an even smoother interpolation than {@link Phaser.Math.SmoothStep}.
*
* @function Phaser.Math.SmootherStep
* @since 3.0.0
*
* @param {number} x - [description]
* @param {number} min - [description]
* @param {number} max - [description]
* @param {number} x - The percentage of interpolation, between 0 and 1.
* @param {number} min - The minimum value.
* @param {number} max - The maximum value.
*
* @return {number} [description]
* @return {number} The smoothly interpolated value.
*/
var SmootherStep = function (x, min, max)
{

View file

@ -20,7 +20,7 @@ var Vector2 = require('./Vector2');
* @param {number} rotation - Rotation of the transform point, in radians.
* @param {number} scaleX - Horizontal scale of the transform point.
* @param {number} scaleY - Vertical scale of the transform point.
* @param {(Phaser.Math.Vector2|Phaser.Geom.Point|object)} [output] - [description]
* @param {(Phaser.Math.Vector2|Phaser.Geom.Point|object)} [output] - The output vector, point or object for the translated coordinates.
*
* @return {(Phaser.Math.Vector2|Phaser.Geom.Point|object)} The translated point.
*/

View file

@ -12,8 +12,8 @@ var Class = require('../utils/Class');
/**
* @typedef {object} Vector2Like
*
* @property {number} x - [description]
* @property {number} y - [description]
* @property {number} x - The x component.
* @property {number} y - The y component.
*/
/**
@ -395,7 +395,9 @@ var Vector2 = new Class({
},
/**
* Normalise this Vector, that is, make it a unit length vector (magnitude of 1) in the same direction.
* Normalise this Vector.
*
* Makes the vector a unit length vector (magnitude of 1) in the same direction.
*
* @method Phaser.Math.Vector2#normalize
* @since 3.0.0
@ -419,10 +421,7 @@ var Vector2 = new Class({
},
/**
* Right-hand normalize (make unit length) this Vector
*/
/**
* [description]
* Right-hand normalize (make unit length) this Vector.
*
* @method Phaser.Math.Vector2#normalizeRightHand
* @since 3.0.0
@ -440,14 +439,14 @@ var Vector2 = new Class({
},
/**
* Perform a dot product between this Vector and the given Vector
* Compute the dot product of this Vector and the given Vector.
*
* @method Phaser.Math.Vector2#dot
* @since 3.0.0
*
* @param {Phaser.Math.Vector2} src - The Vector2 to dot product with this Vector2.
*
* @return {number} The result of the dot product
* @return {number} The dot product of this Vector and the given Vector.
*/
dot: function (src)
{
@ -470,13 +469,13 @@ var Vector2 = new Class({
},
/**
* [description]
* Linearly interpolate between this Vector and the given Vector.
*
* @method Phaser.Math.Vector2#lerp
* @since 3.0.0
*
* @param {Phaser.Math.Vector2} src - [description]
* @param {number} [t=0] - [description]
* @param {Phaser.Math.Vector2} src - The Vector2 to interpolate towards.
* @param {number} [t=0] - The interpolation percentage, between 0 and 1.
*
* @return {Phaser.Math.Vector2} This Vector2.
*/
@ -494,12 +493,12 @@ var Vector2 = new Class({
},
/**
* [description]
* Transform this Vector with the given Matrix.
*
* @method Phaser.Math.Vector2#transformMat3
* @since 3.0.0
*
* @param {Phaser.Math.Matrix3} mat - [description]
* @param {Phaser.Math.Matrix3} mat - The Matrix3 to transform this Vector2 with.
*
* @return {Phaser.Math.Vector2} This Vector2.
*/
@ -516,12 +515,12 @@ var Vector2 = new Class({
},
/**
* [description]
* Transform this Vector with the given Matrix.
*
* @method Phaser.Math.Vector2#transformMat4
* @since 3.0.0
*
* @param {Phaser.Math.Matrix4} mat - [description]
* @param {Phaser.Math.Matrix4} mat - The Matrix4 to transform this Vector2 with.
*
* @return {Phaser.Math.Vector2} This Vector2.
*/

View file

@ -14,7 +14,7 @@ var Linear = require('../Linear');
* @see https://en.wikipedia.org/wiki/Linear_interpolation
*
* @param {number[]} v - The input array of values to interpolate between.
* @param {!number} k - The percentage of interploation, between 0 and 1.
* @param {!number} k - The percentage of interpolation, between 0 and 1.
*
* @return {!number} The interpolated value.
*/