cgmath-next 0.18.1

A maintained, soundness-focused, source-compatible successor to cgmath 0.18.
Documentation

cgmath-next

CI Documentation crates.io License

English | 日本語 | 中文

A maintained, soundness-focused, source-compatible successor to cgmath 0.18.

Keep the API. Remove the unsoundness.

cgmath-next is an independently maintained, community successor to cgmath 0.18.0.

The original cgmath is unmaintained (RUSTSEC-2026-0196) and has a known soundness issue (RUSTSEC-2026-0197 / rustgd/cgmath#565). cgmath-next exists to fix that issue and keep receiving soundness and maintenance fixes, while staying a drop-in replacement wherever possible.

Migration

In most cases, migrating is a one-line Cargo.toml change and nothing else:

[dependencies]
cgmath = { package = "cgmath-next", version = "0.18.1" }
use cgmath::{Matrix4, Quaternion, Vector3}; // unchanged

This works because cgmath-next's compiled library name is still cgmath (see docs/compatibility.md for the fixture-based verification behind this). See docs/migration.md for more detail and for cases where a rename isn't even necessary.

Examples

See examples/camera_transform.rs for a minimal, runnable example: building a camera view-projection matrix and pushing a point through it into clip space and normalized device coordinates — the same per-vertex pipeline a renderer runs.

cargo run --example camera_transform

What this project preserves

  • The public API of cgmath 0.18.0 as published on crates.io — verified by a machine-generated path diff, currently zero differences (see docs/api-inventory.md)
  • Numeric results, except where a soundness fix required a change — verified by a 9-case differential test suite against real cgmath 0.18.0 with exact (not approximate) equality (see docs/compatibility.md)
  • Types and trait implementations, including the serde/mint/rand derive impls — unchanged code, but their wire-format output isn't independently round-trip-tested against upstream yet (also noted in docs/compatibility.md)
  • The [lib] name = "cgmath" the original crate already declared, so existing use cgmath::... code keeps compiling
  • Apache-2.0 licensing and the original copyright notices

What this project does not guarantee

  • Not a "100% memory safe" or "fully audited" claim. Soundness work is ongoing and tracked item-by-item in docs/unsafe-audit.md. One category of existing unsafe code (AsRef/AsMut/From conversions to homogeneous tuples, e.g. (f32, f32, f32)) relies on tuple memory layout that Rust's language reference does not formally guarantee — flagged as UNSAFE-002. This is now guarded: a runtime check verifies size, alignment, and per-field byte offsets before every such conversion and panics instead of transmuting if they don't match (verified via Miri, a negative-control test, and release-build disassembly confirming zero cost when layout matches, as it does today). This converts a hypothetical future layout divergence from silent undefined behavior into a loud, immediate panic — it is not a language-level soundness proof; tuple layout remains officially unspecified, and the only way to fully close this out would be removing the reference-returning conversions (a public API change, out of scope for this series). See docs/unsafe-audit.md's feasibility-study section for the full writeup, and rustgd/cgmath#538 for independent corroboration that this isn't specific to this fork.
  • No Rust ABI compatibility guarantee. #[repr(C)] layout (size_of, align_of, field offsets) is verified specifically for types that declare it, not implied crate-wide.
  • Not a "complete drop-in replacement" for every possible use. Verified compatibility is scoped to what's actually been tested: the upstream test suite (unmodified, all passing), a handful of dependency-rename fixtures, and 5 real downstream crates (see compat/fixtures/reverse-deps/RESULTS.md). See docs/compatibility.md for exactly what's been checked.

RustSec advisory status

Advisory Status
RUSTSEC-2026-0197 (soundness: swap_columns same-index UB) Fixed, and the fix covers more than the advisory's literal scope — see docs/unsafe-audit.md and the project's commit history for Array::swap_elements and Matrix::swap_elements, which shared the same bug and were not named in the advisory.
RUSTSEC-2026-0196 (unmaintained) Addressed by this project's existence: cgmath-next is actively maintained.

Relationship to upstream

cgmath-next is based on cgmath 0.18.0 as published on crates.io, not upstream's master branch (which has diverged with unreleased features and a dependency bump). See docs/provenance.md for the exact source, checksum, and the classification of every upstream commit since the 0.18.0 tag. See Release status for what's published so far.

Compatibility policy

  • Public API removals, renames, signature changes, or trait-bound tightening are treated as a release blocker for the 0.18.1 series, not something to slip in silently.
  • Soundness fixes take priority over strict behavioral preservation when the two conflict (e.g. same-index swap becoming an explicit no-op).
  • New features and large redesigns are deferred until after the API-parity release. See AGENTS.md in this repository for the full policy this project follows.

MSRV

See docs/msrv.md for the measured minimum supported Rust version and how it was determined.

Features

Declared vs. implicit (Cargo auto-generates a feature for each optional dependency) — see docs/compatibility.md for the full breakdown:

Feature What it enables
swizzle GPU-style swizzle accessors (v.xyxz(), etc.)
unstable Present for compatibility with 0.18.0; currently gates no reachable code
serde Serialize/Deserialize impls
mint Conversions to/from the mint interop types
rand Distribution impls for random generation

Swizzling

This library offers an optional feature called "swizzling", widely familiar to GPU programmers. Enable it with --features="swizzle".

let v = Vector3::new(1.0, 2.0, 3.0);
v.xyxz(); // Vector4 { x: 1.0, y: 2.0, z: 1.0, w: 3.0 }
v.zy();   // Vector2 { x: 3.0, y: 2.0 }

Conventions

cgmath-next interprets its vectors as column matrices ("column vectors"), meaning when transforming a vector with a matrix, the matrix goes on the left. This is reflected in the fact that cgmath-next implements the multiplication operator for Matrix * Vector, but not Vector * Matrix. Unchanged from upstream.

Limitations

cgmath-next is not an n-dimensional library and is aimed at computer graphics applications rather than general linear algebra. It only offers the 2, 3, and 4 dimensional structures, inherited unchanged from upstream. Dynamic-dimension matrices, GPU compute, and a nalgebra/glam-style API redesign are explicitly out of scope for this release series — see AGENTS.md for the full list.

Security reporting

See SECURITY.md. Soundness issues (safe-Rust-reachable undefined behavior) are treated as security issues, not ordinary bugs.

Release status

0.18.1-alpha.1 is published to crates.io, tagged (v0.18.1-alpha.1), and marked as a GitHub pre-release. This is an alpha, not a stability guarantee — see docs/release-checklist.md for the exact gating conditions met and not yet met, and docs/unsafe-audit.md's UNSAFE-002 section for the one known gap before a 0.18.1 stable release. No stable release has been published.

Contributing

See CONTRIBUTING.md.

API diff / unsafe audit