Mirrors/phaser
2
0
Fork 0
mirror of https://github.com/photonstorm/phaser synced 2025-02-18 15:08:31 +00:00
Code Issues Projects Releases Packages Wiki Activity

Documented most of Vector4. Improved documentation consistency between Vector classes.

Browse source
This commit is contained in:
Chris Andrew 2018-05-23 15:00:03 +01:00
parent c9d17fb9c7
commit 01d45f5d83
3 changed files with 101 additions and 81 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
src/math/Vector2.js
View file

@ -178,9 +178,9 @@ var Vector2 = new Class({
}, },
/** /**
* Check if this Vector is equal to a given Vector. * Check whether this Vector is equal to a given Vector.
* *
* Performs a strict equality comparison between each Vector's components. * Performs a strict equality check against each Vector's components.
* *
* @method Phaser.Math.Vector2#equals * @method Phaser.Math.Vector2#equals
* @since 3.0.0 * @since 3.0.0
@ -255,7 +255,7 @@ var Vector2 = new Class({
/** /**
* Perform a component-wise multiplication between this Vector and the given Vector. * Perform a component-wise multiplication between this Vector and the given Vector.
* *
* This Vector is multiplied by the given Vector. * Multiplies this Vector by the given Vector.
* *
* @method Phaser.Math.Vector2#multiply * @method Phaser.Math.Vector2#multiply
* @since 3.0.0 * @since 3.0.0
@ -301,7 +301,7 @@ var Vector2 = new Class({
/** /**
* Perform a component-wise division between this Vector and the given Vector. * Perform a component-wise division between this Vector and the given Vector.
* *
* This Vector is divided by the given Vector. * Divides this Vector by the given Vector.
* *
* @method Phaser.Math.Vector2#divide * @method Phaser.Math.Vector2#divide
* @since 3.0.0 * @since 3.0.0
@ -319,7 +319,7 @@ var Vector2 = new Class({
}, },
/** /**
* Negate the x and y components of this Vector. * Negate the `x` and `y` components of this Vector.
* *
* @method Phaser.Math.Vector2#negate * @method Phaser.Math.Vector2#negate
* @since 3.0.0 * @since 3.0.0
@ -335,14 +335,14 @@ var Vector2 = new Class({
}, },
/** /**
* Calculate the distance between this Vector, and the given Vector. * Calculate the distance between this Vector and the given Vector.
* *
* @method Phaser.Math.Vector2#distance * @method Phaser.Math.Vector2#distance
* @since 3.0.0 * @since 3.0.0
* *
* @param {Phaser.Math.Vector2} src - The Vector to calculate the distance to. * @param {Phaser.Math.Vector2} src - The Vector to calculate the distance to.
* *
* @return {number} The distance to the given Vector from this Vector. * @return {number} The distance from this Vector to the given Vector.
*/ */
distance: function (src) distance: function (src)
{ {
@ -360,7 +360,7 @@ var Vector2 = new Class({
* *
* @param {Phaser.Math.Vector2} src - The Vector to calculate the distance to. * @param {Phaser.Math.Vector2} src - The Vector to calculate the distance to.
* *
* @return {number} The distance to this Vector and the given Vector, squared. * @return {number} The distance from this Vector to the given Vector, squared.
*/ */
distanceSq: function (src) distanceSq: function (src)
{ {
@ -421,6 +421,7 @@ var Vector2 = new Class({
if (len > 0) if (len > 0)
{ {
len = 1 / Math.sqrt(len); len = 1 / Math.sqrt(len);
this.x = x * len; this.x = x * len;
this.y = y * len; this.y = y * len;
} }
@ -479,6 +480,8 @@ var Vector2 = new Class({
/** /**
* Linearly interpolate between this Vector and the given Vector. * Linearly interpolate between this Vector and the given Vector.
* *
* Interpolates this Vector towards the given Vector.
*
* @method Phaser.Math.Vector2#lerp * @method Phaser.Math.Vector2#lerp
* @since 3.0.0 * @since 3.0.0
* *

22
src/math/Vector3.js
View file

@ -134,9 +134,9 @@ var Vector3 = new Class({
}, },
/** /**
* Determine whether this Vector is equal to a given Vector. * Check whether this Vector is equal to a given Vector.
* *
* Performs a strict equality comparison between each Vector's components. * Performs a strict equality check against each Vector's components.
* *
* @method Phaser.Math.Vector3#equals * @method Phaser.Math.Vector3#equals
* @since 3.0.0 * @since 3.0.0
@ -257,7 +257,7 @@ var Vector3 = new Class({
/** /**
* Perform a component-wise multiplication between this Vector and the given Vector. * Perform a component-wise multiplication between this Vector and the given Vector.
* *
* This Vector is multiplied by the given Vector. * Multiplies this Vector by the given Vector.
* *
* @method Phaser.Math.Vector3#multiply * @method Phaser.Math.Vector3#multiply
* @since 3.0.0 * @since 3.0.0
@ -306,7 +306,7 @@ var Vector3 = new Class({
/** /**
* Perform a component-wise division between this Vector and the given Vector. * Perform a component-wise division between this Vector and the given Vector.
* *
* This Vector is divided by the given Vector. * Divides this Vector by the given Vector.
* *
* @method Phaser.Math.Vector3#divide * @method Phaser.Math.Vector3#divide
* @since 3.0.0 * @since 3.0.0
@ -325,7 +325,7 @@ var Vector3 = new Class({
}, },
/** /**
* Negate the x, y and z components of this Vector. * Negate the `x`, `y` and `z` components of this Vector.
* *
* @method Phaser.Math.Vector3#negate * @method Phaser.Math.Vector3#negate
* @since 3.0.0 * @since 3.0.0
@ -342,14 +342,14 @@ var Vector3 = new Class({
}, },
/** /**
* Calculate the distance between this Vector, and the given Vector. * Calculate the distance between this Vector and the given Vector.
* *
* @method Phaser.Math.Vector3#distance * @method Phaser.Math.Vector3#distance
* @since 3.0.0 * @since 3.0.0
* *
* @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - The Vector to calculate the distance to. * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - The Vector to calculate the distance to.
* *
* @return {number} The distance to the given Vector from this Vector. * @return {number} The distance from this Vector to the given Vector.
*/ */
distance: function (v) distance: function (v)
{ {
@ -368,7 +368,7 @@ var Vector3 = new Class({
* *
* @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - The Vector to calculate the distance to. * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3)} v - The Vector to calculate the distance to.
* *
* @return {number} The distance between this Vector, and the given Vector, squared. * @return {number} The distance from this Vector to the given Vector, squared.
*/ */
distanceSq: function (v) distanceSq: function (v)
{ {
@ -486,6 +486,8 @@ var Vector3 = new Class({
/** /**
* Linearly interpolate between this Vector and the given Vector. * Linearly interpolate between this Vector and the given Vector.
* *
* Interpolates this Vector towards the given Vector.
*
* @method Phaser.Math.Vector3#lerp * @method Phaser.Math.Vector3#lerp
* @since 3.0.0 * @since 3.0.0
* *
@ -563,7 +565,7 @@ var Vector3 = new Class({
* @method Phaser.Math.Vector3#transformCoordinates * @method Phaser.Math.Vector3#transformCoordinates
* @since 3.0.0 * @since 3.0.0
* *
* @param {Phaser.Math.Matrix4} mat - [description] * @param {Phaser.Math.Matrix4} mat - The Matrix4 to transform this Vector3 with.
* *
* @return {Phaser.Math.Vector3} This Vector3. * @return {Phaser.Math.Vector3} This Vector3.
*/ */
@ -628,7 +630,7 @@ var Vector3 = new Class({
* @method Phaser.Math.Vector3#project * @method Phaser.Math.Vector3#project
* @since 3.0.0 * @since 3.0.0
* *
* @param {Phaser.Math.Matrix4} mat - [description] * @param {Phaser.Math.Matrix4} mat - The Matrix4 to multiply this Vector3 with.
* *
* @return {Phaser.Math.Vector3} This Vector3. * @return {Phaser.Math.Vector3} This Vector3.
*/ */

141
src/math/Vector4.js
View file

@ -11,17 +11,19 @@ var Class = require('../utils/Class');
/** /**
* @classdesc * @classdesc
* [description] * A representation of a vector in 4D space.
*
* A four-component vector.
* *
* @class Vector4 * @class Vector4
* @memberOf Phaser.Math * @memberOf Phaser.Math
* @constructor * @constructor
* @since 3.0.0 * @since 3.0.0
* *
* @param {number} [x] - [description] * @param {number} [x] - The x component of this Vector.
* @param {number} [y] - [description] * @param {number} [y] - The y component of this Vector.
* @param {number} [z] - [description] * @param {number} [z] - The z component of this Vector.
* @param {number} [w] - [description] * @param {number} [w] - The w component of this Vector.
*/ */
var Vector4 = new Class({ var Vector4 = new Class({
@ -37,6 +39,7 @@ var Vector4 = new Class({
* @default 0 * @default 0
* @since 3.0.0 * @since 3.0.0
*/ */
this.x = 0;
/** /**
* The y component of this Vector. * The y component of this Vector.
@ -46,6 +49,7 @@ var Vector4 = new Class({
* @default 0 * @default 0
* @since 3.0.0 * @since 3.0.0
*/ */
this.y = 0;
/** /**
* The z component of this Vector. * The z component of this Vector.
@ -55,6 +59,7 @@ var Vector4 = new Class({
* @default 0 * @default 0
* @since 3.0.0 * @since 3.0.0
*/ */
this.z = 0;
/** /**
* The w component of this Vector. * The w component of this Vector.
@ -64,6 +69,7 @@ var Vector4 = new Class({
* @default 0 * @default 0
* @since 3.0.0 * @since 3.0.0
*/ */
this.w = 0;
if (typeof x === 'object') if (typeof x === 'object')
{ {
@ -82,12 +88,12 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Make a clone of this Vector4.
* *
* @method Phaser.Math.Vector4#clone * @method Phaser.Math.Vector4#clone
* @since 3.0.0 * @since 3.0.0
* *
* @return {Phaser.Math.Vector4} [description] * @return {Phaser.Math.Vector4} A clone of this Vector4.
*/ */
clone: function () clone: function ()
{ {
@ -95,14 +101,14 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Copy the components of a given Vector into this Vector.
* *
* @method Phaser.Math.Vector4#copy * @method Phaser.Math.Vector4#copy
* @since 3.0.0 * @since 3.0.0
* *
* @param {Phaser.Math.Vector4} src - [description] * @param {Phaser.Math.Vector4} src - The Vector to copy the components from.
* *
* @return {Phaser.Math.Vector4} This Vector4 object. * @return {Phaser.Math.Vector4} This Vector4.
*/ */
copy: function (src) copy: function (src)
{ {
@ -115,7 +121,9 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Check whether this Vector is equal to a given Vector.
*
* Performs a strict quality check against each Vector's components.
* *
* @method Phaser.Math.Vector4#equals * @method Phaser.Math.Vector4#equals
* @since 3.0.0 * @since 3.0.0
@ -130,17 +138,17 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Set the `x`, `y`, `z` and `w` components of the this Vector to the given `x`, `y`, `z` and `w` values.
* *
* @method Phaser.Math.Vector4#set * @method Phaser.Math.Vector4#set
* @since 3.0.0 * @since 3.0.0
* *
* @param {number} x - [description] * @param {(number|object)} x - The x value to set for this Vector, or an object containing x, y, z and w components.
* @param {number} y - [description] * @param {number} y - The y value to set for this Vector.
* @param {number} z - [description] * @param {number} z - The z value to set for this Vector.
* @param {number} w - [description] * @param {number} w - The z value to set for this Vector.
* *
* @return {Phaser.Math.Vector4} This Vector4 object. * @return {Phaser.Math.Vector4} This Vector4.
*/ */
set: function (x, y, z, w) set: function (x, y, z, w)
{ {
@ -163,14 +171,14 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Add a given Vector to this Vector. Addition is component-wise.
* *
* @method Phaser.Math.Vector4#add * @method Phaser.Math.Vector4#add
* @since 3.0.0 * @since 3.0.0
* *
* @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - [description] * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - The Vector to add to this Vector.
* *
* @return {Phaser.Math.Vector4} This Vector4 object. * @return {Phaser.Math.Vector4} This Vector4.
*/ */
add: function (v) add: function (v)
{ {
@ -183,14 +191,14 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Subtract the given Vector from this Vector. Subtraction is component-wise.
* *
* @method Phaser.Math.Vector4#subtract * @method Phaser.Math.Vector4#subtract
* @since 3.0.0 * @since 3.0.0
* *
* @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - [description] * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - The Vector to subtract from this Vector.
* *
* @return {Phaser.Math.Vector4} This Vector4 object. * @return {Phaser.Math.Vector4} This Vector4.
*/ */
subtract: function (v) subtract: function (v)
{ {
@ -203,14 +211,14 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Scale this Vector by the given value.
* *
* @method Phaser.Math.Vector4#scale * @method Phaser.Math.Vector4#scale
* @since 3.0.0 * @since 3.0.0
* *
* @param {number} scale - [description] * @param {number} scale - The value to scale this Vector by.
* *
* @return {Phaser.Math.Vector4} This Vector4 object. * @return {Phaser.Math.Vector4} This Vector4.
*/ */
scale: function (scale) scale: function (scale)
{ {
@ -223,12 +231,12 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Calculate the length (or magnitude) of this Vector.
* *
* @method Phaser.Math.Vector4#length * @method Phaser.Math.Vector4#length
* @since 3.0.0 * @since 3.0.0
* *
* @return {number} [description] * @return {number} The length of this Vector.
*/ */
length: function () length: function ()
{ {
@ -241,12 +249,12 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Calculate the length of this Vector squared.
* *
* @method Phaser.Math.Vector4#lengthSq * @method Phaser.Math.Vector4#lengthSq
* @since 3.0.0 * @since 3.0.0
* *
* @return {number} [description] * @return {number} The length of this Vector, squared.
*/ */
lengthSq: function () lengthSq: function ()
{ {
@ -259,12 +267,14 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Normalize this Vector.
*
* Makes the vector a unit length vector (magnitude of 1) in the same direction.
* *
* @method Phaser.Math.Vector4#normalize * @method Phaser.Math.Vector4#normalize
* @since 3.0.0 * @since 3.0.0
* *
* @return {Phaser.Math.Vector4} This Vector4 object. * @return {Phaser.Math.Vector4} This Vector4.
*/ */
normalize: function () normalize: function ()
{ {
@ -288,14 +298,14 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Calculate the dot product of this Vector and the given Vector.
* *
* @method Phaser.Math.Vector4#dot * @method Phaser.Math.Vector4#dot
* @since 3.0.0 * @since 3.0.0
* *
* @param {Phaser.Math.Vector4} v - [description] * @param {Phaser.Math.Vector4} v - The Vector4 to dot product with this Vector4.
* *
* @return {number} [description] * @return {number} The dot product of this Vector and the given Vector.
*/ */
dot: function (v) dot: function (v)
{ {
@ -303,15 +313,17 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Linearly interpolate between this Vector and the given Vector.
*
* Interpolates this Vector towards the given Vector.
* *
* @method Phaser.Math.Vector4#lerp * @method Phaser.Math.Vector4#lerp
* @since 3.0.0 * @since 3.0.0
* *
* @param {Phaser.Math.Vector4} v - [description] * @param {Phaser.Math.Vector4} v - The Vector4 to interpolate towards.
* @param {number} [t=0] - [description] * @param {number} [t=0] - The interpolation percentage, between 0 and 1.
* *
* @return {Phaser.Math.Vector4} This Vector4 object. * @return {Phaser.Math.Vector4} This Vector4.
*/ */
lerp: function (v, t) lerp: function (v, t)
{ {
@ -331,14 +343,16 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Perform a component-wise multiplication between this Vector and the given Vector.
*
* Multiplies this Vector by the given Vector.
* *
* @method Phaser.Math.Vector4#multiply * @method Phaser.Math.Vector4#multiply
* @since 3.0.0 * @since 3.0.0
* *
* @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - [description] * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - The Vector to multiply this Vector by.
* *
* @return {Phaser.Math.Vector4} This Vector4 object. * @return {Phaser.Math.Vector4} This Vector4.
*/ */
multiply: function (v) multiply: function (v)
{ {
@ -351,14 +365,16 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Perform a component-wise division between this Vector and the given Vector.
*
* Divides this Vector by the given Vector.
* *
* @method Phaser.Math.Vector4#divide * @method Phaser.Math.Vector4#divide
* @since 3.0.0 * @since 3.0.0
* *
* @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - [description] * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - The Vector to divide this Vector by.
* *
* @return {Phaser.Math.Vector4} This Vector4 object. * @return {Phaser.Math.Vector4} This Vector4.
*/ */
divide: function (v) divide: function (v)
{ {
@ -371,14 +387,14 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Calculate the distance between this Vector and the given Vector.
* *
* @method Phaser.Math.Vector4#distance * @method Phaser.Math.Vector4#distance
* @since 3.0.0 * @since 3.0.0
* *
* @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - [description] * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - [description]
* *
* @return {number} [description] * @return {number} The distance from this Vector to the given Vector.
*/ */
distance: function (v) distance: function (v)
{ {
@ -391,14 +407,14 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Calculate the distance between this Vector, and the given Vector, squared.
* *
* @method Phaser.Math.Vector4#distanceSq * @method Phaser.Math.Vector4#distanceSq
* @since 3.0.0 * @since 3.0.0
* *
* @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - [description] * @param {(Phaser.Math.Vector2|Phaser.Math.Vector3|Phaser.Math.Vector4)} v - The Vector to calculate the distance to.
* *
* @return {number} [description] * @return {number} The distance from this Vector to the given Vector, squared.
*/ */
distanceSq: function (v) distanceSq: function (v)
{ {
@ -411,12 +427,12 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Negate the `x`, `y`, `z` and `w` components of this Vector.
* *
* @method Phaser.Math.Vector4#negate * @method Phaser.Math.Vector4#negate
* @since 3.0.0 * @since 3.0.0
* *
* @return {Phaser.Math.Vector4} This Vector4 object. * @return {Phaser.Math.Vector4} This Vector4.
*/ */
negate: function () negate: function ()
{ {
@ -429,14 +445,14 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Transform this Vector with the given Matrix.
* *
* @method Phaser.Math.Vector4#transformMat4 * @method Phaser.Math.Vector4#transformMat4
* @since 3.0.0 * @since 3.0.0
* *
* @param {Phaser.Math.Matrix4} mat - [description] * @param {Phaser.Math.Matrix4} mat - The Matrix4 to transform this Vector4 with.
* *
* @return {Phaser.Math.Vector4} This Vector4 object. * @return {Phaser.Math.Vector4} This Vector4.
*/ */
transformMat4: function (mat) transformMat4: function (mat)
{ {
@ -454,21 +470,20 @@ var Vector4 = new Class({
return this; return this;
}, },
// TODO: is this really the same as Vector3?
// Also, what about this: http://molecularmusings.wordpress.com/2013/05/24/a-faster-quaternion-vector-multiplication/
/** /**
* [description] * Transform this Vector with the given Quaternion.
* *
* @method Phaser.Math.Vector4#transformQuat * @method Phaser.Math.Vector4#transformQuat
* @since 3.0.0 * @since 3.0.0
* *
* @param {Phaser.Math.Quaternion} q - [description] * @param {Phaser.Math.Quaternion} q - The Quaternion to transform this Vector with.
* *
* @return {Phaser.Math.Vector4} This Vector4 object. * @return {Phaser.Math.Vector4} This Vector4.
*/ */
transformQuat: function (q) transformQuat: function (q)
{ {
// TODO: is this really the same as Vector3?
// Also, what about this: http://molecularmusings.wordpress.com/2013/05/24/a-faster-quaternion-vector-multiplication/
// benchmarks: http://jsperf.com/quaternion-transform-vec3-implementations // benchmarks: http://jsperf.com/quaternion-transform-vec3-implementations
var x = this.x; var x = this.x;
var y = this.y; var y = this.y;
@ -493,12 +508,12 @@ var Vector4 = new Class({
}, },
/** /**
* [description] * Make this Vector the zero vector (0, 0, 0, 0).
* *
* @method Phaser.Math.Vector4#reset * @method Phaser.Math.Vector4#reset
* @since 3.0.0 * @since 3.0.0
* *
* @return {Phaser.Math.Vector4} This Vector4 object. * @return {Phaser.Math.Vector4} This Vector4.
*/ */
reset: function () reset: function ()
{ {