New pixel formats

Cargo.toml

@@ -33,27 +33,37 @@ resolver = "2"
 
 [workspace.package]
 edition = "2024"
-version = "0.4.0-pre4"
+version = "0.4.0"
 authors = ["Johannes 'Sharlin' Dahlström <johannes.dahlstrom@gmail.com>"]
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/jdahlstrom/retrofire"
 keywords = ["graphics", "gamedev", "demoscene", "retrocomputing", "rendering"]
 categories = ["graphics", "game-development", "no-std"]
 
-[workspace.lints.clippy]
-manual_range_contains = "allow"
-collapsible_if = "allow"
+[workspace.lints]
+clippy.manual_range_contains = "allow"
+clippy.collapsible_if = "allow"
+
+[features]
+default = ["std"]
+std = ["retrofire-core/std", "retrofire-geom/std"]
 
 [dependencies]
-retrofire-core = { version = "0.4.0-pre4", path = "core" }
-retrofire-front = { version = "0.4.0-pre4", path = "front" }
-retrofire-geom = { version = "0.4.0-pre4", path = "geom" }
+retrofire-core = { version = "0.4.0", path = "core" }
+retrofire-front = { version = "0.4.0", path = "front" }
+retrofire-geom = { version = "0.4.0", path = "geom" }
 
 [profile.release]
 opt-level = 2
+codegen-units = 1
 lto = "thin"
 debug = 1
 
+[profile.bench]
+opt-level = 3
+codegen-units = 1
+lto = "fat"
+
 [profile.dev]
 opt-level = 1
 split-debuginfo = "unpacked"

README.md

@@ -14,7 +14,8 @@
 
 *Note: This document is best viewed on an 80-column VGA terminal.*
 
-Retrofire is a software 3D rendering library
+Retrofire is a software 3D rendering library focusing on performance,
+correctness, and pedagogical value.
 
 The Retrofire project began as a shamelessly nostalgic effort to explore
 the state of graphics programming as it was in the mid-to-late 90s in
@@ -88,10 +89,11 @@ for custom allocators is planned in order to make `alloc` optional as well.
 
 Retrofire is split into several packages:
 
-* core:  math, renderer, utilities; no-std compatible
-* geom:  geometric shapes, mesh builders, model loading
-* front: frontends for writing simple graphical applications
-* demos: binaries showcasing retrofire features
+* retrofire: a metapackage that just re-exports core, geom, and front
+* retrofire-core:  math, renderer, utilities; no-std compatible
+* retrofire-geom:  geometric shapes, mesh builders, model loading
+* retrofire-front: frontends for writing simple graphical applications
+* retrofire-demos: binaries showcasing retrofire features.
 
 # Dependencies
 
@@ -103,13 +105,25 @@ functions, the package is not fully functional unless either the `std`,
 `libm`, or `mm` feature is enabled. Activating `std` additionally enables
 APIs that do I/O.
 
-The `front` package depends on either `sdl2`, `minifb`, or `wasm-bindgen`
-and `web-sys`, depending on enabled features.
+The `retrofire-front` package depends on either `sdl2`, `minifb`, or
+`wasm-bindgen` and `web-sys`, depending on enabled features.
 
-The `geom` package has no external dependencies. It only requires `alloc`;
-activating the optional feature `std` enables APIs that do I/O.
+The `retrofire-geom` package has no external dependencies. It only requires
+`alloc`; activating the optional feature `std` enables APIs that do I/O.
 
-The `retrofire-demos` package depends on `retrofire-front`.
+The `retrofire-demos` package depends on `retrofire`.
+
+# Screenshots
+
+The classic Stanford bunny.
+![The classic Stanford bunny 3D model.](docs/bunny.jpg)
+
+A first-person mouse-and-keyboard scene with many "Rust crates" strewn on a
+checkered floor.
+![Many wooden crates on a plane, each with the Rust logo](docs/crates.jpg)
+
+Ten thousand spherical particles positioned randomly in a sphere.
+![Ten thousand spherical particles in random positions.](docs/sprites.jpg)
 
 # License
 

core/README.md

@@ -12,12 +12,14 @@
 
 # Retrofire-core
 
