vector package

This is simply a memory-efficient way to encapsulate many vectors. They can all be multiplied by matrices at the same time in parallel, as well. This class is only useful if you're writing low-level graphics routines instead of using someone else's.

There are three Vector types. They are largely interchangeable; any Vector may, unless otherwise specified, participate in any binary operation with any other Vector, and may multiply any Matrix.

A Vector type takes the form VecN, with 2 <= N <= 4. VecN is an N-element vector.

Actually, all vectors are 4-element. A 2-element vector is actually pretending to be a 4-element vector like {x,y,0,1}, and a 3-element vector a 4-element vector like {x,y,z,1}. Among other things, this means that if you only use Vec2 and Mat2x2, no extra work is done. And, you can use Vec3 and Mat3x4 to implement all the useful 3D affine and linear transforms you'd expect coming from OpenGL or Direct3D. (For that matter, you can use Vec2 and Mat2x4 and the third column of the matrix never even gets touched.)

vec = SubCritical.Construct("VecN") vec = SubCritical.Construct("Vec2", x, y) vec = SubCritical.Construct("Vec3", x, y, z) vec = SubCritical.Construct("Vec4", x, y, z, w)

Create a Vector. If no elements are specified, the vector contains {0,0,0,1}; otherwise, exactly the right number of elements must be given.

x,y,... = vec()

If called as though it were a function, a Vector will return its elements. You can conveniently serialize an arbitrary Vector like this:

local serial_table = {vector:Identity(), vector()}
-- Serialize the table, using (for instance) SCUtil.Dehydrate.
-- Later, when you've rehydrated the table:
local vector = SC.Construct(unpack(serial_table))

It's probably a good idea to make sure the first element of serial_table starts with "Vec" for security reasons.

new_vector = old_vector_A + old_vector_B new_vector = old_vector_A - old_vector_B

These behave as the normal simple arithmetic operators, splatted across all the elements of each Vector. The returned Vector is same size as the larger of the two operand Vectors.

is_equal = (vector_A == vector_B)

Returns true if the two Vectors are the same order and element-for-element identical, false otherwise. (This will still return false even if the two Vectors are very, very close to equal.)

dot_product = vector_A .. vector_B

Returns the dot product of the two Vectors.

new_vector = old_vector + factor new_vector = old_vector - factor

factor is a single number, which is added to (or subtracted from) all the elements of old_vector.

new_vector = old_vector * scale_factor

scale_factor is a single number, which is multiplied across all the elements of old_vector.

new_vector = old_vector / scale_factor

scale_factor is a single number, which all the elements of old_vector are divided by.

new_vector = vector_A * vector_B

Returns the component-wise product of the two vectors. new_vector will be as small as necessary; multiply a Vec2 by a Vec3 and you get another Vec2.

new_vector = -old_vector

This behaves as the normal unary negation operator, splatted across all the elements of the source Vector.

x_coordinate = vec[1] y_coordinate = vec.y z_coordinate = vec.Z

You can access individual elements of a Vector with the above notations. You can also assign to them, as long as you do not assign elements that do not exist (e.g. doing "vec.z = 1" on a Vec2).

magnitude = vector:Magnitude() magnitude_squared = vector:MagnitudeSquared()

Returns the magnitude of the Vector. (The squared magnitude is simpler to calculate, and is useful in certain other calculations.)

angle = vec:Angle() -- equivalent to AngleXY angle = vec:AngleXY() -- 2D angle -- The below functions are only defined on Vec3 and larger angle = vec:AngleXZ() -- 2D angle with Z mapped to Y angle = vec:AngleYZ() -- 2D angle with X and Y mapped to Y and Z

Returns the angle the Vector "points" along.

new_vector = old_vector:Normalize()

Returns a new Vector, in the same direction as the old one, but with unit magnitude. (If the magnitude of the old vector was zero, the new vector will be zero rather than NAN.)