base_2/

lib.rs

#![warn(missing_docs)]
//! # `base_2`
//!
//! Exact fixed-point geometry. Float in, float out, zero drift inside.
//!
//! ## The problem
//!
//! Floating point geometry drifts. Every transform, every frame, every
//! physics tick adds a tiny error. Over time vertices shift, collision
//! checks disagree, and multiplayer clients desync. The root cause is always
//! the same: floating point math is approximate by design.
//!
//! ## The fix
//!
//! `base_2` intercepts your geometry once, freezes it to exact 64-bit integers,
//! and gives you back two representations:
//!
//! - **Exact `i64`** — for logic, physics, collision. Deterministic on a given platform.
//! - **Clean `f32`** — freshly derived from the exact source every frame, for your GPU.
//!
//! Error is introduced exactly once, at freeze time, bounded at ≤ 2^-33 of your input unit.
//! It does not grow with subsequent operations.
//!
//! ## Coordinate system
//!
//! Internally, 1 unit = 2^-32 of your input unit.
//! This gives:
//! - **Resolution**: 2^-32 per input unit
//! - **Range**: ±2^31 input units with `i64`, ±2^95 input units with `i128`
//! - **Overflow**: predictable — `i64` always uses all 64 bits, so worst-case
//!   arithmetic behavior is known upfront, not discovered at runtime
//!
//! Units in your API are user-defined. Pass millimeters, game units, or
//! anything else — as long as you are consistent.
//!
//! ## Quick start
//!
//! ```rust
//! use base_2::api::Mesh;
//!
//! // load from any float source — STL, OBJ, GLTF, engine mesh, etc.
//! let mesh = Mesh::from_floats(&float_verts)
//!     .translate(10.0, 0.0, 0.0)
//!     .rotate_quat(0.0, 0.0, 0.707, 0.707);
//!
//! // compute once per frame
//! let pts = mesh.compute();
//!
//! let gpu   = pts.to_f32();  // clean floats for renderer — derived fresh each frame
//! let logic = pts.to_i64();  // exact integers for physics and collision
//! ```
//!
//! ## Why `base_2`?
//!
//! The 2^-32 scaling is not arbitrary. It means every coordinate uses all 64 bits,
//! giving uniform precision across the entire range. There is no false headroom,
//! no "works on small inputs but breaks on large ones." Overflow behavior is
//! always worst-case, always documented, always the same.
//!
//! It is the fixed-point equivalent of Rust's ownership model:
//! honest about what it costs, in exchange for guarantees you can rely on.

mod coord;
mod point;
mod transforms;

pub mod api;

pub use api::{Mesh, Points, Transform, RotationMatrix};
pub use coord::{Coord64, Coord128};
pub use point::{Point3, Point2};