Struct Chunk 

pub struct Chunk<V, S: VolSize, M> {
    indices: Vec<u8>,
    vox: Vec<V>,
    default: V,
    meta: M,
    phantom: PhantomData<S>,
}

The volume is spatially subdivided into groups of 4*4*4 blocks. Since a Chunk is of total size 32*32*16, this implies that there are 8*8*4 groups. (These numbers are generic in the actual code such that there are always 256 groups. I.e. the group size is chosen depending on the desired total size of the Chunk.)

There’s a single vector self.vox which consecutively stores these groups. Each group might or might not be contained in self.vox. A group that is not contained represents that the full group consists only of self.default voxels. This saves a lot of memory because oftentimes a Chunk consists of either a lot of air or a lot of stone.

To track whether a group is contained in self.vox, there’s an index buffer self.indices : [u8; 256]. It contains for each group

• (a) the order in which it has been inserted into self.vox, if the group is contained in self.vox or
• (b) 255, otherwise. That case represents that the whole group consists only of self.default voxels.

(Note that 255 is a valid insertion order for case (a) only if self.vox is full and then no other group has the index 255. Therefore there’s no ambiguity.)

Rationale:

The index buffer should be small because:

• Small size increases the probability that it will always be in cache.
• The index buffer is allocated for every Chunk and an almost empty Chunk shall not consume too much memory.

The number of 256 groups is particularly nice because it means that the index buffer can consist of u8s. This keeps the space requirement for the index buffer as low as 4 cache lines.

Fields

indices: Vec<u8>

vox: Vec<V>

default: V

meta: M

phantom: PhantomData<S>

Implementations

impl<V, S: VolSize, M> Chunk<V, S, M>

pub const GROUP_COUNT: Vec3<u32>

const GROUP_COUNT_TOTAL: u32

GROUP_COUNT_TOTAL is always 256, except if VOLUME < 256

const GROUP_LONG_SIDE_LEN: u32

const GROUP_SIZE: Vec3<u32>

const GROUP_VOLUME: u32

const VOLUME: u32

pub fn filled(default: V, meta: M) -> Self

Creates a new Chunk with the provided dimensions and all voxels filled with duplicates of the provided voxel.

pub fn defragment(&mut self)

where V: Clone + Eq + Hash,

Compress this subchunk by frequency.

pub fn metadata(&self) -> &M

Get a reference to the internal metadata.

pub fn metadata_mut(&mut self) -> &mut M

Get a mutable reference to the internal metadata.

pub fn num_groups(&self) -> usize

pub fn homogeneous(&self) -> Option<&V>

Returns Some(v) if the block is homogeneous and contains nothing but voxels of value v, and None otherwise. This method is conservative (it may return None when the chunk is actually homogeneous) unless called immediately after defragment.

fn grp_idx(pos: Vec3<i32>) -> u32

fn rel_idx(pos: Vec3<i32>) -> u32

fn idx_unchecked(&self, pos: Vec3<i32>) -> Option<usize>

fn force_idx_unchecked(&mut self, pos: Vec3<i32>) -> usize

where V: Clone,

fn get_unchecked(&self, pos: Vec3<i32>) -> &V

fn set_unchecked(&mut self, pos: Vec3<i32>, vox: V) -> V

where V: Clone + PartialEq,

impl<V, S: VolSize, M> Chunk<V, S, M>

pub fn pos_iter( lower_bound: Vec3<i32>, upper_bound: Vec3<i32>, ) -> ChunkPosIter<V, S, M>

It’s possible to obtain a positional iterator without having a Chunk instance.

Trait Implementations

impl<V, S: VolSize, M> BaseVol for Chunk<V, S, M>

type Error = ChunkError

type Vox = V

fn scaled_by(self, scale: Vec3<f32>) -> Scaled<Self>

where Self: Sized,

impl<V: Clone, S: Clone + VolSize, M: Clone> Clone for Chunk<V, S, M>

fn clone(&self) -> Chunk<V, S, M>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<V: Debug, S: Debug + VolSize, M: Debug> Debug for Chunk<V, S, M>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, V, S: VolSize, M> Deserialize<'de> for Chunk<V, S, M>

where V: Deserialize<'de>, M: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<V, S: VolSize, M> IntoPosIterator for &Chunk<V, S, M>

type IntoIter = ChunkPosIter<V, S, M>

fn pos_iter( self, lower_bound: Vec3<i32>, upper_bound: Vec3<i32>, ) -> Self::IntoIter

impl<'a, V, S: VolSize, M> IntoVolIterator<'a> for &'a Chunk<V, S, M>

type IntoIter = ChunkVolIter<'a, V, S, M>

fn vol_iter( self, lower_bound: Vec3<i32>, upper_bound: Vec3<i32>, ) -> Self::IntoIter

impl<V, S: VolSize, M> RasterableVol for Chunk<V, S, M>

const SIZE: Vec3<u32> = S::SIZE

impl<V, S: VolSize, M> ReadVol for Chunk<V, S, M>

fn get(&self, pos: Vec3<i32>) -> Result<&Self::Vox, Self::Error>

Get a reference to the voxel at the provided position in the volume.

fn get_unchecked(&self, pos: Vec3<i32>) -> &Self::Vox

Get a reference to the voxel at the provided position in the volume. Many volumes provide a fast path, provided the position is always in-bounds. Note that this function is still safe.

fn for_each_in(&self, aabb: Aabb<i32>, f: impl FnMut(Vec3<i32>, Self::Vox))

where Self::Vox: Copy,

Call provided closure with each block in the supplied Aabb Portions of the Aabb outside the volume are ignored

fn ray( &self, from: Vec3<f32>, to: Vec3<f32>, ) -> Ray<'_, Self, fn(&Self::Vox) -> bool, fn(&Self::Vox, Vec3<i32>)>

where Self: Sized,

NOTE: By default, this ray will simply run from from to to without stopping. To make something interesting happen, call until or for_each.

impl<V, S: VolSize, M> Serialize for Chunk<V, S, M>

where V: Serialize, M: Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<V: Clone + PartialEq, S: VolSize, M> WriteVol for Chunk<V, S, M>

fn set( &mut self, pos: Vec3<i32>, vox: Self::Vox, ) -> Result<Self::Vox, Self::Error>

Set the voxel at the provided position in the volume to the provided value.

fn map<F: FnOnce(Self::Vox) -> Self::Vox>( &mut self, pos: Vec3<i32>, f: F, ) -> Result<Self::Vox, Self::Error>

where Self: ReadVol, Self::Vox: Clone,

Map a voxel to another using the provided function.