-Core functionality of the `retrofire` project.
+Core functionality of the [`retrofire`][1] project.
 
 Includes a math library with strongly typed points, vectors, matrices,
 colors, and angles; basic geometry primitives; a software 3D renderer with
 customizable shaders; with more to come.
 
+[1]: https://crates.io/crates/retrofire
+
 ## Crate features
 
 * `std`:

core/examples/hello_tri.rs

@@ -1,4 +1,3 @@
-use retrofire_core::geom::tri;
 use retrofire_core::{prelude::*, util::*};
 
 fn main() {
@@ -10,7 +9,7 @@ fn main() {
 
     #[cfg(feature = "fp")]
     let shader = shader::new(
-        |v: Vertex3<Color3f>, mvp: &Mat4x4<ModelToProj>| {
+        |v: Vertex3<Color3f>, mvp: &ProjMat3<Model>| {
             // Transform vertex position from model to projection space
             // Interpolate vertex colors in linear color space
             vertex(mvp.apply(&v.pos), v.attrib.to_linear())
@@ -19,7 +18,7 @@ fn main() {
     );
     #[cfg(not(feature = "fp"))]
     let shader = shader::new(
-        |v: Vertex3<Color3f>, mvp: &Mat4x4<ModelToProj>| {
+        |v: Vertex3<Color3f>, mvp: &ProjMat3<Model>| {
             // Transform vertex position from model to projection space
             // Interpolate vertex colors in normal sRGB color space
             vertex(mvp.apply(&v.pos), v.attrib)

core/src/geom.rs

@@ -4,9 +4,10 @@ use alloc::vec::Vec;
 use core::fmt::Debug;
 
 use crate::math::{
-    Affine, Lerp, Linear, Mat4x4, Parametric, Point2, Point3, Vec2, Vec3,
-    Vector, mat::RealToReal, space::Real, vec2, vec3,
+    Affine, Lerp, Linear, Mat4, Parametric, Point2, Point3, Vec2, Vec3, Vector,
+    space::Real, vec2, vec3,
 };
+
 use crate::render::Model;
 
 pub use mesh::Mesh;
@@ -517,7 +518,7 @@ impl<B> Plane3<B> {
     ///
     /// assert_approx_eq!(m.apply(&Point3::origin()), pt3(0.0, 0.5, 0.5));
     /// ```
-    pub fn basis<F>(&self) -> Mat4x4<RealToReal<3, F, B>> {
+    pub fn basis<F>(&self) -> Mat4<F, B> {
         let up = self.abc();
 
         let right: Vec3<B> =
@@ -531,7 +532,7 @@ impl<B> Plane3<B> {
 
         let origin = self.offset() * up;
 
-        Mat4x4::from_affine(right, up, fwd, origin.to_pt())
+        Mat4::from_affine(right, up, fwd, origin.to_pt())
     }
 
     /// Helper that returns the plane normal non-normalized.
@@ -864,8 +865,8 @@ mod tests {
 
     #[test]
     fn singleton_polyline_eval() {
-        let pl = Polyline(vec![3.14]);
-        assert_eq!(pl.eval(0.0), 3.14);
-        assert_eq!(pl.eval(1.0), 3.14);
+        let pl = Polyline(vec![1.23]);
+        assert_eq!(pl.eval(0.0), 1.23);
+        assert_eq!(pl.eval(1.0), 1.23);
     }
 }

core/src/geom/mesh.rs

@@ -7,7 +7,7 @@ use core::{
 };
 
 use crate::{
-    math::{Apply, Linear, Mat4x4, Point3, mat::RealToReal},
+    math::{Linear, Mat4, Point3},
     render::Model,
 };
 
@@ -79,12 +79,7 @@ impl<A, B> Mesh<A, B> {
         let faces: Vec<_> = faces.into_iter().collect();
         let verts: Vec<_> = verts.into_iter().collect();
 
-        for (i, Tri(vs)) in faces.iter().enumerate() {
-            assert!(
-                vs.iter().all(|&j| j < verts.len()),
-                "vertex index out of bounds at faces[{i}]: {vs:?}"
-            )
-        }
+        assert_indices_in_bounds(&faces, verts.len());
         Self { faces, verts }
     }
 
@@ -109,6 +104,16 @@ impl<A, B> Mesh<A, B> {
     }
 }
 
+#[inline(never)]
+fn assert_indices_in_bounds(faces: &[Tri<usize>], len: usize) {
+    for (Tri(vs), i) in zip(faces.iter(), 0..) {
+        assert!(
+            vs.iter().all(|&j| j < len),
+            "vertex index out of bounds at faces[{i}]: {vs:?}"
+        )
+    }
+}
+
 impl<A> Mesh<A> {
     /// Returns a new mesh builder.
     pub fn builder() -> Builder<A> {
@@ -173,7 +178,7 @@ impl<A> Builder<A> {
     ///
     /// This is an eager operation, that is, only vertices *currently*
     /// added to the builder are transformed.
-    pub fn transform(self, tf: &Mat4x4<RealToReal<3, Model, Model>>) -> Self {
+    pub fn transform(self, tf: &Mat4<Model, Model>) -> Self {
         self.warp(|v| vertex(tf.apply(&v.pos), v.attrib))
     }
 

core/src/lib.rs

@@ -62,7 +62,7 @@ pub mod prelude {
             Mesh, Normal2, Normal3, Tri, Vertex, Vertex2, Vertex3, tri, vertex,
         },
         math::*,
-        render::{raster::Frag, *},
+        render::*,
         util::buf::{AsMutSlice2, AsSlice2, Buf2, MutSlice2, Slice2},
     };
 }

core/src/math.rs

@@ -24,15 +24,15 @@ pub use {
     approx::ApproxEq,
     color::{Color, Color3, Color3f, Color4, Color4f, rgb, rgba},
     mat::{
-        Apply, Mat2x2, Mat3x3, Mat4x4, Matrix, orthographic, perspective,
+        Apply, Mat2, Mat3, Mat4, Matrix, ProjMat3, orthographic, perspective,
         scale, scale3, translate, translate3, viewport,
     },
     param::Parametric,
     point::{Point, Point2, Point2u, Point3, pt2, pt3},
     space::{Affine, Linear},
     spline::{BezierSpline, CubicBezier, smootherstep, smoothstep},
     vary::Vary,
-    vec::{Vec2, Vec2i, Vec3, Vec3i, Vector, splat, vec2, vec3},
+    vec::{ProjVec3, Vec2, Vec2i, Vec3, Vec3i, Vector, splat, vec2, vec3},
 };
 #[cfg(feature = "fp")]
 pub use {
@@ -177,6 +177,7 @@ where
     /// let p1 = pt2(-5.0, 0.0);
     /// assert_eq!(p0.lerp(&p1, 0.4),pt2(-8.0, 3.0));
     /// ```
+    #[inline]
     fn lerp(&self, other: &Self, t: f32) -> Self {
         self.add(&other.sub(self).mul(t))
     }
@@ -187,6 +188,7 @@ impl Lerp for () {
 }
 
 impl<U: Lerp, V: Lerp> Lerp for (U, V) {
+    #[inline]
     fn lerp(&self, (u, v): &Self, t: f32) -> Self {
         (self.0.lerp(u, t), self.1.lerp(v, t))
     }

core/src/math/angle.rs

@@ -45,17 +45,17 @@ pub type SphericalVec<B = ()> = Vector<[f32; 3], Spherical<B>>;
 //
 
 /// Returns an angle of `a` radians.
-pub fn rads(a: f32) -> Angle {
+pub const fn rads(a: f32) -> Angle {
     Angle(a)
 }
 
 /// Returns an angle of `a` degrees.
-pub fn degs(a: f32) -> Angle {
+pub const fn degs(a: f32) -> Angle {
     Angle(a * RADS_PER_DEG)
 }
 
 /// Returns an angle of `a` turns.
-pub fn turns(a: f32) -> Angle {
+pub const fn turns(a: f32) -> Angle {
     Angle(a * RADS_PER_TURN)
 }
 
@@ -546,6 +546,14 @@ impl Rem for Angle {
     }
 }
 
+impl Mul<Angle> for f32 {
+    type Output = Angle;
+
+    fn mul(self, rhs: Angle) -> Self::Output {
+        rhs * self
+    }
+}
+
 #[cfg(feature = "fp")]
 impl<B> From<PolarVec<B>> for Vec2<B> {
     /// Converts a polar vector into the equivalent Cartesian vector.