nalgebra_glam

Conversions between nalgebra-cairo and glam-cairo types: the glam interop of the Rust nalgebra crate (third_party/glam, behind its convert-glam0XX features), as a separate package because Scarb has no optional dependencies and glam costs every dependent of nalgebra compile time and memory.

It depends on the sub-crates of nalgebra-cairo that define the types it converts: nalgebra_core (Unit, the dimension-1 types), nalgebra_types2, nalgebra_types3 and nalgebra_types4 (the shapes, Point2..4, Translation2..4, Rotation2..3), nalgebra_static2 and nalgebra_static3 (their methods up to 3x3) and nalgebra_geometry2 and nalgebra_geometry3 (the 2D / 3D geometry: rotations, quaternions, isometries, similarities), and on glam-cairo's glam_core 0.5.0 (every glam type it converts and every impl it needs; it needs glam >= 0.5.0, which re-exports glam_core), not on the nalgebra / glam facades: a much cheaper build. The types are the same as the facades' (nalgebra and glam re-export them, glam from 0.4.1 on), so a dependent of the facades uses it unchanged; glam 0.4.0 defines its own types, so a lock file pinned to it needs scarb update glam (0.5.0):

[dependencies]
nalgebra = "0.3.0"          # or the sub-crates above
nalgebra_glam = "0.3.0"
glam = "0.5.0"              # or glam_core
fixed = "0.5.0"

Upstream's From<X> for Y is Into<X, Y> here, TryFrom is TryInto (returning an Option), and the impls are found by the compiler only when in scope:

use fixed::Fixed;
use glam::{Mat4, Quat, Vec3};
use nalgebra::{Isometry3, Vector3};
use nalgebra_glam::prelude::*;

let v: Vector3<Fixed> = vec3.into();                    // Vec3 -> Vector3<Fixed>
let iso: Isometry3<Fixed> = (vec3, quat).into();        // (Vec3, Quat) -> Isometry3
let mat: Mat4 = iso.into();                             // Isometry3 -> Mat4 (column-major)
let back: Option<Isometry3<Fixed>> = mat.try_into();    // None unless the matrix is rigid

Coverage

Every conversion of upstream's glam_matrix, glam_point, glam_translation, glam_quaternion, glam_rotation, glam_unit_complex, glam_isometry and glam_similarity for the types glam-cairo has (91 items of docs/API_PARITY.md), one module per upstream file:

glam-cairo's Mat2..4 are column-major (x_axis is the first COLUMN) and Quat is (x, y, z, w) where nalgebra's Quaternion::new takes (w, i, j, k): the conversions map them exactly. The types glam-cairo does not have (f64 D*, aligned Vec3A, other integer widths) have no impls.

Deviations from upstream (Result is an Option, zero-length inputs panic instead of giving NaN, the 2D Similarity conversion works where upstream panics) are documented in each module.

When to depend on it

Depend on nalgebra_glam when you convert between nalgebra-cairo and glam-cairo types. It is the declared closure nalgebra_glam (6.5 s / 1.55 GB on a GitHub runner over an empty consumer, budget 15 s / 3 GB; the reference glam_core 0.5.0 alone is 1.4 s / 0.44 GB), and it does not pull dimension 5 or 6. The facade nalgebra does not depend on it: add it next to the facade.

internal

This crate has no internal module.

License

MIT.