Giter Site home page Giter Site logo

building-blocks's Introduction

building-blocks

Crates.io Docs.rs license Crates.io Discord

Building Blocks is a voxel library for real-time applications.

LOD Terrain

We focus on generally useful data structures and algorithms. Features include:

  • 2D and 3D data storage
    • Array with structure-of-arrays (SoA) storage of multiple data channels per spatial dimension
    • ChunkMap with generic chunk storage
    • ChunkDb for compressed, persistent voxel worlds, backed by the sled embedded database
    • OctreeSet hierarchical bitset of voxel points
  • level of detail
    • ChunkMap can downsample chunks into lower resolutions within the same storage
    • dynamic 3D clipmap for keeping high detail close to a focal point
  • mesh generation
    • Surface Nets isosurface extraction (TODO: multiresolution)
    • Minecraft-style greedy meshing
    • height maps
  • spatial queries
    • ray and ball casting against octrees with ncollide3d
    • Amanatides and Woo ray grid traversal
    • pathfinding
  • procedural generation
    • sampling signed distance fields
    • constructive solid geometry with sdfu

Short Code Example

The code below samples a signed distance field and generates a mesh from it.

use building_blocks::{
    core::sdfu::{Sphere, SDF},
    prelude::*,
    mesh::{SurfaceNetsBuffer, surface_nets},
};

let center = Point3f::fill(25.0);
let radius = 10.0;
let sphere_sdf = Sphere::new(radius).translate(center);

let extent = Extent3i::from_min_and_shape(Point3i::ZERO, Point3i::fill(50));
let mut samples = Array3x1::fill_with(extent, |p| sphere_sdf.dist(Point3f::from(p)));

let mut mesh_buffer = SurfaceNetsBuffer::default();
let voxel_size = 2.0; // length of the edge of a voxel
let estimate_normals = true; // use the SDF to estimate normals instead of flat shading
surface_nets(&samples, samples.extent(), voxel_size, estimate_normals, &mut mesh_buffer);

Learning

Design and Architecture

There is a terse design doc that gives an overview of design decisions made concerning the current architecture. You might find this useful as a high-level summary of the most important pieces of code.

Docs and Examples

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.

Getting Started

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 and Z^3

Then you get extra bits of functionality from the others:

  • mesh: 3D mesh generation algorithms
  • search: search algorithms on lattice maps

To learn the basics about lattice maps, start with these doc pages:

Benchmarks

To run the benchmarks (using the "criterion" crate), go to the root of a crate and run cargo bench. As of version 0.5.0, all benchmark results are posted in the release notes.

Configuration

LTO

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 = "thin"

Cargo Features

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. Some features are enabled by default. You can avoid taking unnecessary dependencies by declaring default-features = false in your Cargo.toml:

[dependencies.building-blocks]
version = "0.7"
default-features = false
features = ["foo", "bar"]

Math Type Conversions

The PointN types have conversions to/from glam, nalgebra, and mint types by enabling the corresponding feature.

Compression Backends and WASM

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.

VOX Files

".VOX" files are supported via the vox-format crate. Enable the vox-format feature to get the VoxModelBuffer trait impl for Array3x1, which allows you to read VOX files directly into an array.

Images

Arrays can be converted to ImageBuffers and constructed from GenericImageViews from the image crate. Enable the image feature to expose the generic encode_image function and From<Im> where Im: GenericImageView impl.

Signed Distance Field Utilities (sdfu)

The sdfu crate provides convenient APIs for constructive solid geometry operations. By enabling this feature, the PointN types will implement the sdfu::mathtypes traits in order to be used with these APIs. The sdfu crate also gets exported under building_blocks::core::sdfu.

Development

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

building-blocks's People

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.