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.

Constructor

@:value({ y : 0, x : 0 })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.

length:Float

Length of this Vec2.

This value can be set and may be set to negative values so that vec.length &#42= -1 is a valid - if sub-optimal - way of negating a Vec2.

x:Float

x coordinate of vector.

y:Float

y coordinate of vector.

zpp_disp:Bool

@private

@:value(null)zpp_inner:ZPP_Vec2 = null

@private

@:value(null)zpp_pool:Vec2 = null

@private

Methods

@:value({ weak : false })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.

@:value({ weak : false })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.

@:value({ weak : false })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 &#42 vec.length except for being more effecient.

Returns:

The squared length of this Vec2.

Throws:

#

If this vector has been disposed.

@:value({ weak : false })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.

@:value({ weak : false })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.

@:value({ weak : false })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.

@:value({ weak : false })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.

@:value({ output : 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.

@:keeptoString():String

@private

@:value({ weak : false })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.

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.

@:value({ weak : false })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.

@:value({ weak : false })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&#42Math.cos(angle), length&#42Math.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.

@:value({ weak : false, y : 0, x : 0 })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.

@:value({ y : 0, x : 0 })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.