README.md

GoVec

A library providing vector operations for Go. It focuses on performance so that it can be used in games and other demanding applications.

Installation

go get github.com/xkonti/govec

Usage

Vector types

The library provides the following vector types:

• V2F[T] - 2D floating point vector, where T is the type of the vector components (float32 or float64)
• V2I[T] - 2D integer vector, where T is the type of the vector components (int, int8, int16, int32 or int64)
• V3F[T] - 3D floating point vector, where T is the type of the vector components (float32 or float64)
• V3I[T] - 3D integer vector, where T is the type of the vector components (int, int8, int16, int32 or int64)

Creating new vectors

Vectors can be created in various ways:

• Constructing vectors manually:

  vector1 := govec.V2F{1.0, 2.0};
  vector2 := govec.V3F{1.0, 2.0, 3.0};
  vector3 := govec.V2I{1, 2};
  vector4 := govec.V3I{1, 2, 3};

• Using the New function, which takes the vector components as arguments:

  vector1 := govec.NewV2F(1.0, 2.0);
  vector2 := govec.NewV3F(1.0, 2.0, 3.0);
  vector3 := govec.NewV2I(1, 2);
  vector4 := govec.NewV3I(1, 2, 3);

• Using the Fill function, which assigns the same value to all components of a vector:

  vector1 := govec.FillV2F(1.0);
  vector2 := govec.FillV3F(1.0);
  vector3 := govec.FillV2I(1);
  vector4 := govec.FillV3I(1);

• Using the Zero function, which creates a vector with all components set to 0:

  vector1 := govec.ZeroV2F();
  vector2 := govec.ZeroV3F();
  vector3 := govec.ZeroV2I();
  vector4 := govec.ZeroV3I();

• Using the One function, which creates a vector with all components set to 1:

  vector1 := govec.OneV2F();
  vector2 := govec.OneV3F();
  vector3 := govec.OneV2I();
  vector4 := govec.OneV3I();

• Using ...FromArray
• Using ...FromSlice

Conversions

Vectors can be converted to other types using the To... functions:

vector1 := govec.V3F{1.0, 2.0, 3.0}; // Creates a 3D floating point vector (float64)
vector2 := vector1.ToV3I16(); // converts to 3D vector with int16 components

2D vectors have the following conversion functions:

• ToV2F64, ToV2F32, ToV2I64, ToV2I32, ToV2I16, ToV2I8, ToV2I

3D vectors have the following conversion functions:

• ToV3F64, ToV3F32, ToV3I64, ToV3I32, ToV3I16, ToV3I8, ToV3I

You can remove a component from a vector using the Discard function:

v1 := govec.V3F{1.0, 2.0, 3.0}; // Creates a 3D floating point vector (float64)
v2 := vector1.DiscardY(); // Returns a 2D vector with the Y component removed (v1.X -> v2.X, v1.Z -> v2.Y)

You can add a component to a vector using the Extend function:

v1 := govec.V2F{1.0, 2.0}; // Creates a 2D floating point vector (float64)
v2 := v1.Extend(3.0); // Returns a 3D vector with the Z component added.

You can insert a component to a vector using the Insert function:

v1 := govec.V2F{1.0, 2.0}; // Creates a 2D floating point vector (float64)
v2 := v1.InsertY(3.0); // Returns a 3D vector with the new component: newY -> Y, oldY -> Z.

You can swap components in a vector using the Swizzle function:

v1 := govec.V3F{1.0, 2.0, 3.0}; // Creates a 3D floating point vector (float64)
v2 := v1.SwizzleZYX(); // Returns a 3D vector with the components swapped (v1.Z -> v2.X, v1.Y -> v2.Y, v1.X -> v2.Z)
v3 := v1.SwizzleYZX(); // Returns a 3D vector with the components swapped (v1.Y -> v2.X, v1.Z -> v2.Y, v1.X -> v2.Z)

Common variants

Most vector operations are available in various forms:

• Default form - returns a new vector, usually takes other vector as an argument
• InPlace form - modifies the original vector, usually takes other vector as an argument
• Comp form - returns a new vector, usually takes raw vector components as arguments instead of another vector
• CompInPlace form - modifies the original vector, usually takes raw vector components as arguments instead of another vector
• Scalar form - returns a new vector, takes a scalar value as an argument
• ScalarInPlace form - modifies the original vector, takes a scalar value as an argument

For example, the Add operation is available as:

• Add - takes another vector as an argument and returns a new vector
• AddInPlace - takes another vector as an argument and modifies the original vector
• AddComp - takes raw vector components (x, y, z) as arguments and returns a new vector
• AddCompInPlace - takes raw vector components (x, y, z) as arguments and modifies the original vector
• AddScalar - takes a scalar value as an argument and returns a new vector
• AddScalarInPlace - takes a scalar value as an argument and modifies the original vector

For some operations, the Comp, InPlace or Scalar variants are not available as it doesn't make sense to use them.

