Skip to main content

qualia_core_db/render/
scene_primitives.rs

1//! Deterministic primitive assembly for small authored scenes.
2//! Geometry is built once when scene state changes; rendering remains in the portal.
3
4use crate::render::assets::Mesh;
5use crate::specialized_libs::computational_geometry::authoring::box_mesh;
6use crate::specialized_libs::computational_geometry::geometry_workspace::GeometryWorkspace;
7
8#[derive(Debug, Clone, Copy)]
9pub enum Primitive {
10    Box { center: [f32; 3], size: [f32; 3] },
11    Roof { center: [f32; 3], size: [f32; 3] },
12}
13
14#[derive(Debug, Clone, Copy, PartialEq, Eq)]
15pub enum ScenePrimitiveError {
16    InvalidDimension,
17    TooManyVertices,
18    EmptyScene,
19    OutputTooSmall,
20    WorkspaceLimit,
21}
22
23#[derive(Debug, Clone, Copy, PartialEq)]
24pub struct AssemblyReceipt {
25    pub vertex_count: usize,
26    pub triangle_count: usize,
27    pub min: [f32; 3],
28    pub max: [f32; 3],
29}
30
31/// Assemble at most 256 primitives in caller-owned buffers. The caller owns
32/// the geometry arena and output storage; no scene-sized allocation is hidden
33/// inside this API. Existing primitive builders may use bounded cold scratch.
34pub fn assemble_into(
35    primitives: &[Primitive],
36    positions: &mut [[f32; 3]],
37    triangles: &mut [[u32; 3]],
38    workspace: &mut GeometryWorkspace<'_>,
39) -> Result<AssemblyReceipt, ScenePrimitiveError> {
40    if primitives.is_empty() {
41        return Err(ScenePrimitiveError::EmptyScene);
42    }
43    if primitives.len() > 256 {
44        return Err(ScenePrimitiveError::TooManyVertices);
45    }
46    let needed_vertices: usize = primitives
47        .iter()
48        .map(|p| match p {
49            Primitive::Box { .. } => 8,
50            Primitive::Roof { .. } => 6,
51        })
52        .sum();
53    let needed_triangles: usize = primitives
54        .iter()
55        .map(|p| match p {
56            Primitive::Box { .. } => 12,
57            Primitive::Roof { .. } => 8,
58        })
59        .sum();
60    if positions.len() < needed_vertices || triangles.len() < needed_triangles {
61        return Err(ScenePrimitiveError::OutputTooSmall);
62    }
63    let recipe_len = 6 + primitives.len() * 25;
64    workspace
65        .admit_pass(recipe_len)
66        .map_err(|_| ScenePrimitiveError::WorkspaceLimit)?;
67    let scratch = workspace
68        .alloc(recipe_len)
69        .map_err(|_| ScenePrimitiveError::WorkspaceLimit)?;
70    recipe_write(primitives, scratch)?;
71    let mut receipt = AssemblyReceipt {
72        vertex_count: 0,
73        triangle_count: 0,
74        min: [f32::INFINITY; 3],
75        max: [f32::NEG_INFINITY; 3],
76    };
77    for primitive in primitives {
78        let (center, size, mesh) = match *primitive {
79            Primitive::Box { center, size } => {
80                let mesh = box_mesh(size[0], size[1], size[2])
81                    .map_err(|_| ScenePrimitiveError::InvalidDimension)?;
82                (center, size, mesh)
83            }
84            Primitive::Roof { center, size } => {
85                validate(center, size)?;
86                let x = size[0] * 0.5;
87                let z = size[2] * 0.5;
88                let mesh = Mesh {
89                    positions: vec![
90                        [-x, 0.0, -z],
91                        [x, 0.0, -z],
92                        [x, 0.0, z],
93                        [-x, 0.0, z],
94                        [-x, size[1], 0.0],
95                        [x, size[1], 0.0],
96                    ],
97                    triangles: vec![
98                        [0, 4, 3],
99                        [0, 1, 5],
100                        [0, 5, 4],
101                        [1, 2, 5],
102                        [2, 3, 5],
103                        [3, 5, 4],
104                        [2, 3, 0],
105                        [2, 0, 1],
106                    ],
107                    min: [-x, 0.0, -z],
108                    max: [x, size[1], z],
109                };
110                (center, size, mesh)
111            }
112        };
113        validate(center, size)?;
114        let offset = receipt.vertex_count as u32;
115        for mut p in mesh.positions {
116            for axis in 0..3 {
117                p[axis] += center[axis];
118                receipt.min[axis] = receipt.min[axis].min(p[axis]);
119                receipt.max[axis] = receipt.max[axis].max(p[axis]);
120            }
121            positions[receipt.vertex_count] = p;
122            receipt.vertex_count += 1;
123        }
124        for t in mesh.triangles {
125            triangles[receipt.triangle_count] = [t[0] + offset, t[1] + offset, t[2] + offset];
126            receipt.triangle_count += 1;
127        }
128    }
129    Ok(receipt)
130}
131
132/// Write a canonical primitive source receipt into caller storage. The recipe
133/// is carried inside a `.10d` provenance sidecar; the mesh is derived data.
134/// `QSP1` = four-byte magic, u16 little-endian primitive count, then one
135/// u8 kind (1 box, 2 roof) and six little-endian f32 values per primitive
136/// (center xyz followed by size xyz), preserving declared primitive order.
137pub fn recipe_write(
138    primitives: &[Primitive],
139    bytes: &mut [u8],
140) -> Result<usize, ScenePrimitiveError> {
141    if primitives.is_empty() {
142        return Err(ScenePrimitiveError::EmptyScene);
143    }
144    if primitives.len() > 256 {
145        return Err(ScenePrimitiveError::TooManyVertices);
146    }
147    let len = 6 + primitives.len() * 25;
148    if bytes.len() < len {
149        return Err(ScenePrimitiveError::OutputTooSmall);
150    }
151    bytes[..4].copy_from_slice(b"QSP1");
152    bytes[4..6].copy_from_slice(&(primitives.len() as u16).to_le_bytes());
153    let mut offset = 6;
154    for primitive in primitives {
155        let (kind, center, size) = match *primitive {
156            Primitive::Box { center, size } => (1_u8, center, size),
157            Primitive::Roof { center, size } => (2_u8, center, size),
158        };
159        validate(center, size)?;
160        bytes[offset] = kind;
161        offset += 1;
162        for value in center.into_iter().chain(size) {
163            bytes[offset..offset + 4].copy_from_slice(&value.to_le_bytes());
164            offset += 4;
165        }
166    }
167    Ok(len)
168}
169
170fn validate(center: [f32; 3], size: [f32; 3]) -> Result<(), ScenePrimitiveError> {
171    if center.iter().all(|v| v.is_finite()) && size.iter().all(|v| v.is_finite() && *v > 0.0) {
172        Ok(())
173    } else {
174        Err(ScenePrimitiveError::InvalidDimension)
175    }
176}
177
178/// Match the portal's shared mesh orbit normalisation for semantic pick nodes.
179pub fn portal_point(bounds_min: [f32; 3], bounds_max: [f32; 3], point: [f32; 3]) -> [f32; 3] {
180    let span = (0..3)
181        .map(|i| bounds_max[i] - bounds_min[i])
182        .fold(1e-6_f32, f32::max);
183    std::array::from_fn(|i| (point[i] - (bounds_min[i] + bounds_max[i]) * 0.5) * 1.6 / span)
184}
185
186#[cfg(test)]
187mod tests {
188    use super::*;
189    use crate::specialized_libs::computational_geometry::geometry_workspace::Cancellation;
190
191    #[test]
192    fn assembles_translated_primitives_and_rejects_invalid_input() {
193        let mut positions = [[0.0; 3]; 16];
194        let mut triangles = [[0; 3]; 24];
195        let mut scratch = [0u8; 256];
196        let cancel = Cancellation::new();
197        let mut workspace = GeometryWorkspace::new(&mut scratch, &cancel);
198        let scene = assemble_into(
199            &[
200                Primitive::Box {
201                    center: [2.0, 0.5, 0.0],
202                    size: [2.0, 1.0, 1.0],
203                },
204                Primitive::Roof {
205                    center: [2.0, 1.0, 0.0],
206                    size: [2.0, 0.5, 1.0],
207                },
208            ],
209            &mut positions,
210            &mut triangles,
211            &mut workspace,
212        )
213        .unwrap();
214        assert_eq!(scene.vertex_count, 14);
215        assert_eq!(scene.triangle_count, 20);
216        assert_eq!(scene.min[0], 1.0);
217        assert_eq!(scene.max[1], 1.5);
218        assert_eq!(portal_point(scene.min, scene.max, [2.0, 0.75, 0.0])[0], 0.0);
219        assert_eq!(
220            assemble_into(&[], &mut positions, &mut triangles, &mut workspace),
221            Err(ScenePrimitiveError::EmptyScene)
222        );
223        let mut recipe = [0u8; 31];
224        let written = recipe_write(
225            &[Primitive::Box {
226                center: [2.0, 0.5, 0.0],
227                size: [2.0, 1.0, 1.0],
228            }],
229            &mut recipe,
230        )
231        .unwrap();
232        assert_eq!(&recipe[..4], b"QSP1");
233        assert_eq!(written, 31);
234    }
235}