kooparse / zalgebra

Linear algebra library for games and real-time graphics.

zalgebra

Linear algebra library for games and computer graphics.

The goal is to become as complete and useful as the Unity one. I'm currently using it for my projects and will continue to update it as new needs are coming.

If you would like to contribute, don't hesitate! :)

Note: Zig 0.11.x is required.

Examples

Example of usage is located at example/.

const za = @import("zalgebra");
const Vec3 = za.Vec3;
const Mat4 = za.Mat4;

pub fn main () void {
  const projection = za.perspective(45.0, 800.0 / 600.0, 0.1, 100.0);
  const view = za.lookAt(Vec3.new(0.0, 0.0, -3.), Vec3.zero(), Vec3.up());
  const model = Mat4.fromTranslate(Vec3.new(0.2, 0.5, 0.0));

  const mvp = Mat4.mul(projection, view.mul(model));
  mvp.debugPrint();
}

Quick reference

Aliases

Type	Description
Vec2	Two dimensional vector for f32
Vec2_f64	Two dimensional vector for f64
Vec2_i32	Two dimensional vector for i32
Vec2_usize	Two dimensional vector for usize
Vec3	Three dimensional vector for f32
Vec3_f64	Three dimensional vector for f64
Vec3_i32	Three dimensional vector for i32
Vec3_usize	Three dimensional vector for usize
Vec4	Four dimensional vector for f32
Vec4_f64	Four dimensional vector for f64
Vec4_i32	Four dimensional vector for i32
Vec4_usize	Four dimensional vector for usize
Mat3	3x3 matrix for f32
Mat3_f64	3x3 matrix for f64
Mat4	4x4 matrix for f32
Mat4_f64	4x4 matrix for f64
Quat	Quaternion for f32
Quat_f64	Quaternion for f64
perspective	Perspective function for f32 4x4 mat4
orthographic	Orthographic function for f32 4x4 mat4
lookAt	LookAt function for f32 4x4 mat4

Vectors

Methods	Description
new	Construct a vector from 2 to 4 components
x	Return first component
y	Return second component
z	Return third component (only for vec3, vec4)
w	Return fourth component (only for vec4)
at	Return component from given index
set	Set all components to the same given value
negate	Scale all components by -1
cast	Cast a type to another type
fromSlice	Construct new vectors from slice
zero	Shorthand for (0, 0, 0)
one	Shorthand for (1, 1, 1)
up	Shorthand for (0, 1, 0)
down	Shorthand for (0, -1, 0)
right	Shorthand for (1, 0, 0)
left	Shorthand for (-1, 0, 0)
forward	Shorthand for (0, 0, 1) (only for vec3 and vec4)
back	Shorthand for (0, 0, -1) (only for vec3 and vec4)
toArray	Return an array of same size.
getAngle	Return angle in degrees between two vectors (only for vec2 and vec3)
rotate	Rotate vector by angle (in degrees)
length	Return the magnitude of the current vector
distance	Return the distance between two points
norm	Construct a new normalized vector based on the given one
eql	Return true if two vectors are equals
sub	Construct new vector resulting from the substraction between two vectors
add	Construct new vector resulting from the addition between two vectors
mul	Construct new vector resulting from the multiplication between two vectors
scale	Construct new vector after multiplying each components by a given scalar
cross	Construct the cross product (as vector) from two vectors (only for vec3)
dot	Return the dot product between two vectors
lerp	Linear interpolation between two vectors
min	Construct vector from the min components between two vectors
max	Construct vector from the max components between two vectors

Matrices

Note: All matrices are column-major.

Methods	Description
identity	Construct an identity matrix
set	Set all matrix values to given value
fromSlice	Construct new matrix from given slice of data
getData	Return a pointer to the inner data
transpose	Return the transpose matrix
negate	Scale all components by -1
cast	Cast a type to another type
eql	Return true if two matrices are equals
mulByVec4	Multiply a given vec4 by matrix (only for mat4)
fromTranslate	Construct a translation matrix
translate	Construct a translation from the given matrix according to given axis (vec3)
fromRotation	Construct a rotation matrix
fromEulerAngles	Construct a rotation matrix from pitch/yaw/roll in degrees (X _ Y _ Z)
rotate	Construct a rotation from the given matrix according to given axis (vec3)
fromScale	Construct a scale matrix
scale	Construct a scale from the given matrix according to given axis (vec3)
extractTranslation	Return a vector with proper translation
orthoNormalize	Ortho normalize the given matrix.
extractEulerAngles	Return a vector with Euler angles in degrees (pitch/yaw/roll)
extractScale	Return a vector with proper scale
perspective	Construct a perspective matrix from given fovy, aspect ratio, near/far inputs
perspectiveReversedZ	Construct a perspective matrix with reverse Z and infinite far plane.
orthographic	Construct an orthographic matrix from given left, right, bottom, top, near/far inputs
lookAt	Construct a right-handed lookAt matrix from given position (eye) and target
mul	Multiply two matrices
inv	Inverse the given matrix
recompose	Return mat4 matrix from given translation, rotation and scale components
decompose	Return components translation, rotation and scale from given 4x4 matrix.
debugPrint	Print the matrix data for debug purpose

