Skip to main content

qualia_core_db/render/source_frame/
mod.rs

1//! Borrowed source-bound pose publication. This is view state, not a player,
2//! source store, authority grant, renderer or frame clock.
3mod model;
4mod validation;
5pub use model::{decode_bound_model, validate_resident_mesh};
6pub use validation::{validate_pose, SourceFrameState};
7#[cfg(test)]
8mod tests;
9
10#[derive(Clone, Copy, Debug, PartialEq, Eq)]
11pub struct SourceFrameBinding {
12    pub model_sha256: [u8; 32],
13    pub source_sha256: [u8; 32],
14    pub source_generation: u64,
15    pub mesh_generation: u64,
16    /// Advances on seek/clip/rate changes without redecoding the resident model.
17    pub transport_epoch: u64,
18    pub vertex_count: u32,
19    pub index_count: u32,
20}
21
22/// A complete single-model authored-space pose, borrowed from the native player.
23/// The host owns exact timeline ticks (timeline-editing's existing timebase).
24pub struct SourceMeshFrame<'a> {
25    pub binding: SourceFrameBinding,
26    pub frame_sequence: u64,
27    pub timeline_tick: u64,
28    pub positions: &'a [[f32; 3]],
29    pub normals: &'a [[f32; 3]],
30    pub tangents: &'a [[f32; 4]],
31}
32
33/// Admission/submission only. This is neither a device-present receipt nor
34/// visual acceptance; asynchronous device failure cannot be rolled back here.
35#[derive(Clone, Copy, Debug, PartialEq)]
36pub struct SourceFrameReceipt {
37    pub binding: SourceFrameBinding,
38    pub frame_sequence: u64,
39    pub timeline_tick: u64,
40    pub bounds: [[f32; 3]; 2],
41}
42
43#[derive(Clone, Copy, Debug, PartialEq, Eq)]
44pub enum SourceFrameError {
45    Input,
46    Budget,
47    Model,
48    Integrity,
49    ResidentMismatch,
50    Stale,
51    Sequence,
52    Attributes,
53    Backend,
54    Upload,
55}
56impl core::fmt::Display for SourceFrameError {
57    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
58        f.write_str(match self {
59            Self::Input => "invalid source-frame binding or exact clock",
60            Self::Budget => "source-frame cold admission budget exceeded",
61            Self::Model => "source-frame canonical model refused",
62            Self::Integrity => "source-frame model integrity refused",
63            Self::ResidentMismatch => "source-frame requires the exact full authored resident mesh",
64            Self::Stale => "source-frame source, mesh or transport epoch changed",
65            Self::Sequence => "source-frame sequence is stale or exhausted",
66            Self::Attributes => "source-frame surface attributes refused",
67            Self::Backend => "source-frame requires the full WebGPU backend",
68            Self::Upload => "source-frame upload refused before publication",
69        })
70    }
71}
72impl std::error::Error for SourceFrameError {}
73
74/// Cold model verification is separate from zero-allocation pose publication.
75#[derive(Clone, Copy, Debug)]
76pub struct SourceFrameBindLimits {
77    pub max_model_bytes: usize,
78    pub max_vertices: usize,
79    pub max_indices: usize,
80    pub max_cold_bytes: usize,
81}
82impl Default for SourceFrameBindLimits {
83    fn default() -> Self {
84        Self {
85            max_model_bytes: 64 * 1024 * 1024,
86            max_vertices: 1_000_000,
87            max_indices: 6_000_000,
88            max_cold_bytes: 192 * 1024 * 1024,
89        }
90    }
91}