Move util into root.zig, avoid circualar reference.

Author: hazeycode

README.md

@@ -1,4 +1,4 @@
-# [zmath](https://github.com/michal-z/zig-gamedev/zmath)
+# [zmath](https://github.com/zig-gamedev/zmath)
 
 SIMD math library for game developers
 

build.zig

@@ -26,7 +26,7 @@ pub fn build(b: *std.Build) void {
     const options_module = options_step.createModule();
 
     const zmath = b.addModule("root", .{
-        .root_source_file = b.path("src/main.zig"),
+        .root_source_file = b.path("src/root.zig"),
         .imports = &.{
             .{ .name = "zmath_options", .module = options_module },
         },
@@ -36,7 +36,7 @@ pub fn build(b: *std.Build) void {
 
     const tests = b.addTest(.{
         .name = "zmath-tests",
-        .root_source_file = b.path("src/main.zig"),
+        .root_source_file = b.path("src/root.zig"),
         .target = target,
         .optimize = options.optimize,
     });

src/main.zig renamed to src/root.zig

@@ -3,8 +3,6 @@
 // SIMD math library for game developers
 // https://github.com/michal-z/zig-gamedev/tree/main/libs/zmath
 //
-// See util.zig for additional functionality.
-//
 // Should work on all OSes supported by Zig. Works on x86_64 and ARM.
 // Provides ~140 optimized routines and ~70 extensive tests.
 // Can be used with any graphics API.
@@ -264,13 +262,6 @@
 //
 // ==============================================================================
 
-pub const util = @import("util.zig");
-
-// ensure transitive closure of test coverage
-comptime {
-    _ = util;
-}
-
 // Fundamental types
 pub const F32x4 = @Vector(4, f32);
 pub const F32x8 = @Vector(8, f32);
@@ -4539,6 +4530,147 @@ pub fn approxEqAbs(v0: anytype, v1: anytype, eps: f32) bool {
     return true;
 }
 
+/// ==============================================================================
+///
+/// Collection of useful functions building on top of, and extending, core zmath.
+/// https://github.com/michal-z/zig-gamedev/tree/main/libs/zmath
+///
+/// ------------------------------------------------------------------------------
+/// 1. Matrix functions
+/// ------------------------------------------------------------------------------
+///
+/// As an example, in a left handed Y-up system:
+///   getAxisX is equivalent to the right vector
+///   getAxisY is equivalent to the up vector
+///   getAxisZ is equivalent to the forward vector
+///
+/// getTranslationVec(m: Mat) Vec
+/// getAxisX(m: Mat) Vec
+/// getAxisY(m: Mat) Vec
+/// getAxisZ(m: Mat) Vec
+///
+/// ==============================================================================
+pub const util = struct {
+    pub fn getTranslationVec(m: Mat) Vec {
+        var _translation = m[3];
+        _translation[3] = 0;
+        return _translation;
+    }
+
+    pub fn set_TranslationVec(m: *Mat, _translation: Vec) void {
+        const w = m[3][3];
+        m[3] = _translation;
+        m[3][3] = w;
+    }
+
+    pub fn getScaleVec(m: Mat) Vec {
+        const scale_x = length3(f32x4(m[0][0], m[1][0], m[2][0], 0))[0];
+        const scale_y = length3(f32x4(m[0][1], m[1][1], m[2][1], 0))[0];
+        const scale_z = length3(f32x4(m[0][2], m[1][2], m[2][2], 0))[0];
+        return f32x4(scale_x, scale_y, scale_z, 0);
+    }
+
+    pub fn getRotationQuat(_m: Mat) Quat {
+        // Ortho normalize given matrix.
+        const c1 = normalize3(f32x4(_m[0][0], _m[1][0], _m[2][0], 0));
+        const c2 = normalize3(f32x4(_m[0][1], _m[1][1], _m[2][1], 0));
+        const c3 = normalize3(f32x4(_m[0][2], _m[1][2], _m[2][2], 0));
+        var m = _m;
+        m[0][0] = c1[0];
+        m[1][0] = c1[1];
+        m[2][0] = c1[2];
+        m[0][1] = c2[0];
+        m[1][1] = c2[1];
+        m[2][1] = c2[2];
+        m[0][2] = c3[0];
+        m[1][2] = c3[1];
+        m[2][2] = c3[2];
+
+        // Extract rotation
+        return quatFromMat(m);
+    }
+
+    pub fn getAxisX(m: Mat) Vec {
+        return normalize3(f32x4(m[0][0], m[0][1], m[0][2], 0.0));
+    }
+
+    pub fn getAxisY(m: Mat) Vec {
+        return normalize3(f32x4(m[1][0], m[1][1], m[1][2], 0.0));
+    }
+
+    pub fn getAxisZ(m: Mat) Vec {
+        return normalize3(f32x4(m[2][0], m[2][1], m[2][2], 0.0));
+    }
+
+    test "zmath.util.mat.translation" {
+        // zig fmt: off
+        const mat_data = [18]f32{
+            1.0,
+            2.0, 3.0, 4.0, 5.0,
+            6.0, 7.0, 8.0, 9.0,
+            10.0,11.0, 12.0,13.0,
+            14.0, 15.0, 16.0, 17.0,
+            18.0,
+        };
+        // zig fmt: on
+        const mat = loadMat(mat_data[1..]);
+        try expectVecApproxEqAbs(getTranslationVec(mat), f32x4(14.0, 15.0, 16.0, 0.0), 0.0001);
+    }
+
+    test "zmath.util.mat.scale" {
+        const mat = mul(scaling(3, 4, 5), translation(6, 7, 8));
+        const scale = getScaleVec(mat);
+        try expectVecApproxEqAbs(scale, f32x4(3.0, 4.0, 5.0, 0.0), 0.0001);
+    }
+
+    test "zmath.util.mat.rotation" {
+        const rotate_origin = matFromRollPitchYaw(0.1, 1.2, 2.3);
+        const mat = mul(mul(rotate_origin, scaling(3, 4, 5)), translation(6, 7, 8));
+        const rotate_get = getRotationQuat(mat);
+        const v0 = mul(f32x4s(1), rotate_origin);
+        const v1 = mul(f32x4s(1), quatToMat(rotate_get));
+        try expectVecApproxEqAbs(v0, v1, 0.0001);
+    }
+
+    test "zmath.util.mat.z_vec" {
+        const degToRad = std.math.degreesToRadians;
+        var z_vec = getAxisZ(identity());
+        try expectVecApproxEqAbs(z_vec, f32x4(0.0, 0.0, 1.0, 0), 0.0001);
+        const rot_yaw = rotationY(degToRad(90));
+        identity = mul(identity(), rot_yaw);
+        z_vec = getAxisZ(identity());
+        try expectVecApproxEqAbs(z_vec, f32x4(1.0, 0.0, 0.0, 0), 0.0001);
+    }
+
+    test "zmath.util.mat.y_vec" {
+        const degToRad = std.math.degreesToRadians;
+        var y_vec = getAxisY(identity());
+        try expectVecApproxEqAbs(y_vec, f32x4(0.0, 1.0, 0.0, 0), 0.01);
+        const rot_yaw = rotationY(degToRad(90));
+        identity = mul(identity(), rot_yaw);
+        y_vec = getAxisY(identity());
+        try expectVecApproxEqAbs(y_vec, f32x4(0.0, 1.0, 0.0, 0), 0.01);
+        const rot_pitch = rotationX(degToRad(90));
+        identity = mul(identity(), rot_pitch);
+        y_vec = getAxisY(identity());
+        try expectVecApproxEqAbs(y_vec, f32x4(0.0, 0.0, 1.0, 0), 0.01);
+    }
+
+    test "zmath.util.mat.right" {
+        const degToRad = std.math.degreesToRadians;
+        var right = getAxisX(identity());
+        try expectVecApproxEqAbs(right, f32x4(1.0, 0.0, 0.0, 0), 0.01);
+        const rot_yaw = rotationY(degToRad(90));
+        identity = mul(identity, rot_yaw);
+        right = getAxisX(identity());
+        try expectVecApproxEqAbs(right, f32x4(0.0, 0.0, -1.0, 0), 0.01);
+        const rot_pitch = rotationX(degToRad(90));
+        identity = mul(identity(), rot_pitch);
+        right = getAxisX(identity());
+        try expectVecApproxEqAbs(right, f32x4(0.0, 1.0, 0.0, 0), 0.01);
+    }
+}; // util
+
 // ------------------------------------------------------------------------------
 // This software is available under 2 licenses -- choose whichever you prefer.
 // ------------------------------------------------------------------------------