jStage.Vector

Description

A set of functions that perform mathematical operations on 2D Vectors.

Hierarchy

Remarks

Though create(x, y) initializes a vector as a 2-element Float32Array, any array object with two elements may be used with these functions. See tojicode.com for more information about this implementation.

Function List

Function Documentation

add(vec1, vec2, out)

Adds the X and Y values of two vectors together.

Parameters

vec1:A vector object with values you'd like to add to another vector.

vec2:A vector object with values you'd like to add to another vector.

out:The vector object into which the result of the addition will be stored.

Returns

The vector object passed as the out parameter.

addValues(vec, x, y, out)

Adds arbitrary X and Y values to the X and Y values of a vector.

Parameters

vec:The vector object to which the arbitrary X and Y values will be added.

x:An arbitrary numeric value to add to the vector's X value.

y:An arbitrary numeric value to add to the vector's Y value.

out:The vector object into which the result of the addition will be stored.

Returns

The vector object passed as the out parameter.

clone(vec)

Initializes a new Float32Array with two elements for use as a 2D vector, taking it's initial values from another vector object.

Parameters

vec:A compatible array-vector object to clone.

Returns

A new Float32Array with the same initial values as the input.

copy(vec, out)

Sets the values of the given vector to the values of another vector.

Parameters

vec:The vector object from which you're copying values.

out:The vector object to which you're assigning values.

Returns

The vector object passed as the out parameter.

create(x, y)

Initializes a new Float32Array with two elements for use as a 2D vector.

Parameters

x:The initial value for the X component.

y:The initial value for the Y component.

Returns

A new Float32Array with two elements representing x and y.

difference(vec1, vec2)

A shortcut function for providing a few different measures of difference between two vector objects.

Parameters

vec1:A vector object with which you'd like to measure the difference with another vector.

vec2:A vector object with which you'd like to measure the difference with another vector.

Returns

An object with three properties:
{
   x: vec2.x - vec1.x,
   y: vec2.y - vec1.y,
   distance: distance(vec1,vec2)
}

distance(vec1, vec2)

Determines the distance between two points.

Parameters

vec1:A vector object representing a point in 2D space.

vec2:A vector object representing a point in 2D space.

Returns

The length of a line directly connecting the two points.

Remarks

This function requires the use of Math.sqrt(); since this can be expensive if called many times per second, in instances where you're checking against a known distance threshold it may be faster instead to determine what your trigger value is when squared and compare that to distanceSquared(vec1, vec2) (which does not use Math.sqrt()).

distanceSquared(vec1, vec2)

Determines the square of the distance between two points.

Parameters

vec1:A vector object representing a point in 2D space.

vec2:A vector object representing a point in 2D space.

Returns

The square of the length of a line directly connecting the two points.

distanceValues(vec, vx, vy)

Determines the distance between two points.

Parameters

vec:A vector object representing a point in 2D space.

vx:The X component of an arbitrary point in 2D space.

vy:The Y component of an arbitrary point in 2D space.

Returns

The length of a line directly connecting the two points.

divide(vec1, vec2, out)

Divides the X and Y values of one vector by the X and Y values of another.

Parameters

vec1:A vector object with values acting as numerators in a division with another vector.

vec2:A vector object with values acting as denominators in a division with another vector.

out:The vector object into which the result of the division will be stored.

Returns

The vector object passed as the out parameter.

dot(vec1, vec2)

Determines the dot product of two vectors.

Parameters

vec1:A vector object to use in a dot product calculation.

vec2:A vector object to use in a dot product calculation.

Returns

The dot product of the two vector objects.

isZero(vec)

Quickly check if the values of this vector are small enough to consider the length of the vector as being zero.

Parameters

vec:A vector object to check for zero-ness.

Returns

true if both components of the vector object were within +/- 1E-06 of 0.0, false otherwise.

length(vec)

Gets the length of a vector (i.e. the distance from (0,0) if the vector represented coordinates in 2D space).

Parameters

vec:The vector object from which to calculate length.

Returns

The length of a line directly connecting the vector and the origin.

Remarks

This function requires the use of Math.sqrt(); since this can be expensive if called many times per second, in instances where you're checking against a known length threshold it may be faster instead to determine what your trigger value is when squared and compare that to lengthSquared(vec) (which does not use Math.sqrt()).

lengthSquared(vec)

Determines the square of the length of a vector.

Parameters

vec:The vector object from which to calculate length.

Returns

The square of the length of a line directly connecting the vector and the origin.

max(vec1, out)

Compares the X and Y values of two vectors, returning a vector with the max of each.

Parameters

vec1:A vector object to compare with another.

out:The vector object into which the result of the comparison will be stored.

Returns

The vector object passed as the out parameter.

min(vec1, out)

Compares the X and Y values of two vectors, returning a vector with the minimum of each.

Parameters

vec1:A vector object to compare with another.

out:The vector object into which the result of the comparison will be stored.

Returns

The vector object passed as the out parameter.

multiply(vec1, vec2, out)

Multiplies the X and Y values of two vectors together.

Parameters

vec1:A vector object with values you'd like to multiply with another vector.

