Skip to main content

qualia_core_db/render/
portal_load_10d.rs

1//! CPU decode for QualiaPortal `load_10d`.
2//!
3//! Lives outside the wasm-only `portal` facade so native tests can cover the
4//! SurfaceReading colour buffer, UV01 stream, and MAT3/MAT4 records that
5//! `load_10d` uploads.
6
7use crate::container_10d;
8use crate::container_10d::header::{Container10dHeader, FLAG_DEFAULT_DISPOSITION_REFUSE};
9use crate::container_10d::{MaterialRecord, SubmeshRange};
10
11/// Orbit-framed mesh buffers `load_10d` passes to GPU upload.
12#[derive(Debug, Clone)]
13pub struct Load10dGpuBuffers {
14    /// Positions centred and scaled into the portal orbit frame.
15    pub positions: Vec<[f32; 3]>,
16    /// Per-vertex linear RGBA from SurfaceReading. Empty iff SurfaceReading is absent.
17    pub colors: Vec<[f32; 4]>,
18    /// Authored UV01 when the section is present and vertex-aligned.
19    pub uv0: Option<Vec<[f32; 2]>>,
20    /// Authored normals when the frame sidecar is present and vertex-aligned.
21    pub normals: Option<Vec<[f32; 3]>>,
22    /// Authored tangents when the frame sidecar is present and vertex-aligned.
23    pub tangents: Option<Vec<[f32; 4]>>,
24    /// Flat triangle-list indices.
25    pub indices: Vec<u32>,
26    /// MAT3/MAT4 records. Empty when the section is absent (colour path stays).
27    pub materials: Vec<MaterialRecord>,
28    /// Submesh ranges bound to [`Self::materials`]. Empty with missing MAT.
29    pub ranges: Vec<SubmeshRange>,
30    /// First Tensor10DNodes μ, or 0 when that section is absent.
31    pub provenance_mu: f32,
32    /// Header default-refuse with no attestation sidecar.
33    pub governance_refused: bool,
34    pub vertex_count: u32,
35    pub triangle_count: u32,
36}
37
38/// Parse a sealed `.10d` into the GPU upload arguments `QualiaPortal::load_10d` uses.
39pub fn decode_load_10d(bytes: &[u8]) -> Result<Load10dGpuBuffers, String> {
40    let mut bytes_mut = bytes.to_vec();
41    let header = Container10dHeader::parse(&bytes_mut).map_err(|e| format!("10d header: {e}"))?;
42
43    container_10d::verify_whole_file_crc32c(&mut bytes_mut).map_err(|e| format!("10d CRC: {e}"))?;
44
45    let descs = container_10d::parse_section_table(&bytes_mut, &header)
46        .map_err(|e| format!("10d section table: {e}"))?;
47
48    let mut mesh = None;
49    let mut provenance_mu: f32 = 0.0;
50    let mut has_attestation = false;
51
52    for desc in descs.iter() {
53        let st = container_10d::SectionType::from_u8(desc.section_type)
54            .ok_or_else(|| "10d: unknown section type".to_string())?;
55        let off = desc.byte_offset as usize;
56        let len = desc.byte_length as usize;
57        let payload = &bytes_mut[off..off + len];
58
59        match st {
60            container_10d::SectionType::QuantizedMesh => {
61                mesh = Some(
62                    container_10d::decode_mesh_section(payload)
63                        .map_err(|e| format!("10d mesh decode: {e}"))?,
64                );
65            }
66            container_10d::SectionType::Tensor10DNodes => {
67                if let Ok(t) = container_10d::read_node(payload, 0) {
68                    provenance_mu = t.mu;
69                }
70            }
71            container_10d::SectionType::ProvenanceSidecar => {
72                if let Ok(view) =
73                    crate::container_10d::provenance_section::decode_provenance_section(payload)
74                {
75                    if crate::container_10d::provenance_section::validate_provenance(&view).is_ok()
76                    {
77                        has_attestation = true;
78                    }
79                }
80            }
81            _ => {}
82        }
83    }
84
85    let mesh = mesh.ok_or_else(|| "10d: no mesh section".to_string())?;
86    let frames = container_10d::read_container_mesh_frames_with_limits(
87        &bytes_mut,
88        mesh.vertex_count(),
89        container_10d::MeshFrameDecodeLimits {
90            max_vertices: container_10d::MAX_NORMAL_COUNT,
91            max_payload_bytes: 64 * 1024 * 1024,
92            max_decoded_bytes: 256 * 1024 * 1024,
93        },
94    )
95    .map_err(|e| format!("10d frames decode: {e}"))?;
96    let (authored_normals, authored_tangents) = frames
97        .map(|frames| (frames.normals, frames.tangents))
98        .unwrap_or((None, None));
99    if authored_normals
100        .as_ref()
101        .is_some_and(|normals: &Vec<[f32; 3]>| normals.len() != mesh.vertex_count())
102    {
103        return Err("10d normal field vertex count does not match mesh".into());
104    }
105    if authored_tangents
106        .as_ref()
107        .is_some_and(|tangents: &Vec<[f32; 4]>| tangents.len() != mesh.vertex_count())
108    {
109        return Err("10d tangent field vertex count does not match mesh".into());
110    }
111
112    let mut surface = None;
113    for desc in descs.iter() {
114        if container_10d::SectionType::from_u8(desc.section_type)
115            != Some(container_10d::SectionType::SurfaceReading)
116        {
117            continue;
118        }
119        let off = desc.byte_offset as usize;
120        let len = desc.byte_length as usize;
121        if off.saturating_add(len) > bytes_mut.len() {
122            continue;
123        }
124        surface =
125            container_10d::surface_reading::decode_surface_reading(&bytes_mut[off..off + len]);
126    }
127    let colors = match surface {
128        Some(reading) if reading.len() == mesh.vertex_count() => reading,
129        Some(reading) => {
130            return Err(format!(
131                "10d SurfaceReading vertex count {} does not match mesh count {}",
132                reading.len(),
133                mesh.vertex_count()
134            ));
135        }
136        None => Vec::new(),
137    };
138
139    let mut uv0 = vec![[0.0; 2]; mesh.vertex_count()];
140    let uv0 = match container_10d::read_texture_coordinate_section_into(
141        &bytes_mut,
142        mesh.vertex_count(),
143        &mut uv0,
144    ) {
145        Ok(_) => Some(uv0),
146        Err(container_10d::TextureCoordinateContainerError::Missing) => None,
147        Err(container_10d::TextureCoordinateContainerError::CountMismatch { expected, got }) => {
148            return Err(format!(
149                "10d UV01 vertex count {got} does not match mesh count {expected}"
150            ));
151        }
152        Err(e) => return Err(format!("10d UV01: {e:?}")),
153    };
154
155    let mesh_index_count = u32::try_from(mesh.triangles.len().saturating_mul(3))
156        .map_err(|_| "10d index count exceeds u32".to_string())?;
157    let (materials, ranges) = decode_load_10d_materials(&bytes_mut, mesh_index_count)?;
158
159    let governance_refused =
160        (header.flags & FLAG_DEFAULT_DISPOSITION_REFUSE) != 0 && !has_attestation;
161
162    let c = mesh.centroid();
163    let ext = [
164        mesh.max[0] - mesh.min[0],
165        mesh.max[1] - mesh.min[1],
166        mesh.max[2] - mesh.min[2],
167    ];
168    let span = ext[0].max(ext[1]).max(ext[2]).max(1e-6);
169    let s = 1.6 / span;
170    let positions: Vec<[f32; 3]> = mesh
171        .positions
172        .iter()
173        .map(|p| [(p[0] - c[0]) * s, (p[1] - c[1]) * s, (p[2] - c[2]) * s])
174        .collect();
175    let indices: Vec<u32> = mesh
176        .triangles
177        .iter()
178        .flat_map(|t| [t[0], t[1], t[2]])
179        .collect();
180
181    Ok(Load10dGpuBuffers {
182        vertex_count: mesh.positions.len() as u32,
183        triangle_count: mesh.triangles.len() as u32,
184        positions,
185        colors,
186        uv0,
187        normals: authored_normals,
188        tangents: authored_tangents,
189        indices,
190        materials,
191        ranges,
192        provenance_mu,
193        governance_refused,
194    })
195}
196
197fn decode_load_10d_materials(
198    bytes: &[u8],
199    mesh_index_count: u32,
200) -> Result<(Vec<MaterialRecord>, Vec<SubmeshRange>), String> {
201    match container_10d::material_container_counts(bytes) {
202        Ok((material_count, range_count)) => {
203            if material_count == 0 || range_count == 0 {
204                return Err("10d MAT section is empty".into());
205            }
206            if material_count > container_10d::MAX_MATERIALS
207                || range_count > container_10d::MAX_SUBMESH_RANGES
208            {
209                return Err("10d MAT section exceeds portal limits".into());
210            }
211            let mut materials = vec![MaterialRecord::legacy_default(); material_count];
212            let mut ranges = vec![
213                SubmeshRange {
214                    first_index: 0,
215                    index_count: 0,
216                    material_id: 0,
217                    semantic_id: 0,
218                };
219                range_count
220            ];
221            match container_10d::read_material_section_into(
222                bytes,
223                mesh_index_count,
224                &mut materials,
225                &mut ranges,
226            ) {
227                Ok((got_materials, got_ranges))
228                    if got_materials == material_count && got_ranges == range_count =>
229                {
230                    Ok((materials, ranges))
231                }
232                Ok(_) => Err("10d MAT section count mismatch".into()),
233                Err(error) => Err(format!("10d MAT: {error:?}")),
234            }
235        }
236        Err(container_10d::MaterialContainerError::Missing) => Ok((Vec::new(), Vec::new())),
237        Err(error) => Err(format!("10d MAT: {error:?}")),
238    }
239}
240
241/// Upload the decoded `load_10d` buffers. Authored MAT3/MAT4 is used when present;
242/// otherwise UV0 uses the legacy default material. Empty `colors` is the GPU grey default.
243#[cfg(feature = "gpu-runtime")]
244pub fn upload_load_10d_to_gpu(
245    gpu: &mut crate::render::gpu::PortalGpu,
246    decoded: &Load10dGpuBuffers,
247) -> Result<u32, String> {
248    upload_load_10d_to_gpu_with_textures(gpu, decoded, &[])
249}
250
251/// Upload mesh plus optional PNG/KTX2 albedo (or other MAT maps). Texture
252/// failures skip the map; the mesh and vertex colour still draw.
253#[cfg(feature = "gpu-runtime")]
254pub fn upload_load_10d_to_gpu_with_textures(
255    gpu: &mut crate::render::gpu::PortalGpu,
256    decoded: &Load10dGpuBuffers,
257    texture_bytes: &[&[u8]],
258) -> Result<u32, String> {
259    let use_legacy_colour = decoded.materials.is_empty()
260        && decoded.uv0.is_none()
261        && texture_bytes.is_empty();
262    if use_legacy_colour {
263        return Ok(gpu.upload_mesh_colored_with_frames(
264            &decoded.positions,
265            &decoded.colors,
266            decoded.normals.as_deref(),
267            decoded.tangents.as_deref(),
268            &decoded.indices,
269        ));
270    }
271
272    let (mut materials, ranges) = if decoded.materials.is_empty() {
273        let material = MaterialRecord::legacy_default();
274        let material_id = material.id;
275        let index_count = u32::try_from(decoded.indices.len())
276            .map_err(|_| "10d index count exceeds u32".to_string())?;
277        (
278            vec![material],
279            vec![SubmeshRange {
280                first_index: 0,
281                index_count,
282                material_id,
283                semantic_id: 0,
284            }],
285        )
286    } else {
287        (decoded.materials.clone(), decoded.ranges.clone())
288    };
289
290    bind_and_upload_textures(gpu, &mut materials, texture_bytes);
291
292    gpu.upload_mesh_colored_with_frames_and_materials_and_uv0(
293        &decoded.positions,
294        &decoded.colors,
295        decoded.normals.as_deref(),
296        decoded.tangents.as_deref(),
297        decoded.uv0.as_deref(),
298        &decoded.indices,
299        &materials,
300        &ranges,
301    )
302}
303
304#[cfg(feature = "gpu-runtime")]
305fn bind_and_upload_textures(
306    gpu: &mut crate::render::gpu::PortalGpu,
307    materials: &mut [MaterialRecord],
308    texture_bytes: &[&[u8]],
309) {
310    use crate::render::portal_load_textures::{
311        ingest_portal_texture, material_references_digest, upload_portal_texture_rgba8,
312        PortalTextureIngest,
313    };
314    for bytes in texture_bytes {
315        let tex = match ingest_portal_texture(None, bytes) {
316            Ok(PortalTextureIngest::Rgba8(decoded)) => decoded,
317            Ok(PortalTextureIngest::SkippedTranscode) | Err(_) => continue,
318        };
319        if !materials
320            .iter()
321            .any(|material| material_references_digest(material, tex.digest))
322        {
323            if let Some(material) = materials
324                .iter_mut()
325                .find(|material| material.base_color_texture == [0; 32])
326            {
327                material.base_color_texture = tex.digest;
328            }
329        }
330        let _ = upload_portal_texture_rgba8(gpu, materials, &tex);
331    }
332}
333
334#[cfg(all(test, not(target_arch = "wasm32")))]
335#[path = "portal_load_10d_tests.rs"]
336mod tests;