1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91
//! ## `ultraviolet` //! //! This is a crate to computer-graphics and games-related linear algebra, but *fast*, both in terms //! of productivity and in terms of runtime performance. //! //! In terms of productivity, ultraviolet uses no generics and is designed to be as straightforward //! of an interface as possible, resulting in fast compilation times and clear code. In addition, the //! lack of generics and Rust type-system "hacks" result in clear and concise errors that are easy to //! parse and fix for the user. //! //! In terms of runtime performance, ultraviolet was designed from the start with performance in mind. //! To do so, we provide two separate kinds of each type, each with nearly identical functionality, //! one with usual scalar f32 values, and the other a 'wide' type which uses SIMD f32x4 vectors for //! each value. This design is clearn and explicit in intent, and it also allows code to //! take full advantage of SIMD. //! //! The 'wide' types use an "SoA" (Structure of Arrays) architecture //! such that each `Wec` (wide-Vec) actually contains the data for 4 `Vec`s and will do any operation //! on all 4 of the vector 'lanes' at the same time (the same concept applies to a `Wat`, or 'wide-Mat'). //! Doing this is potentially *much* (factor of 10) //! faster than an "AoS" (Array of Structs) layout, as all current Rust linear algebra libraries do, //! though it does depend on your workload. Algorithms must be carefully architected to take full advantage //! of this, and doing so can be easier said than done, especially if your algorithm involves significant //! branching. //! //! ### Benchmarks //! //! Benchmarks done using my own fork of [mathbench-rs](https://github.com/bitshifter/mathbench-rs) with support for //! ultraviolet added to some benchmarks. //! //! For the euler 2d and 3d benchmarks, the work being done is exactly equivalent. For the rest of the benchmarks, //! the work being done is *made equivalent* by performing 4 of the benchmarked operation per iteration instead of just //! one for all of the other libraries, since `ultraviolet` is computing that operation on four Vec/Mats at a time. //! //! | benchmark | glam | cgmath | nalgebra | euclid | ultraviolet | //! |------------------------|---------------|----------------|----------------|----------------|-----------------| //! | euler 2d | 9.911 us | 9.583 us | 21.99 us | 15.22 us | __6.675 us__ | //! | euler 3d | 15.11 us | 32.88 us | 237.2 us | 32.62 us | __9.928 us__ | //! | mat3 transform vector3 | 6.1533 ns | 15.2933 ns | 15.6202 ns | N/A | __4.4778 ns__ | //! | vec3 cross | 7.6824 ns | 16.9919 ns | 12.3683 ns | 12.4657 ns | __3.3286 ns__ | //! | vec3 dot | 5.6354 ns | 10.4704 ns | 8.7803 ns | 7.4304 ns | __2.4937 ns__ | //! | vec3 length | 5.8759 ns | 4.2015 ns | 4.5598 ns | 4.2083 ns | __1.9067 ns__ | //! | vec3 normalize | 8.7861 ns | 8.1677 ns | 33.2839 ns | 7.6300 ns | __4.4362 ns__ | //! //! ### Features //! //! This crate is currently being dogfooded in my ray tracer [`rayn`](https://github.com/termhn/rayn), //! and is being used by some Amethyst developers in experimental projects while it is considered for adoption //! into Amethyst. It does what those users have currently needed it to do. //! //! There are a couple relatively unique/novel features in this lib, the most important being the use of the Geometric Algebra //! concepts of Bivectors and Rotors to represent 2d and 3d rotations, rather than implementing complex number algebra //! and Quaternion algebra. //! //! What this means for the programmer is that you will be using the `Rotor3` type in place of //! a Quaternion, though you can expect it to do basically all the same things that a Quaternion does. In fact, Quaternions //! are essentially just a special case of Rotors. The reason this decision was made was twofold: first, the derivation of //! the math is actually quite simple to understand. All the derivations for the code implemented in the Rotor structs in this //! library are written out in the `docs` folder of the GitHub repo; I derived them manually as part of the implementation. //! On the other hand, Quaternions are often basically just seen as black boxes that we programmers use to do rotations because //! they have some nice properties, but that we don't really understand. You can use Rotors this same way, but you can also easily //! understand them. Second is that in some sense they can be seen as 'more correct' than Quaternions, and especially they //! facilitate a more proper understanding of rotation as being something that occurs *within a plane* rather than something //! that occurs *around an axis*, as it is generally thought. Finally, Rotors also generalize do 4 and even higher dimensions, //! and if someone wants to they could implement a Rotor4 which retains all the properties of a Rotor3/Quaternion but does rotation //! in 4 dimensions instead, something which simply is not possible to do with Quaternions. //! //! If it's missing something you need it to do, bug me on the [GitHub issue tracker](https://github.com/termhn/ultraviolet/issues) and/or Rust community discord server //! (I'm Fusha there) and I'll try to add it for you, if I believe it fits with the vision of the lib :) extern crate alloc; mod util; pub mod bivec; pub mod lerp; pub mod mat; pub mod projection; pub mod rotor; pub mod transform; pub mod vec; pub use bivec::*; pub use lerp::*; pub use mat::*; pub use rotor::*; pub use transform::*; pub use vec::*; pub use wide; pub use wide::f32x4;