- Builds on:
- Tests on:
If you're a CI pro, please submit a PR that gives even more CI coverage!
A library for hekkin vectors.
f32Vectors of dimension 2, 3, and 4.
f32Matrices with one vector per column (aka "column-major"). This is optimal for uploading into OpenGL or Vulkan with a GLSL shader.
STATUS: NOT READY FOR USE
Code Organization Details
Code is largely organized with one type per module. These modules are made part
of the crate by having
lib.rs do the following for each one:
mod foo; pub use foo::*;
The combination of a private module and a
pub use of the content of said
module causes the outside world see all of the content of the
foo module as
being directly within the crate's top level module. This is easiest on end
users, without forcing us to literally put the entire crate in a single file.
Tests are organized as one test file per operation group. This is a lot easier to keep track of when adding one operation at a time and checking that it's implemented for each appropriate type.
- Any "accessor" and "view" style methods, as well as
new, are marked#[inline(always)]`.
- Most other methods are marked
- Formatting methods are not even marked for inlining.
- If it can be shown that insufficient inlines are the cause of a slowdown
then we can upgrade a particular method to be
#[inline(always)], but there must first be some sort of benchmark demonstrating the issue.
At the moment I'm using the adding of new operations to the library as a bit of a way to re-verify that I personally know how each thing works because it's sure been a bit since I had to do any of this. Accordingly, having other people add in large piles of functionality isn't something I'm super interested in.
That said, there are plenty of places where people who want to contribute can help speed up the process:
- It's Not All Perfectly Fast: Benchmark any potentially-slow operation that's already in the library, benchmark an alternate way of computing the same thing, and submit a PR if you've found an improvement.
- Math Research Is Hard: Look up how an operation works and post the appropriate formulas and a source link into the issue for the operation in the issue tracker. This is particularly important for anything to do with Quaternions.
- Test Data Is Dull: Based on the formula of an operation, write up some expected test cases and post them in the appropriate issue in the issue tracker so that I know what I'm targeting ahead of time. If there's already a test case written I'm a lot more likely to want to try and handle that first, since writing tests myself is very boring.
- Open New Issues: If there's an operation, particularly one that
nalgebra-glmhandles, that isn't in the issue tracker then please add it to the issue tracker.
- Help My Dependencies: I'm trying to stay
no_stdfor as long as possible which means that I end up having to rely on the libm crate, so you can always help out there.
- Do It Wide: This is one of the hardest ones. With
Vec4we want to take advantage of the individual components being parts of a "f32x4" SIMD lane as much as we can. This means that we have to write custom versions of some operations, particularly trigonometry, because normal branching code is far less helpful to us. For example, when there's a brach in SIMD you have execute both branches and then combine the results with a mask, so branching to exit a function early is no help. This usually means that you have to re-think how to handle things. Properly wide versions of things like trig are essential to eventual good performance across the board. This isn't a hard blocker: when a wide version isn't available I just call the necessary
libmfunction on each component individually, but that's about 4x as long to execute.