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/gufranthakur]

It is always nice looking at efforts towards Java game dev. Good work man, are you planning to work on a Game library framework next? I am willing to contribute (and a few others as well)

[u/Xasmedy → u/gufranthakur]

Thank you!
Saying I haven't thought about that would be a lie, but I'd prefer trying to work on a game, and I don't want to fall in the "making an engine/framework instead of a game" trap.
Just making the math took around 9 months of work, and I'm quite burned out. Then my idea of a framework could be different from yours.

But I do plan for it to be the case in the future, maybe when LWJGL 4 releases.
I don't mind discussing about the possibility, you can write me on discord (I'm in the libgdx & lwjgl discord) or via email.

[u/Plixo2]

Does your library have support for ffm / bytebuffers? You said the library was graphics-api oriented.

I don't know if you are aware, but there is also joml2 that supports value classes now!

[u/Xasmedy → u/Plixo2]

As of now there's no support for FFM, I did have in mind to create a separate library for it, but I'm not sure when. I'm also curious on how serialization 2.0 is going to shape things.

Agnostic as not being tied to any graphic-API, at the disadvantage of a few methods like creating a camera matrix not being included.

I discovered about JOML2 literally yesterday, it's quite hard to find and there isn't a release version as of now (just a snapshot).
Aside it being tied to OpenGL, by reading the source it uses a different approach than mine, they define the math on generic tuples while I tend to stay higher-level (E.g. Double4 vs Vec4F64 & Point4F64).

[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.