Skip to main content

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}