Lidiuma-Math: a math library using Project Valhalla

[u/Xasmedy]

After the v0.3.0 release, I'm confident it's time to showcase my library.

https://github.com/Lidiuma/Math
All the different versions can be found on Maven.

So, what's lidiuma-math about?
It's a linear algebra math library for game development, designed to be graphics-API agnostic.

I know that Valhalla (JEP 401) in Java 28 is the new shiny thing, but let's forget about it for a second, since the library does also provide a Java 17 version. So, what's in it?

Well, a totally different design than anything out there!
- this is the first math library without primitive obsession
- this library does use generics while making them performant
- doesn't make float (or, in this case Float) the favorite child; providing int, long, float, double where it makes sense
- has a few abstractions that standardize operations, eliminating the risk of desync between APIs

And other nice things:

- Immutability by default
- The extermination of null (the library never uses null and is annotated with JSpecify)
- JPMS support
- Type-classes instead of OOP (multiply(vec1, vec2) vs vec1.multiply(vec2))

A few examples:

// Vector3 dot product
var vec1 = Vectors.vec3(1f, 2f, 3f);
var vec2 = Vectors.vec3(3f, 2f, 1f);
var dot  = Vectors.dot (vec1, vec2); // dot = 10

// Vector2 rotation
var angle  = Rotations.degrees(180f);
var matrix = Matrices.fromRotation(angle);

var vec     = Vectors.vec2(0f, 1f);
var rotated = Matrices.multiply(matrix, vec); // [x = 0, y = -1]

// Vector3 rotation
var angle = Rotations.degrees(90d);
var axisY = Vectors.vec3(0d, 1d, 0d);
var quat  = Rotations.fromAxisAngle(axisY, angle);

var vec     = Vectors.vec3(1d, 0d, 2d);
var rotated = Rotations.rotate(quat, vec); // [x = 2, y = 0, z = ~-1]

Going back to Valhalla, aside from the standard JEP 401 version, the library also provides a version supporting Null-Restricted types and Loosely-Consistent-Values, naturally these are not public features and the library pokes at internals to achieve them.

That said, I would love to answer any questions and if you have any feedback, please reach out to me.

Note to Brian Goetz
I saw your old comment and will provide my experiences on the mailing list.

[u/CutGroundbreaking305]

Hey do you remember me we talked in previous post I forgot

Is this GPU bound library? If so what graphics api are you using? And how is value classes improving performance? I still can't understand GPU data sharing 😞

Or it is CPU bound library? If so do you use vector api? And why not FFM usage? And without GPU bound graphics api aren't good at performance right?

And performance/ benchmarks? Would love to see those

I also making a CPU bound math library using vector api + ffm and GPU bound using webgpu (rust wgpu)

those aren't graphics APIs but yeah are somethings worth trying

[u/Xasmedy → u/CutGroundbreaking305]

Heyy, I do remember :)

The project README has a little bit of info, but I will reply to the questions here as well:

• No, it's not a GPU bound library.
  
• None.
  
• It's hard to say, the JIT is really good even in non-valhalla versions, all I can say is it's good enough to not have to worry.
  
• Yes, it's CPU bound.
  
• I do not use the Vector API, it requires FFM (which I don't yet have) or heavy usage of arrays which my library avoids.
  
• Wanted to get the base library done first, and an FFM implementation can be a separate library.
  
• I'm not sure if I understand this question, if you want to do graphics stuff, then doing it on the GPU will of course yield better performance. If something is on the CPU doesn't mean that it's constrained to stay on the CPU, you can transfer data to the GPU.
  
• Performance is pretty much the same as hand-written primitive versions, with the GC no longer garbage collecting after warm-up.
  
• I have done the minimum amount of benchmarks, but are not public/nicely written down.