vec2:A vector object with values you'd like to multiply with another vector.

out:The vector object into which the result of the multiplication will be stored.

Returns

The vector object passed as the out parameter.

multiplyValues(vec, x, y, out)

Multiplies arbitrary X and Y values with the X and Y values of a vector.

Parameters

vec:The vector object with which the arbitrary X and Y values will be multiplied.

x:An arbitrary numeric value to multiply with the vector's X value.

y:An arbitrary numeric value to multiply with the vector's Y value.

out:The vector object into which the result of the multiplication will be stored.

Returns

The vector object passed as the out parameter.

normalize(vec, out)

Normalizes the X and Y values of a vector such that the length of the vector will equal 1.

Parameters

vec:The vector to normalize.

out:The vector object into which the result of the normalization will be stored.

Returns

The vector object passed as the out parameter.

scale(vec, scalar, out)

Multiplies the X and Y values of a vector by a scalar value.

Parameters

vec:A vector object with values you'd like to multiply by a given scalar.

scalar:A scalar (numeric value) by which you'd like to multiply the given vector.

out:The vector object into which the result of the multiplication will be stored.

Returns

The vector object passed as the out parameter.

scaleAdd(vec1, vec2, scalar, out)

Multiplies the X and Y values of a vector by a scalar value, then adds the result to another vector.

Parameters

vec1:A vector object with values you'd like to add to the result of the scale operation.

vec2:A vector object with values you'd like to multiply by a given scalar.

scalar:A scalar (numeric value) by which you'd like to multiply the given vector.

out:The vector object into which the result of the operations will be stored.

Returns

The vector object passed as the out parameter.

Remarks

This function can be represented algebraically as out = vec1 + (vec2 * scalar).

scaleAddAdd(vec1, vec2, vec3, scalar, out)

Adds two vectors together, multiplies the result by a scalar value, then adds the result to a third vector.

Parameters

vec1:The outermost vector to which the result of all other operations will be added.

vec2:One of the two inner vectors which will be added together.

vec3:The other of the inner vectors which will be added together.

scalar:A scalar (numeric value) by which you'd like to multiply the result of the inner vector addition.

out:The vector object into which the result of the operations will be stored.

Returns

The vector object passed as the out parameter.

Remarks

This function can be represented algebraically as out = vec1 + ((vec2 + vec3) * scalar).

scaleAddValues(vec, x, y, scalar, out)

Multiplies arbitrary X and Y values by a scalar value, then adds the result to a vector.

Parameters

vec:A vector object with values you'd like to add to the result of the scale operation.

x:An arbitrary numeric value to multiply with the given scalar.

y:An arbitrary numeric value to multiply with the given scalar.

scalar:A scalar (numeric value) by which you'd like to multiply the given X and Y values.

out:The vector object into which the result of the operations will be stored.

Returns

The vector object passed as the out parameter.

Remarks

Functionally this is the same as scaleAdd(vec1, vec2, scalar, out), but with the X and Y parameters taking place of the vec2 parameter.

set(x, y, out)

Sets the values of the given vector to the passed parameters.

Parameters

x:The value to apply for the X component.

y:The value to apply for the Y component.

out:The vector object to which you're assigning values.

Returns

The vector object passed as the out parameter.

subtract(vec1, vec2, out)

Subtracts the X and Y values of one vector from those of another.

Parameters

vec1:The vector object from which the subtraction will occur.

vec2:The vector object with values that will be subtracted from the other.

out:The vector object into which the result of the subtraction will be stored.

Returns

The vector object passed as the out parameter.

subtractFromValues(vec, x, y, out)

Subtracts the X and Y values of a vector from arbitrary X and Y values.

Parameters

vec:The vector object with values that will be subtracted from the arbitary X and Y values.

x:An arbitrary numeric value from which to subtract from the vector's X value.

y:An arbitrary numeric value from which to subtract from the vector's Y value.

out:The vector object into which the result of the subtraction will be stored.

Returns

The vector object passed as the out parameter.

Remarks

Functionally this is the same as subtractValues(vec, x, y, out), but with the operands switched around to opposite sides of the subtraction.

subtractValues(vec, x, y, out)

Subtracts arbitrary X and Y values from the X and Y values of a vector.

Parameters

vec:The vector object from which the arbitrary X and Y values will be subtracted.

x:An arbitrary numeric value to subtract from the vector's X value.

y:An arbitrary numeric value to subtract from the vector's Y value.

out:The vector object into which the result of the subtraction will be stored.

Returns

The vector object passed as the out parameter.

toString(vec)

Generates a human-readable coordinate pair string from a vector.

Parameters

vec:The vector object from which you're creating a string.

Returns

A string containing an XY coordinate pair.

transform(vector, matrix, out)

Transforms a vector to another coordinate system.

Parameters

vector:A vector object to to transform to another coordinate system.

matrix:A 2x2 Matrix object representing the two axes of the new coordinate system.

out:The vector object into which the result of the transformation will be stored.

Returns

The vector object passed as the out parameter.

zero(vec)

Resets the X and Y values of a vector to 0.0

Parameters

vec:The vector object to reset to 0.0

Returns

The vector object passed as the vec parameter.