Skip to main content

qualia_core_db/container_10d/skeletal_section/
binary.rs

1use super::*;
2use crate::render::skeletal::Motor;
3
4fn u16_at(b: &[u8], p: usize) -> u16 {
5    u16::from_le_bytes(b[p..p + 2].try_into().unwrap())
6}
7fn u32_at(b: &[u8], p: usize) -> u32 {
8    u32::from_le_bytes(b[p..p + 4].try_into().unwrap())
9}
10fn u64_at(b: &[u8], p: usize) -> u64 {
11    u64::from_le_bytes(b[p..p + 8].try_into().unwrap())
12}
13fn f64_at(b: &[u8], p: usize) -> f64 {
14    f64::from_bits(u64_at(b, p))
15}
16fn motor_at(b: &[u8], p: usize) -> Motor {
17    let a: [f64; 8] = std::array::from_fn(|i| f64_at(b, p + i * 8));
18    Motor {
19        r_w: a[0],
20        r_x: a[1],
21        r_y: a[2],
22        r_z: a[3],
23        d_w: a[4],
24        d_x: a[5],
25        d_y: a[6],
26        d_z: a[7],
27    }
28}
29fn write_motor(b: &mut [u8], p: usize, m: Motor) {
30    for (i, v) in [m.r_w, m.r_x, m.r_y, m.r_z, m.d_w, m.d_x, m.d_y, m.d_z]
31        .iter()
32        .enumerate()
33    {
34        b[p + i * 8..p + i * 8 + 8].copy_from_slice(&v.to_le_bytes());
35    }
36}
37
38#[derive(Clone, Copy)]
39struct Offsets {
40    clips: usize,
41    tracks: usize,
42    keys: usize,
43    skin: usize,
44}
45impl Offsets {
46    fn new(c: Counts) -> Self {
47        let clips = HEADER_BYTES + c.joints * JOINT_BYTES;
48        let tracks = clips + c.clips * CLIP_BYTES;
49        let keys = tracks + c.tracks * TRACK_BYTES;
50        Self {
51            clips,
52            tracks,
53            keys,
54            skin: keys + c.keys * KEY_BYTES,
55        }
56    }
57}
58
59/// Zero-copy validated record view. Private fields prevent unchecked construction.
60pub struct SkeletalSection<'a> {
61    bytes: &'a [u8],
62    counts: Counts,
63    offsets: Offsets,
64}
65impl<'a> SkeletalSection<'a> {
66    /// Validate an `SKL1` payload and return a zero-copy view over it.
67    ///
68    /// Checks magic/version/reserved header fields, computes the expected
69    /// length from the five counts (rejecting overflow via `CountLimit`),
70    /// requires `bytes.len()` to match exactly and the declared vertex
71    /// count to equal `expected_vertices`, scans joint/clip records for
72    /// non-zero reserved bytes, then runs `validation::validate` for
73    /// cross-record consistency. No allocation — the view borrows `bytes`.
74    pub fn parse(bytes: &'a [u8], expected_vertices: usize) -> Result<Self, SkeletalSectionError> {
75        if bytes.len() < HEADER_BYTES
76            || bytes[..4] != *b"SKL1"
77            || u16_at(bytes, 4) != 1
78            || u16_at(bytes, 6) != 0
79            || u32_at(bytes, 28) != 0
80        {
81            return Err(SkeletalSectionError::Header);
82        }
83        let c = Counts {
84            joints: u32_at(bytes, 8) as usize,
85            vertices: u32_at(bytes, 12) as usize,
86            clips: u32_at(bytes, 16) as usize,
87            tracks: u32_at(bytes, 20) as usize,
88            keys: u32_at(bytes, 24) as usize,
89        };
90        let len = c.encoded_len().ok_or(SkeletalSectionError::CountLimit)?;
91        if bytes.len() != len || c.vertices != expected_vertices {
92            return Err(SkeletalSectionError::Length);
93        }
94        let result = Self {
95            bytes,
96            counts: c,
97            offsets: Offsets::new(c),
98        };
99        for i in 0..c.joints {
100            let p = HEADER_BYTES + i * JOINT_BYTES;
101            if bytes[p + 2..p + 8].iter().any(|b| *b != 0) {
102                return Err(SkeletalSectionError::Header);
103            }
104        }
105        for i in 0..c.clips {
106            let p = result.offsets.clips + i * CLIP_BYTES;
107            if u32_at(bytes, p + 24) > 1 || u32_at(bytes, p + 28) != 0 {
108                return Err(SkeletalSectionError::Header);
109            }
110        }
111        validation::validate(&result)?;
112        Ok(result)
113    }
114    /// Record counts decoded from the header (joints, vertices, clips,
115    /// tracks, keys).
116    pub fn counts(&self) -> Counts {
117        self.counts
118    }
119    /// Joint record `i` (parent index, rest pose, inverse bind motor), or
120    /// `None` when out of range.
121    pub fn joint(&self, i: usize) -> Option<Joint> {
122        (i < self.counts.joints).then(|| Records::joint(self, i))
123    }
124    /// Stable 64-bit identifier of joint `i`, or `None` when out of range.
125    pub fn joint_id(&self, i: usize) -> Option<u64> {
126        (i < self.counts.joints).then(|| Records::joint_id(self, i))
127    }
128    /// Animation clip record `i` (id, duration, track span, loop flag),
129    /// or `None` when out of range.
130    pub fn clip(&self, i: usize) -> Option<ClipRecord> {
131        (i < self.counts.clips).then(|| Records::clip(self, i))
132    }
133    /// Track record `i` (target joint + key span), or `None` when out of
134    /// range.
135    pub fn track(&self, i: usize) -> Option<Track> {
136        (i < self.counts.tracks).then(|| Records::track(self, i))
137    }
138    /// Keyframe `i` (time + local-space motor pose), or `None` when out
139    /// of range.
140    pub fn key(&self, i: usize) -> Option<Key> {
141        (i < self.counts.keys).then(|| Records::key(self, i))
142    }
143    /// Skin weights for vertex `i` (up to four joint/weight pairs), or
144    /// `None` when out of range.
145    pub fn skin(&self, i: usize) -> Option<SkinWeight> {
146        (i < self.counts.vertices).then(|| Records::skin(self, i))
147    }
148
149    /// Copy every decoded record into caller-supplied buffers.
150    ///
151    /// All six buffers must be at least as large as the corresponding
152    /// count — `joints`/`ids` ≥ joints, `skin` ≥ vertices, `clips` ≥
153    /// clips, `tracks` ≥ tracks, `keys` ≥ keys — otherwise
154    /// `SkeletalSectionError::OutputTooSmall` is returned before any
155    /// writes. Returns the decoded `Counts`.
156    pub fn decode_into(
157        &self,
158        joints: &mut [Joint],
159        ids: &mut [u64],
160        skin: &mut [SkinWeight],
161        clips: &mut [ClipRecord],
162        tracks: &mut [Track],
163        keys: &mut [Key],
164    ) -> Result<Counts, SkeletalSectionError> {
165        let c = self.counts;
166        if joints.len() < c.joints
167            || ids.len() < c.joints
168            || skin.len() < c.vertices
169            || clips.len() < c.clips
170            || tracks.len() < c.tracks
171            || keys.len() < c.keys
172        {
173            return Err(SkeletalSectionError::OutputTooSmall);
174        }
175        for i in 0..c.joints {
176            joints[i] = Records::joint(self, i);
177            ids[i] = Records::joint_id(self, i);
178        }
179        for (i, s) in skin[..c.vertices].iter_mut().enumerate() {
180            *s = Records::skin(self, i);
181        }
182        for (i, s) in clips[..c.clips].iter_mut().enumerate() {
183            *s = Records::clip(self, i);
184        }
185        for (i, s) in tracks[..c.tracks].iter_mut().enumerate() {
186            *s = Records::track(self, i);
187        }
188        for (i, s) in keys[..c.keys].iter_mut().enumerate() {
189            *s = Records::key(self, i);
190        }
191        Ok(c)
192    }
193}
194impl Records for SkeletalSection<'_> {
195    fn counts(&self) -> Counts {
196        self.counts
197    }
198    fn joint(&self, i: usize) -> Joint {
199        let p = HEADER_BYTES + i * JOINT_BYTES;
200        let parent = u16_at(self.bytes, p);
201        Joint {
202            parent: (parent != u16::MAX).then_some(parent),
203            rest_local: motor_at(self.bytes, p + 16),
204            inverse_bind: motor_at(self.bytes, p + 80),
205        }
206    }
207    fn joint_id(&self, i: usize) -> u64 {
208        u64_at(self.bytes, HEADER_BYTES + i * JOINT_BYTES + 8)
209    }
210    fn clip(&self, i: usize) -> ClipRecord {
211        let p = self.offsets.clips + i * CLIP_BYTES;
212        let b = self.bytes;
213        ClipRecord {
214            id: u64_at(b, p),
215            duration: f64_at(b, p + 8),
216            first_track: u32_at(b, p + 16),
217            track_count: u32_at(b, p + 20),
218            looping: u32_at(b, p + 24) == 1,
219        }
220    }
221    fn track(&self, i: usize) -> Track {
222        let p = self.offsets.tracks + i * TRACK_BYTES;
223        Track {
224            joint: u16_at(self.bytes, p),
225            key_count: u16_at(self.bytes, p + 2),
226            first_key: u32_at(self.bytes, p + 4),
227        }
228    }
229    fn key(&self, i: usize) -> Key {
230        let p = self.offsets.keys + i * KEY_BYTES;
231        Key {
232            time: f64_at(self.bytes, p),
233            local: motor_at(self.bytes, p + 8),
234        }
235    }
236    fn skin(&self, i: usize) -> SkinWeight {
237        let p = self.offsets.skin + i * SKIN_BYTES;
238        SkinWeight {
239            joints: std::array::from_fn(|j| u16_at(self.bytes, p + j * 2)),
240            weights: std::array::from_fn(|j| f32::from_bits(u32_at(self.bytes, p + 8 + j * 4))),
241        }
242    }
243}
244
245/// Serialise `data` as an `SKL1` section into `out`, returning the byte
246/// count (header + joints + clips + tracks + keys + skin weights).
247///
248/// Validates `data` (including `joint_ids.len() == joints`), requires
249/// `out` to hold the computed size, and zero-fills before writing so all
250/// reserved/padding bytes are deterministic. Fails closed on overflow,
251/// inconsistent input, or undersized output.
252pub fn encode_skeletal_section_into(
253    data: &SkeletalData<'_>,
254    out: &mut [u8],
255) -> Result<usize, SkeletalSectionError> {
256    let c = data.counts();
257    let len = c.encoded_len().ok_or(SkeletalSectionError::CountLimit)?;
258    if data.joint_ids.len() != c.joints {
259        return Err(SkeletalSectionError::InvalidData);
260    }
261    validation::validate(data)?;
262    if out.len() < len {
263        return Err(SkeletalSectionError::OutputTooSmall);
264    }
265    let o = Offsets::new(c);
266    out[..len].fill(0);
267    out[..4].copy_from_slice(b"SKL1");
268    out[4..6].copy_from_slice(&1u16.to_le_bytes());
269    for (i, count) in [c.joints, c.vertices, c.clips, c.tracks, c.keys]
270        .iter()
271        .enumerate()
272    {
273        out[8 + i * 4..12 + i * 4].copy_from_slice(&(*count as u32).to_le_bytes());
274    }
275    for (i, j) in data.joints.iter().enumerate() {
276        let p = HEADER_BYTES + i * JOINT_BYTES;
277        out[p..p + 2].copy_from_slice(&j.parent.unwrap_or(u16::MAX).to_le_bytes());
278        out[p + 8..p + 16].copy_from_slice(&data.joint_ids[i].to_le_bytes());
279        write_motor(out, p + 16, j.rest_local);
280        write_motor(out, p + 80, j.inverse_bind);
281    }
282    for (i, clip) in data.clips.iter().enumerate() {
283        let p = o.clips + i * CLIP_BYTES;
284        out[p..p + 8].copy_from_slice(&clip.id.to_le_bytes());
285        out[p + 8..p + 16].copy_from_slice(&clip.duration.to_le_bytes());
286        out[p + 16..p + 20].copy_from_slice(&clip.first_track.to_le_bytes());
287        out[p + 20..p + 24].copy_from_slice(&clip.track_count.to_le_bytes());
288        out[p + 24..p + 28].copy_from_slice(&(clip.looping as u32).to_le_bytes());
289    }
290    for (i, t) in data.tracks.iter().enumerate() {
291        let p = o.tracks + i * TRACK_BYTES;
292        out[p..p + 2].copy_from_slice(&t.joint.to_le_bytes());
293        out[p + 2..p + 4].copy_from_slice(&t.key_count.to_le_bytes());
294        out[p + 4..p + 8].copy_from_slice(&t.first_key.to_le_bytes());
295    }
296    for (i, k) in data.keys.iter().enumerate() {
297        let p = o.keys + i * KEY_BYTES;
298        out[p..p + 8].copy_from_slice(&k.time.to_le_bytes());
299        write_motor(out, p + 8, k.local);
300    }
301    for (i, s) in data.skin.iter().enumerate() {
302        let p = o.skin + i * SKIN_BYTES;
303        for j in 0..4 {
304            out[p + j * 2..p + j * 2 + 2].copy_from_slice(&s.joints[j].to_le_bytes());
305            out[p + 8 + j * 4..p + 12 + j * 4].copy_from_slice(&s.weights[j].to_le_bytes());
306        }
307    }
308    Ok(len)
309}