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

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,
+        }
+    }
+}