Skip to main content

webizen_render/pipeline/
frame_schedule.rs

1//! Frame graph scheduling and capability integration for the Webizen renderer.
2//!
3//! Exposes pass compilation, budget enforcement, and quality profile adaptation
4//! across native and WASM render adapters. Strictly zero-heap in execution.
5
6#[cfg(feature = "qualia")]
7use qualia_core_db::render::frame_graph::{
8    CompiledSchedule, FrameGraphBuilder, FrameGraphError, TemporalOutputSchedule,
9};
10#[cfg(feature = "qualia")]
11use qualia_core_db::render::quality_profiles::RenderQualityProfile;
12#[cfg(feature = "qualia")]
13use qualia_core_db::render::temporal_resolve::TemporalResolveConfig;
14
15#[cfg(feature = "qualia")]
16use super::temporal_contract::{
17    FrameExtent, TemporalCapabilityRefusal, TemporalContractError, TemporalFrameContract,
18};
19
20/// Errors from webizen temporal admission or the underlying Qualia graph compiler.
21#[cfg(feature = "qualia")]
22#[derive(Clone, Copy, Debug, PartialEq, Eq)]
23pub enum WebizenFrameScheduleError {
24    FrameGraph(FrameGraphError),
25    Contract(TemporalContractError),
26    Temporal(TemporalCapabilityRefusal),
27}
28
29#[cfg(feature = "qualia")]
30impl From<FrameGraphError> for WebizenFrameScheduleError {
31    fn from(error: FrameGraphError) -> Self {
32        Self::FrameGraph(error)
33    }
34}
35
36/// A compiled Qualia schedule carried together with the real producer contract that admitted it.
37///
38/// This type contains no owned GPU resource and performs no recording. An adapter may use the
39/// borrowed producer views and `schedule` later at its existing Qualia GPU seam.
40#[cfg(feature = "qualia")]
41#[derive(Clone, Copy)]
42pub struct WebizenFramePlan<'a> {
43    pub schedule: CompiledSchedule,
44    pub temporal: TemporalFrameContract<'a>,
45}
46
47#[cfg(feature = "qualia")]
48impl<'a> WebizenFramePlan<'a> {
49    /// Temporal contract.
50    pub const fn temporal_contract(&self) -> TemporalFrameContract<'a> {
51        self.temporal
52    }
53}
54
55/// High-level renderer pass scheduler.
56#[cfg(feature = "qualia")]
57pub struct WebizenFrameScheduler {
58    builder: FrameGraphBuilder,
59}
60
61/// Return the only temporal handoff that a backend may submit for a compiled frame.
62///
63/// The scheduler does not own GPU attachments. It supplies the ordered contract; the host must
64/// provide real producer views through `PortalGpu::record_scheduled_temporal_output`.
65#[cfg(feature = "qualia")]
66pub fn temporal_submission_schedule(
67    schedule: &CompiledSchedule,
68) -> Option<TemporalOutputSchedule> {
69    (schedule.temporal.is_complete() && schedule.temporal_order_is_valid())
70        .then_some(schedule.temporal)
71}
72
73#[cfg(feature = "qualia")]
74impl Default for WebizenFrameScheduler {
75    fn default() -> Self {
76        Self::new()
77    }
78}
79
80#[cfg(feature = "qualia")]
81impl WebizenFrameScheduler {
82    /// Creates a new instance.
83    pub const fn new() -> Self {
84        Self {
85            builder: FrameGraphBuilder::new(),
86        }
87    }
88
89    /// Build a frame execution schedule from the given quality profile and viewport dimensions.
90    pub fn plan_frame(
91        &mut self,
92        profile: &RenderQualityProfile,
93        viewport_width: u32,
94        viewport_height: u32,
95        vram_budget: Option<u64>,
96    ) -> Result<CompiledSchedule, FrameGraphError> {
97        self.builder = FrameGraphBuilder::new();
98        self.builder
99            .configure_from_profile(profile, viewport_width, viewport_height)?;
100        self.builder.compile(vram_budget)
101    }
102
103    /// Build a schedule with an explicitly admitted temporal resolve/output path.
104    ///
105    /// Callers must declare motion-vector and reactive-mask ownership. Missing inputs preserve
106    /// the existing direct/bloom output schedule instead of silently accumulating stale history.
107    pub fn plan_frame_with_temporal(
108        &mut self,
109        profile: &RenderQualityProfile,
110        viewport_width: u32,
111        viewport_height: u32,
112        vram_budget: Option<u64>,
113        temporal: TemporalResolveConfig,
114    ) -> Result<CompiledSchedule, FrameGraphError> {
115        self.builder = FrameGraphBuilder::new();
116        self.builder.configure_from_profile_with_temporal(
117            profile,
118            viewport_width,
119            viewport_height,
120            temporal,
121        )?;
122        self.builder.compile(vram_budget)
123    }
124
125    /// Build a Qualia schedule only after admitting real typed temporal producer views.
126    ///
127    /// The contract's views are borrowed and never copied into GPU resources. Missing producer
128    /// capabilities, history lifecycle mistakes, and extent mismatches refuse deterministically
129    /// before the existing Qualia frame graph is invoked.
130    pub fn plan_frame_with_temporal_contract<'a>(
131        &mut self,
132        profile: &RenderQualityProfile,
133        viewport_width: u32,
134        viewport_height: u32,
135        vram_budget: Option<u64>,
136        temporal: TemporalFrameContract<'a>,
137    ) -> Result<WebizenFramePlan<'a>, WebizenFrameScheduleError> {
138        let expected_extent = FrameExtent::scaled(
139            viewport_width,
140            viewport_height,
141            profile.render_scale_bps,
142        )
143        .map_err(WebizenFrameScheduleError::Contract)?;
144        let admission = temporal
145            .admit(expected_extent)
146            .map_err(WebizenFrameScheduleError::Temporal)?;
147        let schedule = self.plan_frame_with_temporal(
148            profile,
149            viewport_width,
150            viewport_height,
151            vram_budget,
152            TemporalResolveConfig {
153                enabled: true,
154                motion_vectors_available: true,
155                reactive_mask_available: true,
156                history_valid: admission.reads_history,
157                reset_history: admission.reset_history,
158            },
159        )?;
160        if temporal_submission_schedule(&schedule).is_none() {
161            return Err(WebizenFrameScheduleError::Temporal(
162                TemporalCapabilityRefusal::QualiaScheduleIncomplete,
163            ));
164        }
165        Ok(WebizenFramePlan { schedule, temporal })
166    }
167
168    /// Access the underlying builder to inject custom passes or resources.
169    pub fn builder_mut(&mut self) -> &mut FrameGraphBuilder {
170        &mut self.builder
171    }
172}
173
174#[cfg(all(test, feature = "qualia"))]
175mod tests {
176    use super::*;
177    use qualia_core_db::render::quality_profiles::QualityTier;
178    use super::super::temporal_contract::{
179        TemporalHistoryContract, TemporalProducerCapabilities, TemporalProducerContract,
180        TemporalResource,
181    };
182
183    #[test]
184    fn scheduler_produces_valid_plan_from_high_profile() {
185        let mut scheduler = WebizenFrameScheduler::new();
186        let profile = RenderQualityProfile {
187            tier: QualityTier::High,
188            render_scale_bps: 10_000,
189            shadows_enabled: true,
190            shadow_map_dimension: 2048,
191            shadow_cascade_count: 2,
192            ambient_occlusion_enabled: true,
193            ao_scale_bps: 5_000,
194            bloom_enabled: true,
195            bloom_levels: 3,
196            texture_residency_bytes: 1024 * 1024 * 1024,
197            hdr_enabled: true,
198            volume_projection_enabled: false,
199        };
200
201        let schedule = scheduler
202            .plan_frame(&profile, 1920, 1080, None)
203            .expect("plan frame");
204
205        assert!(schedule.pass_count > 0);
206        assert!(schedule.total_resource_bytes > 0);
207        assert!(temporal_submission_schedule(&schedule).is_none());
208    }
209
210    #[test]
211    fn scheduler_can_admit_temporal_output_only_with_declared_inputs() {
212        let mut scheduler = WebizenFrameScheduler::new();
213        let profile = RenderQualityProfile {
214            tier: QualityTier::Balanced,
215            render_scale_bps: 8_500,
216            shadows_enabled: false,
217            shadow_map_dimension: 0,
218            shadow_cascade_count: 0,
219            ambient_occlusion_enabled: false,
220            ao_scale_bps: 0,
221            bloom_enabled: false,
222            bloom_levels: 0,
223            texture_residency_bytes: 128 * 1024 * 1024,
224            hdr_enabled: false,
225            volume_projection_enabled: false,
226        };
227        let schedule = scheduler
228            .plan_frame_with_temporal(
229                &profile,
230                800,
231                450,
232                None,
233                TemporalResolveConfig {
234                    enabled: true,
235                    motion_vectors_available: true,
236                    reactive_mask_available: true,
237                    history_valid: false,
238                    reset_history: true,
239                },
240            )
241            .expect("temporal schedule");
242        let passes = &schedule.passes[..schedule.pass_count];
243        assert!(passes.iter().any(|pass| {
244            *pass == Some(qualia_core_db::render::frame_graph::PassId::TemporalResolve)
245        }));
246        assert!(passes.iter().any(|pass| {
247            *pass == Some(qualia_core_db::render::frame_graph::PassId::HistoryPublication)
248        }));
249        let temporal = temporal_submission_schedule(&schedule).expect("ordered temporal seam");
250        assert!(temporal.enabled);
251        assert!(temporal.reset_history);
252        assert!(!temporal.reads_history);
253        assert!(temporal.publish_history && temporal.final_output);
254        assert!(schedule.temporal_order_is_valid());
255    }
256
257    #[test]
258    fn typed_contract_connects_to_qualia_schedule_without_gpu_data() {
259        let mut scheduler = WebizenFrameScheduler::new();
260        let profile = RenderQualityProfile {
261            tier: QualityTier::Balanced,
262            render_scale_bps: 8_500,
263            shadows_enabled: false,
264            shadow_map_dimension: 0,
265            shadow_cascade_count: 0,
266            ambient_occlusion_enabled: false,
267            ao_scale_bps: 0,
268            bloom_enabled: false,
269            bloom_levels: 0,
270            texture_residency_bytes: 128 * 1024 * 1024,
271            hdr_enabled: false,
272            volume_projection_enabled: false,
273        };
274        let extent = FrameExtent::scaled(800, 450, profile.render_scale_bps).unwrap();
275        let capabilities = TemporalProducerCapabilities {
276            extent: Some(extent),
277            linear_depth: false,
278            motion_vectors: false,
279            reactive_mask: false,
280        };
281        let contract = TemporalFrameContract::new(
282            TemporalProducerContract::for_extent(extent),
283            TemporalHistoryContract::first_frame(0),
284        );
285        assert_eq!(contract.producers.capabilities(), capabilities);
286        let result = scheduler.plan_frame_with_temporal_contract(
287            &profile,
288            800,
289            450,
290            None,
291            contract,
292        );
293        match result {
294            Err(error) => assert_eq!(
295                error,
296                WebizenFrameScheduleError::Temporal(
297                    TemporalCapabilityRefusal::MissingProducer {
298                        resource: TemporalResource::LinearDepth,
299                    }
300                )
301            ),
302            Ok(_) => panic!("partial producer contract must refuse temporal scheduling"),
303        }
304    }
305}