This module provides the following directional vector and point classes:
The Normal2d and Normal3d classes are provided for clarity when the intent is to store a unit vector functioning as a surface normal. Otherwise they are identical to the Dir2d and Dir3d classes, and actually implemented by the same.
Single precision variants of these classes are also available. Simply prefix these class names with "Float" to use them.
x_axis -> An object of Dir3d initialized with (1, 0, 0)
y_axis -> An object of Dir3d initialized with (0, 1, 0)
z_axis -> An object of Dir3d initialized with (0, 0, 1)
The Dir2d Class
Objects of this class represent directional vectors which are typically kept a unit length.
This class has the following constant data members:
Dir2d.kNumElements -> constant integer value of 2
Dir2d.kElementSize -> constant integer value of 4
This class has the following construction methods:
Dir2d ()
Constructs a new 2D vector with uninitialized values.
Returns the new vector.
Dir2d (dir)
dir -> Dir2d
Constructs a new 2D vector by copying the given 2D vector.
Returns the new vector.
Dir2d (x, y)
x -> double
y -> double
Constructs a new 2D vector with the given values.
Returns the new vector.
Dir2d (t)
t -> table of two double values, either numerically indexed
or indexed by the keys 'x' and 'y'
Constructs a new 2D vector with the values from the given table.
Returns the new vector.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "x" -> the x coordinate value
2 | "y" -> the y coordinate value
Every instance of this class has the following member methods:
Dir2d:GetAngleBetween (other)
other -> Dir2d
Returns the 2D angle between one vector and the other in radians.
Dir2d:Normalize ()
Normalizes the vector to a length of one.
The original vector is modified in place. Returns the newly normalized vector.
Dir2d:NormalTransform (richMatrix, useInverse)
richMatrix -> FloatRichMatrix3x3 | RichMatrix3x3
useInverse -> boolean
Transforms the vector by the supplied rich matrix, treating the vector as a normal and preserving the normal properties.
This means it will remain perpendicular to any surface also transformed.
Rich matrices contain both a transformation and its inverse.
The original vector is modified in place.
Returns the newly transformed vector.
Dir2d:Set (value [ , value2 ] )
value [ , value2 ]-> double
Sets the vector with a single value in all positions, or using two new values.
The original vector is modified in place.
Returns the newly modified vector.
Dir2d:Transform (matrix)
matrix -> FloatMatrix3x3 | Matrix3x3
Transforms the vector by the supplied matrix.
The original vector is modified in place.
Returns the newly transformed vector.
... plus all of the member methods documented in the Common Vector Methods section.
Objects of this class represent directional vectors which are typically kept a unit length.
This class has the following constant data members:
Dir3d.kNumElements -> constant integer value of 3
Dir3d.kElementSize -> constant integer value of 4
This class has the following construction methods:
Dir3d ()
Constructs a new 3D vector with uninitialized values.
Returns the new vector.
Dir3d (dir)
dir -> Dir3d
Constructs a new 3D vector by copying the given 3D vector.
Returns the new vector.
Dir3d (x, y, z)
x -> double
y -> double
z -> double
Constructs a new 3D vector with the given values.
Returns the new vector.
Dir3d (t)
t -> table of three double values, either numerically indexed or indexed by the keys 'x', 'y' and 'z'
Constructs a new 3D vector with the values from the given table.
Returns the new vector.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "x" -> the x coordinate value
2 | "y" -> the y coordinate value
3 | "z" -> the z coordinate value
Every instance of this class has the following member methods:
Dir3d:GetAngleBetween (other)
other -> Dir3d
Returns the 3D angle between one vector and the other in radians.
Dir3d:Normalize ()
Normalizes the vector to a length of one.
The original vector is modified in place.
Returns the newly normalized vector.
Dir3d:NormalTransform (quaternion)
quaternion -> Quaternion | DoubleQuaternion
Transforms the vector by the supplied quaternion, treating the vector as a normal and preserving the normal properties.
This means it will remain perpendicular to any surface also transformed. The original vector is modified in place. Returns the newly transformed vector.
Dir3d:NormalTransform (richMatrix, useInverse)
richMatrix -> FloatRichMatrix3x3 | FloatRichMatrix4x3 | FloatRichMatrix4x4 | RichMatrix3x3 | RichMatrix4x3 | RichMatrix4x4
useInverse -> boolean
Transforms the vector by the supplied rich matrix,
treating the vector as a normal and preserving the normal properties.
This means it will remain perpendicular to any surface also transformed.
Rich matrices contain both a transformation and its inverse.
The original vector is modified in place.
Returns the newly transformed vector.
Dir3d:Set (value [ , value2, value3 ] )
value [ , value2, value3 ]-> double
Sets the vector with a single value in all positions, or using three new values.
The original vector is modified in place.
Returns the newly modified vector.
Dir3d:SetCrossProduct (other)
other -> Dir3d
Sets the vector to the cross product of this vector with another vector.
The original vector is modified in place.
Returns the newly modified vector.
Dir3d:Transform (matrix)
matrixOrQuaternion -> FloatMatrix3x3 | FloatMatrix4x3 | FloatMatrix4x4 | Matrix3x3 | Matrix4x3 | Matrix4x4 | Quaternion | DoubleQuaternion
Transforms the vector by the supplied matrix or quaternion.
The original vector is modified in place.
Returns the newly transformed vector.
... plus all of the member methods documented in the Common Vector Methods section.
The Point2d Class
Objects of this class represent positional vectors (points), and their component values may range over all real numbers.
This class has the following constant data members:
Point2d.kNumElements -> constant integer value of 2
Point2d.kElementSize -> constant integer value of 4
This class has the following construction methods:
Point2d ()
Constructs a new 2D point with uninitialized values.
Returns the new point.
Point2d (point)
point -> Point2d
Constructs a new 2D point by copying the given 2D point.
Returns the new point.
Point2d (x, y)
x -> double
y -> double
Constructs a new 2D point with the given values.
Returns the new point.
Point2d (t)
t -> table of two double values, either numerically indexed or indexed by the keys 'x' and 'y'
Constructs a new 2D point with the values from the given table.
Returns the new point.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "x" -> the x coordinate value
2 | "y" -> the y coordinate value
Every instance of this class has the following member methods:
Point2d:GetDistanceBetween (other)
other -> Point2d
Returns the 2D distance between one point and the other.
Point2d:GetDistanceBetweenSquared (other)
other -> Point2d
Returns the square of the 2D distance between one point and the other.
Point2d:Set (value [ , value2 ] )
value [ , value2 ] -> double
Sets the point with a single value in all positions, or using two new values.
The original point is modified in place.
Returns the newly modified point.
Point2d:Transform (matrix)
matrix -> FloatMatrix3x3 | Matrix3x3
Transforms the point by the supplied matrix.
The original point is modified in place.
Returns the newly transformed point.
... plus all of the member methods documented in the Common Vector Methods section.
Objects of this class represent positional vectors (points), and their component values may range over all real numbers.
This class has the following constant data members:
Point3d.kNumElements -> constant integer value of 3
Point3d.kElementSize -> constant integer value of 4
This class has the following construction methods:
Point3d ()
Constructs a new 3D point with uninitialized values.
Returns the new point.
Point3d (point)
point -> Point3d
Constructs a new 3D point by copying the given 3D point.
Returns the new point.
Point3d (x, y, z)
x -> double
y -> double
z -> double
Constructs a new 3D point with the given values.
Returns the new point.
Point3d (t)
t -> table of three double values, either numerically indexed or indexed by the keys 'x', 'y' and 'z'
Constructs a new 3D point with the values from the given table.
Returns the new point.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "x" -> the x coordinate value
2 | "y" -> the y coordinate value
3 | "z" -> the z coordinate value
Every instance of this class has the following member methods:
Point3d: GetDistanceBetween (other)
other -> Point3d
Returns the 3D distance between one point and the other.
Point3d:GetDistanceBetweenSquared (other)
other -> Point3d
Returns the square of the 3D distance between one point and the other.
Point3d:Set (value [ , value2, value3 ] )
value [ , value2, value3 ] -> double
Sets the point with a single value in all positions, or using three new values.
The original point is modified in place.
Returns the newly modified point.
Point3d:SetCrossProduct (other)
other -> Point3d
Sets the point to the cross product of this point with another point.
The original point is modified in place.
Returns the newly modified point.
Point3d:Transform (matrixOrQuaternion)
matrixOrQuaternion -> FloatMatrix3x3 | FloatMatrix4x3 | FloatMatrix4x4 | Matrix3x3 |
Matrix4x3 | Matrix4x4 | Quaternion | DoubleQuaternion
Transforms the point by the supplied matrix or quaternion.
The original point is modified in place.
Returns the newly transformed point.
... plus all of the member methods documented in the Common Vector Methods section.
All instances of the vector and point classes also support the following member methods, where the vector or point class is referenced as "this_object_type":
object: Add (obj)
obj -> this_object_type (the same type as this object)
Adds the given object to this object in memberwise fashion, value by value.
The original object is modified in place.
Returns the newly added to object.
object:Clone ()
Returns a newly allocated copy of this object.
object:DotProduct (obj)
obj -> this_object_type (the same type as this object)
Returns the dot product of this object with the given object.
object:GetLength ()
Returns the scalar length of this object.
object:GetLengthSquared ()
Returns the square of the scalar length of this object.
object:IndexedElement (index)
index -> integer (from 1 to this_object_type.kNumElements)
Returns the indexed value.
This seems a bit redundant now that I think of it, but it's potentially faster than the normal numerical Lua index operation.
object:IsEqual (obj)
obj -> this_object_type (the same type as this object)
Returns true if this object is exactly equal to the given object, compared value by value.
Returns false otherwise.
object:IsFinite ()
Returns true this object defines a finite value, otherwise false.
object:IsNearEqual (obj)
tolerance -> double
obj -> this_object_type (the same type as this object)
Returns true if the elements of this object are equal to the elements of the given object within a tolerance determined by the precision of the elements.
Returns false otherwise.
object:IsNearEqual (obj, tolerance)
tolerance -> double
obj -> this_object_type (the same type as this object)
Returns true if the elements of this object are equal to the elements of the given object within the given tolerance.
Returns false otherwise.
object:IsNearZero ()
tolerance -> double
Returns true if every value in this object is nearly zero using a tolerance determined by the precision of the elements.
Returns false otherwise.
object:IsNearZero (tolerance)
tolerance -> double
Returns true if every value in this object is nearly zero using the given tolerance.
Returns false otherwise.
object:IsZero ()
Returns true if this object is filled with zeros.
Returns false otherwise.
object:Multiply (scalar) Multiplies the given object by a scalar, value by value.
scalar -> double
The original object is modified in place.
Returns the newly scaled object.
object:Negate ()
Sets every value in this object to the negative value of the existing value.
The original object is modified in place.
Returns the newly negated object.
object:SetAbs ()
Sets every value in this object to the absolute value of the existing value.
The original object is modified in place.
Returns the newly changed object.
object:SetZero ()
Sets every value in this object to zero.
The original object is modified in place.
Returns the newly zeroed object.
object:Subtract (obj)
obj -> this_object_type (the same type as this object)
subtracts the given object from this object in memberwise fashion, value by value.
The original object is modified in place.
Returns the newly subtracted from object.
All instances of the vector and point classes also support the following operators:
object:__eq (obj)
Available as the infix notation "=="
Returns the result of calling object:IsEqual(obj).
object:__tostring ()
Available via the tostring() global Lua function, and called from many other places.
Returns a textual representation of this object.
Objects of this class consist of a three-dimensional origin point and direction vector, useful for tasks such as ray casting.
This class has the following constant data members:
VectorPair3d.kOriginClass -> The class of the origin of this pair, in this case Point3d.
VectorPair3d.kDirectionClass -> The class of the origin of this pair, in this case Dir3d.
This class has the following construction methods:
VectorPair3d ()
Constructs a new vector pair with uninitialized values.
Returns the new object.
VectorPair3d (vector)
vector -> VectorPair3d
Constructs a new vector pair by copying the given vector pair.
Returns the new object.
VectorPair3d (origin, direction)
origin -> Point3d
direction -> Dir3d
Constructs a new vector pair with the given values.
Returns the new object.
Every instance of this class has the following member values, accessible both by numeric indices and the following keys:
1 | "origin" -> the origin as a Point3d
2 | "direction" -> the direction as a Dir3d
Every instance of this class has the following member methods:
VectorPair3d:Clone ()
Returns a newly allocated copy of this object.