Skip to main content

webizen_render/
volumetric_native_preview.rs

1//! Native `.10d` review projection on the existing QualiaDB PortalGpu path.
2#![cfg(all(feature = "qualia", not(target_arch = "wasm32")))]
3
4use super::{SystemTelemetry, VolumetricRenderer};
5use image::ImageEncoder;
6use qualia_core_db::container_10d::{
7    self as c, header::Container10dHeader, MeshFrameDecodeLimits, SectionType,
8};
9use std::io::{self, Write};
10
11pub const MAX_REVIEW_10D_BYTES: usize = 42 * 1024 * 1024;
12pub const MAX_REVIEW_SIDE: u32 = 2048;
13pub const MAX_REVIEW_PIXELS: usize = 2048 * 2048;
14const MAX_REVIEW_VERTICES: usize = 262_144;
15const MAX_REVIEW_TRIANGLES: usize = 524_288;
16const MAX_REVIEW_FRAME_BYTES: usize = 8 * 1024 * 1024;
17const MAX_REVIEW_FRAME_DECODED_BYTES: usize = MAX_REVIEW_VERTICES * 28;
18const MAX_REVIEW_SIGMA_COMPARISONS: usize = 20_000_000;
19const REVIEW_CAMERA_FIT_MARGIN: f32 = 1.08;
20
21#[derive(Debug, Clone, Copy, serde::Serialize)]
22pub struct ReviewLighting {
23    /// Unit directional key light passed to PortalGpu.
24    pub sun_direction: [f32; 3],
25    pub direct_intensity: f32,
26    pub ambient_intensity: f32,
27    /// Additive final RGB contribution when no environment probe is bound.
28    /// This is not diffuse irradiance and must not add a grey veil to albedo.
29    pub environment_additive_fallback_rgb: [f32; 3],
30    /// Neutral opaque clear color; this does not alter rendered subject pixels.
31    pub clear_color: [f32; 4],
32}
33
34const REVIEW_LIGHTING: ReviewLighting = ReviewLighting {
35    sun_direction: [0.408_248_3, 0.816_496_6, 0.408_248_3],
36    direct_intensity: 1.8,
37    ambient_intensity: 0.45,
38    environment_additive_fallback_rgb: [0.0, 0.0, 0.0],
39    clear_color: [0.34, 0.34, 0.34, 1.0],
40};
41
42#[derive(Clone, Copy)]
43struct LoadProfile {
44    max_input_bytes: Option<usize>,
45    max_vertices: usize,
46    max_triangles: usize,
47    require_renderable_mesh: bool,
48    frame_limits: MeshFrameDecodeLimits,
49    max_sigma_comparisons: Option<usize>,
50}
51
52impl LoadProfile {
53    const fn compatibility() -> Self {
54        Self {
55            max_input_bytes: None,
56            max_vertices: c::MAX_VERTEX_COUNT,
57            max_triangles: c::MAX_TRIANGLE_COUNT,
58            require_renderable_mesh: false,
59            frame_limits: MeshFrameDecodeLimits::COMPATIBILITY,
60            max_sigma_comparisons: None,
61        }
62    }
63    const fn review() -> Self {
64        Self {
65            max_input_bytes: Some(MAX_REVIEW_10D_BYTES),
66            max_vertices: MAX_REVIEW_VERTICES,
67            max_triangles: MAX_REVIEW_TRIANGLES,
68            require_renderable_mesh: true,
69            frame_limits: MeshFrameDecodeLimits {
70                max_vertices: MAX_REVIEW_VERTICES,
71                max_payload_bytes: MAX_REVIEW_FRAME_BYTES,
72                max_decoded_bytes: MAX_REVIEW_FRAME_DECODED_BYTES,
73            },
74            max_sigma_comparisons: Some(MAX_REVIEW_SIGMA_COMPARISONS),
75        }
76    }
77}
78
79#[derive(Debug, Clone, Copy, serde::Serialize)]
80pub struct ReviewView {
81    pub name: &'static str,
82    pub yaw: f32,
83    pub pitch: f32,
84}
85
86pub const REVIEW_VIEWS: [ReviewView; 3] = [
87    ReviewView { name: "three-quarter-view-assumed", yaw: 0.72, pitch: 0.28 },
88    ReviewView { name: "side-view-assumed", yaw: 1.5707964, pitch: 0.12 },
89    ReviewView { name: "front-view-assumed", yaw: 0.0, pitch: 0.12 },
90];
91
92#[derive(Debug, Clone, serde::Serialize)]
93pub struct ReviewGeometry {
94    pub vertex_count: u32,
95    pub triangle_count: u32,
96    pub bounds_min: [f32; 3],
97    pub bounds_max: [f32; 3],
98    pub camera_target: [f32; 3],
99    pub camera_aspect: f32,
100    pub vertical_tan_half_fov: f32,
101    pub camera_fit_margin: f32,
102    pub requested_camera_distance: f32,
103    /// Exact zoom/distance submitted after applying Core's public clamp.
104    pub camera_distance: f32,
105    pub colors: &'static str,
106    pub normals: &'static str,
107    pub tangents: &'static str,
108    pub texture_coordinates: &'static str,
109    pub materials: &'static str,
110    pub lighting: ReviewLighting,
111    pub screen_space_ao_available: bool,
112    pub screen_space_ao_radius_m: f32,
113    pub screen_space_ao_strength: f32,
114    pub screen_space_ao_samples: u32,
115    pub shadows_available: bool,
116}
117
118fn apply_review_camera_fit(geometry: &mut ReviewGeometry, aspect: f32) -> Result<(), String> {
119    let half_extent = [
120        (geometry.bounds_max[0] - geometry.bounds_min[0]).abs() * 0.5,
121        (geometry.bounds_max[1] - geometry.bounds_min[1]).abs() * 0.5,
122        (geometry.bounds_max[2] - geometry.bounds_min[2]).abs() * 0.5,
123    ];
124    let radius = (half_extent[0] * half_extent[0]
125        + half_extent[1] * half_extent[1]
126        + half_extent[2] * half_extent[2])
127        .sqrt();
128    let tan_vertical = qualia_core_db::render::camera::CAMERA_TAN_HALF_FOV;
129    let tan_horizontal = tan_vertical * aspect;
130    let limiting_half_angle = tan_vertical.min(tan_horizontal).atan();
131    if !aspect.is_finite() || aspect <= 0.0 || !radius.is_finite() || radius <= 0.0
132        || !limiting_half_angle.is_finite() || limiting_half_angle <= 0.0
133    {
134        return Err("10d bounds or preview aspect cannot produce a finite camera fit".into());
135    }
136    // A bounding sphere fits every yaw/pitch. tan_half_fov is Core's vertical
137    // projection constant; horizontal FOV scales with the render target aspect.
138    let fit_distance = (radius / limiting_half_angle.sin()) * REVIEW_CAMERA_FIT_MARGIN;
139    if !fit_distance.is_finite() {
140        return Err("10d bounds produce a non-finite sphere-fit camera distance".into());
141    }
142    geometry.requested_camera_distance = fit_distance;
143    geometry.camera_distance = fit_distance.clamp(
144        qualia_core_db::render::camera::CAMERA_MIN_ZOOM,
145        qualia_core_db::render::camera::CAMERA_MAX_ZOOM,
146    );
147    geometry.camera_aspect = aspect;
148    geometry.vertical_tan_half_fov = tan_vertical;
149    geometry.camera_fit_margin = REVIEW_CAMERA_FIT_MARGIN;
150    Ok(())
151}
152
153struct NodeAdmission<'a> {
154    payload: &'a [u8],
155    count: usize,
156    first_mu: Option<f32>,
157}
158
159pub(super) struct CappedPngWriter {
160    bytes: Vec<u8>,
161    cap: usize,
162}
163
164impl CappedPngWriter {
165    pub(super) fn new(cap: usize) -> Self { Self { bytes: Vec::new(), cap } }
166    pub(super) fn into_inner(self) -> Vec<u8> { self.bytes }
167}
168
169impl Write for CappedPngWriter {
170    fn write(&mut self, bytes: &[u8]) -> io::Result<usize> {
171        let _end = self.bytes.len().checked_add(bytes.len())
172            .filter(|end| *end <= self.cap)
173            .ok_or_else(|| io::Error::new(io::ErrorKind::WriteZero, "PNG output cap exceeded"))?;
174        self.bytes.try_reserve(bytes.len())
175            .map_err(|e| io::Error::new(io::ErrorKind::Other, format!("PNG buffer allocation: {e}")))?;
176        self.bytes.extend_from_slice(bytes);
177        Ok(bytes.len())
178    }
179    fn flush(&mut self) -> io::Result<()> { Ok(()) }
180}
181
182impl VolumetricRenderer {
183    /// Shared loader entry for the existing native general-purpose API. It
184    /// retains Core's compatibility limits rather than the review profile.
185    pub(super) fn load_10d_compat_asset(&mut self, bytes: &[u8]) -> Result<(u32, u32, f32), String> {
186        let (geometry, provenance_mu) = self.load_10d_with_profile(bytes, LoadProfile::compatibility(), None)?;
187        Ok((geometry.vertex_count, geometry.triangle_count, provenance_mu))
188    }
189
190    pub fn load_10d_review_asset(&mut self, bytes: &[u8]) -> Result<(ReviewGeometry, f32), String> {
191        self.load_10d_with_profile(bytes, LoadProfile::review(), None)
192    }
193
194    pub(super) fn load_10d_shot_pose(&mut self, bytes: &[u8], clip_id: u64, time: f64) -> Result<ReviewGeometry, String> {
195        self.load_10d_with_profile(bytes, LoadProfile::review(), Some((clip_id, time))).map(|r| r.0)
196    }
197
198    fn load_10d_with_profile(
199        &mut self,
200        bytes: &[u8],
201        profile: LoadProfile,
202        pose: Option<(u64, f64)>,
203    ) -> Result<(ReviewGeometry, f32), String> {
204        if bytes.is_empty() || profile.max_input_bytes.is_some_and(|max| bytes.len() > max) {
205            return Err("10d input is empty or exceeds the selected loader profile".into());
206        }
207        let mut verified = bytes.to_vec();
208        let header = Container10dHeader::parse(&verified).map_err(|e| format!("10d header: {e}"))?;
209        c::verify_whole_file_crc32c(&mut verified).map_err(|e| format!("10d CRC: {e}"))?;
210        let sections = c::parse_section_table(&verified, &header)
211            .map_err(|e| format!("10d section table: {e}"))?;
212        let mut mesh_payload = None;
213        let mut material_payload = None;
214        let mut texture_coordinates_payload = None;
215        let mut surface_payload = None;
216        let mut node_admission = None;
217        for section in sections {
218            let offset = section.byte_offset as usize;
219            let end = offset.checked_add(section.byte_length as usize)
220                .filter(|end| *end <= verified.len()).ok_or("10d section range is invalid")?;
221            let payload = &verified[offset..end];
222            match section.typ().ok_or("10d section type is invalid")? {
223                SectionType::QuantizedMesh => mesh_payload = Some(payload),
224                SectionType::Materials => material_payload = Some(payload),
225                SectionType::TextureCoordinates => texture_coordinates_payload = Some(payload),
226                SectionType::SurfaceReading => surface_payload = Some(payload),
227                SectionType::Tensor10DNodes => {
228                    let (node_header, _) = c::node_section::parse_node_header(payload)
229                        .map_err(|e| format!("10d node preflight: {e:?}"))?;
230                    let count = node_header.node_count as usize;
231                    let first_mu = if count == 0 { None } else {
232                        Some(c::read_node(payload, 0)
233                            .map_err(|e| format!("10d first-node preflight: {e:?}"))?.mu)
234                    };
235                    let admission = NodeAdmission { payload, count, first_mu };
236                    node_admission = Some(admission);
237                }
238                _ => {}
239            }
240        }
241
242        // Core's canonical mesh header admits counts and payload extent before
243        // decode_mesh_section allocates vertex and triangle vectors.
244        let mesh_payload = mesh_payload.ok_or("10d has no QuantizedMesh")?;
245        let (mesh_header, _) = c::parse_mesh_header(mesh_payload)
246            .map_err(|e| format!("10d mesh preflight: {e:?}"))?;
247        let vertex_count = mesh_header.vertex_count as usize;
248        let triangle_count = mesh_header.triangle_count as usize;
249        if vertex_count > profile.max_vertices || (profile.require_renderable_mesh && vertex_count == 0) {
250            return Err("10d vertex count exceeds the selected loader profile".into());
251        }
252        if triangle_count > profile.max_triangles || (profile.require_renderable_mesh && triangle_count == 0) {
253            return Err("10d triangle count exceeds the selected loader profile".into());
254        }
255        let mesh = c::decode_mesh_section(mesh_payload).map_err(|e| format!("10d mesh decode: {e:?}"))?;
256        if mesh.positions.len() != vertex_count || mesh.triangles.len() != triangle_count {
257            return Err("decoded 10d mesh counts differ from canonical header".into());
258        }
259
260        let frames = c::read_container_mesh_frames_with_limits(
261            &verified, vertex_count, profile.frame_limits,
262        ).map_err(|e| format!("10d authored normals/tangents: {e:?}"))?;
263        let (mut normals, mut tangents, normals_label, tangents_label) = match frames {
264            Some(frame) => {
265                let normals = frame.normals;
266                let tangents = frame.tangents;
267                let normal_label = if normals.is_some() { "authored" } else { "absent-renderer-derived" };
268                let tangent_label = if tangents.is_some() { "authored" } else { "absent-renderer-derived" };
269                (normals, tangents, normal_label, tangent_label)
270            }
271            None => (None, None, "absent-renderer-derived", "absent-renderer-derived"),
272        };
273        let texture_coordinates = if let Some(payload) = texture_coordinates_payload {
274            let mut uv = Vec::new();
275            uv.try_reserve_exact(vertex_count).map_err(|_| "UV01 allocation refused")?;
276            uv.resize(vertex_count, [0.0f32; 2]);
277            let decoded = c::decode_texture_coordinates_into(payload, vertex_count, &mut uv)
278                .map_err(|e| format!("10d UV01 decode: {e:?}"))?;
279            if decoded != vertex_count { return Err("10d UV01 count differs from mesh".into()); }
280            Some(uv)
281        } else { None };
282
283        let colors = if let Some(payload) = surface_payload {
284            if payload.len() < 8 || &payload[..4] != c::surface_reading::SURFACE_READING_MAGIC {
285                return Err("present SurfaceReading section has invalid SRD1 header".into());
286            }
287            let count = u32::from_le_bytes(payload[4..8].try_into()
288                .map_err(|_| "SRD1 count header invalid")?) as usize;
289            if count != vertex_count { return Err("SRD1 vertex count differs from mesh".into()); }
290            let expected = 8usize.checked_add(count.checked_mul(4).ok_or("SRD1 length overflow")?)
291                .ok_or("SRD1 length overflow")?;
292            if payload.len() != expected { return Err("present SRD1 section has noncanonical length".into()); }
293            Some(c::surface_reading::decode_surface_reading(payload)
294                .ok_or("present SRD1 section failed canonical decoder")?)
295        } else if let Some(admission) = node_admission.as_ref() {
296            let comparisons = vertex_count.checked_mul(admission.count)
297                .ok_or("legacy sigma projection work overflow")?;
298            if profile.max_sigma_comparisons.is_some_and(|max| comparisons > max) {
299                return Err("legacy sigma fallback exceeds the selected work budget".into());
300            }
301            if admission.count == 0 { None } else {
302                let mut nodes = Vec::new();
303                nodes.try_reserve_exact(admission.count).map_err(|_| "node allocation refused")?;
304                for index in 0..admission.count {
305                    nodes.push(c::read_node(admission.payload, index)
306                        .map_err(|e| format!("10d node {index} decode: {e:?}"))?);
307                }
308                Some(mesh.positions.iter().map(|p| {
309                    let mut best = 0usize;
310                    let mut best_d = f32::INFINITY;
311                    for (i, node) in nodes.iter().enumerate() {
312                        let dx = p[0] - node.x; let dy = p[1] - node.y; let dz = p[2] - node.z;
313                        let distance = dx * dx + dy * dy + dz * dz;
314                        if distance < best_d { best = i; best_d = distance; }
315                    }
316                    let (r, g, b) = qualia_core_db::render::spectral::sigma_to_display_rgb(nodes[best].sigma);
317                    [r as f32 / 255.0, g as f32 / 255.0, b as f32 / 255.0, 1.0]
318                }).collect())
319            }
320        } else { None };
321        let (colors_label, colors) = match colors {
322            Some(colors) => (if surface_payload.is_some() { "canonical-SurfaceReading" } else { "legacy-sigma-projection" }, colors),
323            None => ("absent-renderer-default", Vec::new()),
324        };
325        let provenance_mu = node_admission.as_ref()
326            .and_then(|admission| admission.first_mu).unwrap_or(0.0);
327
328        let mut indices = Vec::new();
329        let index_count = triangle_count.checked_mul(3).ok_or("triangle index count overflow")?;
330        indices.try_reserve_exact(index_count).map_err(|_| "mesh index allocation refused")?;
331        for triangle in &mesh.triangles { indices.extend_from_slice(triangle); }
332        let (materials, ranges, materials_label) = if let Some(payload) = material_payload {
333            let (material_count, range_count) = c::material_section_counts(payload)
334                .map_err(|e| format!("MAT1 header: {e:?}"))?;
335            if material_count > c::MAX_MATERIALS
336                || range_count > qualia_core_db::render::gpu::MAX_GPU_MATERIAL_DRAWS {
337                return Err("MAT1 counts exceed renderer limits".into());
338            }
339            let mut materials = vec![c::MaterialRecord::legacy_default(); material_count];
340            let mut ranges = vec![c::SubmeshRange { first_index: 0, index_count: 0,
341                material_id: materials.first().map(|m| m.id).unwrap_or(1), semantic_id: 0 }; range_count];
342            c::decode_material_section_into(payload, indices.len() as u32, &mut materials, &mut ranges)
343                .map_err(|e| format!("MAT1 decode: {e:?}"))?;
344            (materials, ranges, "canonical-MAT1")
345        } else {
346            let material = c::MaterialRecord::legacy_default();
347            let range = c::SubmeshRange { first_index: 0,
348                index_count: u32::try_from(indices.len()).map_err(|_| "mesh indices exceed u32")?,
349                material_id: material.id, semantic_id: 0 };
350            (vec![material], vec![range], "legacy-default-material")
351        };
352        let mut positions = mesh.positions.clone();
353        if let Some((clip_id, time)) = pose {
354            use qualia_core_db::render::skeletal::SkeletalPlayer;
355            let section = c::skeletal_container::read_skeletal_section(&verified)
356                .map_err(|e| format!("shot SKL1 read: {e:?}"))?;
357            // Player requires a tangent workspace even for untextured meshes. An
358            // internal zero UV workspace triggers its existing orthogonal fallback;
359            // it is never uploaded as an authored texture coordinate stream.
360            let fallback_uv = vec![[0.0; 2]; vertex_count];
361            let uv = texture_coordinates.as_deref().unwrap_or(&fallback_uv);
362            let fallback_normals = if normals.is_none() {
363                let mut derived = vec![[0.0; 3]; vertex_count];
364                qualia_core_db::etalon_render::surface_frames::surface::vertex_normals_from_indices_into(&positions, &indices, &mut derived)
365                    .map_err(|e| format!("shot normal derivation: {e:?}"))?;
366                Some(derived)
367            } else { None };
368            let bind_normals = normals.as_deref().or(fallback_normals.as_deref()).ok_or("shot normals missing")?;
369            let mut player = SkeletalPlayer::from_section(&section, &positions, bind_normals, uv, &indices)
370                .map_err(|e| format!("shot skeletal player: {e:?}"))?;
371            player.select_clip(clip_id, 0.0).map_err(|e| format!("shot clip: {e:?}"))?;
372            player.seek(time).map_err(|e| format!("shot time: {e:?}"))?;
373            player.advance(0.0, false).map_err(|e| format!("shot deformation: {e:?}"))?;
374            positions = player.positions().to_vec();
375            normals = Some(player.normals().to_vec());
376            tangents = Some(player.tangents().to_vec());
377        }
378        let min = mesh.min;
379        let max = mesh.max;
380        let target = [
381            (min[0] + max[0]) * 0.5,
382            (min[1] + max[1]) * 0.5,
383            (min[2] + max[2]) * 0.5,
384        ];
385        let extent = [
386            (max[0] - min[0]).abs(),
387            (max[1] - min[1]).abs(),
388            (max[2] - min[2]).abs(),
389        ];
390        if !target.iter().chain(extent.iter()).all(|value| value.is_finite()) {
391            return Err("10d mesh bounds cannot produce a finite camera".into());
392        }
393        // This preliminary value is replaced by the review render's FOV/aspect-aware
394        // bounding-sphere fit. Keeping a valid compatibility value here preserves the
395        // general loader's previous camera metadata semantics.
396        let requested_distance = extent[0].max(extent[1]).max(extent[2]).max(0.001) * 2.8;
397        if !requested_distance.is_finite() {
398            return Err("10d mesh bounds produce a non-finite camera distance".into());
399        }
400        let camera_distance = requested_distance.clamp(
401            qualia_core_db::render::camera::CAMERA_MIN_ZOOM,
402            qualia_core_db::render::camera::CAMERA_MAX_ZOOM,
403        );
404        let mut geometry = ReviewGeometry {
405            vertex_count: vertex_count as u32,
406            triangle_count: triangle_count as u32,
407            bounds_min: min,
408            bounds_max: max,
409            camera_target: target,
410            camera_aspect: 1.0,
411            vertical_tan_half_fov: qualia_core_db::render::camera::CAMERA_TAN_HALF_FOV,
412            camera_fit_margin: REVIEW_CAMERA_FIT_MARGIN,
413            requested_camera_distance: requested_distance,
414            camera_distance,
415            colors: colors_label,
416            normals: normals_label,
417            tangents: tangents_label,
418            texture_coordinates: if texture_coordinates.is_some() { "authored-UV01" } else { "absent" },
419            materials: materials_label,
420            lighting: REVIEW_LIGHTING,
421            screen_space_ao_available: self.inner.screen_space_ao_available(),
422            screen_space_ao_radius_m: 0.05,
423            screen_space_ao_strength: 0.75,
424            screen_space_ao_samples: 12,
425            shadows_available: self.inner.shadows_enabled(),
426        };
427        if profile.require_renderable_mesh {
428            apply_review_camera_fit(&mut geometry, 1.0)?;
429        }
430        let upload = self.inner.upload_mesh_colored_with_frames_and_materials_and_uv0(
431            &positions, &colors, normals.as_deref(), tangents.as_deref(),
432            texture_coordinates.as_deref(), &indices, &materials, &ranges,
433        ).map_err(|e| format!("10d GPU upload: {e}"))?;
434        if profile.require_renderable_mesh && upload == 0 {
435            return Err("10d review mesh upload produced no resident triangles".into());
436        }
437        Ok((geometry, provenance_mu))
438    }
439
440    pub fn render_10d_review_pngs(
441        &mut self,
442        bytes: &[u8],
443        side: u32,
444    ) -> Result<(ReviewGeometry, Vec<(ReviewView, Vec<u8>)>), String> {
445        let pixels = (side as usize).checked_mul(side as usize).ok_or("preview pixel overflow")?;
446        if side == 0 || side > MAX_REVIEW_SIDE || pixels > MAX_REVIEW_PIXELS {
447            return Err("preview dimensions exceed 2048x2048".into());
448        }
449        self.inner.set_tensor_projection_enabled(false);
450        self.inner.set_ambient_enabled(false);
451        let (mut geometry, _) = self.load_10d_review_asset(bytes)?;
452        self.inner.set_screen_space_ao_enabled(true);
453        self.inner.set_screen_space_ao(0.05,0.75,0.001);
454        self.inner.set_screen_space_ao_sample_count(12);
455        self.inner.set_shadows_enabled(true);
456        geometry.shadows_available=self.inner.shadows_enabled();
457        let aspect = side as f32 / side as f32;
458        apply_review_camera_fit(&mut geometry, aspect)?;
459
460        let lighting = geometry.lighting;
461        self.inner.set_clear_color(
462            lighting.clear_color[0] as f64,
463            lighting.clear_color[1] as f64,
464            lighting.clear_color[2] as f64,
465            lighting.clear_color[3] as f64,
466        );
467        self.inner.set_lighting(
468            lighting.sun_direction[0],
469            lighting.sun_direction[1],
470            lighting.sun_direction[2],
471            lighting.direct_intensity,
472            lighting.ambient_intensity,
473        );
474        self.inner.set_environment_probes(
475            None,
476            lighting.environment_additive_fallback_rgb,
477        );
478        let byte_len = pixels.checked_mul(4).ok_or("RGBA readback size overflow")?;
479        if self.required_rgba8_bytes() != byte_len {
480            return Err("renderer target extent differs from requested PNG dimensions".into());
481        }
482        let mut rgba = Vec::new();
483        rgba.try_reserve_exact(byte_len).map_err(|_| "RGBA buffer allocation refused")?;
484        rgba.resize(byte_len, 0);
485        let png_cap = pixels.checked_mul(5).ok_or("PNG cap overflow")?;
486        let mut outputs = Vec::new();
487        outputs.try_reserve_exact(REVIEW_VIEWS.len()).map_err(|_| "preview list allocation refused")?;
488        for view in REVIEW_VIEWS {
489            self.inner.set_camera_target(view.yaw, view.pitch, geometry.camera_distance,
490                geometry.camera_target[0], geometry.camera_target[1], geometry.camera_target[2]);
491            self.render(0.0, &SystemTelemetry::default())?;
492            let written = self.read_rgba8_into(&mut rgba)?;
493            if written != byte_len { return Err("GPU readback length differs from requested RGBA extent".into()); }
494            let mut png = CappedPngWriter::new(png_cap);
495            image::codecs::png::PngEncoder::new(&mut png).write_image(
496                &rgba, side, side, image::ExtendedColorType::Rgba8,
497            ).map_err(|e| format!("bounded PNG encoding failed: {e}"))?;
498            outputs.push((view, png.into_inner()));
499        }
500        Ok((geometry, outputs))
501    }
502}