Home

Welcome to the Jamma Math Library wiki

Jamma is a modern, immutable-first Java math library for graphics, simulation, and game development. Designed as a ground-up replacement for JOML with Java records, Foreign Function & Memory API support, SIMD acceleration, and a vastly broader mathematical scope.

Modules

Module	Description
math-core	Main library. Zero dependencies. All production types: vectors, matrices, quaternions, dual numbers, geometry, intersection tests, scalar math, interpolation.
math-incubator	Experimental features requiring --add-modules jdk.incubator.vector --enable-preview. SIMD-accelerated vector ops, parallel batch processing, off-heap memory management.
lwjgl-jamma	LWJGL 3 interop. Zero-allocation put/get methods for FloatBuffer, DoubleBuffer, MemorySegment. MemoryStack-ready.

Quick start

Requirements

• Java 26+
• For incubator module: --add-modules jdk.incubator.vector --enable-preview

Dependency (JitPack)

repositories {
    maven { url 'https://jitpack.io' }
}
dependencies {
    implementation 'com.github.ExodusCoder9:Jamma:v1.0'
}
Build from source
./gradlew build
License
MIT License — see LICENSE. Copyright (c) 2026 ExodusCoder9

---

## Page: **Core Design Philosophy**

```markdown
# Core Design Philosophy

## Immutability by Default

Vectors, quaternions, dual numbers, axis-angle, planes, and spheres are **Java records** — fully immutable, with correct `equals`/`hashCode` out of the box. This eliminates entire categories of bugs:

- No defensive copies needed
- Thread-safe without synchronization
- Safe to use as map keys or in sets
- Predictable, side-effect-free chaining: `v1.add(v2).normalize().scale(2.0)`

## Mutability Where It Matters

Matrices (`Matrix4d`, `Matrix4f`, etc.), `AABB`, `Ray`, and `FrustumIntersection` are **mutable classes** with fluent `return this` setters. Matrix operations are the performance-critical path where mutation avoids allocation, and matrices are rarely shared across threads.

## `Math.fma` Everywhere

All dot products, lerps, and matrix multiply accumulations use `Math.fma` (fused multiply-add) for higher precision and (where available) hardware acceleration.

## Modern Java

- `java.lang.foreign.MemorySegment` for off-heap memory I/O
- `java.lang.foreign.ValueLayout` for typed memory access
- `jdk.incubator.vector.DoubleVector` for SIMD
- `StructuredTaskScope` for parallel decomposition
- JPMS `module-info.java` for proper encapsulation
Page: Vector Types
# Vector Types

All vectors are immutable Java records. Every operation returns a **new** instance.

## Precision Variants

| 2D | 3D | 4D | Precision |
|----|----|----|-----------|
| `Vector2d` | `Vector3d` | `Vector4d` | `double` |
| `Vector2f` | `Vector3f` | `Vector4f` | `float` |
| `Vector2i` | `Vector3i` | `Vector4i` | `int` |

## Common Operations

### Arithmetic
```java
Vector3d a = new Vector3d(1, 2, 3);
Vector3d b = new Vector3d(4, 5, 6);

Vector3d sum = a.add(b);        // (5, 7, 9)
Vector3d diff = a.sub(b);       // (-3, -3, -3)
Vector3d product = a.mul(b);    // (4, 10, 18)
Vector3d scaled = a.mul(2.0);  // (2, 4, 6)
Vector3d divided = a.div(2.0); // (0.5, 1, 1.5)
Vector3d neg = a.negate();     // (-1, -2, -3)
Geometry
double d = a.dot(b);                   // 32
Vector3d c = a.cross(b);               // (-3, 6, -3)
double len = a.length();               // 3.741...
double lenSq = a.lengthSquared();      // 14
double dist = a.distance(b);           // 5.196...
Vector3d n = a.normalize();            // (0.267, 0.534, 0.801)
Reflection & Projection (2D/3D)
Vector3d reflected = v.reflect(normal);
Vector3d refracted = v.refract(normal, 1.33);
Vector3d projected = v.project(onto);
Vector3d rejected = v.reject(onto);
Rotation
2D:
Vector2d rotated = v.rotate(Math.PI / 4);
Vector2d perp = v.perpendicular();
3D:
Vector3d rotated = v.rotate(axis, angle);
Interpolation
Vector3d mid = a.midpoint(b);
Vector3d lerped = a.lerp(b, 0.5);
Memory I/O
// NIO Buffer
DoubleBuffer buf = DoubleBuffer.allocate(3);
v.writeToBuffer(buf);
buf.flip();
Vector3d back = Vector3d.fromBuffer(buf);

// MemorySegment (FFM API)
MemorySegment seg = arena.allocate(24);
v.writeToMemorySegment(seg, 0);
Vector3d back2 = Vector3d.fromMemorySegment(seg, 0);
Conversion
Vector3d v3 = v2.toVector3d();        // Vector2d → Vector3d (z=0)
Vector3d v3 = v2.toVector3d(1.0);     // Vector2d → Vector3d (z=1.0)
Vector4d v4 = v3.toVector4d(1.0);     // Vector3d → Vector4d (w=1.0)
Vector2d v2 = v3.xy();                // Vector4d → Vector2d (drop z,w)
Vector3d v32 = v4.xyz();              // Vector4d → Vector3d (drop w)
Vector2f v2f = v3.toVector2f();       // double → float conversion
Full Method Reference
Category
Methods
Arithmetic
add, sub, mul, div, scale, negate, abs, sign
Geometric
dot, cross, length, lengthSquared, distance, distanceSquared, normalize, setLength
Reflection
reflect, refract, project, reject, faceforward, projectOnPlane
Rotation
rotate (2D/3D), perpendicular (2D), angle, angleSigned
Interpolation
lerp, midpoint
Component
min, max, clamp, ceil, floor, round, fma, minComponent, maxComponent
Query
isFinite, isNaN, isPerpendicular (2D)
I/O
fromBuffer, writeToBuffer, fromMemorySegment, writeToMemorySegment, toArray, get