vecmath.js - Outerra/anteworld GitHub Wiki
This is tutorial on functions available in vecmath.js, that can be used when the library is included into a js script.
It is located in bin/lib folder.
Vec2 functions
Vec2.get(obj, index)
Description: Retrieves the x or y component of a vector based on an index.
Parameters:
obj(Vec2): The vector object.index(number): The index (0 = x, 1 = y).
Returns: The corresponding component value or NaN if the index is invalid.
Vec2.set(obj, index, val)
Description: Sets the x or y component of a vector.
Parameters:
obj(Vec2): The vector object.index(number): The index (0 = x, 1 = y).val(number): The new value to assign.
Returns: The modified vector.
Vec2.setAll(obj, x, y)
Description: Sets all components of the vector.
Parameters:
obj(Vec2): The vector object.x(number): Newxvalue.y(number): Newyvalue.
Returns: The modified vector.
Vec2.neg(obj, result)
Description: Negates the components of a vector.
Parameters:
obj(Vec2): The input vector.result(Vec2, optional): Optional vector to store the result.
Returns: The negated vector.
Vec2.add(obj1, obj2, result)
Description: Adds two vectors component-wise.
Parameters:
obj1(Vec2): The first vector.obj2(Vec2): The second vector.result(Vec2, optional): Optional vector to store the result.
Returns: The resulting vector after addition.
Vec2.sub(obj1, obj2, result)
Description: Subtracts one vector from another component-wise.
Parameters:
obj1(Vec2): The first vector.obj2(Vec2): The second vector.result(Vec2, optional): Optional vector to store the result.
Returns: The resulting vector after subtraction.
Vec2.mul(obj1, obj2, result)
Description: Multiplies two vectors component-wise.
Parameters:
obj1(Vec2): The first vector.obj2(Vec2): The second vector.result(Vec2, optional): Optional vector to store the result.
Returns: The resulting vector after multiplication.
Vec2.scale(obj, scalar, result)
Description: Scales a vector by a scalar value.
Parameters:
obj(Vec2): The vector object.scalar(number): The scaling factor.result(Vec2, optional): Optional vector to store the result.
Returns: The scaled vector.
Vec2.dot(obj1, obj2)
Description: Computes the dot product of two vectors.
Parameters:
obj1(Vec2): The first vector.obj2(Vec2): The second vector.
Returns: The dot product of the two vectors.
Vec2.div(obj1, obj2, result)
Description: Divides one vector by another component-wise.
Parameters:
obj1(Vec2): The numerator vector.obj2(Vec2): The denominator vector.result(Vec2, optional): Optional vector to store the result.
Returns: The resulting vector after division.
Vec2.swizzle(obj, index1, index2, result)
Description: Retrieves selected components of a vector in a different order.
Parameters:
obj(Vec2): The source vector.index1(number): Index of the first component.index2(number): Index of the second component.result(Vec2, optional): Optional vector to store the result.
Returns: Resulting vector.
Vec2.clamp(obj, lowerLimit, upperLimit, result)
Description: Clamps a vector's components within a given range.
Parameters:
obj(Vec2): The vector to clamp.lowerLimit(Vec2): The lower limit vector.upperLimit(Vec2): The upper limit vector.result(Vec2, optional): Optional vector to store the result.
Returns: Clamped vector.
Vec2.getLength(obj)
Description: Computes the magnitude (length) of a vector.
Parameters:
obj(Vec2): The vector.
Returns: The length of the vector.
Vec2.sign(obj, result)
Description: Returns the sign of each component of a vector.
Parameters:
obj(Vec2): The input vector.result(Vec2, optional): Optional vector to store the result.
Returns: Sign of each component of a vector.
Vec2.abs(obj, result)
Description: Returns the absolute values of a vector's components.
Parameters:
obj(Vec2): The input vector.result(Vec2, optional): Optional vector to store the result.
Returns: Absolute vector.
Vec2.distance(obj1, obj2)
Description: Computes the Euclidean distance between two vectors.
Parameters:
obj1(Vec2): The first vector.obj2(Vec2): The second vector.
Returns: The distance between the two vectors.
Vec2.normalize(obj, result)
Description: Returns the normalized (unit-length) version of a vector.
Parameters:
obj(Vec2): The vector to normalize.result(Vec2, optional): Optional vector to store the result.
Returns: Normalized vector.
Vec2.equals(obj1, obj2, eps)
Description: Checks if two vectors are approximately equal within a small tolerance.
Parameters:
obj1(Vec2): The first vector.obj2(Vec2): The second vector.eps(number, optional): The tolerance value. Defaults to 0.000001.
Returns: true if the vectors are equal within the tolerance, otherwise false.
Vec2.copy(obj, result)
Description: Copies a vector.
Parameters:
obj(Vec2): The vector to copy.result(Vec2, optional): Optional vector to store the result.
Returns: Copied vector.
Vec3 functions
Vec3.get(obj, index)
Description: Retrieves the x, y or z component of a vector based on the index.
Parameters:
obj(Vec3): The vector object.index(number): The index (0 = x, 1 = y, 2 = z).
Returns: The corresponding component value or NaN if the index is invalid.
Vec3.set(obj, index, val)
Description: Sets the x, y or z component of the vector.
Parameters:
obj(Vec3): The vector object.index(number): The index (0 = x, 1 = y, 2 = z).val(number): The new value to assign.
Returns: The modified vector object.
Vec3.setAll(obj, x, y, z)
Description: Sets all components of the vector.
Parameters:
obj(Vec3): The vector object.x(number): Newxvalue.y(number): Newyvalue.z(number): Newzvalue.
Returns: The modified vector object.
Vec3.neg(obj, result)
Description: Negates the components of a vector.
Parameters:
obj(Vec3): The input vector.result(Vec3, optional): Optional vector to store the result.
Returns: The negated vector.
Vec3.add(obj1, obj2, result)
Description: Adds two vectors.
Parameters:
obj1(Vec3): The first vector.obj2(Vec3): The second vector.result(Vec3, optional): Optional vector to store the result.
Returns: The resulting vector after addition.
Vec3.sub(obj1, obj2, result)
Description: Subtracts one vector from another.
Parameters:
obj1(Vec3): The first vector.obj2(Vec3): The second vector.result(Vec3, optional): Optional vector to store the result.
Returns: The resulting vector after subtraction.
Vec3.mul(obj1, obj2, result)
Description: Multiplies two vectors.
Parameters:
obj1(Vec3): The first vector.obj2(Vec3): The second vector.result(Vec3, optional): Optional vector to store the result.
Returns: The resulting vector after multiplication.
Vec3.cross(obj1, obj2, result)
Description: Computes the cross product of two vectors, returning a vector perpendicular to both.
Parameters:
obj1(Vec3): The first vector.obj2(Vec3): The second vector.result(Vec3, optional): Optional vector to store the result.
Returns: The cross product vector.
Vec3.cross2(obj1, obj2, fallback)
Description: Computes a normalized cross product, using a fallback if vectors are nearly parallel.
Parameters:
obj1(Vec3): The first vector.obj2(Vec3): The second vector.fallback(Vec3, optional): Vector used when inputs are nearly parallel.
Returns: A perpendicular vector or fallback if needed.
Vec3.scale(obj, scalar, result)
Description: Scales a vector by a scalar value.
Parameters:
obj(Vec3): The vector object.scalar(number): The scaling factor.result(Vec3, optional): Optional vector to store the result.
Returns: The scaled vector.
Vec3.dot(obj1, obj2)
Description: Computes the dot product of two vectors.
Parameters:
obj1(Vec3): The first vector.obj2(Vec3): The second vector.
Returns: The dot product of the two vectors.
Vec3.angle(obj1, obj2, upVector)
Description: Finds the angle (radians) between two vectors. Returns a signed angle if 'upVector' is given.
Parameters:
obj1(Vec3): The first vector.obj2(Vec3): The second vector.upVector(Vec3, optional): Defines orientation for signed angles.
Returns: The angle in radians.
Vec3.div(obj1, obj2, result)
Description: Divides one vector by another.
Parameters:
obj1(Vec3): The numerator vector.obj2(Vec3): The denominator vector.result(Vec3, optional): Optional vector to store the result.
Returns: Vector after division.
Vec3.swizzle(obj, index1, index2, index3, result)
Description: Retrieves selected components of a vector in a different order.
Parameters:
obj(Vec3): The source vector.index1(number): Index of the first component.index2(number): Index of the second component.index3(number): Index of the third component.result(Vec3, optional): Optional vector to store the result.
Returns: Selected components of a vector in a different order.
Vec3.clamp(obj, lowerLimit, upperLimit, result)
Description: Clamps a vector's components within a given range.
Parameters:
obj(Vec3): The vector to clamp.lowerLimit(Vec3): The lower limit vector.upperLimit(Vec3): The upper limit vector.result(Vec3, optional): Optional vector to store the result.
Returns: Clamped vector.
Vec3.lerp(fromObj, toObj, t, result)
Description: Performs linear interpolation (LERP) between two vectors based on 't'.
Parameters:
fromObj(Vec3): Start vector.toObj(Vec3): End vector.t(number): Interpolation factor (0 to 1).result(Vec3, optional): Optional vector to store the result.
Returns: An interpolated vector.
Vec3.applyQuaternion(obj, q, result)
Description: Rotates a vector using a quaternion.
Parameters:
obj(Vec3): Vector to rotate.q(Quaternion): Rotation quaternion.result(Vec3, optional): Optional vector to store the result.
Returns: The rotated vector.
Vec3.min(vectors)
Description: Finds the smallest vector based on length.
Parameters:
vectors(Vec3[]): List of vectors.
Returns: The shortest vector.
Vec3.max(vectors)
Description: Finds the largest vector based on length.
Parameters:
obj(vectors[]): List of vectors.
Returns: The longest vector.
Vec3.getLength(obj)
Description: Computes the magnitude (length) of a vector.
Parameters:
obj(Vec3): The vector.
Returns: The length of the vector.
Vec3.sign(obj, result)
Description: Returns the sign of each component of a vector.
Parameters:
obj(Vec3): The input vector.result(Vec3, optional): Optional vector to store the result.
Returns: Sign of each component of a vector.
Vec3.abs(obj, result)
Description: Returns the absolute values of a vector's components.
Parameters:
obj(Vec3): The input vector.result(Vec3, optional): Optional vector to store the result.
Returns: Absolute vector.
Vec3.normalize(obj, result)
Description: Returns the normalized (unit-length) version of a vector.
Parameters:
obj(Vec3): The vector to normalize.result(Vec3, optional): Optional vector to store the result.
Returns: Normalized vector.
Vec3.distance(obj1, obj2)
Description: Computes the Euclidean distance between two vectors.
Parameters:
obj1(Vec3): The first vector.obj2(Vec3): The second vector.
Returns: The distance between the two vectors.
Vec3.equals(obj1, obj2, eps)
Description: Checks if two vectors are approximately equal within a small tolerance.
Parameters:
obj1(Vec3): The first vector.obj2(Vec3): The second vector.eps(number, optional): The tolerance value. Defaults to 0.000001.
Returns: true if the vectors are equal within the tolerance, otherwise false.
Vec3.copy(obj, result)
Description: Copies a vector.
Parameters:
obj(Vec3): The vector to copy.result(Vec3, optional): Optional vector to store the result.
Returns: Copied vector.
Vec4 functions
Vec4.get(obj, index)
Description: Retrieves the x, y, z or w component of a vector based on the index.
Parameters:
obj(Vec4): The vector object.index(Number): The index (0 = x, 1 = y, 2 = z, 3 = w).
Returns: The corresponding component value or NaN if the index is invalid.
Vec4.set(obj, index, val)
Description: Sets the x, y, z or w component of a vector.
Parameters:
obj(Vec4): The vector object.index(Number): The index (0 = x, 1 = y, 2 = z, 3 = w).val(Number): The new value.
Returns: The modified vector.
Vec4.setAll(obj, x, y, z, w)
Description: Sets all four components of the vector.
Parameters:
obj(Vec4): The vector to modify.index(Number): The index (0 = x, 1 = y, 2 = z, 3 = w).val(Number): The new value.
Returns: The modified vector.
Vec4.neg(obj, result)
Description: Negates the components of a vector.
Parameters:
obj(Vec4): The input vector.result(Vec4, optional): Optional vector to store the result.
Returns: The negated vector.
Vec4.add(obj1, obj2, result)
Description: Adds two vectors.
Parameters:
obj1(Vec4): The first vector.obj2(Vec4): The second vector.result(Vec4, optional): Optional vector to store the result.
Returns: The resulting vector after addition.
Vec4.sub(obj1, obj2, result)
Description: Subtracts one vector from another.
Parameters:
obj1(Vec4): The first vector.obj2(Vec4): The second vector.result(Vec4, optional): Optional vector to store the result.
Returns: The resulting vector after subtraction.
Vec4.mul(obj1, obj2, result)
Description: Multiplies two vectors.
Parameters:
obj1(Vec4): The first vector.obj2(Vec4): The second vector.result(Vec4, optional): Optional vector to store the result.
Returns: The resulting vector after multiplication.
Vec4.scale(obj, scalar, result)
Description: Scales a vector by a scalar value.
Parameters:
obj(Vec4): The vector object.scalar(number): The scaling factor.result(Vec4, optional): Optional vector to store the result.
Returns: The scaled vector.
Vec4.dot(obj1, obj2)
Description: Computes the dot product of two vectors.
Parameters:
obj1(Vec4): The first vector.obj2(Vec4): The second vector.
Returns: The dot product of the two vectors.
Vec4.div(obj1, obj2, result)
Description: Divides one vector by another.
Parameters:
obj1(Vec4): The numerator vector.obj2(Vec4): The denominator vector.result(Vec4, optional): Optional vector to store the result.
Returns: Vector after division.
Vec4.swizzle(obj, index1, index2, index3, index4, result)
Description: Retrieves selected components of a vector in a different order.
Parameters:
obj(Vec4): The source vector.index1(number): Index of the first component.index2(number): Index of the second component.index3(number): Index of the third component.index4(number): Index of the fourth component.result(Vec4, optional): Optional vector to store the result.
Returns: Selected components of a vector in a different order.
Vec4.clamp(obj, lowerLimit, upperLimit, result)
Description: Clamps a vector's components within a given range.
Parameters:
obj(Vec4): The vector to clamp.lowerLimit(Vec4): The lower limit vector.upperLimit(Vec4): The upper limit vector.result(Vec4, optional): Optional vector to store the result.
Returns: Clamped vector.
Vec4.getLength(obj)
Description: Computes the magnitude (length) of a vector.
Parameters:
obj(Vec4): The vector.
Returns: The length of the vector.
Vec4.abs(obj, result)
Description: Returns the absolute values of a vector's components.
Parameters:
obj(Vec4): The input vector.result(Vec4, optional): Optional vector to store the result.
Returns: Absolute vector.
Vec4.normalize(obj, result)
Description: Returns the normalized (unit-length) version of a vector.
Parameters:
obj(Vec4): The vector to normalize.result(Vec4, optional): Optional vector to store the result.
Returns: Normalized vector.
Vec4.distance(obj1, obj2)
Description: Computes the Euclidean distance between two vectors.
Parameters:
obj1(Vec4): The first vector.obj2(Vec4): The second vector.
Returns: The distance between the two vectors.
Vec4.equals(obj1, obj2, eps)
Description: Checks if two vectors are approximately equal within a small tolerance.
Parameters:
obj1(Vec4): The first vector.obj2(Vec4): The second vector.eps(number, optional): The tolerance value. Defaults to 0.000001.
Returns: true if the vectors are equal within the tolerance, otherwise false.
Vec4.copy(obj, result)
Description: Copies a vector.
Parameters:
obj(Vec4): The vector to copy.result(Vec4, optional): Optional vector to store the result.
Returns: Copied vector.
Quaternion functions
Quaternion.get(obj, index)
Description: Retrieves a specific component of a quaternion based on an index.
Parameters:
obj(Quaternion): The quaternion object.index(number): The index (0 = x, 1 = y, 2 = z, 3 = w).
Returns: The corresponding component value or NaN if the index is out of range.
Quaternion.set(obj, index, val)
Description: Sets a specific component of a quaternion based on an index.
Parameters:
obj(Quaternion): The quaternion object.index(number): The index (0 = x, 1 = y, 2 = z, 3 = w).val(number): The value to assign.
Returns: The modified quaternion object.
Quaternion.setAll(obj, x, y, z, w)
Description: Sets all four components of a quaternion at once.
Parameters:
obj(Quaternion): The quaternion object.x, y, z, w(numbers): The new values for each component.
Returns: The modified quaternion object.
Quaternion.setFromAxisAngle(axis, angle, result)
Description: Creates a quaternion from an axis-angle rotation.
Parameters:
obj(Vec3): A normalized vector representing the rotation axis.angle(number): The rotation angle in radians.result(Quaternion, optional): Optional quaternion to store the result.
Returns: A new quaternion or the modified result quaternion.
Quaternion.setFromAxisCos(axis, cosAngle, ccw, result)
Description: Creates a quaternion from a given axis and cosine of the angle.
Parameters:
axis(Vec3): A normalized rotation axis.cosAngle(number): Cosine of the rotation angle.ccw(boolean, optional): If true, applies a counterclockwise rotation.result(Quaternion, optional): Optional quaternion to store the result.
Returns: A new quaternion or the modified result.
Quaternion.setFromAxisCosSin(axis, cosAngle, sinAngle, result)
Description: Constructs a quaternion from an axis of rotation and the cosine and sine of an angle.
Parameters:
axis(Vec3): The axis around which the rotation happens.cosAngle(number): Cosine of the rotation angle.sinAngle(number): Sine of the rotation angle.result(Quaternion, optional): Optional quaternion to store the result.
Returns: A new quaternion or the modified result.
Quaternion.setFromTwoVectors(u, v, result)
Description: Computes a quaternion that rotates vector u to align with vector v.
Parameters:
u(Vec3): The initial normalized vector.v(Vec3): The target normalized vector.result(Quaternion, optional): Optional quaternion to store the result.
Returns: A quaternion representing the rotation from u to v.
Quaternion.setFromTwoVectors2(u, v, plane, result)
Description: Computes a quaternion that rotates vector u to align with vector v. Handles edge cases where u and v are opposite directions.
Parameters:
u(Vec3): The initial vector.v(Vec3): The target vector.plane(Vec3, optional): A reference plane to handle 180-degree flips. it's used to compute a perpendicular vector.result(Quaternion, optional): Optional quaternion to store the result.
Returns: A quaternion representing the rotation from u to v.
Quaternion.setFromEuler(euler, order, result)
Description: Creates a quaternion from Euler angles.
Parameters:
euler(Vec3): The Euler angles in radians (x = pitch, y = yaw, z = roll).order(string, optional): Rotation order (e.g., 'XYZ').result(Quaternion, optional): Optional quaternion to store the result.
Returns: A new quaternion or the modified result.
Quaternion.convertToEuler(q, order, result)
Description: Converts a quaternion to Euler angles.
Parameters:
q(Quaternion): The quaternion to convert.order(string, optional): Rotation order ('XYZ' default).result(Quaternion, optional): Optional quaternion to store the result.
Returns: Euler angles as a Vec3.
Quaternion.setFromFwdAndUpVector(fwd, up, camera, result)
Description: Creates a quaternion that aligns a forward vector and an up vector.
Parameters:
fwd(Vec3): The forward vector.up(Vec3): The up vector.camera(boolean, optional): If true, adjusts for camera orientation.result(Quaternion, optional): Optional quaternion to store the result.
Returns: A quaternion that aligns fwd and up.
Quaternion.setFromHpr(wpos, h, p, r, camera, result)
Description: Creates a quaternion from heading, pitch, and roll (HPR).
Parameters:
wpos(Vec3): The world position.h(number): Heading (yaw) in radians.p(number): Pitch in radians.r(number): Roll in radians.camera(boolean, optional): If true, applies camera adjustments.result(Quaternion, optional): Optional quaternion to store the result.
Returns: Quaternion representing the HPR rotation.
Quaternion.convertToHpr(wpos, quat, camera, result)
Description: Converts a quaternion into heading, pitch, and roll.
Parameters:
wpos(Vec3): The world position.quat(Quaternion): The quaternion to convert.camera(boolean, optional): If true, adjusts for camera orientation.result(Quaternion, optional):Optional quaternion to store the result.
Returns: A Vec3 containing heading, pitch, and roll.
Quaternion.conjugate(obj, result)
Description: Computes the conjugate of a quaternion (negates x, y, z).
Parameters:
obj(Quaternion): The quaternion to conjugate.result(Quaternion, optional): Optional quaternion to store the result.
Returns: New quaternion or the modified result.
Quaternion.normalize(obj, result)
Description: Normalizes a quaternion to unit length.
Parameters:
obj(Quaternion): The quaternion to normalize.result(Quaternion, optional): Optional quaternion to store the result.
Returns: New quaternion or the modified result.
Quaternion.inverse(obj, result)
Description: Computes the inverse of a quaternion by conjugating it and then normalizing the result.
Parameters:
obj(Quaternion): The quaternion to invert.result(Quaternion, optional): Optional quaternion to store the result.
Returns: New quaternion or the modified result.
Quaternion.mul(obj1, obj2, result)
Description: Performs quaternion multiplication, combining two rotations.
Parameters:
obj1(Quaternion): The first quaternion.obj2(Quaternion): The second quaternion.result(Quaternion, optional): Optional quaternion to store the result.
Returns: New quaternion or the modified result.
Quaternion.dot(obj1, obj2)
Description: Computes the dot product between two quaternions, measuring similarity.
Parameters:
obj1(Quaternion): The first quaternion.obj2(Quaternion): The second quaternion.
Returns: A number representing the dot product of obj1 and obj2.
Quaternion.slerp(qa, qb, t, result)
Description: Performs spherical linear interpolation (SLERP) between two quaternions for smooth rotation transitions.
Parameters:
qa(Quaternion): The starting quaternion.qb(Quaternion): The target quaternion.t(number): A value between 0 and 1 representing the interpolation amount.result(Quaternion, optional): Optional quaternion to store the result.
Returns: New quaternion or the modified result.
Quaternion.angle(obj1, obj2)
Description: Computes the angle between two quaternions.
Parameters:
obj1(Quaternion): The first quaternion.obj2(Quaternion): The second quaternion.
Returns: The angle (in radians) between obj1 and obj2.
Quaternion.distance(obj1, obj2)
Description: Computes the distance between two quaternions based on their dot product.
Parameters:
obj1(Quaternion): The first quaternion.obj2(Quaternion): The second quaternion.
Returns: A value representing the distance between obj1 and obj2.
Quaternion.getLength(obj)
Description: Computes the magnitude (length) of a quaternion.
Parameters:
obj(Quaternion): The quaternion whose length is to be computed.
Returns: The magnitude of obj.
Quaternion.copy(obj, result)
Description: Copies a quaternion into another quaternion or creates a new one with the same values.
Parameters:
obj(Quaternion): The quaternion to copy.result(Quaternion, optional): Optional quaternion to store the result.
Returns: Quaternion - copy of obj.