sim_logic/rendering/feedback.rs
1//! Optional application-owned recovery from presentation budget exhaustion.
2use crate::identity::WorldGeneration;
3use sim_engine::SceneBudgetResource;
4
5/// Work counters that can reject a composed frame before presentation.
6#[derive(Debug, Clone, Copy, PartialEq, Eq)]
7pub enum PresentationBudgetResource {
8 /// An Engine CPU scene construction limit.
9 Scene(SceneBudgetResource),
10 /// Composed frame items/passes.
11 Passes,
12 /// Source commands.
13 Commands,
14 /// Submitted vertices.
15 Vertices,
16 /// Host-to-GPU upload bytes.
17 UploadBytes,
18 /// Referenced texture bytes.
19 TextureBytes,
20 /// Draw calls.
21 DrawCalls,
22}
23
24/// The boundary that rejected one complete presentation attempt.
25#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub enum PresentationBudgetStage {
27 /// Extraction of world-space geometry.
28 WorldScene,
29 /// Extraction of fixed-screen geometry.
30 ScreenScene,
31 /// Combined native frame preflight/submission.
32 Composition,
33}
34
35/// Exact budget rejection available to the next application update.
36#[derive(Debug, Clone, Copy, PartialEq, Eq)]
37pub struct PresentationBudgetRejection {
38 /// Logical frame that completed its application work but could not be drawn.
39 pub frame_index: u64,
40 /// World that produced the rejected attempt, not the previously visible World.
41 pub generation: WorldGeneration,
42 /// Rejected construction/composition boundary.
43 pub stage: PresentationBudgetStage,
44 /// Which allowance was exceeded.
45 pub resource: PresentationBudgetResource,
46 /// Configured inclusive ceiling.
47 pub limit: usize,
48 /// Required work at the failing boundary (not necessarily the whole scene).
49 pub requested: usize,
50}
51
52/// Opt-in recoverable presentation budgets, independent of GPU dependencies.
53///
54/// Register this as an Application Resource to keep the stock desktop host alive
55/// after typed scene/composition budget rejections. Read via `AppRes` next frame
56/// to reduce presentation work, close a document, request another World or exit.
57/// No limits are raised, no geometry is silently dropped and canonical updates
58/// are not rolled back. Fixed and frame systems continue; pausing is app policy.
59///
60/// A rejected attempt is not presented. The last CPU snapshot survives failed
61/// extraction, but the host never replays a stale-generation frame. The window
62/// manager may retain the previous surface image; this is not guaranteed after
63/// resize or loss. Allocation, invalid-geometry, system and invariant errors
64/// remain errors. Without this optional resource, desktop stays fail-fast.
65#[derive(Debug, Default)]
66pub struct PresentationFeedback {
67 last_rejection: Option<PresentationBudgetRejection>,
68 rejected_frames: u64,
69}
70
71impl PresentationFeedback {
72 /// Last rejection, cleared only after a confirmed native presentation.
73 /// Headless operation never invents a native submission result.
74 pub const fn last_rejection(&self) -> Option<PresentationBudgetRejection> {
75 self.last_rejection
76 }
77 /// Saturating lifetime count, independent of temporary surface skips.
78 pub const fn rejected_frames(&self) -> u64 {
79 self.rejected_frames
80 }
81 #[cfg(feature = "desktop")]
82 pub(crate) fn reject(&mut self, rejection: PresentationBudgetRejection) {
83 self.last_rejection = Some(rejection);
84 self.rejected_frames = self.rejected_frames.saturating_add(1);
85 }
86 #[cfg(feature = "desktop")]
87 pub(crate) fn presented(&mut self) {
88 self.last_rejection = None;
89 }
90}