Skip to main content

sim_engine/
screen.rs

1use std::mem::size_of;
2
3use crate::scene::validate_styled_polyline;
4#[cfg(any(feature = "wgpu", test))]
5use crate::{Camera2d, LogicalViewport};
6use crate::{
7    Color, Fill, Layer, LinearGradient, LogicalPixels, LogicalScreenPosition, LogicalScreenVector,
8    RadialGradient, Rect, Scene, SceneBudget, SceneBudgetResource, SceneError, ScenePrimitive,
9    SceneStatistics, ScreenClipRect, ShapeStyle, StrokeStyle2d, StrokeWidthMode2d, Vec2,
10};
11
12/// A bounded 2D scene whose geometry is expressed in logical screen pixels.
13///
14/// The origin is the top-left of the active logical viewport and positive y
15/// points downward. Geometry stays fixed while world cameras pan, zoom, rotate,
16/// or change pseudo-projection. Physical DPI conversion remains a renderer
17/// boundary operation. Gradient coordinates inside a [`ShapeStyle`] are also
18/// interpreted in this top-left/downward space and converted exactly once at
19/// insertion; the same style passed to an ordinary [`Scene`] instead uses
20/// world coordinates.
21#[derive(Debug, Clone)]
22pub struct ScreenScene {
23    scene: Scene,
24}
25
26impl ScreenScene {
27    /// Creates an explicitly unbounded logical-screen scene.
28    pub fn new(background: Color) -> Result<Self, SceneError> {
29        Scene::new(background).map(|scene| Self { scene })
30    }
31
32    /// Creates a logical-screen scene with explicit work and upload limits.
33    pub fn with_budget(background: Color, budget: SceneBudget) -> Result<Self, SceneError> {
34        Scene::with_budget(background, budget).map(|scene| Self { scene })
35    }
36
37    /// Returns the normalized linear-RGBA clear color.
38    pub fn background(&self) -> Color {
39        self.scene.background()
40    }
41
42    /// Replaces the clear color after normalized-color validation.
43    pub fn set_background(&mut self, background: Color) -> Result<(), SceneError> {
44        self.scene.set_background(background)
45    }
46
47    /// Removes all screen commands and resets their work statistics.
48    pub fn clear(&mut self) {
49        self.scene.clear();
50    }
51
52    /// Returns the explicit scene budget, if configured.
53    pub const fn budget(&self) -> Option<SceneBudget> {
54        self.scene.budget()
55    }
56
57    /// Returns accepted, rejected, and conservatively estimated work.
58    pub const fn statistics(&self) -> SceneStatistics {
59        self.scene.statistics()
60    }
61
62    /// Returns the number of accepted screen commands.
63    pub fn command_count(&self) -> usize {
64        self.scene.command_count()
65    }
66
67    /// Returns actual command/polyline allocation bytes retained for reuse.
68    pub fn allocation_bytes(&self) -> usize {
69        self.scene.allocation_bytes()
70    }
71
72    /// Replaces the logical-screen clip captured by subsequent commands.
73    pub fn set_screen_clip(
74        &mut self,
75        clip: Option<ScreenClipRect>,
76    ) -> Result<Option<ScreenClipRect>, SceneError> {
77        self.scene.set_screen_clip(clip)
78    }
79
80    /// Draws with a temporary nested logical-screen clip.
81    pub fn with_screen_clip<R>(
82        &mut self,
83        clip: ScreenClipRect,
84        draw: impl FnOnce(&mut Self) -> R,
85    ) -> Result<R, SceneError> {
86        let previous = self.scene.current_screen_clip();
87        let clip = match previous {
88            Some(outer) => outer.intersection(clip)?,
89            None => clip,
90        };
91        self.scene.set_screen_clip(Some(clip))?;
92        let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| draw(self)));
93        let restore = self.scene.set_screen_clip(previous);
94        match result {
95            Ok(value) => {
96                restore?;
97                Ok(value)
98            }
99            Err(payload) => {
100                let _ = restore;
101                std::panic::resume_unwind(payload)
102            }
103        }
104    }
105
106    /// Appends a filled/stroked circle in logical screen pixels.
107    pub fn try_circle(
108        &mut self,
109        center: LogicalScreenPosition,
110        radius: LogicalPixels,
111        style: ShapeStyle,
112    ) -> Result<(), SceneError> {
113        self.try_circle_on_layer(Layer::DEFAULT, center, radius, style)
114    }
115
116    /// Appends a logical-screen circle to an explicit shared draw layer.
117    pub fn try_circle_on_layer(
118        &mut self,
119        layer: Layer,
120        center: LogicalScreenPosition,
121        radius: LogicalPixels,
122        style: ShapeStyle,
123    ) -> Result<(), SceneError> {
124        self.scene.try_circle_on_layer(
125            layer,
126            screen_to_internal(center),
127            radius.get(),
128            screen_shape_style_to_internal(style),
129        )
130    }
131
132    /// Appends a rectangle from a logical top-left position and positive size.
133    pub fn try_rect(
134        &mut self,
135        min: LogicalScreenPosition,
136        size: LogicalScreenVector,
137        corner_radius: LogicalPixels,
138        style: ShapeStyle,
139    ) -> Result<(), SceneError> {
140        self.try_rect_on_layer(Layer::DEFAULT, min, size, corner_radius, style)
141    }
142
143    /// Appends a square-cornered rectangle from a logical top-left position
144    /// and positive size.
145    ///
146    /// This entry point represents an exact zero corner radius without
147    /// weakening [`LogicalPixels`]' strictly-positive length invariant.
148    pub fn try_square_rect(
149        &mut self,
150        min: LogicalScreenPosition,
151        size: LogicalScreenVector,
152        style: ShapeStyle,
153    ) -> Result<(), SceneError> {
154        self.try_square_rect_on_layer(Layer::DEFAULT, min, size, style)
155    }
156
157    /// Appends a logical-screen rectangle with positive size to a shared layer.
158    pub fn try_rect_on_layer(
159        &mut self,
160        layer: Layer,
161        min: LogicalScreenPosition,
162        size: LogicalScreenVector,
163        corner_radius: LogicalPixels,
164        style: ShapeStyle,
165    ) -> Result<(), SceneError> {
166        self.try_rect_with_radius_on_layer(layer, min, size, corner_radius.get(), style)
167    }
168
169    fn try_rect_with_radius_on_layer(
170        &mut self,
171        layer: Layer,
172        min: LogicalScreenPosition,
173        size: LogicalScreenVector,
174        corner_radius: f32,
175        style: ShapeStyle,
176    ) -> Result<(), SceneError> {
177        let size_value = size.to_vec2();
178        let max = min.to_vec2() + size_value;
179        if !min.is_finite() || !size.is_finite() || !max.is_finite() {
180            self.scene.record_external_rejection(ScenePrimitive::Rect);
181            return Err(SceneError::NonFiniteGeometry(ScenePrimitive::Rect));
182        }
183        if size_value.x <= 0.0 || size_value.y <= 0.0 {
184            self.scene.record_external_rejection(ScenePrimitive::Rect);
185            return Err(SceneError::InvalidDimension(ScenePrimitive::Rect));
186        }
187        self.scene.try_rect_on_layer(
188            layer,
189            Rect::new(
190                screen_vec_to_internal(min.to_vec2()),
191                screen_vec_to_internal(max),
192            ),
193            corner_radius,
194            screen_shape_style_to_internal(style),
195        )
196    }
197
198    /// Appends a square-cornered logical-screen rectangle to a shared layer.
199    pub fn try_square_rect_on_layer(
200        &mut self,
201        layer: Layer,
202        min: LogicalScreenPosition,
203        size: LogicalScreenVector,
204        style: ShapeStyle,
205    ) -> Result<(), SceneError> {
206        self.try_rect_with_radius_on_layer(layer, min, size, 0.0, style)
207    }
208
209    /// Appends a line whose endpoints and width use logical pixels.
210    pub fn try_line(
211        &mut self,
212        from: LogicalScreenPosition,
213        to: LogicalScreenPosition,
214        width: LogicalPixels,
215        color: Color,
216    ) -> Result<(), SceneError> {
217        self.try_line_on_layer(Layer::DEFAULT, from, to, width, color)
218    }
219
220    /// Appends a logical-screen line to an explicit shared draw layer.
221    pub fn try_line_on_layer(
222        &mut self,
223        layer: Layer,
224        from: LogicalScreenPosition,
225        to: LogicalScreenPosition,
226        width: LogicalPixels,
227        color: Color,
228    ) -> Result<(), SceneError> {
229        self.scene.try_line_on_layer(
230            layer,
231            screen_to_internal(from),
232            screen_to_internal(to),
233            width.get(),
234            color,
235        )
236    }
237
238    /// Appends a logical-screen line with explicit bounded stroke styling.
239    pub fn try_styled_line(
240        &mut self,
241        from: LogicalScreenPosition,
242        to: LogicalScreenPosition,
243        style: StrokeStyle2d,
244    ) -> Result<(), SceneError> {
245        self.try_styled_line_on_layer(Layer::DEFAULT, from, to, style)
246    }
247
248    /// Appends an explicitly styled logical-screen line to a shared layer.
249    pub fn try_styled_line_on_layer(
250        &mut self,
251        layer: Layer,
252        from: LogicalScreenPosition,
253        to: LogicalScreenPosition,
254        style: StrokeStyle2d,
255    ) -> Result<(), SceneError> {
256        if style.width_mode() != StrokeWidthMode2d::LogicalPixels {
257            self.scene.record_external_rejection(ScenePrimitive::Line);
258            return Err(SceneError::InvalidStroke(ScenePrimitive::Line));
259        }
260        self.scene.try_styled_line_on_layer(
261            layer,
262            screen_to_internal(from),
263            screen_to_internal(to),
264            style,
265        )
266    }
267
268    /// Appends a connected logical-screen line strip with fallible point copying.
269    pub fn try_polyline(
270        &mut self,
271        points: &[LogicalScreenPosition],
272        width: LogicalPixels,
273        color: Color,
274    ) -> Result<(), SceneError> {
275        self.try_polyline_on_layer(Layer::DEFAULT, points, width, color)
276    }
277
278    /// Appends a logical-screen line strip to an explicit shared draw layer.
279    pub fn try_polyline_on_layer(
280        &mut self,
281        layer: Layer,
282        points: &[LogicalScreenPosition],
283        width: LogicalPixels,
284        color: Color,
285    ) -> Result<(), SceneError> {
286        self.try_styled_polyline_on_layer(layer, points, StrokeStyle2d::logical(width, color))
287    }
288
289    /// Appends an explicitly styled logical-screen line strip.
290    pub fn try_styled_polyline(
291        &mut self,
292        points: &[LogicalScreenPosition],
293        style: StrokeStyle2d,
294    ) -> Result<(), SceneError> {
295        self.try_styled_polyline_on_layer(Layer::DEFAULT, points, style)
296    }
297
298    /// Appends an explicitly styled logical-screen line strip to a shared layer.
299    pub fn try_styled_polyline_on_layer(
300        &mut self,
301        layer: Layer,
302        points: &[LogicalScreenPosition],
303        style: StrokeStyle2d,
304    ) -> Result<(), SceneError> {
305        if style.width_mode() != StrokeWidthMode2d::LogicalPixels {
306            self.scene
307                .record_external_rejection(ScenePrimitive::Polyline);
308            return Err(SceneError::InvalidStroke(ScenePrimitive::Polyline));
309        }
310        if let Err(error) =
311            validate_styled_polyline(points.iter().copied().map(screen_to_internal), style)
312        {
313            self.scene
314                .record_external_rejection(ScenePrimitive::Polyline);
315            return Err(error);
316        }
317        if let Some(budget) = self.scene.budget() {
318            let requested = self
319                .scene
320                .statistics()
321                .retained_points()
322                .saturating_add(points.len());
323            if requested > budget.max_points() {
324                self.scene
325                    .record_external_rejection(ScenePrimitive::Polyline);
326                return Err(SceneError::BudgetExceeded {
327                    resource: SceneBudgetResource::Points,
328                    limit: budget.max_points(),
329                    requested,
330                });
331            }
332        }
333        let minimum_point_bytes = points.len().saturating_mul(size_of::<Vec2>());
334        if let Err(error) = self.scene.preflight_command_storage(1, minimum_point_bytes) {
335            self.scene
336                .record_external_rejection(ScenePrimitive::Polyline);
337            return Err(error);
338        }
339        let mut internal = Vec::new();
340        if internal.try_reserve_exact(points.len()).is_err() {
341            self.scene
342                .record_external_rejection(ScenePrimitive::Polyline);
343            return Err(SceneError::AllocationFailed {
344                requested_bytes: minimum_point_bytes,
345            });
346        }
347        let actual_point_bytes = internal.capacity().saturating_mul(size_of::<Vec2>());
348        if let Err(error) = self.scene.preflight_command_storage(1, actual_point_bytes) {
349            self.scene
350                .record_external_rejection(ScenePrimitive::Polyline);
351            return Err(error);
352        }
353        internal.extend(points.iter().copied().map(screen_to_internal));
354        self.scene
355            .try_styled_polyline_on_layer(layer, internal, style)
356    }
357
358    /// Creates a linear-gradient fill using typed logical-screen endpoints.
359    pub fn linear_gradient(
360        start: LogicalScreenPosition,
361        end: LogicalScreenPosition,
362        start_color: Color,
363        end_color: Color,
364    ) -> Fill {
365        Fill::LinearGradient(LinearGradient::new(
366            start.to_vec2(),
367            end.to_vec2(),
368            start_color,
369            end_color,
370        ))
371    }
372
373    /// Creates a radial-gradient fill centered in logical screen pixels.
374    pub fn radial_gradient(
375        center: LogicalScreenPosition,
376        inner_radius: Option<LogicalPixels>,
377        outer_radius: LogicalPixels,
378        inner_color: Color,
379        outer_color: Color,
380    ) -> Fill {
381        Fill::RadialGradient(RadialGradient::new(
382            center.to_vec2(),
383            inner_radius.map_or(0.0, LogicalPixels::get),
384            outer_radius.get(),
385            inner_color,
386            outer_color,
387        ))
388    }
389
390    #[cfg(feature = "wgpu")]
391    pub(crate) const fn as_scene(&self) -> &Scene {
392        &self.scene
393    }
394}
395
396#[cfg(any(feature = "wgpu", test))]
397pub(crate) fn screen_camera(viewport: LogicalViewport) -> Result<Camera2d, SceneError> {
398    Camera2d::new(
399        Vec2::new(viewport.width() * 0.5, viewport.height() * -0.5),
400        1.0,
401    )
402    .map_err(|_| SceneError::NonFiniteGeometry(ScenePrimitive::Rect))
403}
404
405fn screen_to_internal(position: LogicalScreenPosition) -> Vec2 {
406    screen_vec_to_internal(position.to_vec2())
407}
408
409fn screen_vec_to_internal(value: Vec2) -> Vec2 {
410    Vec2::new(value.x, -value.y)
411}
412
413fn screen_shape_style_to_internal(style: ShapeStyle) -> ShapeStyle {
414    let fill = style.fill().map(|fill| match fill {
415        Fill::Solid(color) => Fill::Solid(color),
416        Fill::LinearGradient(gradient) => Fill::LinearGradient(LinearGradient::new(
417            screen_vec_to_internal(gradient.start()),
418            screen_vec_to_internal(gradient.end()),
419            gradient.start_color(),
420            gradient.end_color(),
421        )),
422        Fill::RadialGradient(gradient) => Fill::RadialGradient(RadialGradient::new(
423            screen_vec_to_internal(gradient.center()),
424            gradient.inner_radius(),
425            gradient.outer_radius(),
426            gradient.inner_color(),
427            gradient.outer_color(),
428        )),
429    });
430    ShapeStyle::new(fill, style.stroke(), style.shadow())
431}
432
433#[cfg(test)]
434mod tests {
435    use super::*;
436
437    #[test]
438    fn logical_screen_geometry_maps_to_top_left_coordinates() {
439        let viewport = LogicalViewport::new(800.0, 600.0).unwrap();
440        let camera = screen_camera(viewport).unwrap();
441        for point in [
442            LogicalScreenPosition::new(0.0, 0.0),
443            LogicalScreenPosition::new(123.5, 456.25),
444            LogicalScreenPosition::new(800.0, 600.0),
445        ] {
446            let projected = camera
447                .world_to_screen(screen_to_internal(point), viewport)
448                .unwrap();
449            assert_eq!(projected, point);
450        }
451    }
452
453    #[test]
454    fn logical_screen_polyline_checks_budget_before_copying_points() {
455        let budget = SceneBudget::new(1, 2, usize::MAX, usize::MAX, usize::MAX, usize::MAX, 1);
456        let mut scene = ScreenScene::with_budget(Color::BLACK, budget).unwrap();
457        let points = [
458            LogicalScreenPosition::new(0.0, 0.0),
459            LogicalScreenPosition::new(1.0, 0.0),
460            LogicalScreenPosition::new(2.0, 0.0),
461        ];
462
463        assert_eq!(
464            scene.try_polyline(&points, LogicalPixels::new(1.0).unwrap(), Color::WHITE),
465            Err(SceneError::BudgetExceeded {
466                resource: SceneBudgetResource::Points,
467                limit: 2,
468                requested: 3,
469            })
470        );
471        assert_eq!(scene.command_count(), 0);
472        assert_eq!(scene.statistics().rejected_commands(), 1);
473    }
474
475    #[test]
476    fn logical_screen_polyline_checks_allocation_before_copying_points() {
477        let budget = SceneBudget::new(1, usize::MAX, usize::MAX, usize::MAX, 1, usize::MAX, 1);
478        let mut scene = ScreenScene::with_budget(Color::BLACK, budget).unwrap();
479        let points = [
480            LogicalScreenPosition::new(0.0, 0.0),
481            LogicalScreenPosition::new(1.0, 0.0),
482            LogicalScreenPosition::new(2.0, 0.0),
483        ];
484
485        assert!(matches!(
486            scene.try_polyline(&points, LogicalPixels::new(1.0).unwrap(), Color::WHITE),
487            Err(SceneError::BudgetExceeded {
488                resource: SceneBudgetResource::AllocationBytes,
489                limit: 1,
490                ..
491            })
492        ));
493        assert_eq!(scene.command_count(), 0);
494        assert_eq!(scene.allocation_bytes(), 0);
495        assert_eq!(scene.statistics().rejected_commands(), 1);
496    }
497
498    #[test]
499    fn logical_screen_polyline_validates_before_caller_sized_allocation() {
500        let budget = SceneBudget::new(1, 1, usize::MAX, usize::MAX, 1, usize::MAX, 1);
501        let mut scene = ScreenScene::with_budget(Color::BLACK, budget).unwrap();
502        let non_finite = [
503            LogicalScreenPosition::new(f32::NAN, 0.0),
504            LogicalScreenPosition::new(1.0, 0.0),
505        ];
506
507        assert_eq!(
508            scene.try_polyline(&non_finite, LogicalPixels::new(1.0).unwrap(), Color::WHITE,),
509            Err(SceneError::NonFiniteGeometry(ScenePrimitive::Polyline))
510        );
511        assert_eq!(scene.allocation_bytes(), 0);
512
513        let degenerate = [
514            LogicalScreenPosition::new(0.0, 0.0),
515            LogicalScreenPosition::new(0.0, 0.0),
516            LogicalScreenPosition::new(1.0, 0.0),
517        ];
518        assert_eq!(
519            scene.try_polyline(&degenerate, LogicalPixels::new(1.0).unwrap(), Color::WHITE,),
520            Err(SceneError::DegenerateGeometry(ScenePrimitive::Polyline))
521        );
522        assert_eq!(scene.allocation_bytes(), 0);
523        assert_eq!(scene.statistics().rejected_commands(), 2);
524    }
525
526    #[test]
527    fn logical_screen_styled_paths_reject_world_width_before_allocation() {
528        let mut scene = ScreenScene::new(Color::BLACK).unwrap();
529        let style = StrokeStyle2d::world(crate::WorldLength::new(2.0).unwrap(), Color::WHITE);
530        let start = LogicalScreenPosition::new(0.0, 0.0);
531        let end = LogicalScreenPosition::new(8.0, 0.0);
532
533        assert_eq!(
534            scene.try_styled_line(start, end, style),
535            Err(SceneError::InvalidStroke(ScenePrimitive::Line))
536        );
537        assert_eq!(
538            scene.try_styled_polyline(&[start, end], style),
539            Err(SceneError::InvalidStroke(ScenePrimitive::Polyline))
540        );
541        assert_eq!(scene.command_count(), 0);
542        assert_eq!(scene.allocation_bytes(), 0);
543        assert_eq!(scene.statistics().rejected_commands(), 2);
544    }
545
546    #[test]
547    fn logical_screen_rect_requires_positive_size_at_declared_top_left() {
548        let mut scene = ScreenScene::new(Color::BLACK).unwrap();
549        let min = LogicalScreenPosition::new(100.0, 100.0);
550        for size in [
551            LogicalScreenVector::new(-50.0, 20.0),
552            LogicalScreenVector::new(50.0, -20.0),
553            LogicalScreenVector::new(0.0, 20.0),
554            LogicalScreenVector::new(50.0, 0.0),
555        ] {
556            assert_eq!(
557                scene.try_rect(
558                    min,
559                    size,
560                    LogicalPixels::new(1.0).unwrap(),
561                    ShapeStyle::filled(Color::WHITE),
562                ),
563                Err(SceneError::InvalidDimension(ScenePrimitive::Rect))
564            );
565        }
566        assert_eq!(scene.command_count(), 0);
567        assert_eq!(scene.statistics().rejected_commands(), 4);
568    }
569
570    #[test]
571    fn logical_screen_square_rect_expresses_an_exact_zero_corner_radius() {
572        let mut scene = ScreenScene::new(Color::BLACK).unwrap();
573        scene
574            .try_square_rect(
575                LogicalScreenPosition::new(10.0, 20.0),
576                LogicalScreenVector::new(100.0, 50.0),
577                ShapeStyle::filled(Color::WHITE),
578            )
579            .unwrap();
580
581        let crate::DrawCommand::Rect(rect) = scene.scene.commands()[0].command() else {
582            panic!("square screen rectangle should retain a rectangle command");
583        };
584        assert_eq!(rect.corner_radius(), 0.0);
585        assert_eq!(rect.rect().min(), Vec2::new(10.0, -20.0));
586        assert_eq!(rect.rect().max(), Vec2::new(110.0, -70.0));
587    }
588
589    #[test]
590    fn screen_shape_gradients_are_converted_exactly_once() {
591        let red = Color::rgb8(255, 0, 0);
592        let blue = Color::rgb8(0, 0, 255);
593        let mut scene = ScreenScene::new(Color::BLACK).unwrap();
594        scene
595            .try_rect(
596                LogicalScreenPosition::new(0.0, 0.0),
597                LogicalScreenVector::new(100.0, 100.0),
598                LogicalPixels::new(1.0).unwrap(),
599                ShapeStyle::filled_with(Fill::LinearGradient(LinearGradient::new(
600                    Vec2::ZERO,
601                    Vec2::new(0.0, 100.0),
602                    red,
603                    blue,
604                ))),
605            )
606            .unwrap();
607        scene
608            .try_circle(
609                LogicalScreenPosition::new(20.0, 30.0),
610                LogicalPixels::new(10.0).unwrap(),
611                ShapeStyle::filled_with(ScreenScene::radial_gradient(
612                    LogicalScreenPosition::new(20.0, 30.0),
613                    None,
614                    LogicalPixels::new(10.0).unwrap(),
615                    red,
616                    blue,
617                )),
618            )
619            .unwrap();
620
621        let crate::DrawCommand::Rect(rect) = scene.scene.commands()[0].command() else {
622            panic!("screen rectangle should retain a rectangle command");
623        };
624        let Some(Fill::LinearGradient(linear)) = rect.style().fill() else {
625            panic!("screen rectangle should retain its linear gradient");
626        };
627        assert_eq!(linear.start(), Vec2::ZERO);
628        assert_eq!(linear.end(), Vec2::new(0.0, -100.0));
629        assert_eq!(linear.color_at(Vec2::ZERO), red);
630        assert_eq!(linear.color_at(Vec2::new(0.0, -100.0)), blue);
631
632        let crate::DrawCommand::Circle(circle) = scene.scene.commands()[1].command() else {
633            panic!("screen circle should retain a circle command");
634        };
635        let Some(Fill::RadialGradient(radial)) = circle.style().fill() else {
636            panic!("screen circle should retain its radial gradient");
637        };
638        assert_eq!(radial.center(), Vec2::new(20.0, -30.0));
639        assert_eq!(radial.color_at(Vec2::new(20.0, -30.0)), red);
640        assert_eq!(radial.color_at(Vec2::new(30.0, -30.0)), blue);
641    }
642}