Struct VoxelsChunkRef

pub struct VoxelsChunkRef<'a> {
    pub my_id: usize,
    pub parent: &'a Voxels,
    pub states: &'a [VoxelState; 256],
    pub key: &'a Point<i32>,
}

A reference to a chunk of voxels within a Voxels shape.

What is a Chunk?

To efficiently manage large voxel worlds, Parry internally divides the voxel grid into fixed-size chunks. Each chunk contains a small region of voxels (e.g., 8×8×8 in 3D or 16×16 in 2D). This chunking provides:

• Spatial acceleration: Quick queries using a BVH of chunks
• Memory efficiency: Empty chunks are not stored
• Cache locality: Nearby voxels are stored together

A VoxelsChunkRef provides read-only access to a single chunk’s data, allowing you to query voxels within that chunk without iterating through the entire voxel shape.

When to Use

You typically don’t create VoxelsChunkRef directly. Instead, you get them from:

• Voxels::chunk_ref: Get a specific chunk by ID
• BVH traversal for spatial queries on large voxel worlds

Examples

use parry3d::shape::Voxels;
use nalgebra::{Point3, Vector3};

let voxels = Voxels::new(
    Vector3::new(1.0, 1.0, 1.0),
    &[Point3::new(0, 0, 0), Point3::new(1, 0, 0)],
);

// Get a chunk reference (chunk IDs come from BVH traversal)
let chunk_ref = voxels.chunk_ref(0);

// Query voxels within this chunk
for voxel in chunk_ref.voxels() {
    if !voxel.state.is_empty() {
        println!("Voxel at {:?}", voxel.grid_coords);
    }
}

// Get chunk's AABB
let aabb = chunk_ref.local_aabb();
println!("Chunk bounds: {:?}", aabb);

Fields

my_id: usize

The linear index of this chunk within the Voxels shape.

parent: &'a Voxels

The voxel shape this chunk is part of.

states: &'a [VoxelState; 256]

The fill status of each voxel from this chunk.

key: &'a Point<i32>

The spatial index of this chunk.

Implementations

impl<'a> VoxelsChunkRef<'a>

pub fn local_aabb(&self) -> Aabb

The AABB of this chunk of voxels.

Note that this return the AABB of the whole chunk, without taking into account the fact that some voxels are empty.

pub fn domain(&self) -> [Point<i32>; 2]

The domain of this chunk of voxels.

pub fn voxel_at_point_unchecked(&self, pt: Point<f32>) -> Point<i32>

Returns the spatial index of the voxel containing the given point.

pub fn voxel_state(&self, voxel_key: Point<i32>) -> Option<VoxelState>

The state of the voxel with key voxel_key.

pub fn clamp_voxel(&self, voxel_key: Point<i32>) -> Point<i32>

Clamps the voxel_key so it is within the bounds of self.

pub fn voxel_aabb_unchecked(&self, voxel_key: Point<i32>) -> Aabb

The AABB of the voxel with this key.

Returns a result even if the voxel doesn’t belong to this chunk.

pub fn flat_id(&self, voxel_key: Point<i32>) -> Option<u32>

Convert a voxel index (expressed relative to the main Voxels shape, not relative to the chunk alone) into a flat index within a voxel chunk.

Returns None if the voxel isn’t part of this chunk.

pub fn voxels(&self) -> impl Iterator<Item = VoxelData> + '_

Iterates through all the voxels in this chunk.

Note that this only yields non-empty voxels within the range. This does not include any voxel that falls outside Self::domain.

pub fn voxels_in_range( self, mins: Point<i32>, maxs: Point<i32>, ) -> impl Iterator<Item = VoxelData> + use<'a>

Iterate through the data of all the voxels within the given (semi-open) voxel grid indices.

Note that this only yields non-empty voxels within the range. This does not include any voxel that falls outside Self::domain.

Trait Implementations

impl<'a> Clone for VoxelsChunkRef<'a>

fn clone(&self) -> VoxelsChunkRef<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> RayCast for VoxelsChunkRef<'a>

fn cast_local_ray_and_get_normal( &self, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<RayIntersection>

Computes the time of impact, and normal between this transformed shape and a ray.

fn cast_local_ray( &self, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<f32>

Computes the time of impact between this transform shape and a ray.

fn intersects_local_ray(&self, ray: &Ray, max_time_of_impact: f32) -> bool

Tests whether a ray intersects this transformed shape.

fn cast_ray( &self, m: &Isometry<f32>, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<f32>

Computes the time of impact between this transform shape and a ray.

fn cast_ray_and_get_normal( &self, m: &Isometry<f32>, ray: &Ray, max_time_of_impact: f32, solid: bool, ) -> Option<RayIntersection>

Computes the time of impact, and normal between this transformed shape and a ray.

fn intersects_ray( &self, m: &Isometry<f32>, ray: &Ray, max_time_of_impact: f32, ) -> bool

Tests whether a ray intersects this transformed shape.

impl<'a> Copy for VoxelsChunkRef<'a>