1use 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#[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#[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#[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
94pub 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
112pub 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
179pub fn decode_mesh_frames(bytes: &[u8]) -> Result<MeshFrameStreams, NormalSectionError> {
181 decode_mesh_frames_with_limits(bytes, MeshFrameDecodeLimits::COMPATIBILITY)
182}
183pub 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
219pub fn decode_normals(bytes: &[u8]) -> Result<Vec<[f32; 3]>, NormalSectionError> {
221 decode_mesh_frames(bytes)?
222 .normals
223 .ok_or(NormalSectionError::EmptyFrame)
224}
225
226pub 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}