Math Module

GX includes a built-in math module for scalar, vector, and matrix operations. It wraps C’s math.h functions via extern fn and provides pure GX helpers built on GX’s native vec2/vec3/vec4/mat4 types.

Usage

Import everything at once:

import math           // imports scalar, vec, and mat

Or import individual sub-modules:

import math.scalar    // trig, sqrt, clamp, lerp, etc.
import math.vec       // vector length, normalize, distance, etc.
import math.mat       // mat4 perspective, look_at, multiply, etc.

Build with -I modules so the compiler finds the modules/math/gx/ directory:

gx myapp.gx -I modules -o myapp.exe

Scalar Functions (math.scalar)

C math.h Externs

These are direct bindings to C’s single-precision math functions — no wrapper overhead:

Constants

GX has no const globals yet, so constants are zero-argument functions:

var pi:f32 = PI();          // 3.14159265
var tau:f32 = TAU();        // 6.28318530
var eps:f32 = EPSILON();    // 0.00001

Helpers

Example

import math.scalar

fn main() {
    var angle:f32 = radians(45.0);
    var s:f32 = sinf(angle);
    var c:f32 = cosf(angle);
    print("sin(45) = {s}, cos(45) = {c}\n");

    var t:f32 = smoothstep(0.0, 1.0, 0.3);
    print("smoothstep = {t}\n");
}

Vector Functions (math.vec)

Operates on GX’s built-in vec2, vec3, and vec4 types. Functions are suffixed with the vector size: _v2, _v3, _v4.

The built-in dot() and cross() functions are also available (defined in the GX runtime):

var d:f32 = dot(a, b);      // vec3 dot product
var c:vec3 = cross(a, b);   // vec3 cross product

Example

import math.vec

fn main() {
    var a:vec3;
    a.x = 3.0; a.y = 0.0; a.z = 4.0;

    var len:f32 = length_v3(a);
    print("length = {len}\n");             // 5

    var n:vec3 = normalize_v3(a);
    print("normalized = {n}\n");           // vec3(0.6, 0, 0.8)

    var b:vec3;
    b.x = 1.0; b.y = 2.0; b.z = 3.0;
    var mid:vec3 = lerp_v3(a, b, 0.5);
    print("midpoint = {mid}\n");           // vec3(2, 1, 3.5)
}

Matrix Functions (math.mat)

All matrix operations use GX’s built-in mat4 type with column-major layout (col[4] of vec4), matching OpenGL conventions.

Matrix Construction

Projection & View

Multiplication

Note: The built-in mul() function is a non-functional stub that returns zero. Use mul_m4 and mul_m4v4 instead.

Column Access

Access individual columns of a matrix with .col[i]:

var m:mat4 = identity_mat4();
var first_col:vec4 = m.col[0];     // vec4(1, 0, 0, 0)
var tx:f32 = m.col[3].x;           // translation X component

Indexing returns the appropriate vector type: mat4[i] → vec4, mat3[i] → vec3, mat2[i] → vec2.

Example: 3D Camera Setup

import math.scalar
import math.mat

fn setup_camera:mat4(width: f32, height: f32) {
    var eye:vec3;
    eye.x = 0.0; eye.y = 2.0; eye.z = 5.0;

    var target:vec3;
    target.x = 0.0; target.y = 0.0; target.z = 0.0;

    var up:vec3;
    up.x = 0.0; up.y = 1.0; up.z = 0.0;

    var view:mat4 = look_at(eye, target, up);
    var proj:mat4 = perspective(radians(60.0), width / height, 0.1, 100.0);

    return mul_m4(proj, view);
}

Example: Model Transform

import math.scalar
import math.mat

fn model_matrix:mat4(x: f32, y: f32, z: f32, angle: f32) {
    var pos:vec3;
    pos.x = x; pos.y = y; pos.z = z;

    var axis:vec3;
    axis.x = 0.0; axis.y = 1.0; axis.z = 0.0;

    var t:mat4 = translation(pos);
    var r:mat4 = rotation(angle, axis);
    return mul_m4(t, r);
}

Module Layout

modules/
  math/
    gx/
      scalar.gx     C math.h externs + clamp/lerp/smoothstep/radians/degrees
      vec.gx        vec2/vec3/vec4: length, normalize, distance, lerp, reflect
      mat.gx        mat4: perspective, ortho, look_at, translate, rotate, scale, multiply

No C shim files are needed — math.h is a system header that links automatically. On Linux, add -lm to --ldflags. On Windows (MSVC/clang-cl), math is in the default C runtime.