Skip to main content

qualia_core_db/render/source_frame/
validation.rs

1use super::{SourceFrameBinding, SourceFrameError, SourceFrameReceipt, SourceMeshFrame};
2
3/// One resident binding and its publication sequence. No clock or skeletal
4/// state lives here. A detached next-state copy permits preflight before commit.
5#[derive(Clone, Copy, Debug, Default)]
6pub struct SourceFrameState {
7    binding: Option<SourceFrameBinding>,
8    last_sequence: u64,
9    controlled: bool,
10}
11impl SourceFrameState {
12    pub fn binding(&self) -> Option<SourceFrameBinding> {
13        self.binding
14    }
15    pub fn externally_controlled(&self) -> bool {
16        self.controlled
17    }
18    pub fn retire(&mut self) {
19        self.binding = None;
20    }
21    pub fn bind(&mut self, binding: SourceFrameBinding) -> Result<(), SourceFrameError> {
22        // A cold rebind on the same resident mesh could resurrect a retired
23        // epoch-one job. New source/model admission must install a new mesh;
24        // seek/clip/rate changes use advance_epoch instead.
25        if self.controlled {
26            return Err(SourceFrameError::Stale);
27        }
28        if binding.model_sha256 == [0; 32]
29            || binding.source_sha256 == [0; 32]
30            || binding.source_generation == 0
31            || binding.mesh_generation == 0
32            || binding.transport_epoch == 0
33            || binding.vertex_count == 0
34            || binding.index_count == 0
35            || binding.index_count % 3 != 0
36        {
37            return Err(SourceFrameError::Input);
38        }
39        self.binding = Some(binding);
40        self.controlled = true;
41        self.last_sequence = 0;
42        Ok(())
43    }
44    pub fn advance_epoch(
45        &mut self,
46        expected: SourceFrameBinding,
47        next: u64,
48    ) -> Result<SourceFrameBinding, SourceFrameError> {
49        if self.binding != Some(expected) {
50            return Err(SourceFrameError::Stale);
51        }
52        if next <= expected.transport_epoch {
53            return Err(SourceFrameError::Sequence);
54        }
55        let binding = SourceFrameBinding {
56            transport_epoch: next,
57            ..expected
58        };
59        self.binding = Some(binding);
60        self.last_sequence = 0;
61        Ok(binding)
62    }
63    /// No mutation or allocation, including on failure. Backward ticks are
64    /// permitted for explicit seeks; epoch and increasing sequence fence jobs.
65    pub fn prepare(
66        &self,
67        frame: &SourceMeshFrame<'_>,
68        mesh_generation: u64,
69    ) -> Result<(Self, SourceFrameReceipt), SourceFrameError> {
70        if self.binding != Some(frame.binding) || frame.binding.mesh_generation != mesh_generation {
71            return Err(SourceFrameError::Stale);
72        }
73        if frame.frame_sequence == 0 || frame.frame_sequence <= self.last_sequence {
74            return Err(SourceFrameError::Sequence);
75        }
76        if frame.timeline_tick > i64::MAX as u64 {
77            return Err(SourceFrameError::Input);
78        }
79        let bounds = validate_pose(frame)?;
80        let mut next = *self;
81        next.last_sequence = frame.frame_sequence;
82        Ok((
83            next,
84            SourceFrameReceipt {
85                binding: frame.binding,
86                frame_sequence: frame.frame_sequence,
87                timeline_tick: frame.timeline_tick,
88                bounds,
89            },
90        ))
91    }
92}
93
94/// Whole-pose finite/unit/orthogonality validation before any CPU/GPU mutation.
95pub fn validate_pose(frame: &SourceMeshFrame<'_>) -> Result<[[f32; 3]; 2], SourceFrameError> {
96    let count = frame.binding.vertex_count as usize;
97    if count == 0
98        || frame.positions.len() != count
99        || frame.normals.len() != count
100        || frame.tangents.len() != count
101    {
102        return Err(SourceFrameError::Attributes);
103    }
104    let mut bounds = [[f32::INFINITY; 3], [f32::NEG_INFINITY; 3]];
105    for ((position, normal), tangent) in frame
106        .positions
107        .iter()
108        .zip(frame.normals)
109        .zip(frame.tangents)
110    {
111        if position
112            .iter()
113            .chain(normal)
114            .chain(tangent)
115            .any(|v| !v.is_finite())
116        {
117            return Err(SourceFrameError::Attributes);
118        }
119        // Retain f32 headroom for bounds centers and squared distances used by
120        // existing draw sorting/culling. This is a numerical, not physical cap.
121        if position
122            .iter()
123            .any(|v| f64::from(*v).abs() > (f64::from(f32::MAX) / 12.).sqrt())
124        {
125            return Err(SourceFrameError::Attributes);
126        }
127        let n2: f64 = normal.iter().map(|v| f64::from(*v).powi(2)).sum();
128        let t2: f64 = tangent[..3].iter().map(|v| f64::from(*v).powi(2)).sum();
129        let dot: f64 = normal
130            .iter()
131            .zip(tangent)
132            .map(|(n, t)| f64::from(*n) * f64::from(*t))
133            .sum();
134        // Numerical admission tolerance, not a visual quality measurement.
135        if (n2 - 1.).abs() > 0.02
136            || (t2 - 1.).abs() > 0.02
137            || dot.abs() > 0.02
138            || (tangent[3] != -1.0 && tangent[3] != 1.0)
139        {
140            return Err(SourceFrameError::Attributes);
141        }
142        for axis in 0..3 {
143            bounds[0][axis] = bounds[0][axis].min(position[axis]);
144            bounds[1][axis] = bounds[1][axis].max(position[axis]);
145        }
146    }
147    Ok(bounds)
148}