Struct building_blocks_storage::chunk_map::ChunkMap

pub struct ChunkMap<N, T, M = ()> where
    T: Copy,
    M: Clone,
    ExtentN<N>: IntegerExtent<N>,  {
    pub chunks: CompressibleMap<PointN<N>, Chunk<N, T, M>, FastLz4, FnvBuildHasher>,
    // some fields omitted
}

Stores a partial (sparse) function on the N-dimensional integers (where N=2 or N=3) in same-shaped chunks using a CompressibleMap. The data can either be addressed by chunk with the get_chunk* methods or by individual points using the Get* and ForEach* trait impls.

The map of chunks uses Point3i keys. The key for a chunk is the minimum point in that chunk. Chunk dimensions must be powers of 2, which allows for efficiently calculating a chunk key from any point in the chunk.

Because chunks are either cached or compressed, accesses should eventually mutate the cache. If you need to read from the map without mutating it, the const get_chunk* methods take a LocalChunkCache. To read individual points, you can use the ChunkMapReader, which also uses a LocalChunkCache. A LocalChunkCache can be written back to the ChunkMap using the flush_chunk_cache method.

Fields

chunks: CompressibleMap<PointN<N>, Chunk<N, T, M>, FastLz4, FnvBuildHasher>

The chunks themselves, stored in a CompressibleMap.

SAFETY: Don't modify this directly unless you know what you're doing.

Implementations

impl<N, T, M> ChunkMap<N, T, M> where
    T: Copy,
    M: Clone,
    PointN<N>: IntegerPoint + ChunkShape<N> + Eq + Hash,
    ExtentN<N>: IntegerExtent<N>, 

pub fn new(
    chunk_shape: PointN<N>,
    ambient_value: T,
    default_chunk_metadata: M,
    compression_params: FastLz4
) -> Self

Creates an empty map.

All dimensions of chunk_shape must be powers of 2.

pub fn chunk_shape(&self) -> &PointN<N>

The constant shape of a chunk. The same for all chunks.

pub fn chunk_shape_mask(&self) -> &PointN<N>

The mask used for calculating the chunk key of a chunk that contains a given point.

pub fn chunk_key_containing_point(&self, point: &PointN<N>) -> PointN<N>

Returns the key of the chunk that contains point.

pub fn chunk_keys_for_extent(
    &self,
    extent: &ExtentN<N>
) -> impl Iterator<Item = PointN<N>>

Returns an iterator over all chunk keys for chunks that overlap the given extent.

pub fn extent_for_chunk_at_key(&self, key: &PointN<N>) -> ExtentN<N>

The extent spanned by the chunk at key.

pub fn get_chunk<'a>(
    &'a self,
    key: PointN<N>,
    local_cache: &'a LocalChunkCache<N, T, M>
) -> Option<&Chunk<N, T, M>>

Returns the chunk at key if it exists.

pub fn get_mut_chunk(&mut self, key: PointN<N>) -> Option<&mut Chunk<N, T, M>>

Returns the mutable chunk at key if it exists.

pub fn get_mut_chunk_or_insert_with(
    &mut self,
    key: PointN<N>,
    create_chunk: impl Fn(&PointN<N>, &ExtentN<N>) -> Chunk<N, T, M>
) -> &mut Chunk<N, T, M>

Get mutable chunk for key. If key does not exist, calls fill_empty_chunk to fill that entry first.

pub fn get_chunk_containing_point<'a>(
    &'a self,
    point: &PointN<N>,
    local_cache: &'a LocalChunkCache<N, T, M>
) -> Option<(PointN<N>, &Chunk<N, T, M>)>

Returns the chunk containing point if it exists.

pub fn get_mut_chunk_containing_point(
    &mut self,
    point: &PointN<N>
) -> Option<(PointN<N>, &mut Chunk<N, T, M>)>

Returns the mutable chunk containing point if it exists.

pub fn chunk_keys(&self) -> impl Iterator<Item = &PointN<N>>

An iterator over all occupied chunk keys.

pub fn bounding_extent(&self) -> ExtentN<N>

The smallest extent that bounds all chunks.

pub fn get_mut_or_insert_chunk_with(
    &mut self,
    p: &PointN<N>,
    create_chunk: impl Fn(&PointN<N>, &ExtentN<N>) -> Chunk<N, T, M>
) -> (PointN<N>, &mut T) where
    ArrayN<N, T>: Array<N>, 

Get mutable data for point p. If p does not exist, calls fill_empty_chunk to fill that entry first.

pub fn get_mut_and_key(&mut self, p: &PointN<N>) -> (PointN<N>, &mut T) where
    ArrayN<N, T>: Array<N>, 

Sets point p to value T. If p is in a chunk that doesn't exist yet, then the chunk will first be filled with the ambient value and default metadata.

pub fn compress_lru_chunk(&mut self)

Compressed the least-recently-used chunk using LZ4 compression. On access, compressed chunks will be decompressed and cached.

pub fn flush_chunk_cache(&mut self, local_cache: LocalChunkCache<N, T, M>)

Consumes and flushes the chunk cache into the chunk map. This is not strictly necessary, but it will help with caching efficiency.

pub async fn to_serializable<'_>(
    &'_ self,
    params: BincodeLz4
) -> SerializableChunkMap<N, T, M> where
    Chunk<N, T, M>: DeserializeOwned + Serialize, 

Returns a serializable version of this map. This will compress every chunk in a portable way.

pub async fn from_serializable<'_>(
    map: &'_ SerializableChunkMap<N, T, M>,
    params: FastLz4
) -> Self where
    Chunk<N, T, M>: DeserializeOwned + Serialize, 

Returns a new map from the serialized, compressed version. This will decompress each chunk and compress it again, but in a faster format.

impl<N, T, M> ChunkMap<N, T, M> where
    Self: ForEachMut<N, PointN<N>, Data = T>,
    T: Copy,
    M: Clone,
    PointN<N>: IntegerPoint + ChunkShape<N> + Eq + Hash,
    ExtentN<N>: IntegerExtent<N>, 

pub fn fill_extent(&mut self, extent: &ExtentN<N>, value: T)

Trait Implementations

impl<'a, N, T, M> ForEachMut<N, PointN<N>> for ChunkMap<N, T, M> where
    T: Copy,
    M: Clone,
    PointN<N>: Point + ChunkShape<N> + Eq + Hash,
    ExtentN<N>: IntegerExtent<N>,
    ArrayN<N, T>: ForEachMut<N, PointN<N>, Data = T>, 

type Data = T

fn for_each_mut(
    &mut self,
    extent: &ExtentN<N>,
    f: impl FnMut(PointN<N>, &mut Self::Data)
)

impl<N, T, M, '_> GetMut<&'_ PointN<N>> for ChunkMap<N, T, M> where
    T: Copy,
    M: Clone,
    PointN<N>: IntegerPoint + ChunkShape<N> + Eq + Hash,
    ExtentN<N>: IntegerExtent<N>,
    ArrayN<N, T>: Array<N>, 

type Data = T

fn get_mut(&mut self, p: &PointN<N>) -> &mut T

Get a mutable reference to the value at location.

impl<'a, N, T, M, Src> WriteExtent<N, Src> for ChunkMap<N, T, M> where
    T: Copy,
    M: Clone,
    Src: Copy,
    PointN<N>: Point + Eq + Hash,
    ExtentN<N>: IntegerExtent<N>,
    ArrayN<N, T>: WriteExtent<N, Src>, 

fn write_extent(&mut self, extent: &ExtentN<N>, src: Src)