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#[derive(Debug, Clone)]
22pub struct ScreenScene {
23 scene: Scene,
24}
25
26impl ScreenScene {
27 pub fn new(background: Color) -> Result<Self, SceneError> {
29 Scene::new(background).map(|scene| Self { scene })
30 }
31
32 pub fn with_budget(background: Color, budget: SceneBudget) -> Result<Self, SceneError> {
34 Scene::with_budget(background, budget).map(|scene| Self { scene })
35 }
36
37 pub fn background(&self) -> Color {
39 self.scene.background()
40 }
41
42 pub fn set_background(&mut self, background: Color) -> Result<(), SceneError> {
44 self.scene.set_background(background)
45 }
46
47 pub fn clear(&mut self) {
49 self.scene.clear();
50 }
51
52 pub const fn budget(&self) -> Option<SceneBudget> {
54 self.scene.budget()
55 }
56
57 pub const fn statistics(&self) -> SceneStatistics {
59 self.scene.statistics()
60 }
61
62 pub fn command_count(&self) -> usize {
64 self.scene.command_count()
65 }
66
67 pub fn allocation_bytes(&self) -> usize {
69 self.scene.allocation_bytes()
70 }
71
72 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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(°enerate, 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}