Split out new crate all-is-cubes-base.

It contains the majority of code from the `math` and `util` modules of
`all-is-cubes`.

This new crate will enable us to use `raycast` in the build script of
`all-is-cubes` to generate fully pre-calculated light propagation data.
It may also assist in further splitting of `all-is-cubes` into
separately compilable parts, if I find such divisions worth making.

I chose the name “base” to be sufficiently abstract that it will not
become unsuitable for its purpose (being the crate that all others
eventually depend on) regardless of exactly what it evolves to contain.
I also considered “all-is-cubes-core”, but I feel that only the crate
containing `Block` and `Space` deserves that name if I were to use it.

Also, because it's now possible and convenient, the macros `notnan`,
`rgb_const`, and `rgba_const` have been moved to `all_is_cubes::math`.
(This is only possible because macro re-exports can be exported from
specific modules, even though `macro_rules` declarations can only be
exported from the crate root.)

CHANGELOG.md

@@ -66,6 +66,8 @@
         - `AnyURef` to `AnyHandle`
         - `VisitRefs` to `VisitHandles`
         - `RefVisitor` to `HandleVisitor`
+
+    - The macros `rgb_const!`, `rgba_const!`, and `notnan!` have been moved to the `math` module.
 
 - `all-is-cubes-mesh` library:
     - The return type of `GetBlockMesh::get_block_mesh()` has changed to `Option<&BlockMesh>`.

Cargo.toml

