Prepare 0.20 release (#201)

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+## 0.20.0
+
 ### HexLayout
 
 * (**BREAKING**) `HexLayout` Y axis is no longer inverted by default (#187)

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "hexx"
-version = "0.19.1"
+version = "0.20.0"
 edition = "2021"
 authors = ["Felix de Maneville <[email protected]>"]
 description = "Hexagonal utilities"

README.md

@@ -7,7 +7,7 @@
 [![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/)
 [![Crates.io](https://img.shields.io/crates/v/hexx.svg)](https://crates.io/crates/hexx)
 [![Docs.rs](https://docs.rs/hexx/badge.svg)](https://docs.rs/hexx)
-[![dependency status](https://deps.rs/crate/hexx/0.19.1/status.svg)](https://deps.rs/crate/hexx)
+[![dependency status](https://deps.rs/crate/hexx/0.20.0/status.svg)](https://deps.rs/crate/hexx)
 
 <!-- cargo-sync-readme start -->
 
@@ -23,8 +23,8 @@
  * Generate hexagon meshes (planes or columns)
 
  I made the choice to use *Axial Coordinates* for performance and utility
- reasons, but the [`Hex`] type has conversion utilities with *cubic*,
- *doubled*, *hexmod* and *offset* coordinates.
+ reasons, but the [`Hex`](https://docs.rs/hexx/latest/hexx/hex/struct.Hex.html) type has conversion utilities with
+ *cubic*, *doubled*, *hexmod* and *offset* coordinates.
 
  > See the [hexagonal coordinate systems](https://www.redblobgames.com/grids/hexagons/#coordinates)
 
@@ -33,38 +33,38 @@
  Run `cargo add hexx` in your project or add the following line to your
  `Cargo.toml`:
 
- * `hexx = "0.19"`
+ * `hexx = "0.20"`
 
  ### Cargo features
 
  `hexx` supports serialization and deserialization of most types using [serde](https://github.com/serde-rs/serde),
  through the `serde` feature gate. To enable it add the following line to
  your `Cargo.toml`:
 
- * `hexx = { version = "0.19", features = ["serde"] }`
+ * `hexx = { version = "0.20", features = ["serde"] }`
 
  By default `Hex` uses rust classic memory layout, if you want to use `hexx`
  through the FFI or have `Hex` be stored without any memory padding, the
  `packed` feature will make `Hex` `repr(C)`. To enable this behaviour add the
  following line to your `Cargo.toml`:
 
- * `hexx = { version = "0.19", features = ["packed"] }`
+ * `hexx = { version = "0.20", features = ["packed"] }`
 
  `hexx` supports [Bevy Reflection](https://docs.rs/bevy_reflect/latest/bevy_reflect)
  through the `bevy_reflect` feature. To enable it add the following line to
  your `Cargo.toml`:
 
- * `hexx = { version = "0.19", features = ["bevy_reflect"] }`
+ * `hexx = { version = "0.20", features = ["bevy_reflect"] }`
 
  `hexx` supports Face/Vertex/Edge [grid handling](https://www.redblobgames.com/grids/parts/#hexagon-coordinates)
  using `Hex` as Face, `GridVertex` as vertex and `GridEdge` as edge. To
  enable it add the following line to your `Cargo.toml`:
 
- * `hexx = { version = "0.19", features = ["grid"] }`
+ * `hexx = { version = "0.20", features = ["grid"] }`
 
  ## Features
 
- `hexx` provides the [`Hex`] coordinates with:
+ `hexx` provides the [`Hex`](https://docs.rs/hexx/latest/hexx/hex/struct.Hex.html) coordinates with:
 
  * Distances
  * Neighbors and directions
@@ -112,8 +112,8 @@
 
  ## Layout usage
 
- [`HexLayout`] is the bridge between your world/screen/pixel coordinate
- system and the hexagonal coordinates system.
+ [`HexLayout`](https://docs.rs/hexx/latest/hexx/layout/struct.HexLayout.html) is the bridge between your
+ world/screen/pixel coordinate system and the hexagonal coordinates system.
 
 ```rust
  use hexx::*;
@@ -134,9 +134,9 @@
 
  ## Wrapping
 
- [`HexBounds`] defines a bounding hexagon around a center coordinate.
- It can be used for boundary and interesection checks but also for wrapping
- coordinates.
+ [`HexBounds`](https://docs.rs/hexx/latest/hexx/bounds/struct.HexBounds.html) defines a bounding hexagon around a
+ center coordinate. It can be used for boundary and interesection checks but
+ also for wrapping coordinates.
  Coordinate wrapping transform a point outside of the bounds to a point
  inside. This allows for seamless or repeating [wraparound](https://www.redblobgames.com/grids/hexagons/#wraparound)
  maps.
@@ -155,7 +155,7 @@
 
  ## Resolutions and chunks
 
- [`Hex`] support multi-resolution coordinates.
+ [`Hex`](https://docs.rs/hexx/latest/hexx/hex/struct.Hex.html) support multi-resolution coordinates.
  In practice this means that you may convert a coordinate to a different
  resolution:
 
@@ -205,10 +205,33 @@
  An other usage could be to draw an infinite hex grid, with different
  resolutions displayed, dynamically changing according to user zoom level.
 
- ## Usage in [Bevy](https://bevyengine.org/)
+ ## Dense map storage
 
- If you want to generate 3D hexagonal mesh and use it in
- [bevy](bevyengine.org) you may do it this way:
+ [`Hex`](https://docs.rs/hexx/latest/hexx/hex/struct.Hex.html) implements `Hash`, and most users store hexagonal
+ maps in a `HashMap`. But for some cases `hexx` provides *dense storage*
+  [collections](https://docs.rs/hexx/latest/hexx/storage/) with more performant accessors:
+
+ - [`HexagonalMap<T>`](https://docs.rs/hexx/latest/hexx/storage/hexagonal/struct.HexagonalMap.html)
+ - [`RombusMap<T>`](https://docs.rs/hexx/latest/hexx/storage/rombus/struct.RombusMap.html)
+
+ ## Procedural meshes
+
+ `hexx` provides 3 built-in procedural mesh construction utilies:
+ - [`PlaneMeshBuilder`](https://docs.rs/hexx/latest/hexx/mesh/plane_builder/struct.PlaneMeshBuilder.html) for
+   hexagonal planes
+ - [`ColumnMeshBuilder`](https://docs.rs/hexx/latest/hexx/mesh/column_builder/struct.ColumnMeshBuilder.html)  for
+   hexagonal columns
+ - [`HeightMapMeshBuilder`](https://docs.rs/hexx/latest/hexx/mesh/heightmap_builder/struct.HeightMapMeshBuilder.html)
+   for hexagonal height maps
+
+ All those builders have a lot of customization options and will output a
+ [`MeshInfo`](https://docs.rs/hexx/latest/hexx/mesh/struct.MeshInfo.html) struct containing vertex positions,
+ normals and uvs
+
+ ### Usage in [Bevy](https://bevyengine.org/)
+
+ If you want to integrate the procedural meshes in [bevy](bevyengine.org) you
+ may do it this way:
 
 ```rust
  use bevy::{
@@ -233,9 +256,6 @@
  }
  ```
 
- The [`MeshInfo`] can be produced from [`PlaneMeshBuilder`],
- [`ColumnMeshBuilder`] or [`HeightMapMeshBuilder`]
-
 <!-- cargo-sync-readme end -->
 
 > See the [examples](examples) for bevy usage

src/lib.rs

@@ -10,8 +10,8 @@
 //! * Generate hexagon meshes (planes or columns)
 //!
 //! I made the choice to use *Axial Coordinates* for performance and utility
-//! reasons, but the [`Hex`] type has conversion utilities with *cubic*,
-//! *doubled*, *hexmod* and *offset* coordinates.
+//! reasons, but the [`Hex`](crate::hex::Hex) type has conversion utilities with
+//! *cubic*, *doubled*, *hexmod* and *offset* coordinates.
 //!
 //! > See the [hexagonal coordinate systems](https://www.redblobgames.com/grids/hexagons/#coordinates)
 //!
@@ -20,38 +20,38 @@
 //! Run `cargo add hexx` in your project or add the following line to your
 //! `Cargo.toml`:
 //!
-//! * `hexx = "0.19"`
+//! * `hexx = "0.20"`
 //!
 //! ### Cargo features
 //!
 //! `hexx` supports serialization and deserialization of most types using [serde](https://github.com/serde-rs/serde),
 //! through the `serde` feature gate. To enable it add the following line to
 //! your `Cargo.toml`:
 //!
-//! * `hexx = { version = "0.19", features = ["serde"] }`
+//! * `hexx = { version = "0.20", features = ["serde"] }`
 //!
 //! By default `Hex` uses rust classic memory layout, if you want to use `hexx`
 //! through the FFI or have `Hex` be stored without any memory padding, the
 //! `packed` feature will make `Hex` `repr(C)`. To enable this behaviour add the
 //! following line to your `Cargo.toml`:
 //!
-//! * `hexx = { version = "0.19", features = ["packed"] }`
+//! * `hexx = { version = "0.20", features = ["packed"] }`
 //!
 //! `hexx` supports [Bevy Reflection](https://docs.rs/bevy_reflect/latest/bevy_reflect)
 //! through the `bevy_reflect` feature. To enable it add the following line to
 //! your `Cargo.toml`:
 //!
-//! * `hexx = { version = "0.19", features = ["bevy_reflect"] }`
+//! * `hexx = { version = "0.20", features = ["bevy_reflect"] }`
 //!
 //! `hexx` supports Face/Vertex/Edge [grid handling](https://www.redblobgames.com/grids/parts/#hexagon-coordinates)
 //! using `Hex` as Face, `GridVertex` as vertex and `GridEdge` as edge. To
 //! enable it add the following line to your `Cargo.toml`:
 //!
-//! * `hexx = { version = "0.19", features = ["grid"] }`
+//! * `hexx = { version = "0.20", features = ["grid"] }`
 //!
 //! ## Features
 //!
-//! `hexx` provides the [`Hex`] coordinates with:
+//! `hexx` provides the [`Hex`](crate::hex::Hex) coordinates with:
 //!
 //! * Distances
 //! * Neighbors and directions
@@ -99,8 +99,8 @@
 //!
 //! ## Layout usage
 //!
-//! [`HexLayout`] is the bridge between your world/screen/pixel coordinate
-//! system and the hexagonal coordinates system.
+//! [`HexLayout`](crate::layout::HexLayout) is the bridge between your
+//! world/screen/pixel coordinate system and the hexagonal coordinates system.
 //!
 //!```rust
 //! use hexx::*;
@@ -121,9 +121,9 @@
 //!
 //! ## Wrapping
 //!
-//! [`HexBounds`] defines a bounding hexagon around a center coordinate.
-//! It can be used for boundary and interesection checks but also for wrapping
-//! coordinates.
+//! [`HexBounds`](crate::bounds::HexBounds) defines a bounding hexagon around a
+//! center coordinate. It can be used for boundary and interesection checks but
+//! also for wrapping coordinates.
 //! Coordinate wrapping transform a point outside of the bounds to a point
 //! inside. This allows for seamless or repeating [wraparound](https://www.redblobgames.com/grids/hexagons/#wraparound)
 //! maps.
@@ -142,7 +142,7 @@
 //!
 //! ## Resolutions and chunks
 //!
-//! [`Hex`] support multi-resolution coordinates.
+//! [`Hex`](crate::hex::Hex) support multi-resolution coordinates.
 //! In practice this means that you may convert a coordinate to a different
 //! resolution:
 //!
@@ -192,10 +192,33 @@
 //! An other usage could be to draw an infinite hex grid, with different
 //! resolutions displayed, dynamically changing according to user zoom level.
 //!
-//! ## Usage in [Bevy](https://bevyengine.org/)
+//! ## Dense map storage
 //!
-//! If you want to generate 3D hexagonal mesh and use it in
-//! [bevy](bevyengine.org) you may do it this way:
+//! [`Hex`](crate::hex::Hex) implements `Hash`, and most users store hexagonal
+//! maps in a `HashMap`. But for some cases `hexx` provides *dense storage*
+//!  [collections](crate::storage) with more performant accessors:
+//!
+//! - [`HexagonalMap<T>`](crate::storage::hexagonal::HexagonalMap)
+//! - [`RombusMap<T>`](crate::storage::rombus::RombusMap)
+//!
+//! ## Procedural meshes
+//!
+//! `hexx` provides 3 built-in procedural mesh construction utilies:
+//! - [`PlaneMeshBuilder`](crate::mesh::plane_builder::PlaneMeshBuilder) for
+//!   hexagonal planes
+//! - [`ColumnMeshBuilder`](crate::mesh::column_builder::ColumnMeshBuilder)  for
+//!   hexagonal columns
+//! - [`HeightMapMeshBuilder`](crate::mesh::heightmap_builder::HeightMapMeshBuilder)
+//!   for hexagonal height maps
+//!
+//! All those builders have a lot of customization options and will output a
+//! [`MeshInfo`](crate::mesh::MeshInfo) struct containing vertex positions,
+//! normals and uvs
+//!
+//! ### Usage in [Bevy](https://bevyengine.org/)
+//!
+//! If you want to integrate the procedural meshes in [bevy](bevyengine.org) you
+//! may do it this way:
 //!
 //!```rust
 //! use bevy::{
@@ -219,9 +242,6 @@
 //!     .with_inserted_indices(Indices::U16(mesh_info.indices))
 //! }
 //! ```
-//!
-//! The [`MeshInfo`] can be produced from [`PlaneMeshBuilder`],
-//! [`ColumnMeshBuilder`] or [`HeightMapMeshBuilder`]
 #![forbid(unsafe_code)]
 #![warn(
     clippy::nursery,
@@ -233,6 +253,8 @@
     future_incompatible
 )]
 #![allow(clippy::module_name_repetitions, clippy::multiple_crate_versions)]
+// For lib.rs docs only
+#![allow(rustdoc::redundant_explicit_links)]
 /// Non exhaustive collection of classic algorithms.
 #[cfg(feature = "algorithms")]
 pub mod algorithms;

src/mesh/mod.rs

@@ -1,8 +1,8 @@
-mod column_builder;
+pub(crate) mod column_builder;
 /// Utility module for mesh construction
 pub mod face;
-mod heightmap_builder;
-mod plane_builder;
+pub(crate) mod heightmap_builder;
+pub(crate) mod plane_builder;
 #[cfg(test)]
 mod tests;
 mod uv_mapping;

src/storage/mod.rs

@@ -6,8 +6,8 @@
 //! * [`RombusMap`] is up to ~100x faster than a hash map
 //!
 //! [this article]: https://www.redblobgames.com/grids/hexagons/#map-storage
-mod hexagonal;
-mod rombus;
+pub(crate) mod hexagonal;
+pub(crate) mod rombus;
 
 pub use hexagonal::HexagonalMap;
 pub use rombus::RombusMap;