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.Static methods
staticinlinedistance(a:Vec2, b:Vec2):Float
Compute distance between two points.
Parameters:
a | The first point Vec2. |
|---|---|
b | The second point Vec2. |
Returns:
Distance between points.
Throws:
# | If a, b are disposed of or null. |
|---|
staticinlinedsq(a:Vec2, b:Vec2):Float
Compute square distance between two points.
Parameters:
a | The first point Vec2. |
|---|---|
b | The second point Vec2. |
Returns:
Squared distance between points.
Throws:
# | If a, b are disposed of or null. |
|---|
staticfromPoint(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.
Parameters:
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.
Throws:
# | If the point argument is null. |
|---|
staticfromPolar(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)
Parameters:
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.
staticinlineget(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.
Parameters:
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.
staticinlineweak(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).
Parameters:
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.
Constructor
new(x:Float = 0, y:Float = 0)
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).
Parameters:
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.
Variables
angle:Float
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.
Methods
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.
Parameters:
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.
Throws:
# | If this vector, or the vector argument has been disposed. |
|---|---|
# | If the vector passed as argument is null. |
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.
Parameters:
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.
Throws:
# | If this vector, or the vector argument has been disposed. |
|---|---|
# | If the vector passed as argument is null. |
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))
Parameters:
vector | The vector to add into this vector. |
|---|
Returns:
A reference to this vector.
Throws:
# | If this vector, or the vector argument has been disposed. |
|---|---|
# | If this vector is immutable. |
# | If the vector passed as argument is null. |
inlinecopy(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'.
Parameters:
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.
Throws:
# | If this vector has been disposed. |
|---|
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.
Parameters:
vector | The vector to compute cross product with. |
|---|
Returns:
The cross product of this vector and the other.
Throws:
# | If this vector, or the vector argument has been disposed. |
|---|---|
# | If the vector passed as argument is null. |
inlinedispose():Void
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.
Throws:
# | If this vector has already been disposed. |
|---|---|
# | If this vector is immutable. |
# | If this vector is in use in some other manner, such as being an element of a Polygon's vertex list. |
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))
Parameters:
vector | The vector to compute dot product with. |
|---|
Returns:
The dot product of this vector and the other.
Throws:
# | If this vector, or the vector argument has been disposed. |
|---|---|
# | If the vector passed as argument is null. |
lsq():Float
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.
Throws:
# | If this vector has been disposed. |
|---|
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.
Parameters:
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.
Throws:
# | If this vector has been disposed. |
|---|
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))
Parameters:
scalar | The number to multiply this vector with. |
|---|
Returns:
A reference to this vector.
Throws:
# | If this vector has been disposed. |
|---|---|
# | If this vector is immutable. |
normalise():Vec2
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.
Throws:
# | If this vector has been disposed of or is immutable. |
|---|---|
# | If length of this vector is 0. |
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'
Parameters:
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.
Throws:
# | If this vector has been disposed. |
|---|
reflect(vec:Vec2, weak:Bool = false):Vec2
Reflect given Vec2 in plane whose normal is this Vec2.
Parameters:
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.
Throws:
# | If this vector or argument has been disposed. |
|---|---|
# | If this vector has zero length. |
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.
Parameters:
angle | The number of radians to rotate Vec2 by in the clockwise direction. |
|---|
Returns:
A reference to 'this' Vec2.
Throws:
# | If this vector has been disposed. |
|---|---|
# | If this vector is immutable. |
inlineset(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).
Parameters:
vector | The Vec2 to set the values of this Vec2 with. |
|---|
Returns:
A reference to 'this' Vec2.
Throws:
# | If this vector, or vector argument has been disposed. |
|---|---|
# | If this vector is immutable. |
# | If the vector passed as argument is null. |
inlinesetxy(x:Float, y:Float):Vec2
Set values of this Vec2 given pair of x/y values.
Parameters:
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.
Throws:
# | If this vector has been disposed. |
|---|---|
# | If this vector is immutable. |
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.
Parameters:
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.
Throws:
# | If this vector, or the vector argument has been disposed. |
|---|---|
# | If the vector passed as argument is null. |
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))
Parameters:
vector | The vector to subtract from this vector. |
|---|
Returns:
A reference to this vector.
Throws:
# | If this vector, or the vector argument has been disposed. |
|---|---|
# | If this vector is immutable. |
# | If the vector passed as argument is null. |
toPoint(?output:Point):Point
Create an AS3 Point object from Vec2.
This method is only available on flash and
openfl||nme targets.
Parameters:
output | If supplied, this Point will have its x/y set instead of creating a new Point. |
|---|
Returns:
The AS3 Point object representing Vec2.
Throws:
# | If this vector has been disposed of. |
|---|
unit(weak:Bool = false):Vec2
Return normalisation of this vector.
Parameters:
weak | If true then the allocated Vec2 will be automatically released to the global object pool when used as an argument to a Nape function. (default false) |
|---|
Returns:
A copy of this vector, normalised.
Throws:
# | If this vector has been disposed of. |
|---|---|
# | If length of this vector is 0. |