class nape.geom.Vec2
Available on all platforms
2 Dimensional vector.
*
* Note that in many cases of a Vec2 object being returned by a Nape function
* the Vec2 object will be marked internally as an 'immutable' Vec2. This will
* always be documented and trying to mutate such a Vec2 will result in an
* error being thrown.
*
* Vec2 objects can make use of a global object pool, attempting to make use
* of a disposed Vec2 will also result in an error with the object pool
* working in a FILO order to increase the likelihood of such misuse being
* caught.
*
* Additionally Vec2 objects can be created as 'weak'. Passing a weak Vec2 to
* any Nape function as an argument will result in the automatic disposal of
* the Vec2 once the method has finished with it. There may be exceptions to
* this rule which will also be documented; a notable case being the appending
* of a weak Vec2 to a Nape Vec2List in which case the disposal of the weak
* Vec2 is performed when that Vec2List is handed to a Nape function instead.
*
* Example:
*
* var vertices = Polygon.box(20, 20, true); * var polygon = new Polygon(vertices); ** In this example, passing
true
to the Polygon.box method means
* that we will be returned a Vec2List containing only 'weak' Vec2s. Upon
* passing this Vec2List to the Polygon constructor, all of the Vec2s from
* that list will be automatically disposed.Class Fields
static function distance(a:Vec2, b:Vec2):Float
Compute distance between two points. * *
a | The first point Vec2. * |
b | The second point Vec2. * |
returns | Distance between points. * |
static function dsq(a:Vec2, b:Vec2):Float
Compute square distance between two points. * *
a | The first point Vec2. * |
b | The second point Vec2. * |
returns | Squared distance between points. * |
static function fromPoint(point:Point, ?weak:Bool = false):Vec2
Allocate a Vec2 from AS3 Point object.
*
* This Vec2 will be allocated from the global object pool.
*
* This method is only available on flash
and
* openfl||nme
targets.
*
*
point | The AS3 Point to initialise Vec2 with * |
weak | If true, then a weak Vec2 will be allocated which will * be automatically released to the object pool when * pass as an argument to any Nape function. * (default false) * |
returns | The possibly weak Vec2 allocated with same values as input Point object. |
static function fromPolar(length:Float, angle:Float, ?weak:Bool = false):Vec2
Allocate a Vec2 given polar coordinates.
*
* This Vec2 will be allocated from the global object pool.
*
* This method will assign x/y values equal respectively to:
* length*Math.cos(angle)
,
* length*Math.sin(angle)
*
*
length | The length of the Vec2. This value may be negative. * |
angle | The angle of the Vec2 as measured in radians clockwise * from the positive x axis. * |
weak | If true, then a weak Vec2 will be allocated which will be * automatically released to the object pool when passed as * an argument to any Nape function. (default false) * |
returns | The possibly weak Vec2 allocated with given polar values. |
static function get(?x:Float = 0, ?y:Float = 0, ?weak:Bool = false):Vec2
Allocates a Vec2 from the global object pool.
*
* Note that Vec2.get(x, y, true)
is exactly equivalent to
* Vec2.weak(x, y)
and should be preferred.
*
*
x | The x coordinate for the vector. (default 0) * |
y | The y coordinate for the vector. (default 0) * |
weak | If true, then a weak Vec2 will be allocated which will be * automatically released to object pool when passed as an * argument to a Nape function. (default false) * |
returns | The allocated, possibly weak Vec2 with given x/y values. |
static function weak(?x:Float = 0, ?y:Float = 0):Vec2
Allocate a weak Vec2 from global object pool.
*
* This object which will be automaticaly released back to the object pool
* when supplied as an argument to a Nape function.
*
* Note that Vec2.weak(x, y)
is exactly equivalent to
* Vec2.get(x, y, true)
.
*
*
x | The x coordinate for the vector. (default 0) * |
y | The y coordiante for the vector. (default 0) * |
returns | The allocated weak Vec2 with given x/y values. |
Instance Fields
Angle of this Vec2.
* Measured in radians as measured clockwise from the positive x axis.
* The value will be given in the range -pi to pi.
*
* If the x/y values of this Vec2 are both 0, then the angle value will
* default to 0.
*
* This value can also be set (to any value) so that vec.angle +=
* Math.PI
is a valid - if sub-optimial - way of negating a Vec2.
* @default 0
Length of this Vec2.
*
* This value can be set and may be set to negative values so that
* vec.length *= -1
is a valid - if sub-optimal - way of
* negating a Vec2.
*
* @default 0
function new(?x:Float = 0, ?y:Float = 0):Void
Construct a new Vec2.
*
* This constructor will obviously not make use of
* the global object pool: Vec2.get
should be used in
* preference noting that new Vec2(x, y)
is semantically
* equivalent to Vec2.get(x, y)
.
*
*
x | The x coordinate for the vector. (default 0) * |
y | The y coordinate for the vector. (default 0) * |
returns | The newly constructed Vec2 object with given x/y values. |
function add(vector:Vec2, ?weak:Bool = false):Vec2
Add another vector to this vector.
*
* Returns a newly allocated vector so that
* this vector is not modified.
*
*
vector | The vector to add to this vector. This value can not be * null * |
weak | If true then the returned vector will be automatically * released to the global object pool when used as an * argument to another Nape function. (default false) * |
returns | The possibly weak vector representing the sum of this and the input vector. |
function addMul(vector:Vec2, scalar:Float, ?weak:Bool = false):Vec2
Add a multiple of a vector to this vector.
*
* This operation is equivalent to:
*
* this.add(vector.mul(scalar, true)); **
* Returns a newly allocated vector so that * this vector is not modified. *
*
vector | The vector to add to this vector. This value can not be * null * |
scalar | The scalar multiplier for the vector being added. * |
weak | If true then the returned vector will be automatically * released to the global object pool when used as an * argument to another Nape function. (default false) * |
returns | The possibly weak vector representing the sum of this and the input vector by scalar multiplier. |
function addeq(vector:Vec2):Vec2
Add another vector into this vector.
*
* This vector is mutated to be the result of the operation.
*
* Semantically equivalent to (the less optimal)
* vec1.set(vec1.add(vec2))
*
*
vector | The vector to add into this vector. * |
returns | A reference to this vector. * |
function copy(?weak:Bool = false):Vec2
Produce a copy of this Vec2.
*
* The Vec2 will be allocated from the global object pool.
*
* As would be expected, if you produce a copy of an 'immutable' Vec2, then
* the copy will be 'mutable'.
*
*
weak | If true, then a weak Vec2 will be allocated which will be * automatically released to the object pool when passed as an * argument to any Nape function. (default false) * |
returns | The possibly weak copy of this Vec2. * |
function cross(vector:Vec2):Float
Cross product with another vector.
*
* Also known as the perp-dot product, this operation represents
* the determinant of the matrix formed by having the 2 columns
* as the two vectors. This is also the z-value of a 3D cross product
* if you extend the input vectors with a z-value of 0.
*
* Though not technically a cross-product in the way a 3D cross product
* is, it shares many mathematical similarities.
*
* If one of the vectors is of length 1. Then the cross product is the
* length of the projection of the other vector onto the
* right-perpendicular of the unit vector.
*
* The cross and dot product are related like:
* vec1.cross(vec2) == vec1.perp().dot(vec2)
* Hence the name 'perp-dot'
*
* Another useful property is that if the cross-product of two vectors
* is 0, then the vectors are collinear, if positive then the second
* vector is 'to the right' of the first vector, and if negative then
* the second vector is 'to the left' of the first vector.
*
*
vector | The vector to compute cross product with. * |
returns | The cross product of this vector and the other. * |
Release this Vec2 to global object pool.
*
* Once diposed this Vec2
* will be accessible to Nape internals for re-allocation and should
* not be touched (Good practice would be to set any references to this
* Vec2 to null to help ensure this).
*
* In debug mode, should you attempt to access this Vec2 after disposal
* and the Vec2 is still in the object pool, you will be given an Error.
* The object pool operates on a First-In-Last-Out principal in debug
* mode to help catch these sort of errors.
*
function dot(vector:Vec2):Float
Dot product with another vector.
*
* The dot product is equal to the product of the length of each
* vector, multiplied by the cosine of the smallest angle between them.
*
* If one of the vectors is of length 1. Then the dot product is the
* length of the projection of the other vector onto it which may be
* computed (assuming 'this' is of length 1) like:
* vec1.mul(vec1.dot(vec2))
*
*
vector | The vector to compute dot product with. * |
returns | The dot product of this vector and the other. * |
Compute squared length of this Vec2.
*
* This is exactly the same as performing vec.length *
* vec.length
except for being more effecient.
*
*
returns | The squared length of this Vec2. * |
function mul(scalar:Float, ?weak:Bool = false):Vec2
Multiply this vector with a number.
*
* Returns a newly allocated vector so that this vector is not mutated.
*
*
scalar | The number to multiply this vector with. * |
weak | If true then the returned vector will be automatically * released to the global object pool when used as an * argument to another Nape function. (default false) * |
returns | The possibly weak vector representing the multiplication of this vector and the input number. |
function muleq(scalar:Float):Vec2
Multiply this vector with a number.
*
* This vector is mutated to be the result of the operation.
*
* Semantically equivalent to (the less optimal)
* vec.set(vec.mul(scalar))
*
*
scalar | The number to multiply this vector with. * |
returns | A reference to this vector. * |
Normalise this vector.
*
* Equivalent to setting the length of the vector to 1, and also to the
* (less-optimal) this.set(this.unit())
.
*
*
returns | A reference to 'this' vector. * |
function perp(?weak:Bool = false):Vec2
The right-perpendicular to this vector.
*
* Computes the result of rotating this vector by 90 degrees clockwise
* returning a newly allocated vector.
*
* This is semantically equivalent to (the less optimal)
* vec.copy().rotate(Math.PI/2)
*
* The cross and dot product are related like:
* vec1.cross(vec2) == vec1.perp().dot(vec2)
* Hence the name 'perp-dot'
*
*
weak | If true then the returned vector will be automatically * released to the global object pool when used as an argument * to another Nape function. (default false) * |
returns | The possibly weakly allocated, right-perpendicular to this vector. |
function reflect(vec:Vec2, ?weak:Bool = false):Vec2
Reflect given Vec2 in plane whose normal is this Vec2.
*
*
vec | The vector to be reflected. * |
weak | If true, the returned Vec2 will be automatically released * to object pool when used in another Nape function (default false) * |
returns | The reflected Vec2. * |
function rotate(angle:Float):Vec2
Rotate Vec2 in-place by given number of radians..
*
* Rotation performed in the clockwise direction.
*
* The Vec2 will be mutated, with it's new x/y values being the result
* of the rotation.
*
*
angle | The number of radians to rotate Vec2 by in the clockwise * direction. * |
returns | A reference to 'this' Vec2. * |
function set(vector:Vec2):Vec2
Set values of this Vec2 to those of the argument.
*
* Note that vec.set(p)
is semantically equivalent to
* vec.setxy(p.x, p.y)
.
*
*
vector | The Vec2 to set the values of this Vec2 with. * |
returns | A reference to 'this' Vec2. * |
function setxy(x:Float, y:Float):Vec2
Set values of this Vec2 given pair of x/y values. * *
x | The x value to set this Vec2's x value to. * |
y | The y value to set this Vec2's y value to. * |
returns | A reference to 'this' Vec2. * |
function sub(vector:Vec2, ?weak:Bool = false):Vec2
Subtract another vector from this vector.
*
* Returns a newly allocated vector so that this vector is not mutated.
*
*
vector | The vector to subtract from this vector. This value can * not be null * |
weak | If true then the returned vector will be automatically * released to the global object pool when used as an * argument to another Nape function. (default false) * |
returns | The possibly weak vector representing the subtraction of the input vector from this vector. |
function subeq(vector:Vec2):Vec2
Subtract another vector from this vector.
*
* This vector is mutated to be the result of the operation.
*
* Semantically equivalent to (the less optimal)
* vec1.set(vec1.sub(vec2))
*
*
vector | The vector to subtract from this vector. * |
returns | A reference to this vector. * |