Skip to main content

qualia_core_db/container_10d/
normal_section.rs

1//! Compact, optional vertex-normal field sidecar for compiled mesh assets.
2//!
3//! The existing QuantizedMesh payload remains byte-for-byte stable. This field sidecar stores
4//! unit normals as two signed normalized 16-bit octahedral coordinates (4 bytes per vertex).
5
6use bytemuck::{bytes_of, Pod, Zeroable};
7
8mod frame_decode;
9pub use frame_decode::{
10    decode_mesh_frames_into, decode_mesh_frames_with_limits, inspect_mesh_frames,
11    MeshFrameDecodeLimits, MeshFrameLayout,
12};
13
14pub const NORMAL_SECTION_HEADER_SIZE: usize = 16;
15pub const NORMAL_SECTION_VERSION: u16 = 1;
16pub const NORMAL_ENCODING_OCT16: u16 = 1;
17pub const MAX_NORMAL_COUNT: usize = 4_194_304;
18const NORMAL_SECTION_MAGIC: [u8; 4] = *b"NRM1";
19const FRAME_SECTION_MAGIC: [u8; 4] = *b"FRM1";
20const FRAME_FLAG_NORMALS: u16 = 1 << 0;
21const FRAME_FLAG_TANGENTS: u16 = 1 << 1;
22
23/// Whether a FieldSidecar payload uses the per-vertex normal codec.
24#[inline]
25pub fn is_normal_section(bytes: &[u8]) -> bool {
26    bytes.starts_with(&NORMAL_SECTION_MAGIC) || bytes.starts_with(&FRAME_SECTION_MAGIC)
27}
28
29/// Normal and tangent data decoded from one vertex-aligned FieldSidecar.
30#[derive(Debug, Clone, PartialEq)]
31pub struct MeshFrameStreams {
32    pub normals: Option<Vec<[f32; 3]>>,
33    pub tangents: Option<Vec<[f32; 4]>>,
34}
35
36#[repr(C)]
37#[derive(Debug, Clone, Copy, PartialEq, Eq, Pod, Zeroable)]
38struct NormalSectionHeader {
39    magic: [u8; 4],
40    version: u16,
41    encoding: u16,
42    count: u32,
43    reserved: u32,
44}
45
46#[derive(Debug, Clone, PartialEq, Eq)]
47pub enum NormalSectionError {
48    HeaderTooShort,
49    BadMagic,
50    UnsupportedVersion(u16),
51    UnsupportedEncoding(u16),
52    NonZeroReserved,
53    CountTooLarge { count: u32, max: usize },
54    PayloadLength { expected: usize, got: usize },
55    OutputTooSmall { needed: usize, got: usize },
56    InvalidNormal { index: usize },
57    InvalidTangent { index: usize },
58    StreamCountMismatch { expected: usize, got: usize },
59    UnknownFlags(u16),
60    EmptyFrame,
61    PayloadTooLarge { needed: usize, max: usize },
62    DecodedTooLarge { needed: usize, max: usize },
63    AllocationFailed,
64}
65
66impl std::fmt::Display for NormalSectionError {
67    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
68        write!(f, "10d normal field: {self:?}")
69    }
70}
71
72impl std::error::Error for NormalSectionError {}
73
74#[repr(C)]
75#[derive(Debug, Clone, Copy, PartialEq, Eq, Pod, Zeroable)]
76struct FrameSectionHeader {
77    magic: [u8; 4],
78    version: u16,
79    flags: u16,
80    count: u32,
81    reserved: u32,
82}
83
84/// Byte size of a normals-only (NRM1) section for `count` vertices
85/// (header + 4 bytes per vertex); `None` on overflow.
86#[inline]
87pub const fn encoded_len(count: usize) -> Option<usize> {
88    match count.checked_mul(4) {
89        Some(body) => NORMAL_SECTION_HEADER_SIZE.checked_add(body),
90        None => None,
91    }
92}
93
94/// Byte size of an interleaved FRM1 frame section for `count` vertices,
95/// with 4-byte normals and/or 8-byte tangents per vertex. `None` when
96/// neither stream is present or on overflow.
97pub const fn frame_encoded_len(
98    count: usize,
99    has_normals: bool,
100    has_tangents: bool,
101) -> Option<usize> {
102    if !has_normals && !has_tangents {
103        return None;
104    }
105    let stride = (if has_normals { 4usize } else { 0 }) + (if has_tangents { 8usize } else { 0 });
106    match count.checked_mul(stride) {
107        Some(body) => NORMAL_SECTION_HEADER_SIZE.checked_add(body),
108        None => None,
109    }
110}
111
112/// Encode normal and tangent streams in an interleaved, vertex-aligned FRM1 sidecar. Normals-only
113/// data retains the existing NRM1 representation for byte-stable containers.
114pub fn encode_mesh_frames(
115    normals: Option<&[[f32; 3]]>,
116    tangents: Option<&[[f32; 4]]>,
117    out: &mut [u8],
118) -> Result<usize, NormalSectionError> {
119    let count = match (normals, tangents) {
120        (None, None) => return Err(NormalSectionError::EmptyFrame),
121        (Some(values), None) => return encode_normals(values, out),
122        (None, Some(values)) => values.len(),
123        (Some(values), Some(tangents)) => {
124            if values.len() != tangents.len() {
125                return Err(NormalSectionError::StreamCountMismatch {
126                    expected: values.len(),
127                    got: tangents.len(),
128                });
129            }
130            values.len()
131        }
132    };
133    if count > MAX_NORMAL_COUNT || count > u32::MAX as usize {
134        return Err(NormalSectionError::CountTooLarge {
135            count: count.min(u32::MAX as usize) as u32,
136            max: MAX_NORMAL_COUNT,
137        });
138    }
139    let has_normals = normals.is_some();
140    let has_tangents = tangents.is_some();
141    let needed = frame_encoded_len(count, has_normals, has_tangents)
142        .ok_or(NormalSectionError::EmptyFrame)?;
143    if out.len() < needed {
144        return Err(NormalSectionError::OutputTooSmall {
145            needed,
146            got: out.len(),
147        });
148    }
149    let header = FrameSectionHeader {
150        magic: FRAME_SECTION_MAGIC,
151        version: NORMAL_SECTION_VERSION,
152        flags: (if has_normals { FRAME_FLAG_NORMALS } else { 0 })
153            | (if has_tangents { FRAME_FLAG_TANGENTS } else { 0 }),
154        count: count as u32,
155        reserved: 0,
156    };
157    out[..NORMAL_SECTION_HEADER_SIZE].copy_from_slice(bytes_of(&header));
158    let mut offset = NORMAL_SECTION_HEADER_SIZE;
159    for index in 0..count {
160        if let Some(values) = normals {
161            let packed =
162                oct_encode(values[index]).ok_or(NormalSectionError::InvalidNormal { index })?;
163            out[offset..offset + 2].copy_from_slice(&packed[0].to_le_bytes());
164            out[offset + 2..offset + 4].copy_from_slice(&packed[1].to_le_bytes());
165            offset += 4;
166        }
167        if let Some(values) = tangents {
168            let packed = tangent_encode(values[index])
169                .ok_or(NormalSectionError::InvalidTangent { index })?;
170            for component in packed {
171                out[offset..offset + 2].copy_from_slice(&component.to_le_bytes());
172                offset += 2;
173            }
174        }
175    }
176    Ok(offset)
177}
178
179/// Decode either the legacy NRM1 stream or the combined FRM1 normal/tangent stream.
180pub fn decode_mesh_frames(bytes: &[u8]) -> Result<MeshFrameStreams, NormalSectionError> {
181    decode_mesh_frames_with_limits(bytes, MeshFrameDecodeLimits::COMPATIBILITY)
182}
183/// Encode normalized vertex normals into a caller-owned payload buffer.
184pub fn encode_normals(normals: &[[f32; 3]], out: &mut [u8]) -> Result<usize, NormalSectionError> {
185    if normals.len() > MAX_NORMAL_COUNT || normals.len() > u32::MAX as usize {
186        return Err(NormalSectionError::CountTooLarge {
187            count: normals.len().min(u32::MAX as usize) as u32,
188            max: MAX_NORMAL_COUNT,
189        });
190    }
191    let needed = encoded_len(normals.len()).ok_or(NormalSectionError::CountTooLarge {
192        count: u32::MAX,
193        max: MAX_NORMAL_COUNT,
194    })?;
195    if out.len() < needed {
196        return Err(NormalSectionError::OutputTooSmall {
197            needed,
198            got: out.len(),
199        });
200    }
201    let header = NormalSectionHeader {
202        magic: NORMAL_SECTION_MAGIC,
203        version: NORMAL_SECTION_VERSION,
204        encoding: NORMAL_ENCODING_OCT16,
205        count: normals.len() as u32,
206        reserved: 0,
207    };
208    out[..NORMAL_SECTION_HEADER_SIZE].copy_from_slice(bytes_of(&header));
209    let mut offset = NORMAL_SECTION_HEADER_SIZE;
210    for (index, normal) in normals.iter().enumerate() {
211        let encoded = oct_encode(*normal).ok_or(NormalSectionError::InvalidNormal { index })?;
212        out[offset..offset + 2].copy_from_slice(&encoded[0].to_le_bytes());
213        out[offset + 2..offset + 4].copy_from_slice(&encoded[1].to_le_bytes());
214        offset += 4;
215    }
216    Ok(offset)
217}
218
219/// Decode vertex normals from a normal-only or combined mesh-frame FieldSidecar.
220pub fn decode_normals(bytes: &[u8]) -> Result<Vec<[f32; 3]>, NormalSectionError> {
221    decode_mesh_frames(bytes)?
222        .normals
223        .ok_or(NormalSectionError::EmptyFrame)
224}
225
226/// Decode vertex tangents and handedness from a combined mesh-frame FieldSidecar.
227pub fn decode_tangents(bytes: &[u8]) -> Result<Vec<[f32; 4]>, NormalSectionError> {
228    decode_mesh_frames(bytes)?
229        .tangents
230        .ok_or(NormalSectionError::EmptyFrame)
231}
232
233fn oct_encode(normal: [f32; 3]) -> Option<[i16; 2]> {
234    if normal.iter().any(|value| !value.is_finite()) {
235        return None;
236    }
237    let length = (normal[0] * normal[0] + normal[1] * normal[1] + normal[2] * normal[2]).sqrt();
238    if !length.is_finite() || length <= f32::EPSILON {
239        return None;
240    }
241    let mut x = normal[0] / length;
242    let mut y = normal[1] / length;
243    let z = normal[2] / length;
244    let l1 = x.abs() + y.abs() + z.abs();
245    x /= l1;
246    y /= l1;
247    let mut ox = x;
248    let mut oy = y;
249    if z < 0.0 {
250        ox = (1.0 - y.abs()) * sign_not_zero(x);
251        oy = (1.0 - x.abs()) * sign_not_zero(y);
252    }
253    Some([
254        (ox.clamp(-1.0, 1.0) * i16::MAX as f32).round() as i16,
255        (oy.clamp(-1.0, 1.0) * i16::MAX as f32).round() as i16,
256    ])
257}
258
259fn oct_decode(encoded: [i16; 2]) -> [f32; 3] {
260    let mut x = (encoded[0] as f32 / i16::MAX as f32).max(-1.0);
261    let mut y = (encoded[1] as f32 / i16::MAX as f32).max(-1.0);
262    let mut z = 1.0 - x.abs() - y.abs();
263    if z < 0.0 {
264        let old_x = x;
265        x = (1.0 - y.abs()) * sign_not_zero(old_x);
266        y = (1.0 - old_x.abs()) * sign_not_zero(y);
267    }
268    let length = (x * x + y * y + z * z).sqrt();
269    if length > f32::EPSILON {
270        x /= length;
271        y /= length;
272        z /= length;
273    }
274    [x, y, z]
275}
276
277fn tangent_encode(tangent: [f32; 4]) -> Option<[i16; 4]> {
278    if tangent.iter().any(|value| !value.is_finite()) || (tangent[3].abs() - 1.0).abs() > 1e-3 {
279        return None;
280    }
281    let length =
282        (tangent[0] * tangent[0] + tangent[1] * tangent[1] + tangent[2] * tangent[2]).sqrt();
283    if !length.is_finite() || length <= f32::EPSILON {
284        return None;
285    }
286    Some([
287        ((tangent[0] / length).clamp(-1.0, 1.0) * i16::MAX as f32).round() as i16,
288        ((tangent[1] / length).clamp(-1.0, 1.0) * i16::MAX as f32).round() as i16,
289        ((tangent[2] / length).clamp(-1.0, 1.0) * i16::MAX as f32).round() as i16,
290        if tangent[3] < 0.0 {
291            -i16::MAX
292        } else {
293            i16::MAX
294        },
295    ])
296}
297
298fn tangent_decode(encoded: [i16; 4]) -> Option<[f32; 4]> {
299    if encoded[3] != i16::MAX && encoded[3] != -i16::MAX {
300        return None;
301    }
302    let mut tangent = [
303        (encoded[0] as f32 / i16::MAX as f32).max(-1.0),
304        (encoded[1] as f32 / i16::MAX as f32).max(-1.0),
305        (encoded[2] as f32 / i16::MAX as f32).max(-1.0),
306    ];
307    let length =
308        (tangent[0] * tangent[0] + tangent[1] * tangent[1] + tangent[2] * tangent[2]).sqrt();
309    if !length.is_finite() || length <= f32::EPSILON {
310        return None;
311    }
312    for component in &mut tangent {
313        *component /= length;
314    }
315    Some([
316        tangent[0],
317        tangent[1],
318        tangent[2],
319        if encoded[3] < 0 { -1.0 } else { 1.0 },
320    ])
321}
322
323#[inline]
324fn sign_not_zero(value: f32) -> f32 {
325    if value < 0.0 {
326        -1.0
327    } else {
328        1.0
329    }
330}
331
332#[cfg(test)]
333mod tests {
334    use super::*;
335
336    #[test]
337    fn oct16_round_trip_stays_within_angular_tolerance() {
338        let input = [[0.0, 0.0, 1.0], [0.0, 0.0, -1.0], [1.0, 2.0, 3.0]];
339        let mut bytes = vec![0; encoded_len(input.len()).unwrap()];
340        let written = encode_normals(&input, &mut bytes).unwrap();
341        let output = decode_normals(&bytes[..written]).unwrap();
342        assert_eq!(output.len(), input.len());
343        for (a, b) in input.iter().zip(output) {
344            let length = (a[0] * a[0] + a[1] * a[1] + a[2] * a[2]).sqrt();
345            let dot = (a[0] * b[0] + a[1] * b[1] + a[2] * b[2]) / length;
346            assert!(dot > 0.9999, "angular dot product {dot}");
347        }
348    }
349
350    #[test]
351    fn encoder_rejects_zero_or_non_finite_normals() {
352        for normal in [[0.0, 0.0, 0.0], [f32::NAN, 0.0, 1.0]] {
353            let mut bytes = vec![0; encoded_len(1).unwrap()];
354            assert!(matches!(
355                encode_normals(&[normal], &mut bytes),
356                Err(NormalSectionError::InvalidNormal { index: 0 })
357            ));
358        }
359    }
360
361    #[test]
362    fn decoder_rejects_trailing_bytes() {
363        let mut bytes = vec![0; encoded_len(1).unwrap()];
364        encode_normals(&[[0.0, 0.0, 1.0]], &mut bytes).unwrap();
365        bytes.push(0);
366        assert!(matches!(
367            decode_normals(&bytes),
368            Err(NormalSectionError::PayloadLength { .. })
369        ));
370    }
371
372    #[test]
373    fn field_kind_detection_leaves_other_sidecar_families_available() {
374        assert!(!is_normal_section(b"WAVE"));
375        assert!(is_normal_section(b"NRM1"));
376        assert!(is_normal_section(b"FRM1"));
377    }
378
379    #[test]
380    fn frm1_round_trips_normal_tangent_and_mirrored_handedness() {
381        let normals = [[0.0, 0.0, 1.0], [0.0, 0.0, -1.0]];
382        let tangents = [[1.0, 0.0, 0.0, 1.0], [0.0, 1.0, 0.0, -1.0]];
383        let mut bytes = vec![0; frame_encoded_len(2, true, true).unwrap()];
384        let written = encode_mesh_frames(Some(&normals), Some(&tangents), &mut bytes).unwrap();
385        let decoded = decode_mesh_frames(&bytes[..written]).unwrap();
386        assert_eq!(decoded.normals.unwrap(), normals);
387        assert_eq!(decoded.tangents.unwrap(), tangents);
388    }
389
390    #[test]
391    fn frm1_rejects_tangent_count_mismatch_and_bad_handedness() {
392        let mut bytes = vec![0; frame_encoded_len(2, true, true).unwrap()];
393        assert!(matches!(
394            encode_mesh_frames(
395                Some(&[[0.0, 0.0, 1.0]]),
396                Some(&[[1.0, 0.0, 0.0, 1.0]; 2]),
397                &mut bytes
398            ),
399            Err(NormalSectionError::StreamCountMismatch { .. })
400        ));
401        assert!(matches!(
402            encode_mesh_frames(None, Some(&[[1.0, 0.0, 0.0, 0.0]]), &mut bytes),
403            Err(NormalSectionError::InvalidTangent { index: 0 })
404        ));
405    }
406
407    #[test]
408    fn frm1_rejects_corrupt_serialized_handedness_and_zero_direction() {
409        let mut bytes = vec![0; frame_encoded_len(1, false, true).unwrap()];
410        encode_mesh_frames(None, Some(&[[1.0, 0.0, 0.0, 1.0]]), &mut bytes).unwrap();
411        bytes[NORMAL_SECTION_HEADER_SIZE + 6..NORMAL_SECTION_HEADER_SIZE + 8]
412            .copy_from_slice(&0i16.to_le_bytes());
413        assert!(matches!(
414            decode_mesh_frames(&bytes),
415            Err(NormalSectionError::InvalidTangent { index: 0 })
416        ));
417
418        let mut bytes = vec![0; frame_encoded_len(1, false, true).unwrap()];
419        encode_mesh_frames(None, Some(&[[1.0, 0.0, 0.0, 1.0]]), &mut bytes).unwrap();
420        bytes[NORMAL_SECTION_HEADER_SIZE..NORMAL_SECTION_HEADER_SIZE + 6].fill(0);
421        assert!(matches!(
422            decode_mesh_frames(&bytes),
423            Err(NormalSectionError::InvalidTangent { index: 0 })
424        ));
425    }
426}