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&#42Math.cos(angle), * length&#42Math.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

var 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.
* @default 0

var 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. * * @default 0

var x:Float

x coordinate of vector. * * @default 0

var y:Float

y coordinate of vector. * * @default 0

var zpp_disp:Bool

@private

var zpp_inner:ZPP_Vec2

@private

var zpp_pool:Vec2

@private

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. *

function dispose():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. *

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. *

function 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. *

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. *

function 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. *

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. *

function toPoint(?output:Point = null):Point

Create an AS3 Point object from Vec2. *

* This method is only available on flash and * openfl||nme targets. * *

output

If supplied, this Point will have its x/y * set instead of creating a new Point. *

returns

The AS3 Point object representing Vec2. *

function toString():String

@private

function unit(?weak:Bool = false):Vec2

Return normalisation of this vector. * *

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. *