Skip to main content

webizen_render/
volumetric_shot.rs

1//! Bounded, explicitly authored native review shots.
2use super::{SystemTelemetry, VolumetricRenderer, ReviewGeometry};
3use image::ImageEncoder;
4use qualia_core_db::render::lighting::environment_lighting::{EnvironmentProbe, EnvironmentProbeSet, MAX_ENVIRONMENT_PROBES};
5use super::volumetric_native_preview::CappedPngWriter;
6fn default_true() -> bool { true }
7fn default_radius() -> f32 { 0.05 }
8fn default_strength() -> f32 { 0.75 }
9fn default_bias() -> f32 { 0.001 }
10fn default_samples() -> u32 { 12 }
11#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
12#[serde(deny_unknown_fields)]
13pub struct ShotProbe {
14    pub position: [f32; 3], pub radius: f32, pub irradiance: [f32; 3],
15    pub specular_levels: [[f32; 3]; 5], pub dominant_direction: [f32; 3],
16}
17
18#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
19#[serde(deny_unknown_fields)]
20pub struct NativeShot {
21    pub side: u32,
22    pub camera_yaw: f32,
23    pub camera_pitch: f32,
24    pub camera_distance: f32,
25    pub camera_target: [f32; 3],
26    pub sun_direction: [f32; 3],
27    pub direct_intensity: f32,
28    pub ambient_intensity: f32,
29    pub clear_color: [f32; 4],
30    #[serde(default = "default_true")] pub shadows: bool,
31    #[serde(default = "default_true")] pub ao_enabled: bool,
32    #[serde(default = "default_radius")] pub ao_radius: f32,
33    #[serde(default = "default_strength")] pub ao_strength: f32,
34    #[serde(default = "default_bias")] pub ao_bias: f32,
35    #[serde(default = "default_samples")] pub ao_samples: u32,
36    #[serde(default)] pub environment_probes: Vec<ShotProbe>,
37    #[serde(default)] pub environment_fallback_rgb: [f32; 3],
38    /// Omit for a static still; otherwise one output per time using this SKL1 clip.
39    pub clip_id: Option<u64>,
40    pub times: Vec<f64>,
41}
42impl NativeShot {
43    pub fn validate(&self) -> Result<(), String> {
44        let finite = self.camera_target.iter().chain(self.sun_direction.iter()).chain(self.clear_color.iter()).all(|x| x.is_finite());
45        let norm = self.sun_direction.iter().map(|v| v*v).sum::<f32>();
46        let probes_valid = self.environment_probes.len() <= MAX_ENVIRONMENT_PROBES && self.environment_fallback_rgb.iter().all(|v| v.is_finite() && *v >= 0.0 && *v <= 100.0) && self.environment_probes.iter().all(|p| {
47            p.radius.is_finite() && p.radius > 0.0 && p.radius <= 1e8 && p.position.iter().chain(p.dominant_direction.iter()).all(|v| v.is_finite() && v.abs() <= 1e8)
48            && p.irradiance.iter().chain(p.specular_levels.iter().flatten()).all(|v| v.is_finite() && *v >= 0.0 && *v <= 100.0)
49            && p.dominant_direction.iter().map(|v| v*v).sum::<f32>() > 1e-12
50        });
51        if !probes_valid || !finite || self.camera_target.iter().any(|v| v.abs() > 1e8) || !self.camera_yaw.is_finite() || self.camera_yaw.abs() > 1e6 || !self.camera_pitch.is_finite() || !self.camera_distance.is_finite()
52            || !self.direct_intensity.is_finite() || !self.ambient_intensity.is_finite()
53            || self.side == 0 || self.side > 2048 || self.times.is_empty() || self.times.len() > 16
54            || (self.side as u64 * self.side as u64 * 4 * self.times.len() as u64) > 64 * 1024 * 1024
55            || !(-1.45..=1.45).contains(&self.camera_pitch)
56            || self.times.iter().any(|t| !t.is_finite() || *t < 0.0 || *t > 86400.0)
57            || self.times.windows(2).any(|p| p[0] > p[1])
58            || !(0.0001..=1e8).contains(&norm)
59            || !(0.05..=2.0).contains(&self.ao_radius) || !(0.0..=1.0).contains(&self.ao_strength) || !(0.0..=0.2).contains(&self.ao_bias) || ![4,8,12].contains(&self.ao_samples)
60            || !(0.0..=100.0).contains(&self.direct_intensity) || !(0.0..=100.0).contains(&self.ambient_intensity)
61            || self.clear_color.iter().any(|v| !(0.0..=1.0).contains(v))
62            || !(qualia_core_db::render::camera::CAMERA_MIN_ZOOM..=qualia_core_db::render::camera::CAMERA_MAX_ZOOM).contains(&self.camera_distance)
63 {
64            return Err("invalid or out-of-budget native shot".into());
65        }
66        Ok(())
67    }
68}
69impl VolumetricRenderer {
70    /// Render explicit timestamps from immutable bind geometry. Texture resources,
71    /// when used, must first be admitted with `load_hmc_asset_with_texture_budget`.
72    pub fn render_10d_shot(&mut self, bytes: &[u8], shot: &NativeShot) -> Result<(ReviewGeometry, Vec<Vec<u8>>), String> {
73        shot.validate()?;
74        let pixels = (shot.side as usize).checked_mul(shot.side as usize).ok_or("shot dimensions overflow")?;
75        let len = pixels.checked_mul(4).ok_or("shot frame overflow")?;
76        if self.required_rgba8_bytes() != len { return Err("shot renderer target size differs".into()); }
77        self.inner.set_tensor_projection_enabled(false);
78        self.inner.set_ambient_enabled(false);
79        self.inner.set_screen_space_ao_enabled(shot.ao_enabled);
80        self.inner.set_screen_space_ao(shot.ao_radius, shot.ao_strength, shot.ao_bias);
81        self.inner.set_screen_space_ao_sample_count(shot.ao_samples);
82        self.inner.set_shadows_enabled(shot.shadows);
83        self.inner.set_clear_color(shot.clear_color[0] as f64, shot.clear_color[1] as f64, shot.clear_color[2] as f64, shot.clear_color[3] as f64);
84        self.inner.set_lighting(shot.sun_direction[0], shot.sun_direction[1], shot.sun_direction[2], shot.direct_intensity, shot.ambient_intensity);
85        let mut probes = EnvironmentProbeSet::new();
86        for p in &shot.environment_probes {
87            if !probes.push(EnvironmentProbe { position: p.position, radius: p.radius, irradiance: p.irradiance, specular_levels: p.specular_levels, dominant_direction: p.dominant_direction, valid: true }) { return Err("environment probe limit exceeded".into()); }
88        }
89        self.inner.set_camera_target(shot.camera_yaw, shot.camera_pitch, shot.camera_distance, shot.camera_target[0], shot.camera_target[1], shot.camera_target[2]);
90        let mut rgba = vec![0; len];
91        let mut frames = Vec::with_capacity(shot.times.len());
92        let mut encoded_total = 0usize;
93        let mut geometry = None;
94        for &time in &shot.times {
95            let mut g = if let Some(clip) = shot.clip_id { self.load_10d_shot_pose(bytes, clip, time)? } else { self.load_10d_review_asset(bytes)?.0 };
96            g.camera_target = shot.camera_target;
97            g.requested_camera_distance = shot.camera_distance;
98            g.camera_distance = shot.camera_distance;
99            g.lighting.sun_direction = shot.sun_direction;
100            g.lighting.direct_intensity = shot.direct_intensity;
101            g.lighting.ambient_intensity = shot.ambient_intensity;
102            g.lighting.clear_color = shot.clear_color;
103            g.lighting.environment_additive_fallback_rgb = shot.environment_fallback_rgb;
104            g.screen_space_ao_radius_m = shot.ao_radius;
105            g.screen_space_ao_strength = shot.ao_strength;
106            g.screen_space_ao_samples = shot.ao_samples;
107            g.shadows_available = self.inner.shadows_enabled();
108            // Upload replaces material bindings, so probes must be set after each frame upload.
109            self.inner.set_environment_probes(Some(&probes), shot.environment_fallback_rgb);
110            self.render(time as f32, &SystemTelemetry::default())?;
111            if self.read_rgba8_into(&mut rgba)? != len { return Err("shot readback size mismatch".into()); }
112            let mut png = CappedPngWriter::new(pixels.checked_mul(5).ok_or("PNG cap overflow")?);
113            image::codecs::png::PngEncoder::new(&mut png).write_image(&rgba, shot.side, shot.side, image::ExtendedColorType::Rgba8).map_err(|e| format!("shot PNG: {e}"))?;
114            let png = png.into_inner();
115            encoded_total = encoded_total.checked_add(png.len()).ok_or("shot PNG total overflow")?;
116            if encoded_total > 64 * 1024 * 1024 { return Err("shot PNGs exceed aggregate output budget".into()); }
117            frames.push(png);
118            geometry = Some(g);
119        }
120        Ok((geometry.ok_or("empty shot")?, frames))
121    }
122}
123
124#[cfg(test)]
125mod tests {
126    use super::*;
127    #[test]
128    fn shot_admission_rejects_invalid_frames_and_camera() {
129        let mut s = NativeShot { side: 64, camera_yaw: 0.0, camera_pitch: 0.0, camera_distance: 2.0, camera_target: [0.0;3], sun_direction: [0.0,1.0,0.0], direct_intensity: 1.0, ambient_intensity: 0.2, clear_color: [0.0,0.0,0.0,1.0], shadows:true, ao_enabled:true, ao_radius:0.05, ao_strength:0.75, ao_bias:0.001, ao_samples:12, environment_probes:vec![], environment_fallback_rgb:[0.0;3], clip_id: Some(1), times: vec![0.0,0.5,1.0] };
130        assert!(s.validate().is_ok());
131        s.times = vec![1.0,0.0]; assert!(s.validate().is_err());
132        s.times = vec![0.0]; s.sun_direction = [0.0;3]; assert!(s.validate().is_err());
133    }
134}