Packageutils.geom
Classpublic class VMath
InheritanceVMath Inheritance Object

A class full of static functions for performing mathematical operations on vectors. These functions are kept in a static class as opposed to being methods of a Vector2D class. It takes a little more typing but it keeps the size of the vectors small and the performance as fast as possible.

Note on using Point objects: Vectors are not, strictly speaking, Points. But due to the intricate ways the Flash Player is optimized, the Point object can perform many of these functions faster than a custom-built Vector2D object. In AS3, Points are faster, functionally interchangeable with vectors, and in many cases more convenient when working with the Flash Player API (e.g. globalToLocal()). That's why I chose to use them.

Note about '$' functions: Some functions have two versions, one that affects the vector argument directly and one that returns a new vector. The ones that affect the vector argument are denoted by a '$'.

Thanks to FlashGameDojo (http://flashgamedojo.com/wiki/index.php?title=VMath) and Paul Firth (http://www.wildbunny.co.uk/blog/vector-maths-a-primer-for-games-programmers/)

View the examples



Public Properties
 PropertyDefined By
  $scale : Function
[static]
VMath
  getMagnitude : Function
[static] Alternate name for getLength()
VMath
  interpolate : Function
[static]
VMath
  scale : Function
[static]
VMath
  setMagnitude : Function
[static] Alternate name for setLength()
VMath
Public Methods
 MethodDefined By
  
$add(v1:Point, v2:Point, ... vn):Point
[static] Adds vector2 to vector1 and modifies the value of v1.
VMath
  
$divide(v:Point, s:Number):Point
[static] Divides a vector by a scalar and alters the original vector.
VMath
  
$multiply(v:Point, s:Number):Point
[static] Multiplies a vector by a scalar and altering the original vector.
VMath
  
$reverse(v:Point):void
[static] Reverses the vector v.
VMath
  
$rotate(v:Point, angle:Number):void
[static] Rotates the vector by the specified angle in radians.
VMath
  
$subtract(v1:Point, v2:Point):Point
[static] Subtracts v2 from v1 and affects the original vector
VMath
  
add(v1:Point, v2:Point, ... vn):Point
[static] Adds vector2 to vector1 and returns the result without altering either vector.
VMath
  
angleBetween(v1:Point, v2:Point):Number
[static] Calculates the angle between two vectors.
VMath
  
cross(v1:Point, v2:Point):Number
[static] Gets the cross product of two vectors
VMath
  
distance(v1:Point, v2:Point):Number
[static]
VMath
  
divide(v:Point, s:Number):Point
[static] Divides a vector by a scalar and returns the result without affecting the original vector.
VMath
  
dot(v1:Point, v2:Point):Number
[static] Gets the dot product of two vectors.
VMath
  
getAngle(v:Point):Number
[static] Returns the angle of the vector in radians.
VMath
  
getLength(v:Point):Number
[static] Returns the length of the vector (distance from 0,0 to v).
VMath
  
getMagnitudeSquared(v:Point):Number
[static] Returns the square of the magnitude of the vector.
VMath
  
getPerpindicular(v:Point):Point
[static]
VMath
  
getUnit(v:Point):Point
[static] Returns a copy of the vector as a unit vector.
VMath
  
getUnitI():Point
[static] Returns a unit vector "i-hat" codirectional with the x axis.
VMath
  
getUnitJ():Point
[static] Returns a unit vector "j-hat" codirectional with the y axis.
VMath
  
[static] Returns a new vector with components (0,0).
VMath
  
isEqual(v1:Point, v2:Point, ... vn):Boolean
[static] Returns true if all of the vector arguments have the same x and y components.
VMath
  
isOpposite(v1:Point, v2:Point):Boolean
[static] Returns true if v2 points in the opposite direction of v1.
VMath
  
isParallel(v1:Point, v2:Point):Boolean
[static] Returns true if the angle between v1 and v2 is 0° or 180°.
VMath
  
isPerpindicular(v1:Point, v2:Point):Boolean
[static] Returns true if the angle between v1 and v2 is 90° or 270°.
VMath
  
isUnit(v:Point):Boolean
[static] Returns true if the length of the vector is 1.
VMath
  
multiply(v:Point, s:Number):Point
[static] Multiplies a vector by a scalar and returns the result without affecting the original vector.
VMath
  
normalize(v:Point, l:Number = 1.0):void
[static] A copy of the Point object's normalize() function put here for consistency.
VMath
  
pointBetween(p1:Point, p2:Point, percentageBetween:Number = 0.5):Point
[static] Finds a point on a line between two points.
VMath
  
project(v1:Point, v2:Point):Point
[static] Projects v1 onto v2.
VMath
  
reverse(v:Point):Point
[static] Returns a new vector that is pointing the opposite direction from v.
VMath
  
rotate(v:Point, angle:Number):Point
[static] Returns a vector which is the original vector by the specified angle in radians.
VMath
  
setAngle(v:Point, angle:Number):void
[static] Sets the angle of the vector in radians while maintaining the length
VMath
  
setLength(v:Point, l:Number):void
[static] Sets the length of the vector to a new scalar.
VMath
  
sign(v1:Point, v2:Point):int
[static] Determines if a given vector is to the right or left of this vector.
VMath
  
subtract(v1:Point, v2:Point):Point
[static] Subtracts v2 from v1 and returns the result.
VMath
  
toArray(v:Point):Array
[static] Returns an array with two elements based on the vector.
VMath
  
toMatrix(v:Point):Matrix
[static] Returns a transformation matrix with x and y translation based on the vector.
VMath
Property Detail
$scaleproperty
public static var $scale:Function

getMagnitudeproperty 
public static var getMagnitude:Function

Alternate name for getLength()

interpolateproperty 
public static var interpolate:Function

scaleproperty 
public static var scale:Function

setMagnitudeproperty 
public static var setMagnitude:Function

Alternate name for setLength()

Method Detail
$add()method
public static function $add(v1:Point, v2:Point, ... vn):Point

Adds vector2 to vector1 and modifies the value of v1.

Parameters

v1:Point — The original vector
 
v2:Point — The vector to be added to v1
 
... vn — Additional vectors to add.

Returns
Point
$divide()method 
public static function $divide(v:Point, s:Number):Point

Divides a vector by a scalar and alters the original vector.

Parameters

v:Point — A vector instance.
 
s:Number — A scalar value to divides by.

Returns
Point
$multiply()method 
public static function $multiply(v:Point, s:Number):Point

Multiplies a vector by a scalar and altering the original vector.

Parameters

v:Point — A vector instance.
 
s:Number — A scalar value to multipy by.

Returns
Point
$reverse()method 
public static function $reverse(v:Point):void

Reverses the vector v.

Parameters

v:Point — A vector to reverse.

$rotate()method 
public static function $rotate(v:Point, angle:Number):void

Rotates the vector by the specified angle in radians. Different from setAngle() in that it adds to the previous angle.

Parameters

v:Point
 
angle:Number

$subtract()method 
public static function $subtract(v1:Point, v2:Point):Point

Subtracts v2 from v1 and affects the original vector

Parameters

v1:Point
 
v2:Point

Returns
Point
add()method 
public static function add(v1:Point, v2:Point, ... vn):Point

Adds vector2 to vector1 and returns the result without altering either vector.

Parameters

v1:Point — The original vector
 
v2:Point — The vector to be added to v1
 
... vn — Additional vectors to add.

Returns
Point
angleBetween()method 
public static function angleBetween(v1:Point, v2:Point):Number

Calculates the angle between two vectors.

Parameters

v1:Point — The first vector instance.
 
v2:Point — The second vector instance.

Returns
Number — Number the angle between the two given vectors.
cross()method 
public static function cross(v1:Point, v2:Point):Number

Gets the cross product of two vectors

Parameters

v1:Point — Vector to evaluate cross product with
 
v2:Point — Vector to evaluate cross product with

Returns
Number — cross product of v1 and v2
distance()method 
public static function distance(v1:Point, v2:Point):Number

Parameters

v1:Point
 
v2:Point

Returns
Number

See also

flash.geom.Point.distance()
divide()method 
public static function divide(v:Point, s:Number):Point

Divides a vector by a scalar and returns the result without affecting the original vector.

Parameters

v:Point — A vector instance.
 
s:Number — A scalar value to divides by.

Returns
Point
dot()method 
public static function dot(v1:Point, v2:Point):Number

Gets the dot product of two vectors.

Parameters

v1:Point
 
v2:Point

Returns
Number — the dot product of v and the instance
getAngle()method 
public static function getAngle(v:Point):Number

Returns the angle of the vector in radians.

Parameters

v:Point

Returns
Number
getLength()method 
public static function getLength(v:Point):Number

Returns the length of the vector (distance from 0,0 to v).

Parameters

v:Point — The vector to get the length from.

Returns
Number — Number The length of the vector.

See also

flash.geom.Point.length
getMagnitudeSquared()method 
public static function getMagnitudeSquared(v:Point):Number

Returns the square of the magnitude of the vector.

Parameters

v:Point

Returns
Number
getPerpindicular()method 
public static function getPerpindicular(v:Point):Point

Parameters

v:Point

Returns
Point — a new Vector that is perpindicular to the vector provided.
getUnit()method 
public static function getUnit(v:Point):Point

Returns a copy of the vector as a unit vector.

Parameters

v:Point

Returns
Point
getUnitI()method 
public static function getUnitI():Point

Returns a unit vector "i-hat" codirectional with the x axis.

Returns
Point
getUnitJ()method 
public static function getUnitJ():Point

Returns a unit vector "j-hat" codirectional with the y axis.

Returns
Point
getZeroVector()method 
public static function getZeroVector():Point

Returns a new vector with components (0,0).

Returns
Point
isEqual()method 
public static function isEqual(v1:Point, v2:Point, ... vn):Boolean

Returns true if all of the vector arguments have the same x and y components.

Parameters

v1:Point
 
v2:Point
 
... vn

Returns
Boolean
isOpposite()method 
public static function isOpposite(v1:Point, v2:Point):Boolean

Returns true if v2 points in the opposite direction of v1.

Parameters

v1:Point
 
v2:Point

Returns
Boolean
isParallel()method 
public static function isParallel(v1:Point, v2:Point):Boolean

Returns true if the angle between v1 and v2 is 0° or 180°.

Parameters

v1:Point
 
v2:Point

Returns
Boolean
isPerpindicular()method 
public static function isPerpindicular(v1:Point, v2:Point):Boolean

Returns true if the angle between v1 and v2 is 90° or 270°.

Parameters

v1:Point
 
v2:Point

Returns
Boolean
isUnit()method 
public static function isUnit(v:Point):Boolean

Returns true if the length of the vector is 1.

Parameters

v:Point

Returns
Boolean
multiply()method 
public static function multiply(v:Point, s:Number):Point

Multiplies a vector by a scalar and returns the result without affecting the original vector.

Parameters

v:Point — A vector instance.
 
s:Number — A scalar value to multipy by.

Returns
Point
normalize()method 
public static function normalize(v:Point, l:Number = 1.0):void

A copy of the Point object's normalize() function put here for consistency.

Parameters

v:Point
 
l:Number (default = 1.0)

pointBetween()method 
public static function pointBetween(p1:Point, p2:Point, percentageBetween:Number = 0.5):Point

Finds a point on a line between two points.

Parameters

p1:Point — The first point.
 
p2:Point — The second point.
 
percentageBetween:Number (default = 0.5) — The location on the line to find the point. Default is 0.5 which is exactly halfway between the two points.

Returns
Point — Point A new point located on the line between the two points.
project()method 
public static function project(v1:Point, v2:Point):Point

Projects v1 onto v2.

Parameters

v1:Point
 
v2:Point

Returns
Point
reverse()method 
public static function reverse(v:Point):Point

Returns a new vector that is pointing the opposite direction from v.

Parameters

v:Point — A vector to reverse.

Returns
Point — Point a new vector.
rotate()method 
public static function rotate(v:Point, angle:Number):Point

Returns a vector which is the original vector by the specified angle in radians. Different from setAngle() in that it adds to the previous angle.

Parameters

v:Point
 
angle:Number

Returns
Point
setAngle()method 
public static function setAngle(v:Point, angle:Number):void

Sets the angle of the vector in radians while maintaining the length

Parameters

v:Point
 
angle:Number

setLength()method 
public static function setLength(v:Point, l:Number):void

Sets the length of the vector to a new scalar. Note: if the vector is already length zero, the result will be zero.

Parameters

v:Point — The vector to set the length of.
 
l:Number — The new length of the vector.

sign()method 
public static function sign(v1:Point, v2:Point):int

Determines if a given vector is to the right or left of this vector.

Parameters

v1:Point
 
v2:Point

Returns
int — int If to the left, returns -1. If to the right, +1.
subtract()method 
public static function subtract(v1:Point, v2:Point):Point

Subtracts v2 from v1 and returns the result.

Parameters

v1:Point
 
v2:Point

Returns
Point
toArray()method 
public static function toArray(v:Point):Array

Returns an array with two elements based on the vector.

Parameters

v:Point

Returns
Array
toMatrix()method 
public static function toMatrix(v:Point):Matrix

Returns a transformation matrix with x and y translation based on the vector.

Parameters

v:Point

Returns
Matrix
Examples
This exampe shows the difference between add() and $add()
     var v1:Point = new Point(5, 5);
     var v2:Point = new Point(10, 0);
     
     var sum:Point = VMath.add(v1, v2); // sum = (15,5). v1 and v2 are unaffected.
     VMath.$add(v1,v2); // v1 = (15, 5), v2 is unaffected.