Struct VoxelClip 

pub struct VoxelClip {
    pub dims: [u32; 3],
    pub pivot: [f32; 3],
    pub voxel_world_size: f32,
    pub loop_mode: LoopMode,
    pub default_frame_ms: u32,
    pub frames: Vec<EncodedFrame>,
    pub durations: Vec<u32>,
    pub extra_chunks: Vec<([u8; 4], Vec<u8>)>,
}

On-disk animated voxel clip. Construct via VoxelClip::from_frames (the encoder) or VoxelClip::parse; expand to a runtime flipbook via VoxelClip::decode.

Fields

dims: [u32; 3]

pivot: [f32; 3]

voxel_world_size: f32

loop_mode: LoopMode

default_frame_ms: u32

Frame duration used when durations is empty.

frames: Vec<EncodedFrame>

I/P frame stream. The first frame must be a Key.

durations: Vec<u32>

Per-frame durations (ms); empty ⇒ uniform default_frame_ms.

extra_chunks: Vec<([u8; 4], Vec<u8>)>

Unknown top-level chunks, preserved verbatim for forward-compat.

Implementations

impl VoxelClip

pub fn occ_words_per_col(&self) -> u32

u32 occupancy words per column for this clip.

pub fn frame_count(&self) -> usize

pub fn from_kv6_frames( frames: &[Kv6], voxel_world_size: f32, loop_mode: LoopMode, durations: &[u32], default_frame_ms: u32, keyframe_interval: u32, ) -> Result<VoxelClip, Kv6ImportError>

Build a clip from a sequence of .kv6 frames sharing one [xsiz, ysiz, zsiz] — the authoring path from animated voxel sprites to a .rvc clip. Each kv6 becomes a VoxelFrame via VoxelFrame::from_kv6, then the lot is encoded with VoxelClip::from_frames (frame 0 + every keyframe_interval-th a keyframe; 0 ⇒ only frame 0). The pivot comes from the first frame’s kv6; voxel_world_size is the render scale (.kv6 carries none). durations is per-frame ms (empty ⇒ uniform default_frame_ms).

Errors

Kv6ImportError::Empty if frames is empty; Kv6ImportError::DimsMismatch if any frame’s dims differ from the first (clips are fixed-bbox).

pub fn from_kv6_frames_auto( frames: &[Kv6], voxel_world_size: f32, loop_mode: LoopMode, durations: &[u32], default_frame_ms: u32, max_keyframe_gap: u32, ) -> Result<VoxelClip, Kv6ImportError>

Like from_kv6_frames but auto-chooses keyframe vs. delta per frame via from_frames_auto (VCL.1) — the turnkey “import .kv6 frames into a well-encoded clip” path. max_keyframe_gap caps keyframe spacing (0 = fully cost-driven).

Errors

Same as from_kv6_frames.

pub fn from_frames( dims: [u32; 3], pivot: [f32; 3], voxel_world_size: f32, loop_mode: LoopMode, frames: &[VoxelFrame], durations: &[u32], default_frame_ms: u32, keyframe_interval: u32, ) -> VoxelClip

Encode a sequence of full frames into a clip. Frame 0 (and every keyframe_interval-th frame) is stored as a keyframe; the rest are diffed against the previous frame. keyframe_interval == 0 ⇒ only frame 0 is a keyframe (smallest, but no mid-stream seek points).

durations is per-frame ms; pass an empty slice for uniform default_frame_ms.

Panics

If any frame fails VoxelFrame::validate for dims, or durations is non-empty but not frames.len() long.

pub fn from_frames_auto( dims: [u32; 3], pivot: [f32; 3], voxel_world_size: f32, loop_mode: LoopMode, frames: &[VoxelFrame], durations: &[u32], default_frame_ms: u32, max_keyframe_gap: u32, ) -> VoxelClip

Encode a sequence of full frames, auto-choosing keyframe vs. delta per frame (VCL.1) instead of a fixed interval — the codec’s I-frame decision. A frame is stored as a keyframe when its delta would be large (a “scene change”: at least [KEYFRAME_COST_PCT]% of the keyframe’s size — a delta that big is barely a saving and a keyframe is independently seekable), or when max_keyframe_gap frames have passed since the last keyframe (a seekability cap; 0 = no cap, fully cost-driven). Frame 0 is always a keyframe. Otherwise identical to from_frames.

Panics

Same as from_frames.

pub fn decode(&self) -> Result<DecodedClip, DecodeError>

Expand the I/P stream to full frames, compute per-frame dirs, and resolve durations — the runtime flipbook.

Errors

DecodeError::DeltaBeforeKey if the stream doesn’t start with a keyframe; DecodeError::ColumnOutOfRange if a delta names a column outside dims; DecodeError::Frame if a reconstructed frame fails validation.

pub fn serialize(&self) -> Vec<u8>

Serialise to the .rvc byte form. Round-trips byte-equally with VoxelClip::parse.

pub fn parse(bytes: &[u8]) -> Result<VoxelClip, ParseError>

Parse the .rvc byte form.

Errors

ParseError for a bad magic / unsupported version / truncation / missing required chunk / malformed frame stream.

Trait Implementations

impl Clone for VoxelClip

fn clone(&self) -> VoxelClip

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for VoxelClip

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

Formats the value using the given formatter.

impl PartialEq for VoxelClip

fn eq(&self, other: &VoxelClip) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for VoxelClip