glm 0.1.2

GLSL mathematics for Rust.
docs.rs failed to build glm-0.1.2
Please check build logs and if you believe this is docs.rs' fault, report into this issue report.

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, dmat3x4 etc., do not work, for the same reason as above. This is rather inconvenient, and the plan is introducing functions like to_vec2, to_dmat3x4 in future version.

  • No implicit conversion.

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