Crate glm

Expand description

GLSL mathematics for Rust programming language.

glm-rs is yet another Rust math library for graphics applications. Inspired by the great GLM library for C++, the goal is to provide familiar math API to porgrammers who knows GLSL as well.

§Differences to GLSL specification

Like GLM, following GLSL conventions is a strict policy of glm-rs too. glm crate implements all GLSL data types, operators and built-in functions. However, Rust is not a C-like language, and the syntax/semantics distances from Rust to GLSL is way longer than from C++ to GLSL. This is the major reason of following feature and syntax differences to GLSL specification,

Precision qualifiers is not supported,
Half float type is not available, yet,
There is no vector swizzle operators. For example, you can’t do this,
ⓘ
```
let mut my_vec2 = my_vec4.wz;
// and,
my_vec2.yx = my_vec4.xx;
```
Part of swizzle operators can be done but must be in a very tedious way at the moment. The plan is to implemente accessing swizzle operators after Rust macro supports concatenating identifiers.
Because Rust does not support function name overloading, loads of convenient constructor functions can’t be implemented. For example, you can’t do this,
ⓘ
```
let v2 = vec2(1., 2.);
// compile error: this function takes 3 parameters but 2 parameters were supplied [E0061]
let v3 = vec3(v2, 3.);
```
This will be fixed in future version by introducing functions like no_run fn vec21(x: Vec2, y: f32) -> Vec3, in which function names indicate the forms of result vectors.
Also because of lacking of function name overloading, following built-in functions are added,

atan2, mod_s, max_s, min_s, clamp_s, mix_s, mix_bool, step_s, and smoothstep_s.

The suffix _s stands for scalar, which means this is a variant of original function that some parameters are specific to be scalar, instead a generic type.

See documentation of these functions for detail.
Most explicit conversion functions, like vec2, dmat4x3 etc., do not work, for the same reason as above. This is rather inconvenient, and the plan is introducing functions like to_vec2, to_dmat4x3 in future version.
No implicit conversion.
Explicit type conversion function bool is renamed to boolean.
Many explicit type conversion functions for vector types are introduced. In GLSL spec, these fucntions have the same name as vector type constructors, which is not allowed in Rust. The naming rule is to get a vector type conversion fucntion, adds a to_ before the constructor function. For example,
```
let v = to_vec2(1_f32);
assert_eq!(v, vec2(1., 1.));
```
Lots of convertion functions are still missing (e.g., from matrices to vectors). These functions are syntax sugar actually, and will be fixed along with the constructor issue in future version.
GLSL uses out parameter for returning multiple results of functions. In Rust, we can do this by returning a tuple. Following functions’ signatures are changed because of this,
- modf,
- frexp,
- uaddCarry,
- usubBorrow,
- umulExtended,
- imulExtended
The rule of changing is the out parameter is the second member of the return tuple.
Function parameters of matrix related functions (e.g., inverse, cross) are passed by reference, instead of by value as in the GLSL spec. For example,
```
let m = mat2(1., 2., 3., 4.);
// instead of `inverse(m)`,
let inv = inverse(&m);
```
Built-in function mod is renamed to fmod, because mod is a Rust keyword.