Crate vek [−] [src]
Generic but efficient SIMD vector+matrix library for game engines, with focus on intent and the small bits that make you happier as a user.
DO NOT USE (yet). This is very much a work-in progress, breaking changes happen all the time on a whim.
The efficiency claim is based on the fact that implementations are specialized according
to the target hardware, and the generated assembly is checked to ensure it is optimal.
As you would expect, SSE-enabled x86 CPUs do benefit from this.
See the FAQ in the README and the the roadmap to 1.0 for more info.
Overview
Here is what vek
has to offer:
- General-purpose vectors:
Vec2<T>
,Vec3<T>
,Vec4<T>
. They are tuple structs and have the same features as spatial vectors. - "Data crunching" vectors:
Vec8<T>
,Vec16<T>
,Vec32<T>
,Vec64<T>
, useful for performing basic operaton on many elements in the best way allowed by CPU features. - Spatial vectors:
Xy<T>
,Xyz<T>
,Xyzw<T>
. They are for storing points and directions in euclidian spaces. - RGB vectors:
Rgb<T>
,Rgba<T>
. They have extended functionality related to color. - Texture coordinate vectors:
Uv<T>
,Uvw<T>
; - Spatial extent vectors:
Extent2<T>
,Extent3<T>
, for representing width, height and depth. - Square matrices:
Mat2<T>
,Mat3<T>
,Mat4<T>
.
Matrices can be row-major or column-major at your option, because there are use cases for both layouts, even though column-major is often better performance-wise, for most use case in computer graphics.
Types share functionality whenever relevant.
Also, there are several (concise) ways to convert from one vector type to another:
- Vectors implement
AsRef
andAsMut
on any lower-dimensioned Vector with the same element type. - Vectors implement
From
on any Vector or tuple type with the same element type. When converting to a higher-dimensioned vector, uninitialized elements are set to the default value of their type.
Here's a small taste of what using this crate could look like :
// TODO make this example work use vek::mat::row_major::Mat4 as Rows4; use vek::mat::column_major::Mat4 as Cols4; use vek::vec::Xyzw; use std::f32::consts::PI; let position = Xyzw::new_point(1_f32, 2_f32, 3_f32); let model: Cols4<_> = Rows4::rotation_x(PI) * Cols4::rotation_3d(PI, position); let new_position = model * position;
You can use straight tuple types for convenience, however since their
memory layout is undefined, the compiler can't generate optimal code. vek
's vector
types are just as convenient (if not more so), but marked #[repr(simd)]
when enabled.
Matrix elements are written as mij
, where i is the row index and j is the column index, independently of storage order.
This convention has been chosen because it is the mathematical standard.
Cargo features
serde
makes vectors and matrices deriveSerialize
andDeserialize
.
vec2
,vec3
,vec8
,vec16
,vec32
,vec64
,xyzw
,xyz
,xy
,rgba
,rgb
,extent3
,extent2
,uvw
,uv
,mat2
,mat3
Select which types you want. Restricting your selection drastically decreases compile times.
They are all enabled by default so that they appear in the documentation (and that doc-tests work).
There is novec4
ormat4
feature, because they are required by examples in documentation.
repr_simd
allows Rust'srepr_simd
andsimd_ffi
features, which require Nightly, but help a lot to generate high-quality code.repr_align
allows Rust'srepr_align
features, which require Nightly. It's always safe to leave disabled, but does increase code quality a bit when enabled.x86intrin
enables x86 intrinsics through thex86intrin
crate.vek
doesn't diretcly depend on it because it won't compile on Stable and there's no way (as of this writing) to selectively depend on a crate based on therustc
version, not even via build scripts.
fix
implements vectors and matrices of fixed-point numbers from thefix
crate.fpa
implements vectors and matrices of fixed-point numbers from thefpa
crate.num-bigint
implements vectors and matrices of big integers from thenum-bigint
crate.
#![no_std]
This crate is #![no_std]
.
Reexports
pub use mat::*; |
pub use vec::*; |
pub use ops::*; |
Modules
mat |
Matrix types. |
ops |
Operations defined by this crate, such as |
vec |
Vector types. |