Skip to main content

qualia_core_db/container_10d/skeletal_section/
mod.rs

1//! SKL1: versioned rigid rigs, four-weight vertex skins and named motor clips.
2//! Stable joint/clip IDs use the engine's q_hash identity domain. All records
3//! are little endian; decoding validates the entire payload before writes.
4
5mod binary;
6pub mod skl2;
7mod validation;
8use crate::render::skeletal::{Clip, Joint, Key, SkinWeight, Track};
9pub use binary::{encode_skeletal_section_into, SkeletalSection};
10pub use skl2::{
11    ActuationPathwayRecord, EpistemicProvenanceWord, KinematicSolverRegime,
12    LoopClosureConstraintRecord, SkeletalSectionPayload, Skl2JointDescriptorV1,
13    Skl2JointDescriptorV2, Ssm1BasisHeader, Ssm1ModeWeight, SwingTwistConeLimits,
14    TopologicalLandmarkRecord, SKL2_HEADER_LEN, SKL2_JOINT_FLAG_EXOSKELETAL,
15    SKL2_JOINT_FLAG_HYDROSTATIC, SKL2_JOINT_FLAG_LOOP_ANCHOR, SKL2_JOINT_FLAG_SYMMETRIC,
16    SKL2_JOINT_FLAG_VESTIGIAL, SKL2_MAGIC, SKL2_MAX_CONTAINER_BYTES, SKL2_MAX_JOINTS,
17    SKL2_NONE_INDEX, SKL2_VERSION_1, SKL2_VERSION_2, SSM1_MAGIC,
18};
19
20pub const MAX_CLIPS: usize = 32;
21pub const MAX_TRACKS: usize = 4096;
22pub const HEADER_BYTES: usize = 32;
23pub const JOINT_BYTES: usize = 144;
24pub const CLIP_BYTES: usize = 32;
25pub const TRACK_BYTES: usize = 8;
26pub const KEY_BYTES: usize = 72;
27pub const SKIN_BYTES: usize = 24;
28
29#[derive(Debug, Clone, Copy, PartialEq, Eq)]
30pub enum SkeletalSectionError {
31    Header,
32    CountLimit,
33    Length,
34    InvalidData,
35    OutputTooSmall,
36}
37
38#[derive(Debug, Clone, Copy)]
39pub struct ClipRecord {
40    pub id: u64,
41    pub duration: f64,
42    pub first_track: u32,
43    pub track_count: u32,
44    pub looping: bool,
45}
46
47#[derive(Debug, Clone, Copy, PartialEq, Eq)]
48pub struct Counts {
49    pub joints: usize,
50    pub vertices: usize,
51    pub clips: usize,
52    pub tracks: usize,
53    pub keys: usize,
54}
55
56impl Counts {
57    /// `encoded` length.
58    pub fn encoded_len(self) -> Option<usize> {
59        use crate::render::skeletal::{MAX_JOINTS, MAX_KEYS, MAX_VERTICES};
60        if self.joints == 0
61            || self.joints > MAX_JOINTS
62            || self.vertices == 0
63            || self.vertices > MAX_VERTICES
64            || self.clips == 0
65            || self.clips > MAX_CLIPS
66            || self.tracks == 0
67            || self.tracks > MAX_TRACKS
68            || self.keys == 0
69            || self.keys > MAX_KEYS
70        {
71            return None;
72        }
73        Some(
74            HEADER_BYTES
75                + self.joints * JOINT_BYTES
76                + self.clips * CLIP_BYTES
77                + self.tracks * TRACK_BYTES
78                + self.keys * KEY_BYTES
79                + self.vertices * SKIN_BYTES,
80        )
81    }
82}
83
84pub struct SkeletalData<'a> {
85    pub joints: &'a [Joint],
86    pub joint_ids: &'a [u64],
87    pub skin: &'a [SkinWeight],
88    pub clips: &'a [ClipRecord],
89    pub tracks: &'a [Track],
90    pub keys: &'a [Key],
91}
92
93pub(crate) trait Records {
94    fn counts(&self) -> Counts;
95    fn joint(&self, i: usize) -> Joint;
96    fn joint_id(&self, i: usize) -> u64;
97    fn clip(&self, i: usize) -> ClipRecord;
98    fn track(&self, i: usize) -> Track;
99    fn key(&self, i: usize) -> Key;
100    fn skin(&self, i: usize) -> SkinWeight;
101}
102impl Records for SkeletalData<'_> {
103    fn counts(&self) -> Counts {
104        Counts {
105            joints: self.joints.len(),
106            vertices: self.skin.len(),
107            clips: self.clips.len(),
108            tracks: self.tracks.len(),
109            keys: self.keys.len(),
110        }
111    }
112    fn joint(&self, i: usize) -> Joint {
113        self.joints[i]
114    }
115    fn joint_id(&self, i: usize) -> u64 {
116        self.joint_ids[i]
117    }
118    fn clip(&self, i: usize) -> ClipRecord {
119        self.clips[i]
120    }
121    fn track(&self, i: usize) -> Track {
122        self.tracks[i]
123    }
124    fn key(&self, i: usize) -> Key {
125        self.keys[i]
126    }
127    fn skin(&self, i: usize) -> SkinWeight {
128        self.skin[i]
129    }
130}
131
132/// Build a runtime view after loading the section into caller-owned arrays.
133pub fn clip_view<'a>(record: ClipRecord, tracks: &'a [Track], keys: &'a [Key]) -> Option<Clip<'a>> {
134    let end = (record.first_track as usize).checked_add(record.track_count as usize)?;
135    Some(Clip {
136        duration: record.duration,
137        looping: record.looping,
138        tracks: tracks.get(record.first_track as usize..end)?,
139        keys,
140    })
141}
142
143#[cfg(test)]
144mod tests;