Return type exceptions

Usually the return type of the operation is the same as the type of the vector on which the operation is performed. However, in some cases the return type is different. Examples:

• Len operation always returns float64 even if the vector is an integer vector. This is the only way to return an accurate length of the vector.
• Norm operations always returns a float64 vectors even if the original vector is an integer vector. Normalization returns values between 0 and 1, which is not possible to represent in an integer vector.

Available Operations

Operation	Description
Creation
...FromArray	Initializes a vector from an array of components.
...FromSlice	Initializes a vector from a slice of components.
Fill	Creates a vector where all components are set to a specified value.
New	Creates a new vector using the provided components.
One	Generates a vector with all components set to 1.
Zero	Generates a vector with all components set to 0.
Conversions
Apply	Applies a given function to each component in the vector.
ApplyToArray	Modifies an array by assigning values from the vector's corresponding components.
ApplyToSlice	Modifies a slice by assigning values from the vector's corresponding components.
Discard	Removes a component from the vector at a specified index.
Extend	Extends the dimensionality of a vector by adding additional components.
Insert	Inserts a value into the vector at a specified index.
Split	Splits a vector into its individual components.
Swizzle...	Swaps components of a vector using a selected pattern.
ToArray	Converts the vector to a new array.
ToSlice	Converts the vector to a new slice.
To...	Transforms the vector into another type. V2F, V3F, V2I, V3I
Mathematics
Abs	Computes the absolute value of each component in the vector.
Add	Performs vector addition.
AddScalar	Adds a scalar value to each component of the vector.
AngleBetweenDeg	Calculates the angle between two vectors in degrees.
AngleBetweenRad	Calculates the angle between two vectors in radians.
AngleDeg	Creates a normalized vector from an angle in degrees.
AngleRad	Creates a normalized vector from an angle in radians.
Average	Calculates the average of the vector's components.
Ceil	Rounds each component of the vector up to the nearest integer.
ClampComp	Clamps the components of this vector to the given range.
ClampLen	Scales the length of the vector so that it fits within provided range.
Cos	Applies the cosine function to all components.
Cross	Computes the cross product of two vectors. (Not applicable for 2D vectors.)
Distance	Calculates the distance between two vectors.
Div	Performs vector division.
DivScalar	Divides each component of the vector by a scalar.
Dot	Computes the dot product of two vectors.
Floor	Rounds each component of the vector down to the nearest integer.
Inv	Computes the multiplicative inverse of each component in the vector.
IsZero	Checks if the vector is a zero vector.
Len	Calculates the length of the vector. Returns float64 for integer vectors.
LenSqrt	Calculates the squared length of the vector. Returns float64 for integer vectors.
Max	Returns the maximum component values from two vectors.
Min	Returns the minimum component values from two vectors.
Mod	Computes the modulus of each component in the vector against another vector components.
ModScalar	Computes the modulus of each component in the vector against a single scalar.
Mul	Performs vector multiplication.
MulScalar	Multiplies each component of the vector by a scalar.
Neg	Negates each component of the vector.
Norm	Normalizes the vector. Returns a float64 vector for integer vectors.
Pow	Raises each component of the vector to the power of the corresponding component in another vector.
Pow2	Squares each component of the vector.
Pow3	Cubes each component of the vector.
PowN	Raises each component of the vector to a specified integer power.
PowNFloat	Raises each component of the vector to a specified floating-point power.
Round	Rounds each component of the vector to the nearest integer.
Sin	Applies the sine function to all components.
Sqrt	Computes the square root of each component in the vector.
Sub	Performs vector subtraction.
SubScalar	Subtracts a scalar from each component of the vector.
Tan	Applies the tangent function to all components.

Not implemented yet

The following list of operations are not implemented yet. Feel free to open an issue if you would like to see any of these implemented or if you'd like to propose a different operation.

Operation	Planned	Description
FromQuaternion		Initializes the vector from a quaternion.
Hash		Produces a hash code for the vector for use in data structures.
IsOrthogonalTo		Checks if the vector is orthogonal to another vector.
IsUnit		Checks if the vector is a unit vector.
Lerp	Yes (v1.0)	Linearly interpolates between two vectors.
Orthogonalize		Generates an orthogonal (or orthonormal) vector set.
Project		Projects a 3D vector onto a plane.
Rand	Yes (v1.0)	Generates a normal vector with random components.
RandIn	Yes (v1.0)	Generates a vector with random components within a zero and the specified vector.
RandBetween	Yes (v1.0)	Generates a vector with random components between two specified vectors.
Reflect		Reflects a vector off the plane defined by a normal.
RotateDeg	Yes (v1.0)	Rotates a vector by an angle in degrees.
RotateRad	Yes (v1.0)	Rotates a vector by an angle in radians.
Slerp		Spherically interpolates between two vectors.
ToQuaternion		Converts the vector to a quaternion.