cgmath-next
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:
[]
= { = "cgmath-next", = "0.18.1" }
use ; // 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
cgmath0.18.0 as published on crates.io — verified by a machine-generated path diff, currently zero differences (seedocs/api-inventory.md) - Numeric results, except where a soundness fix required a change —
verified by a 9-case differential test suite against real
cgmath0.18.0 with exact (not approximate) equality (seedocs/compatibility.md) - Types and trait implementations, including the
serde/mint/randderive impls — unchanged code, but their wire-format output isn't independently round-trip-tested against upstream yet (also noted indocs/compatibility.md) - The
[lib] name = "cgmath"the original crate already declared, so existinguse 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/Fromconversions to homogeneous tuples, e.g.(f32, f32, f32)) relies on tuple memory layout that Rust's language reference does not formally guarantee — flagged asUNSAFE-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). Seedocs/unsafe-audit.md's feasibility-study section for the full writeup, andrustgd/cgmath#538for 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). Seedocs/compatibility.mdfor 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.mdin 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 = new;
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
docs/api-inventory.md— machine-generated public API comparison against 0.18.0docs/unsafe-audit.md— everyunsafeblock in the crate, its safety invariant, and its verification status