@@ -1,6 +1,7 @@
 [workspace]
 members = [
   "all-is-cubes",
+  "all-is-cubes-base",
   "all-is-cubes-content",
   "all-is-cubes-desktop",
   "all-is-cubes-gpu",
@@ -39,6 +40,7 @@ resolver = "2"
 
 [workspace.dependencies]
 all-is-cubes = { path = "all-is-cubes", version = "0.7.1", default-features = false }
+all-is-cubes-base = { path = "all-is-cubes-base", version = "0.7.1", default-features = false }
 all-is-cubes-content = { path = "all-is-cubes-content", version = "0.7.0", default-features = false }
 all-is-cubes-desktop = { path = "all-is-cubes-desktop", version = "0.7.0", default-features = false }
 all-is-cubes-gpu = { path = "all-is-cubes-gpu", version = "0.7.0", default-features = false }
@@ -65,6 +67,7 @@ clap = { version = "4.2.4", default-features = false, features = ["cargo", "depr
 criterion = { version = "0.5.1", features = ["async_tokio", "cargo_bench_support", "html_reports"] }
 displaydoc = { version = "0.2.4", default-features = false}
 either = { version = "1.10.0", default-features = false }
+embedded-graphics = "0.8.0"
 exhaust = { version = "0.1.0", default-features = false }
 flume = { version = "0.11.0", default-features = false, features = ["async"] }
 futures-channel = { version = "0.3.28", default-features = false, features = ["alloc"] }

all-is-cubes-base/Cargo.toml

@@ -0,0 +1,54 @@
+[package]
+name = "all-is-cubes-base"
+version = "0.7.1"
+authors = ["Kevin Reid <[email protected]>"]
+edition = "2021"
+rust-version = "1.73"
+description = "Helper library for all-is-cubes. Do not use directly."
+repository = "https://github.com/kpreid/all-is-cubes"
+license = "MIT OR Apache-2.0"
+
+[lib]
+# Disable running as benchmark so that the default doesn't interfere with Criterion usage.
+bench = false
+
+[features]
+std = []
+# Adds `impl arbitrary::Arbitrary for ...`
+# Note: Not using euclid/arbitrary because it's broken
+arbitrary = ["dep:arbitrary", "ordered-float/arbitrary"]
+rerun = ["dep:re_types"]
+serde = [
+    "dep:serde",
+    "ordered-float/serde",
+]
+
+[dependencies]
+arbitrary = { workspace = true, optional = true }
+bytemuck = { workspace = true, features = ["derive"] }
+cfg-if = { workspace = true }
+displaydoc = { workspace = true }
+embedded-graphics = { workspace = true }
+# mint feature to guarantee that our callers can use mint types
+# libm feature to guarantee compilability and compatibility with no_std
+euclid = { version = "0.22.9", default-features = false, features = ["libm", "mint"] }
+exhaust = { workspace = true, default-features = false }
+futures-core = { workspace = true }
+futures-util = { workspace = true }
+manyfmt = { workspace = true }
+mutants = { workspace = true }
+num-traits = { workspace = true }
+ordered-float = { workspace = true }
+polonius-the-crab = { workspace = true }
+rand = { workspace = true }
+re_types = { workspace = true, optional = true }
+serde = { workspace = true, optional = true, features = ["derive"] }
+
+[dev-dependencies]
+indoc = { workspace = true }
+itertools = { workspace = true }
+pretty_assertions = { workspace = true }
+rand_xoshiro = { workspace = true }
+
+[lints]
+workspace = true

all-is-cubes-base/LICENSE-APACHE

@@ -0,0 +1 @@
+../LICENSE-APACHE

all-is-cubes-base/LICENSE-MIT

@@ -0,0 +1 @@
+../LICENSE-MIT

all-is-cubes-base/README.md

@@ -0,0 +1,21 @@
+This library is an internal component of [`all-is-cubes`],
+which defines some core mathematical types and functions.
+Do not depend on this library; use only [`all-is-cubes`] instead.
+
+[`all-is-cubes`]: https://crates.io/crates/all-is-cubes/
+
+License
+-------
+
+All source code and other materials are Copyright © 2020-2024 Kevin Reid, and licensed under either of
+
+ * Apache License, Version 2.0
+   ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+ * MIT license
+   ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option. 
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
+dual licensed as above, without any additional terms or conditions.

all-is-cubes-base/src/lib.rs

@@ -0,0 +1,32 @@
+//! This library is an internal component of [`all-is-cubes`],
+//! which defines some core mathematical types and functions.
+//! Do not depend on this library; use only [`all-is-cubes`] instead.
+//!
+//! [`all-is-cubes`]: https://crates.io/crates/all-is-cubes/
+
+#![no_std]
+// Crate-specific lint settings. (General settings can be found in the workspace manifest.)
+#![cfg_attr(
+    not(any(test, feature = "arbitrary")),
+    warn(clippy::std_instead_of_core, clippy::std_instead_of_alloc)
+)]
+#![cfg_attr(not(feature = "std"), allow(clippy::arc_with_non_send_sync))]
+
+#[cfg(any(feature = "std", test))]
+#[cfg_attr(test, macro_use)]
+extern crate std;
+#[macro_use]
+extern crate alloc;
+
+/// Do not use this module directly; its contents are re-exported from `all-is-cubes`.
+#[macro_use]
+pub mod math;
+
+/// Do not use this module directly; its contents are re-exported from `all-is-cubes`.
+pub mod resolution;
+
+/// Do not use this module directly; its contents are re-exported from `all-is-cubes`.
+pub mod time;
+
+/// Do not use this module directly; its contents are re-exported from `all-is-cubes`.
+pub mod util;

all-is-cubes-base/src/math.rs

@@ -0,0 +1,176 @@
+//! Mathematical utilities and decisions.
+
+use euclid::Vector3D;
+use num_traits::identities::Zero;
+pub use ordered_float::{FloatIsNan, NotNan};
+
+/// Acts as polyfill for float methods
+#[cfg(not(feature = "std"))]
+#[allow(unused_imports)]
+use num_traits::float::FloatCore as _;
+
+use crate::util::ConciseDebug;
+
+mod aab;
+pub use aab::*;
+mod axis;
+pub use axis::*;
+#[macro_use]
+mod color;
+pub use color::*;
+mod coord;
+pub use coord::*;
+mod cube;
+pub use cube::Cube;
+mod face;
+pub use face::*;
+mod grid_aab;
+pub use grid_aab::*;
+mod grid_iter;
+pub use grid_iter::*;
+mod rigid;
+pub use rigid::*;
+mod matrix;
+pub use matrix::*;
+mod rotation;
+pub use rotation::*;
+#[cfg(feature = "serde")]
+mod serde_impls;
+mod vol;
+pub use vol::*;
+
+// We make an assumption in several places that `usize` is at least 32 bits.
+// It's likely that compilation would not succeed anyway, but let's make it explicit.
+#[cfg(not(any(
+    target_pointer_width = "32",
+    target_pointer_width = "64",
+    target_pointer_width = "128",
+)))]
+compile_error!("all-is-cubes does not support platforms with less than 32-bit `usize`");
+
+/// Allows writing a [`NotNan`] value as a constant expression (which is not currently
+/// a feature provided by the [`ordered_float`] crate itself).
+///
+/// Note that if the expression does not need to be constant, this macro may not be
+/// needed; infallible construction can be written using `NotNan::from(an_integer)`,
+/// `NotNan::zero()`, and `NotNan::one()`.
+///
+/// ```
+/// # extern crate all_is_cubes_base as all_is_cubes;
+/// use all_is_cubes::{notnan, math::NotNan};
+///
+/// const X: NotNan<f32> = notnan!(1.234);
+/// ```
+///
+/// ```compile_fail
+/// # extern crate all_is_cubes_base as all_is_cubes;
+/// # use all_is_cubes::{notnan, math::NotNan};
+/// // Not a literal; will not compile
+/// const X: NotNan<f32> = notnan!(f32::NAN);
+/// ```
+///
+/// ```compile_fail
+/// # extern crate all_is_cubes_base as all_is_cubes;
+/// # use all_is_cubes::{notnan, math::NotNan};
+/// // Not a literal; will not compile
+/// const X: NotNan<f32> = notnan!(0.0 / 0.0);
+/// ```
+///
+/// ```compile_fail
+/// # extern crate all_is_cubes_base as all_is_cubes;
+/// # use all_is_cubes::{notnan, math::NotNan};
+/// const N0N: f32 = f32::NAN;
+/// // Not a literal; will not compile
+/// const X: NotNan<f32> = notnan!(N0N);
+/// ```
+///
+/// ```compile_fail
+/// # extern crate all_is_cubes_base as all_is_cubes;
+/// # use all_is_cubes::{notnan, math::NotNan};
+/// // Not a float; will not compile
+/// const X: NotNan<char> = notnan!('a');
+/// ```
+#[doc(hidden)]
+#[macro_export] // used by all-is-cubes-content
+macro_rules! notnan {
+    ($value:literal) => {
+        match $value {
+            value => {
+                // Safety: Only literal values are allowed, which will either be a non-NaN
+                // float or (as checked below) a type mismatch.
+                let result = unsafe { $crate::math::NotNan::new_unchecked(value) };
+
+                // Ensure that the type is one which could have resulted from a float literal,
+                // by requiring type unification with a literal. This prohibits char, &str, etc.
+                let _ = if false {
+                    // Safety: Statically never NaN, and is also never executed.
+                    unsafe { $crate::math::NotNan::new_unchecked(0.0) }
+                } else {
+                    result
+                };
+
+                result
+            }
+        }
+    };
+}
+
+/// Sort exactly two items; swap them if `a > b`.
+#[inline]
+#[doc(hidden)]
+pub fn sort_two<T: PartialOrd>(a: &mut T, b: &mut T) {
+    if *a > *b {
+        core::mem::swap(a, b);
+    }
+}
+
+/// Common features of objects that have a location and shape in space.
+pub trait Geometry {
+    /// Type of coordinates; generally determines whether this object can be translated by a
+    /// non-integer amount.
+    type Coord;
+
+    /// Translate (move) this object by the specified offset.
+    #[must_use]
+    fn translate(self, offset: Vector3D<Self::Coord, Cube>) -> Self;
+
+    /// Represent this object as a line drawing, or wireframe.
+    ///
+    /// The generated points should be in pairs, each pair defining a line segment.
+    /// If there are an odd number of vertices, the caller should ignore the last.
+    ///
+    /// TODO: This should probably return an iterator instead, but defining the type
+    /// will be awkward until `type_alias_impl_trait` is stable.
+    fn wireframe_points<E>(&self, output: &mut E)
+    where
+        E: Extend<LineVertex>;
+}
+
+/// One end of a line to be drawn.
+///
+/// Mostly used for debugging visualizations and not for game content.
+///
+/// The primary way in which these are used is [`Geometry::wireframe_points()`].
+#[derive(Clone, Copy, Debug, PartialEq)]
+#[allow(clippy::exhaustive_structs)]
+pub struct LineVertex {
+    /// Position of the vertex.
+    pub position: FreePoint,
+
+    /// Color in which to draw the line.
+    ///
+    /// If [`None`], a color set by the context/parent should be used instead.
+    ///
+    /// If the ends of a line are different colors, color should be interpolated along
+    /// the line.
+    pub color: Option<Rgba>,
+}
+
+impl From<FreePoint> for LineVertex {
+    fn from(position: FreePoint) -> Self {
+        Self {
+            position,
+            color: None,
+        }
+    }
+}