Building Blocks is a voxel library for real-time applications.
The primary focus is core data structures and algorithms. Features include:
- memory-efficient storage of voxel maps
- a
ChunkMap
with generic chunk storage - LRU-cached storage of compressed chunks
- compressed serialization format
OctreeSet
bitset structure
- a
- mesh generation
- isosurface
- cubic / blocky
- height map
- accelerated spatial queries
- ray casting and sphere casting
- range queries
- procedural generation
- sampling signed distance fields
- constructive solid geometry (TODO)
- pathfinding on voxel maps
The code below samples a signed distance field and generates a mesh from it.
use building_blocks::{
prelude::*,
mesh::{SurfaceNetsBuffer, surface_nets},
procgen::signed_distance_fields::sphere,
};
let center = PointN([25.0; 3]);
let radius = 10.0;
let sphere_sdf = sphere(center, radius);
let extent = Extent3i::from_min_and_shape(PointN([0; 3]), PointN([50; 3]));
let mut samples = Array3::fill_with(extent, &sphere_sdf);
let mut mesh_buffer = SurfaceNetsBuffer::default();
surface_nets(&samples, samples.extent(), &mut mesh_buffer);
The current best way to learn about the library is to read the documentation and examples. For the latest stable docs, look here. For the latest unstable docs, clone the repo and run
cargo doc --open
There is plentiful documentation with examples. Take a look in the examples/
directory to see how Building Blocks can be
used in real applications.
This library is organized into several crates. The most fundamental are:
- core: lattice point and extent data types
- storage: storage for lattice maps, i.e. functions defined on
Z^2
andZ^3
Then you get extra bits of functionality from the others:
- mesh: 3D mesh generation algorithms
- procgen: procedural generation of lattice maps
- search: search algorithms on lattice maps
To learn the basics about lattice maps, start with these doc pages:
To run the benchmarks (using the "criterion" crate), go to the root of a crate and run cargo bench
.
It is highly recommended that you enable link-time optimization when using building-blocks. It will improve the performance of critical algorithms like meshing by up to 2x. Just add this to your Cargo.toml:
[profile.release]
lto = true
Building Blocks is organized into several crates, some of which are hidden behind features, and some have features themselves, which get re-exported by the top-level crate.
The PointN
types have conversions to/from glam
, nalgebra
, and mint
types by enabling the corresponding feature.
Chunk compression supports two backends out of the box: Lz4
and Snappy
. They are enabled with the "lz4" and "snappy"
features. "lz4" is the default, but it relies on a C++ library, so it's not compatible with WASM. But Snappy is pure Rust,
so it can! Just use default-features = false
and add "snappy" to you features
list, like so:
[dependencies.building-blocks]
version = "0.4.1"
default-features = false
features = ["snappy"]
".VOX" files are supported via the dot_vox
crate. Enable the dot_vox
feature to expose the generic encode_vox
function
and Array3::decode_vox
constructor.
Arrays can be converted to ImageBuffer
s and constructed from GenericImageView
s from the images
crate. Enable the
images
feature to expose the generic encode_image
function and From<Im> where Im: GenericImageView
impl.
We prioritize work according to the project board.
If you'd like to make a contribution, please first read the design philosophy and contribution guidelines.
License: MIT