Quaternions

Methods	Description
new	Construct new quat from given floats
identity	Construct quat as (1, 0, 0, 0)
set	Set all components to the same given value
cast	Cast a type to another type
fromSlice	Construct new quaternion from slice
fromVec3	Construct quaternion from vec3
eql	Return true if two quaternions are equal
norm	Normalize given quaternion
length	Return the magniture of the given quaternion
inv	Construct inverse quaternion
sub	Construct quaternion resulting from the subtraction of two given ones
add	Construct quaternion resulting from the addition of two given ones
mul	Construct quaternion resulting from the multiplication of two given ones
scale	Construct new quaternion resulting from the multiplication of all components by a given scalar
dot	Return the dot product between two quaternions
toMat4	Convert given quat to rotation 4x4 matrix
fromEulerAngles	Construct quaternion from Euler angles
fromAxis	Construct quat from angle around specified axis
extractAxisAngles	Get the rotation angle and axis for a given quaternion
extractRotation	Get euler angles from given quaternion
rotateVec	Rotate given vector

Utilities

Methods	Description
toRadians	Convert degrees to radians
toDegrees	Convert radians to degrees
lerp	Linear interpolation between two floats

Contributing to the project

Don’t be shy about shooting any questions you may have. If you are a beginner/junior, don’t hesitate, I will always encourage you. It’s a safe place here. Also, I would be very happy to receive any kind of pull requests, you will have (at least) some feedback/guidance rapidly.

Behind screens, there are human beings, living any sort of story. So be always kind and respectful, because we all sheer to learn new things.

Thanks

This project is inspired by Handmade Math, nalgebra and Unity.

zalgebra's Issues

std.meta.Vector is deprecated, use @Vector

ziglang/zig@d42d31f

make Vec2/Vec3/Vec4/Mat4 more friendly to OpenGL

With extern, the struct 's layout is pedictable, which is demanded by C library.
For instance, take a look at a typical Vertex definition:

pub const Vertex = struct { 
    position: Vec3, 
    normal: Vec3, 
    tex: Vec3,
}; 
pub const vertices =  std.ArrayList(Vertex).init(allocator);

Without using extern, it's impossible to use vertices to initialize opengl's buffer object.

transpose operation support

Needed when calculating matrix for rotation/scale of vertex's normal attribute.

Interest in mat3?

I love that your vector implementation is generic, but I also understand why your 4x4 matrix implementation isn't. Lots of math.

I have a growing need for 3x3 matrix operations. Occasionally even things like multiplying 1x3 and 3x1 matrices into scalars. Making the current matrix implementation generic would be a lot of work and added complexity, but making a separate mat3 would be highly redundant.

Before I dig too far into either option, I wanted to see if you had an existing plan or preference here.

Speed up `Mat4.recompose`

This showed up while profiling my game. I have a bunch animated models where I need to convert translation, rotation, and scale components into a skinning matrix.

The current implementation first normalizes the rotation quaternion. For my purposes I can skip this step because rotation quaternions are usually already normalized.
Then 3 mat4 matrices are generated and multiplied.

I swapped out Mat4.recompose with my own implementation: fabioarnold/3d-game@396eb85
I added a function to convert a Quat into a Mat3. This could be useful on its own. Then I set the components of the result matrix directly. This of course saves the matrix multiplications. You could also go a step further and combine this with the quat to mat3 conversion function.

Is this worthy of a contribution to this project or do you prefer more understandable and correct (normalize rotation first) code? Please let me know and I could create a PR. :)

negate operation

Hi @kooparse, I'm trying to integrate zalgebra into my framework, and just found
there's no negate functions/methods in Vector/Matrix, is this by design or I'm missing workaround?

BTW, nice work on zalgebra!

Naming

Hello!

Just wanted to let you know that usually function names are camelCase and types are PascalCase.
For example, const quat_f32 = Quaternion(f32); would be const QuatF32 = Quaternion(f32);

Source: https://ziglang.org/documentation/master/#Names

Continue your great work! ♥️

Add scalar add, sub