Skip to content
This repository has been archived by the owner on Nov 13, 2023. It is now read-only.

building-blocks v0.4.1
Compare
Choose a tag to compare
@bonsairobo bonsairobo released this 14 Dec 07:33
· 955 commits to main since this release
v0.4.1
b5b08de

ChunkMap Refactor

This release has some exciting changes to the ChunkMap data structure!

ChunkReadStorage and ChunkWriteStorage

Before, we had a single kind of ChunkMap which forced users to adhere to the LRU caching and compression architecture used in the compressible-map crate. This was potentially cumbersome, especially if you were just getting started with the library and you didn't care about compression (yet).

Now the ChunkMap is generic over the chunk storage. This means you are free to customize how you would like to store you chunks by implementing the ChunkReadStorage and ChunkWriteStorage traits. But we also provide some useful default implementations.

The simplest is ChunkHashMap, which just uses a FnvHashMap for the chunk storage. It's quick and simple, but it doesn't provide any kind of compression. You can construct one using the ChunkMapBuilder::build_with_hash_map_storage method.

For more efficient memory usage, we also have the CompressibleChunkStorage. This is mostly a rewrite of the old CompressibleMap data structure to improve random access performance. The compressible-map dependency was removed and the code lifted into building_blocks_storage::chunk_map::storage.

The architecture is familiar: a top tier LruChunkCache stores uncompressed Chunks, while a bottom tier Slab stores the compressed Chunks. But now we only update the LRU order on insertion or an explicit touch_if_cached method. This made a dramatic improvement to random access performance.

In order to use the read-only access traits on a CompressibleChunkMap (a ChunkMap with CompressibleChunkStorage), you must construct a CompressibleChunkMapReader from a LocalChunkCache. This should be familiar. But now instead of having the reader contain a ChunkMap, the ChunkMap contains the reader as it's storage.

ChunkIndexer

Several methods like extent_for_chunk_at_key, chunk_keys_for_extent, chunk_key_containing_point, etc have moved from the ChunkMap to the ChunkIndexer. Every ChunkMap has a public indexer field.

ChunkMapBuilder

Now it's easier to construct ChunkMaps once you've established a chunk shape, ambient value, and default metadata. All of this data is captured by the ChunkMapBuilder, and you can call ChunkMapBuilder::build with any chunk storage in order to create a ChunkMap. This is especially useful for constructing a CompressibleChunkMapReader from a CompressibleChunkMap, since they will use the same builder.

Take a look at the updated docs for the chunk_map module to learn more.

New OctreeSet Node Traversal

By request, we've added some node-based traversal methods to the OctreeSet. The main use case is for traversing two octrees at the same time; visitors could not do this. So now you can use the root_node and get_child methods to manually traverse the tree.

Default Features

I finally figured out how to make features show up in docs.rs! The rule seems to be: docs.rs will only document default features. However, even if you re-export features from sub-crates in a top-level crate and make them default, that doesn't have any affect on what docs.rs does with the sub-crates (duh?). So I had to make sure every crate had the right default features for what I wanted in docs.rs. However, in order for users of the top-level crate to be able to disable those default features of sub-crates, I need the top-level crate to use default-features = false on all of the sub-crate dependencies.

Phew! TL;DR, you can still pick and choose only the features you want by using default-features = false in your Cargo.toml file, but all of the features will show up in docs.rs now.

Assets 2
Loading