Skip to main content

sim_logic/rendering/extraction/
screen.rs

1use std::mem::size_of;
2
3use sim_engine::{
4    Color, Layer, LogicalScreenPosition, LogicalScreenVector, SceneBudgetResource, SceneError,
5    ScreenScene,
6};
7
8use crate::{
9    identity::{LogicEntity, WorldGeneration},
10    render::RenderLimits,
11    screen::ScreenRectangleVisual,
12};
13
14use super::{ExtractionError, compare_visual_order};
15
16#[path = "screen_cache.rs"]
17mod cache;
18pub use cache::ScreenExtractionUpdates;
19
20#[path = "images.rs"]
21mod images;
22pub use images::ResolvedScreenImage;
23pub(crate) use images::ScreenImageSource;
24#[cfg(feature = "headless-text")]
25#[path = "text.rs"]
26mod text;
27#[cfg(feature = "headless-text")]
28pub use text::ResolvedScreenText;
29#[cfg(feature = "headless-text")]
30pub(crate) use text::ScreenTextSource;
31#[path = "composition.rs"]
32mod composition;
33use composition::RectangleRun;
34pub use composition::ScreenDraw;
35#[path = "primitives.rs"]
36mod primitives;
37pub use primitives::ResolvedScreenPrimitive;
38
39#[derive(Debug, Clone, PartialEq)]
40pub(crate) enum ScreenSource {
41    Rectangle(ScreenRectangleSource),
42    Line(LogicEntity, crate::screen::ScreenLineVisual),
43    Circle(LogicEntity, crate::screen::ScreenCircleVisual),
44    Polyline(LogicEntity, crate::screen::ScreenPolylineVisual),
45    Image(ScreenImageSource),
46    #[cfg(feature = "headless-text")]
47    Text(ScreenTextSource),
48}
49
50impl From<ScreenRectangleSource> for ScreenSource {
51    fn from(source: ScreenRectangleSource) -> Self {
52        Self::Rectangle(source)
53    }
54}
55
56/// One screen-fixed rectangle retained for headless inspection.
57///
58/// The rectangle uses logical pixels with a top-left origin and downward y.
59/// It is sampled directly, independently of camera motion or fixed-time alpha.
60#[derive(Debug, Clone, Copy, PartialEq)]
61pub struct ResolvedScreenRectangle {
62    source: LogicEntity,
63    visual: ScreenRectangleVisual,
64}
65
66impl ResolvedScreenRectangle {
67    /// Returns the exact sampled component, including radius, outline and clip.
68    pub const fn visual(&self) -> &ScreenRectangleVisual {
69        &self.visual
70    }
71    /// Returns the managed entity that produced this screen rectangle.
72    pub const fn source(self) -> LogicEntity {
73        self.source
74    }
75
76    /// Returns the top-left position in logical screen pixels.
77    pub const fn position(self) -> LogicalScreenPosition {
78        self.visual.position()
79    }
80
81    /// Returns the full positive width and height in logical pixels.
82    pub const fn size(self) -> LogicalScreenVector {
83        self.visual.size()
84    }
85
86    /// Returns the normalized straight-linear RGBA fill color.
87    pub const fn color(self) -> Color {
88        self.visual.color()
89    }
90
91    /// Returns the primary ordering layer within the screen scene.
92    pub const fn layer(self) -> Layer {
93        self.visual.layer()
94    }
95
96    /// Returns the finite secondary ordering value within its screen layer.
97    ///
98    /// This is draw order, not camera depth. All screen layers follow world content.
99    pub const fn draw_order_depth(self) -> f32 {
100        self.visual.draw_order_depth()
101    }
102}
103
104#[derive(Debug, Clone, Copy, PartialEq)]
105pub(crate) struct ScreenRectangleSource {
106    entity: LogicEntity,
107    visual: ScreenRectangleVisual,
108}
109
110impl ScreenRectangleSource {
111    pub(crate) const fn new(entity: LogicEntity, visual: &ScreenRectangleVisual) -> Self {
112        Self {
113            entity,
114            visual: *visual,
115        }
116    }
117}
118
119pub(super) struct ScreenExtractionBuffer {
120    resolved: Vec<ResolvedScreenRectangle>,
121    primitives: Vec<ResolvedScreenPrimitive>,
122    scene: ScreenScene,
123    images: Vec<ResolvedScreenImage>,
124    #[cfg(feature = "headless-text")]
125    texts: Vec<ResolvedScreenText>,
126    draws: Vec<ScreenDraw>,
127    runs: Vec<RectangleRun>,
128    source_keys: Vec<ScreenSource>,
129    source_scratch: Vec<ScreenSource>,
130    cache_scope: Option<(WorldGeneration, RenderLimits)>,
131    pub(super) updates: ScreenExtractionUpdates,
132}
133
134impl ScreenExtractionBuffer {
135    pub(super) fn new(limits: RenderLimits) -> Result<Self, ExtractionError> {
136        Ok(Self {
137            resolved: Vec::new(),
138            primitives: Vec::new(),
139            images: Vec::new(),
140            #[cfg(feature = "headless-text")]
141            texts: Vec::new(),
142            draws: Vec::new(),
143            runs: Vec::new(),
144            source_keys: Vec::new(),
145            source_scratch: Vec::new(),
146            cache_scope: None,
147            updates: ScreenExtractionUpdates::default(),
148            scene: ScreenScene::with_budget(Color::TRANSPARENT, limits.screen_scene_budget())
149                .map_err(ExtractionError::ScreenScene)?,
150        })
151    }
152
153    pub(super) fn clear(&mut self) {
154        self.cache_scope = None;
155        self.source_keys.clear();
156        self.source_scratch.clear();
157        self.clear_sources();
158        self.scene.clear();
159        self.runs.clear();
160    }
161
162    fn clear_sources(&mut self) {
163        self.resolved.clear();
164        self.primitives.clear();
165        self.images.clear();
166        #[cfg(feature = "headless-text")]
167        self.texts.clear();
168        self.draws.clear();
169    }
170
171    pub(super) fn resolved(&self) -> &[ResolvedScreenRectangle] {
172        &self.resolved
173    }
174
175    pub(super) fn geometry(&self, index: usize) -> Option<ResolvedScreenPrimitive> {
176        if self.primitives.is_empty() {
177            self.resolved
178                .get(index)
179                .copied()
180                .map(ResolvedScreenPrimitive::Rectangle)
181        } else {
182            self.primitives.get(index).cloned()
183        }
184    }
185
186    pub(super) fn geometry_len(&self) -> usize {
187        if self.primitives.is_empty() {
188            self.resolved.len()
189        } else {
190            self.primitives.len()
191        }
192    }
193
194    pub(super) fn primitive_records(&self) -> impl Iterator<Item = ResolvedScreenPrimitive> + '_ {
195        (0..self.geometry_len()).filter_map(|index| self.geometry(index))
196    }
197
198    pub(super) fn primitive_run_records(
199        &self,
200        run: usize,
201    ) -> Option<impl Iterator<Item = ResolvedScreenPrimitive> + '_> {
202        let range = if self.has_non_rectangles() {
203            let run = self.runs.get(run)?;
204            run.start..run.end
205        } else if run == 0 && self.geometry_len() != 0 {
206            0..self.geometry_len()
207        } else {
208            return None;
209        };
210        Some(range.filter_map(|index| self.geometry(index)))
211    }
212
213    fn geometry_draw(&self, run: usize) -> ScreenDraw {
214        if self.primitives.is_empty() {
215            ScreenDraw::Rectangles { run }
216        } else {
217            ScreenDraw::Primitives { run }
218        }
219    }
220
221    pub(super) fn images(&self) -> &[ResolvedScreenImage] {
222        &self.images
223    }
224    #[cfg(feature = "headless-text")]
225    pub(super) fn texts(&self) -> &[ResolvedScreenText] {
226        &self.texts
227    }
228
229    fn has_non_rectangles(&self) -> bool {
230        #[cfg(feature = "headless-text")]
231        if !self.texts.is_empty() {
232            return true;
233        }
234        !self.images.is_empty()
235    }
236    pub(super) fn draws(&self) -> &[ScreenDraw] {
237        &self.draws
238    }
239    pub(super) fn run_records(&self, run: usize) -> Option<&[ResolvedScreenRectangle]> {
240        if !self.has_non_rectangles() {
241            return (run == 0 && self.geometry_len() != 0).then_some(self.resolved.as_slice());
242        }
243        let run = self.runs.get(run)?;
244        if self.primitives.is_empty() {
245            return self.resolved.get(run.start..run.end);
246        }
247        let start = self.primitives[..run.start]
248            .iter()
249            .filter(|value| matches!(value, ResolvedScreenPrimitive::Rectangle(_)))
250            .count();
251        let count = self.primitives[run.start..run.end]
252            .iter()
253            .filter(|value| matches!(value, ResolvedScreenPrimitive::Rectangle(_)))
254            .count();
255        self.resolved.get(start..start + count)
256    }
257
258    #[cfg(feature = "desktop")]
259    pub(super) fn run_scene(&self, run: usize) -> Option<&ScreenScene> {
260        if !self.has_non_rectangles() {
261            return (run == 0 && self.geometry_len() != 0).then_some(&self.scene);
262        }
263        self.runs.get(run).map(|run| &run.scene)
264    }
265
266    #[cfg(feature = "desktop")]
267    pub(super) const fn scene(&self) -> &ScreenScene {
268        &self.scene
269    }
270
271    fn collect_sources(
272        &mut self,
273        generation: WorldGeneration,
274        limits: RenderLimits,
275        sources: impl IntoIterator<Item = ScreenSource>,
276    ) -> Result<(), ExtractionError> {
277        debug_assert_eq!(self.scene.budget(), Some(limits.screen_scene_budget()));
278        let mut line_count = 0usize;
279        let mut circle_count = 0usize;
280        let mut path_count = 0usize;
281        let mut path_points = 0usize;
282        #[cfg(feature = "headless-text")]
283        let mut text_bytes = 0usize;
284        #[cfg(feature = "headless-text")]
285        let mut text_glyphs = 0usize;
286        for source in sources {
287            let key = source.clone();
288            let source = match source {
289                ScreenSource::Rectangle(source) => source,
290                ScreenSource::Polyline(entity, visual) => {
291                    if entity.world_generation() != generation {
292                        return Err(ExtractionError::ForeignEntity {
293                            entity,
294                            expected: generation,
295                        });
296                    }
297                    path_count += 1;
298                    path_points = path_points.checked_add(visual.points().len()).ok_or(
299                        ExtractionError::ScreenPolylinePointsLimitExceeded {
300                            entity,
301                            limit: limits.max_screen_polyline_points(),
302                            requested: usize::MAX,
303                        },
304                    )?;
305                    if path_points > limits.max_screen_polyline_points() {
306                        return Err(ExtractionError::ScreenPolylinePointsLimitExceeded {
307                            entity,
308                            limit: limits.max_screen_polyline_points(),
309                            requested: path_points,
310                        });
311                    }
312                    self.push_vector(
313                        generation,
314                        entity,
315                        ResolvedScreenPrimitive::Polyline {
316                            source: entity,
317                            visual,
318                        },
319                        path_count,
320                        limits.max_screen_polylines(),
321                        limits.screen_scene_budget().max_commands(),
322                    )?;
323                    self.remember_source(key)?;
324                    continue;
325                }
326                ScreenSource::Line(entity, visual) => {
327                    line_count += 1;
328                    self.push_vector(
329                        generation,
330                        entity,
331                        ResolvedScreenPrimitive::Line {
332                            source: entity,
333                            visual,
334                        },
335                        line_count,
336                        limits.max_screen_lines(),
337                        limits.screen_scene_budget().max_commands(),
338                    )?;
339                    self.remember_source(key)?;
340                    continue;
341                }
342                ScreenSource::Circle(entity, visual) => {
343                    circle_count += 1;
344                    self.push_vector(
345                        generation,
346                        entity,
347                        ResolvedScreenPrimitive::Circle {
348                            source: entity,
349                            visual,
350                        },
351                        circle_count,
352                        limits.max_screen_circles(),
353                        limits.screen_scene_budget().max_commands(),
354                    )?;
355                    self.remember_source(key)?;
356                    continue;
357                }
358                ScreenSource::Image(source) => {
359                    if self.images.len() == limits.max_screen_images() {
360                        return Err(ExtractionError::ScreenImageLimitExceeded {
361                            limit: limits.max_screen_images(),
362                        });
363                    }
364                    let image = source.resolve(generation)?;
365                    self.images
366                        .try_reserve(1)
367                        .map_err(|_| ExtractionError::AllocationFailed {
368                            requested_bytes: size_of::<ResolvedScreenImage>(),
369                        })?;
370                    self.images.push(image);
371                    self.remember_source(key)?;
372                    continue;
373                }
374                #[cfg(feature = "headless-text")]
375                ScreenSource::Text(source) => {
376                    if self.texts.len() == limits.max_screen_texts() {
377                        return Err(ExtractionError::ScreenTextLimitExceeded {
378                            limit: limits.max_screen_texts(),
379                        });
380                    }
381                    let text = source.resolve(generation)?;
382                    text_bytes = text_bytes.checked_add(text.text().len()).ok_or(
383                        ExtractionError::ScreenTextBytesLimitExceeded {
384                            limit: limits.max_screen_text_bytes(),
385                            requested: usize::MAX,
386                        },
387                    )?;
388                    if text_bytes > limits.max_screen_text_bytes() {
389                        return Err(ExtractionError::ScreenTextBytesLimitExceeded {
390                            limit: limits.max_screen_text_bytes(),
391                            requested: text_bytes,
392                        });
393                    }
394                    text_glyphs = text_glyphs.checked_add(text.visual().glyph_count()).ok_or(
395                        ExtractionError::ScreenTextGlyphLimitExceeded {
396                            limit: limits.max_screen_text_glyphs(),
397                            requested: usize::MAX,
398                        },
399                    )?;
400                    if text_glyphs > limits.max_screen_text_glyphs() {
401                        return Err(ExtractionError::ScreenTextGlyphLimitExceeded {
402                            limit: limits.max_screen_text_glyphs(),
403                            requested: text_glyphs,
404                        });
405                    }
406                    self.texts
407                        .try_reserve(1)
408                        .map_err(|_| ExtractionError::AllocationFailed {
409                            requested_bytes: size_of::<ResolvedScreenText>(),
410                        })?;
411                    self.texts.push(text);
412                    self.remember_source(key)?;
413                    continue;
414                }
415            };
416            if source.entity.world_generation() != generation {
417                return Err(ExtractionError::ForeignEntity {
418                    entity: source.entity,
419                    expected: generation,
420                });
421            }
422            if self.resolved.len() == limits.max_screen_rectangles() {
423                return Err(ExtractionError::ScreenRectangleLimitExceeded {
424                    limit: limits.max_screen_rectangles(),
425                });
426            }
427            let command_limit = limits.screen_scene_budget().max_commands();
428            if self.resolved.len().saturating_add(self.primitives.len()) >= command_limit {
429                return Err(ExtractionError::ScreenScene(SceneError::BudgetExceeded {
430                    resource: SceneBudgetResource::Commands,
431                    limit: command_limit,
432                    requested: self
433                        .resolved
434                        .len()
435                        .saturating_add(self.primitives.len())
436                        .saturating_add(1),
437                }));
438            }
439            source
440                .visual
441                .validate()
442                .map_err(|error| ExtractionError::InvalidScreenVisual {
443                    entity: source.entity,
444                    error,
445                })?;
446            self.resolved
447                .try_reserve(1)
448                .map_err(|_| ExtractionError::AllocationFailed {
449                    requested_bytes: size_of::<ResolvedScreenRectangle>(),
450                })?;
451            self.resolved.push(ResolvedScreenRectangle {
452                source: source.entity,
453                visual: source.visual,
454            });
455            self.remember_source(key)?;
456        }
457        self.resolved.sort_unstable_by(|left, right| {
458            compare_visual_order(
459                left.layer(),
460                left.draw_order_depth(),
461                left.source,
462                right.layer(),
463                right.draw_order_depth(),
464                right.source,
465            )
466        });
467        let count = self.primitives.len().saturating_add(self.resolved.len());
468        if count > limits.screen_scene_budget().max_commands() {
469            return Err(ExtractionError::ScreenScene(SceneError::BudgetExceeded {
470                resource: SceneBudgetResource::Commands,
471                limit: limits.screen_scene_budget().max_commands(),
472                requested: count,
473            }));
474        }
475        if !self.primitives.is_empty() {
476            self.primitives
477                .try_reserve(self.resolved.len())
478                .map_err(|_| ExtractionError::AllocationFailed {
479                    requested_bytes: self
480                        .resolved
481                        .len()
482                        .saturating_mul(size_of::<ResolvedScreenPrimitive>()),
483                })?;
484            self.primitives.extend(
485                self.resolved
486                    .iter()
487                    .copied()
488                    .map(ResolvedScreenPrimitive::Rectangle),
489            );
490            self.primitives.sort_unstable_by(|a, b| {
491                compare_visual_order(
492                    a.layer(),
493                    a.draw_order_depth(),
494                    a.source(),
495                    b.layer(),
496                    b.draw_order_depth(),
497                    b.source(),
498                )
499                .then_with(|| a.kind_order().cmp(&b.kind_order()))
500            });
501        }
502        self.images.sort_unstable_by(|left, right| {
503            compare_visual_order(
504                left.layer(),
505                left.draw_order_depth(),
506                left.source(),
507                right.layer(),
508                right.draw_order_depth(),
509                right.source(),
510            )
511        });
512        #[cfg(feature = "headless-text")]
513        self.texts.sort_unstable_by(|left, right| {
514            compare_visual_order(
515                left.layer(),
516                left.draw_order_depth(),
517                left.source(),
518                right.layer(),
519                right.draw_order_depth(),
520                right.source(),
521            )
522        });
523        Ok(())
524    }
525
526    fn push_vector(
527        &mut self,
528        generation: WorldGeneration,
529        entity: LogicEntity,
530        primitive: ResolvedScreenPrimitive,
531        count: usize,
532        limit: usize,
533        command_limit: usize,
534    ) -> Result<(), ExtractionError> {
535        if entity.world_generation() != generation {
536            return Err(ExtractionError::ForeignEntity {
537                entity,
538                expected: generation,
539            });
540        }
541        if count > limit {
542            return Err(ExtractionError::ScreenPrimitiveLimitExceeded { entity, limit });
543        }
544        let requested = self
545            .resolved
546            .len()
547            .saturating_add(self.primitives.len())
548            .saturating_add(1);
549        if requested > command_limit {
550            return Err(ExtractionError::ScreenScene(SceneError::BudgetExceeded {
551                resource: SceneBudgetResource::Commands,
552                limit: command_limit,
553                requested,
554            }));
555        }
556        self.primitives
557            .try_reserve(1)
558            .map_err(|_| ExtractionError::AllocationFailed {
559                requested_bytes: size_of::<ResolvedScreenPrimitive>(),
560            })?;
561        self.primitives.push(primitive);
562        Ok(())
563    }
564}
565
566#[cfg(test)]
567#[path = "screen_tests.rs"]
568mod tests;