Skip to main content

sim_logic/platform/desktop/
images.rs

1//! Retained desktop images and ordered composition of CPU screen snapshots.
2
3use std::{error::Error, fmt, mem::size_of};
4
5use sim_engine::{
6    BlendMode, Camera2d, FrameBudget, FrameBudgetResource, FrameComposerError, FramePassOptions,
7    FrameReport, Image2d, ImageBudget, ImageError, ImageSampling, ImageTexelRect,
8    LogicalScreenPosition, LogicalScreenVector, LogicalViewport, Rect, RenderTarget2d,
9    RendererFrameError, SceneStatistics, Vec2, WgpuRenderer,
10};
11
12use super::draw_plan::{self, DesktopDraw};
13use crate::{
14    ExtractedFrame, ScreenDraw,
15    assets::{ImageAssetId, ImageAssetRegistry},
16    identity::LogicEntity,
17    screen::ImageFilter,
18};
19
20/// Failure while preparing an immutable image for the desktop renderer.
21///
22/// Preparation happens only after a complete CPU snapshot is published. An
23/// earlier successful cache upload may remain cached if later preparation or
24/// composition fails; no partially composed frame is presented.
25#[derive(Debug)]
26pub enum DesktopImageError {
27    /// Retained screen geometry could not be prepared.
28    Geometry(super::geometry::DesktopScreenError),
29    /// A published image did not resolve in the owning application's registry.
30    MissingAsset {
31        /// Managed visual requesting the unavailable asset.
32        source: LogicEntity,
33        /// Immutable asset identity requested by that visual.
34        image: ImageAssetId,
35    },
36    /// The renderer rejected the image or its bounded recovery allocation.
37    Upload {
38        /// Managed visual that first required this uncached image.
39        source: LogicEntity,
40        /// Immutable asset whose preparation failed.
41        image: ImageAssetId,
42        /// Concrete Sim;Engine image failure.
43        error: ImageError,
44    },
45    /// The bounded desktop cache could not reserve one metadata record.
46    CacheAllocationFailed {
47        /// Managed visual requiring the new cache entry.
48        source: LogicEntity,
49        /// Immutable asset associated with the reservation.
50        image: ImageAssetId,
51        /// Minimum additional bytes requested for cache metadata.
52        requested_bytes: usize,
53    },
54    /// A private cache invariant would exceed the registered asset count.
55    CacheLimitExceeded {
56        /// Frozen number of application image registrations.
57        limit: usize,
58    },
59    /// A published draw plan referenced an unavailable image or rectangle run.
60    InvalidDrawPlan,
61    /// Managed text was enabled for CPU extraction without the `text` GPU bridge.
62    TextFeatureRequired,
63}
64
65impl fmt::Display for DesktopImageError {
66    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
67        match self {
68            Self::Geometry(error) => error.fmt(formatter),
69            Self::TextFeatureRequired => formatter.write_str("desktop labels require the `text` feature; `headless-text` alone only extracts CPU text"),
70            Self::MissingAsset { source, image } => write!(
71                formatter,
72                "screen image {source:?} references unavailable asset {image:?}"
73            ),
74            Self::Upload {
75                source,
76                image,
77                error,
78            } => write!(
79                formatter,
80                "screen image {source:?} could not prepare asset {image:?}: {error}"
81            ),
82            Self::CacheAllocationFailed {
83                source,
84                image,
85                requested_bytes,
86            } => write!(
87                formatter,
88                "screen image {source:?} could not reserve {requested_bytes} cache bytes for {image:?}"
89            ),
90            Self::CacheLimitExceeded { limit } => write!(
91                formatter,
92                "desktop image cache exceeded its {limit} registered-asset limit"
93            ),
94            Self::InvalidDrawPlan => {
95                formatter.write_str("published screen draw plan is inconsistent")
96            }
97        }
98    }
99}
100
101impl Error for DesktopImageError {
102    fn source(&self) -> Option<&(dyn Error + 'static)> {
103        match self {
104            Self::Geometry(error) => Some(error),
105            Self::Upload { error, .. } => Some(error),
106            _ => None,
107        }
108    }
109}
110
111#[derive(Debug)]
112pub(super) enum ScreenPresentationError {
113    Images(DesktopImageError),
114    Composition(FrameComposerError),
115    ThreeD(super::three_d::DesktopThreeDError),
116    #[cfg(feature = "text")]
117    Text(super::text::DesktopTextError),
118}
119
120#[cfg(feature = "text")]
121impl From<super::text::DesktopTextError> for ScreenPresentationError {
122    fn from(error: super::text::DesktopTextError) -> Self {
123        Self::Text(error)
124    }
125}
126
127impl From<super::three_d::DesktopThreeDError> for ScreenPresentationError {
128    fn from(error: super::three_d::DesktopThreeDError) -> Self {
129        Self::ThreeD(error)
130    }
131}
132
133impl From<DesktopImageError> for ScreenPresentationError {
134    fn from(error: DesktopImageError) -> Self {
135        Self::Images(error)
136    }
137}
138
139impl From<FrameComposerError> for ScreenPresentationError {
140    fn from(error: FrameComposerError) -> Self {
141        Self::Composition(error)
142    }
143}
144
145#[derive(Debug, PartialEq, Eq)]
146enum CacheError<E> {
147    Limit { limit: usize },
148    Allocation { requested_bytes: usize },
149    Create(E),
150}
151
152struct ResourceCache<K, V> {
153    entries: Vec<(K, V)>,
154}
155
156impl<K: Copy + Eq, V> ResourceCache<K, V> {
157    fn new() -> Self {
158        Self {
159            entries: Vec::new(),
160        }
161    }
162
163    fn get(&self, key: K) -> Option<&V> {
164        self.entries
165            .iter()
166            .find_map(|(stored, value)| (*stored == key).then_some(value))
167    }
168
169    fn clear(&mut self) {
170        self.entries.clear();
171    }
172
173    fn ensure<E>(
174        &mut self,
175        key: K,
176        limit: usize,
177        create: impl FnOnce() -> Result<V, E>,
178    ) -> Result<(), CacheError<E>> {
179        if self.get(key).is_some() {
180            return Ok(());
181        }
182        if self.entries.len() >= limit {
183            return Err(CacheError::Limit { limit });
184        }
185        self.entries
186            .try_reserve_exact(1)
187            .map_err(|_| CacheError::Allocation {
188                requested_bytes: size_of::<(K, V)>(),
189            })?;
190        let resource = create().map_err(CacheError::Create)?;
191        self.entries.push((key, resource));
192        Ok(())
193    }
194}
195
196pub(super) struct DesktopImages {
197    pub(super) geometry: super::geometry::DesktopGeometry,
198    pub(super) screen_mode: super::geometry::DesktopScreenMode,
199    pub(super) text_batching: bool,
200    resources: ResourceCache<ImageAssetId, Image2d>,
201    referenced: ScreenReferences,
202    #[cfg(feature = "text")]
203    pub(super) texts: super::text::DesktopText,
204}
205
206#[derive(Default)]
207struct ScreenReferences {
208    images: Vec<ImageAssetId>,
209    #[cfg(feature = "text")]
210    fonts: Vec<crate::text::TextFont>,
211}
212
213impl ScreenReferences {
214    fn clear(&mut self) {
215        self.images.clear();
216        #[cfg(feature = "text")]
217        self.fonts.clear();
218    }
219}
220
221pub(super) fn needs_managed_presentation(
222    extracted: &ExtractedFrame,
223    _images: &DesktopImages,
224) -> bool {
225    #[cfg(all(feature = "headless-text", not(feature = "text")))]
226    if !extracted.resolved_screen_texts().is_empty() {
227        return true;
228    }
229    #[cfg(feature = "text")]
230    if !extracted.resolved_screen_texts().is_empty() || _images.texts.has_runs() {
231        return true;
232    }
233    !extracted.screen_draws().is_empty() || _images.geometry.has_runs()
234}
235
236impl DesktopImages {
237    pub(super) fn new() -> Self {
238        Self {
239            geometry: super::geometry::DesktopGeometry::default(),
240            screen_mode: super::geometry::DesktopScreenMode::default(),
241            text_batching: true,
242            resources: ResourceCache::new(),
243            referenced: ScreenReferences::default(),
244            #[cfg(feature = "text")]
245            texts: super::text::DesktopText::default(),
246        }
247    }
248
249    pub(super) fn clear(&mut self) {
250        self.geometry.clear();
251        self.resources.clear();
252        self.referenced.clear();
253        #[cfg(feature = "text")]
254        self.texts.clear();
255    }
256
257    pub(super) fn preflight_three_d(
258        &mut self,
259        extracted: &ExtractedFrame,
260        registry: &ImageAssetRegistry,
261        budget: FrameBudget,
262        target_bytes: usize,
263    ) -> Result<(), ScreenPresentationError> {
264        // The public surface format provides exact color-target bytes before
265        // allocation. Engine still validates its private uniform/tessellation work.
266        preflight_with_target(
267            extracted,
268            registry,
269            &mut self.referenced,
270            budget,
271            Some(target_bytes),
272            self.screen_mode,
273            self.text_batching,
274        )
275    }
276
277    fn prepare(
278        &mut self,
279        renderer: &WgpuRenderer,
280        registry: &ImageAssetRegistry,
281        extracted: &ExtractedFrame,
282    ) -> Result<(), DesktopImageError> {
283        for visual in extracted.resolved_screen_images() {
284            if visual.clip() == crate::screen::ScreenClip::Empty {
285                continue;
286            }
287            let source = visual.source();
288            let image = visual.image();
289            let asset = registry
290                .get(image)
291                .ok_or(DesktopImageError::MissingAsset { source, image })?;
292            self.resources
293                .ensure(image, registry.len(), || {
294                    let budget =
295                        ImageBudget::new(asset.width(), asset.height(), asset.pixels().len())?;
296                    renderer.create_image_rgba8_from_slice(
297                        asset.width(),
298                        asset.height(),
299                        asset.pixels(),
300                        budget,
301                    )
302                })
303                .map_err(|error| match error {
304                    CacheError::Limit { limit } => DesktopImageError::CacheLimitExceeded { limit },
305                    CacheError::Allocation { requested_bytes } => {
306                        DesktopImageError::CacheAllocationFailed {
307                            source,
308                            image,
309                            requested_bytes,
310                        }
311                    }
312                    CacheError::Create(error) => DesktopImageError::Upload {
313                        source,
314                        image,
315                        error,
316                    },
317                })?;
318        }
319        Ok(())
320    }
321}
322
323#[derive(Default)]
324struct FrameWork {
325    passes: usize,
326    commands: usize,
327    vertices: usize,
328    upload_bytes: usize,
329    texture_bytes: usize,
330    draw_calls: usize,
331}
332
333impl FrameWork {
334    fn scene(&mut self, statistics: SceneStatistics) {
335        self.geometry(statistics, true);
336    }
337
338    fn geometry(&mut self, statistics: SceneStatistics, streaming: bool) {
339        self.passes = self.passes.saturating_add(1);
340        self.commands = self.commands.saturating_add(statistics.accepted_commands());
341        self.vertices = self
342            .vertices
343            .saturating_add(statistics.estimated_tessellated_vertices());
344        if streaming {
345            self.upload_bytes = self
346                .upload_bytes
347                .saturating_add(statistics.estimated_upload_bytes());
348        }
349        self.draw_calls = self
350            .draw_calls
351            .saturating_add(statistics.estimated_draw_batches());
352    }
353
354    fn image(&mut self) {
355        self.passes = self.passes.saturating_add(1);
356        self.commands = self.commands.saturating_add(1);
357        self.vertices = self.vertices.saturating_add(6);
358        self.draw_calls = self.draw_calls.saturating_add(1);
359    }
360
361    fn validate(&self, budget: FrameBudget) -> Result<(), FrameComposerError> {
362        for (resource, limit, actual) in [
363            (
364                FrameBudgetResource::Passes,
365                budget.max_passes(),
366                self.passes,
367            ),
368            (
369                FrameBudgetResource::Commands,
370                budget.max_commands(),
371                self.commands,
372            ),
373            (
374                FrameBudgetResource::Vertices,
375                budget.max_vertices(),
376                self.vertices,
377            ),
378            (
379                FrameBudgetResource::UploadBytes,
380                budget.max_upload_bytes(),
381                self.upload_bytes,
382            ),
383            (
384                FrameBudgetResource::TextureBytes,
385                budget.max_texture_bytes(),
386                self.texture_bytes,
387            ),
388            (
389                FrameBudgetResource::DrawCalls,
390                budget.max_draw_calls(),
391                self.draw_calls,
392            ),
393        ] {
394            if actual > limit {
395                return Err(FrameComposerError::BudgetExceeded {
396                    resource,
397                    limit,
398                    actual,
399                });
400            }
401        }
402        Ok(())
403    }
404}
405
406#[cfg(test)]
407fn preflight(
408    extracted: &ExtractedFrame,
409    registry: &ImageAssetRegistry,
410    referenced: &mut ScreenReferences,
411    budget: FrameBudget,
412) -> Result<(), ScreenPresentationError> {
413    preflight_with_target(
414        extracted,
415        registry,
416        referenced,
417        budget,
418        None,
419        super::geometry::DesktopScreenMode::Streaming,
420        false,
421    )
422}
423
424fn preflight_with_target(
425    extracted: &ExtractedFrame,
426    registry: &ImageAssetRegistry,
427    referenced: &mut ScreenReferences,
428    budget: FrameBudget,
429    target_bytes: Option<usize>,
430    mode: super::geometry::DesktopScreenMode,
431    text_batching: bool,
432) -> Result<(), ScreenPresentationError> {
433    referenced.clear();
434    if referenced.images.capacity() < registry.len() {
435        referenced
436            .images
437            .try_reserve_exact(registry.len())
438            .map_err(|_| FrameComposerError::AllocationFailed {
439                requested_bytes: registry.len().saturating_mul(size_of::<ImageAssetId>()),
440            })?;
441    }
442    let mut work = FrameWork::default();
443    work.scene(extracted.world_scene().statistics());
444    if let Some(bytes) = target_bytes {
445        work.image();
446        work.texture_bytes = bytes;
447    }
448    for draw in draw_plan::draws(extracted, text_batching) {
449        #[cfg(not(feature = "text"))]
450        let DesktopDraw::Single(draw) = draw?;
451        #[cfg(feature = "text")]
452        let draw = match draw? {
453            DesktopDraw::Single(draw) => draw,
454            #[cfg(feature = "text")]
455            DesktopDraw::TextBatch(range) => {
456                account_texts(
457                    &mut work,
458                    referenced,
459                    &extracted.resolved_screen_texts()[range],
460                )?;
461                continue;
462            }
463        };
464        match draw {
465            #[cfg(all(feature = "headless-text", not(feature = "text")))]
466            ScreenDraw::Text { .. } => return Err(DesktopImageError::TextFeatureRequired.into()),
467            ScreenDraw::Rectangles { run } | ScreenDraw::Primitives { run } => {
468                let scene = extracted
469                    .screen_rectangle_run(run)
470                    .ok_or(DesktopImageError::InvalidDrawPlan)?;
471                // Resource uploads are separately bounded/reported at creation.
472                // Vertex/draw admission stays conservative until Engine preflight.
473                work.geometry(
474                    scene.statistics(),
475                    mode == super::geometry::DesktopScreenMode::Streaming,
476                );
477            }
478            ScreenDraw::Image { index } => {
479                let visual = extracted
480                    .resolved_screen_images()
481                    .get(index)
482                    .ok_or(DesktopImageError::InvalidDrawPlan)?;
483                let image = visual.image();
484                if visual.clip() == crate::screen::ScreenClip::Empty {
485                    continue;
486                }
487                let asset = registry.get(image).ok_or(DesktopImageError::MissingAsset {
488                    source: visual.source(),
489                    image,
490                })?;
491                if !referenced.images.contains(&image) {
492                    // Every identity resolves in the immutable bounded registry,
493                    // so the reserved registry-sized vector cannot grow here.
494                    referenced.images.push(image);
495                    work.texture_bytes = work.texture_bytes.saturating_add(asset.pixels().len());
496                }
497                work.image();
498            }
499            #[cfg(feature = "text")]
500            ScreenDraw::Text { index } => {
501                let text = extracted
502                    .resolved_screen_texts()
503                    .get(index)
504                    .ok_or(super::text::DesktopTextError::InvalidDrawPlan)?;
505                if draw_plan::visible(text) {
506                    account_texts(&mut work, referenced, std::slice::from_ref(text))?;
507                }
508            }
509        }
510    }
511    // This preflight covers public CPU statistics. Engine also checks its
512    // private uniform sizes and exact tessellation before presenting anything.
513    work.validate(budget)?;
514    Ok(())
515}
516
517#[cfg(feature = "text")]
518fn account_texts(
519    work: &mut FrameWork,
520    referenced: &mut ScreenReferences,
521    texts: &[crate::ResolvedScreenText],
522) -> Result<(), super::text::DesktopTextError> {
523    let first = texts
524        .first()
525        .ok_or(super::text::DesktopTextError::InvalidDrawPlan)?;
526    let font = first.font();
527    if !referenced.fonts.contains(font) {
528        referenced
529            .fonts
530            .try_reserve(1)
531            .map_err(|_| super::text::DesktopTextError::Allocation {
532                requested_bytes: size_of::<crate::text::TextFont>(),
533            })?;
534        referenced.fonts.push(font.clone());
535        let atlas = font.settings().atlas_budget();
536        work.texture_bytes = work.texture_bytes.saturating_add(
537            (atlas.width() as usize)
538                .saturating_mul(atlas.height() as usize)
539                .saturating_mul(4),
540        );
541    }
542    work.passes = work.passes.saturating_add(1);
543    work.commands = work.commands.saturating_add(1);
544    let mut previous_clip = None;
545    for text in texts {
546        // Shaped count includes spacing glyphs, so both vertices and clip spans
547        // are conservative. Engine validates actual raster counts afterward.
548        work.vertices = work
549            .vertices
550            .saturating_add(text.visual().glyph_count().saturating_mul(6));
551        let clip = text.visual().clip();
552        if previous_clip != Some(clip) {
553            work.draw_calls = work.draw_calls.saturating_add(1);
554            previous_clip = Some(clip);
555        }
556    }
557    Ok(())
558}
559
560fn screen_camera(viewport: LogicalViewport) -> Result<Camera2d, FrameComposerError> {
561    Camera2d::new(
562        Vec2::new(viewport.width() * 0.5, viewport.height() * -0.5),
563        1.0,
564    )
565    .map_err(|_| RendererFrameError::InvalidGeometryTransform.into())
566}
567
568fn screen_rectangle(position: LogicalScreenPosition, size: LogicalScreenVector) -> Rect {
569    let position = position.to_vec2();
570    let size = size.to_vec2();
571    Rect::new(
572        Vec2::new(position.x(), -(position.y() + size.y())),
573        Vec2::new(position.x() + size.x(), -position.y()),
574    )
575}
576
577fn image_camera(
578    viewport: LogicalViewport,
579    position: LogicalScreenPosition,
580    size: LogicalScreenVector,
581    rotation: f32,
582) -> Result<Camera2d, FrameComposerError> {
583    let mut camera = screen_camera(viewport)?;
584    if rotation == 0.0 {
585        return Ok(camera);
586    }
587    let p = position.to_vec2() + size.to_vec2() * 0.5;
588    let pivot = Vec2::new(p.x(), -p.y());
589    let delta = camera.center() - pivot;
590    let (sin, cos) = rotation.sin_cos();
591    let center = pivot
592        + Vec2::new(
593            delta.x() * cos - delta.y() * sin,
594            delta.x() * sin + delta.y() * cos,
595        );
596    camera
597        .set_center(center)
598        .map_err(|_| FrameComposerError::Frame(RendererFrameError::InvalidGeometryTransform))?;
599    camera
600        .set_rotation(-rotation)
601        .map_err(|_| FrameComposerError::Frame(RendererFrameError::InvalidGeometryTransform))?;
602    Ok(camera)
603}
604
605pub(super) fn present(
606    renderer: &mut WgpuRenderer,
607    extracted: &ExtractedFrame,
608    registry: &ImageAssetRegistry,
609    images: &mut DesktopImages,
610    budget: FrameBudget,
611    target: Option<&RenderTarget2d>,
612) -> Result<FrameReport, ScreenPresentationError> {
613    preflight_with_target(
614        extracted,
615        registry,
616        &mut images.referenced,
617        budget,
618        target.map(RenderTarget2d::allocation_bytes),
619        images.screen_mode,
620        images.text_batching,
621    )?;
622    let viewport = renderer
623        .logical_viewport()
624        .map_err(|_| FrameComposerError::Frame(RendererFrameError::InvalidViewport))?;
625    images.prepare(renderer, registry, extracted)?;
626    images
627        .geometry
628        .prepare(renderer, extracted, images.screen_mode)
629        .map_err(DesktopImageError::Geometry)?;
630    #[cfg(feature = "text")]
631    images
632        .texts
633        .prepare(renderer, extracted, images.text_batching)?;
634
635    let mut frame = renderer.begin_frame(extracted.background(), budget)?;
636    frame.draw_scene(
637        extracted.world_scene(),
638        extracted.camera(),
639        FramePassOptions::new(0),
640    )?;
641    if let Some(target) = target {
642        // Engine targets already contain premultiplied color. Alpha composition
643        // reveals the underlying World through a transparent 3D background.
644        frame.draw_render_target(target, BlendMode::Alpha, 1.0, FramePassOptions::new(0))?;
645    }
646    #[cfg(feature = "text")]
647    let mut text_batch = 0;
648    for draw in draw_plan::draws(extracted, images.text_batching) {
649        // FrameComposer keeps insertion order when the integer order is equal.
650        // CPU layer/depth/entity sorting therefore survives interleaved types.
651        let options = FramePassOptions::new(1);
652        #[cfg(not(feature = "text"))]
653        let DesktopDraw::Single(draw) = draw?;
654        #[cfg(feature = "text")]
655        let draw = match draw? {
656            DesktopDraw::Single(draw) => draw,
657            #[cfg(feature = "text")]
658            DesktopDraw::TextBatch(_) => {
659                images.texts.draw_batch(&mut frame, text_batch, options)?;
660                text_batch += 1;
661                continue;
662            }
663        };
664        match draw {
665            #[cfg(all(feature = "headless-text", not(feature = "text")))]
666            ScreenDraw::Text { .. } => return Err(DesktopImageError::TextFeatureRequired.into()),
667            ScreenDraw::Rectangles { run } | ScreenDraw::Primitives { run } => {
668                let scene = extracted
669                    .screen_rectangle_run(run)
670                    .ok_or(DesktopImageError::InvalidDrawPlan)?;
671                if images.screen_mode == super::geometry::DesktopScreenMode::Streaming {
672                    frame.draw_screen_scene(scene, options)?;
673                } else {
674                    images.geometry.draw(&mut frame, run, options)?;
675                }
676            }
677            ScreenDraw::Image { index } => {
678                let visual = extracted
679                    .resolved_screen_images()
680                    .get(index)
681                    .ok_or(DesktopImageError::InvalidDrawPlan)?;
682                if visual.clip() == crate::screen::ScreenClip::Empty {
683                    continue;
684                }
685                let image = images.resources.get(visual.image()).ok_or(
686                    DesktopImageError::MissingAsset {
687                        source: visual.source(),
688                        image: visual.image(),
689                    },
690                )?;
691                let options = match visual.clip() {
692                    crate::screen::ScreenClip::Empty => continue,
693                    crate::screen::ScreenClip::Unclipped => options,
694                    crate::screen::ScreenClip::Rectangle(clip) => options.with_clip(clip),
695                };
696                let region = visual
697                    .source_region()
698                    .map(|region| {
699                        ImageTexelRect::new(region.x(), region.y(), region.width(), region.height())
700                    })
701                    .transpose()
702                    .map_err(|error| DesktopImageError::Upload {
703                        source: visual.source(),
704                        image: visual.image(),
705                        error,
706                    })?;
707                let sampling = match visual.filter() {
708                    ImageFilter::Nearest => ImageSampling::Nearest,
709                    ImageFilter::Linear => ImageSampling::Linear,
710                };
711                frame.draw_world_image(
712                    image,
713                    region,
714                    screen_rectangle(visual.position(), visual.size()),
715                    0.0,
716                    image_camera(
717                        viewport,
718                        visual.position(),
719                        visual.size(),
720                        visual.rotation(),
721                    )?,
722                    visual.tint(),
723                    sampling,
724                    options,
725                )?;
726            }
727            #[cfg(feature = "text")]
728            ScreenDraw::Text { index } => {
729                let text = extracted
730                    .resolved_screen_texts()
731                    .get(index)
732                    .ok_or(super::text::DesktopTextError::InvalidDrawPlan)?;
733                if !text.text().is_empty() {
734                    let options = match text.visual().clip() {
735                        crate::screen::ScreenClip::Empty => continue,
736                        crate::screen::ScreenClip::Unclipped => options,
737                        crate::screen::ScreenClip::Rectangle(clip) => options.with_clip(clip),
738                    };
739                    images.texts.draw(&mut frame, text, options)?;
740                }
741            }
742        }
743    }
744    Ok(frame.present()?)
745}
746
747#[cfg(test)]
748mod tests {
749    use std::cell::Cell;
750
751    use super::*;
752
753    #[test]
754    fn rotated_images_keep_center_and_clockwise_logical_geometry_for_any_viewport()
755    -> crate::LogicResult {
756        let position = LogicalScreenPosition::new(100.0, 80.0);
757        let size = LogicalScreenVector::new(100.0, 20.0);
758        let pivot = Vec2::new(150.0, -90.0);
759        for (width, height) in [(800.0, 600.0), (640.0, 480.0), (300.0, 900.0)] {
760            let viewport = LogicalViewport::new(width, height)?;
761            for angle in [0.0, std::f32::consts::FRAC_PI_2, 0.4, -0.7] {
762                let camera = image_camera(viewport, position, size, angle)?;
763                let center = camera.world_to_screen(pivot, viewport)?.to_vec2();
764                assert!((center.x() - 150.0).abs() < 0.0002);
765                assert!((center.y() - 90.0).abs() < 0.0002);
766                let right = camera
767                    .world_to_screen(pivot + Vec2::new(50.0, 0.0), viewport)?
768                    .to_vec2();
769                assert!((right.x() - (150.0 + 50.0 * angle.cos())).abs() < 0.0002);
770                assert!((right.y() - (90.0 + 50.0 * angle.sin())).abs() < 0.0002);
771            }
772        }
773        Ok(())
774    }
775
776    #[test]
777    fn cache_reuses_resources_until_renderer_invalidation() {
778        let uploads = Cell::new(0);
779        let mut cache = ResourceCache::new();
780        let create = || {
781            uploads.set(uploads.get() + 1);
782            Ok::<_, ()>(uploads.get())
783        };
784        cache.ensure(7, 2, create).unwrap();
785        cache.ensure(7, 2, create).unwrap();
786        cache.ensure(9, 2, create).unwrap();
787        assert_eq!(uploads.get(), 2);
788        assert_eq!(cache.get(7), Some(&1));
789        assert_eq!(cache.get(9), Some(&2));
790        let capacity = cache.entries.capacity();
791        cache.clear();
792        assert!(cache.get(7).is_none());
793        assert_eq!(cache.entries.capacity(), capacity);
794        cache.ensure(7, 2, create).unwrap();
795        assert_eq!(uploads.get(), 3);
796        assert_eq!(cache.get(7), Some(&3));
797    }
798
799    #[test]
800    fn failed_resource_preparation_preserves_existing_entries_and_retries() {
801        let mut cache = ResourceCache::new();
802        cache.ensure(1, 2, || Ok::<_, &'static str>(10)).unwrap();
803        assert_eq!(
804            cache.ensure(2, 2, || Err("upload failed")),
805            Err(CacheError::Create("upload failed"))
806        );
807        assert_eq!(cache.get(1), Some(&10));
808        assert_eq!(cache.get(2), None);
809        cache.ensure(2, 2, || Ok::<_, &'static str>(20)).unwrap();
810        assert_eq!(cache.get(2), Some(&20));
811        assert_eq!(
812            cache.ensure(3, 2, || Ok::<_, &'static str>(30)),
813            Err(CacheError::Limit { limit: 2 })
814        );
815        assert_eq!(cache.entries.len(), 2);
816    }
817
818    #[cfg(feature = "text")]
819    #[test]
820    fn glyph_group_preflight_counts_one_item_but_preserves_clip_draw_limits() -> crate::LogicResult
821    {
822        use crate::prelude::*;
823        #[derive(Clone, Copy, PartialEq, Eq, Hash)]
824        enum Action {}
825        let mut config = AppConfig::default();
826        config.set_render_limits(
827            RenderLimits::default()
828                .with_max_screen_texts(3)
829                .with_max_screen_text_bytes(64)
830                .with_max_screen_text_glyphs(16),
831        );
832        let mut app = Application::<Action>::new(config)?;
833        let font = app.register_font(
834            include_bytes!("../../../tests/assets/text/DejaVuSans.ttf").to_vec(),
835            TextSettings::new(18.0)?,
836        )?;
837        let a = ScreenTextVisual::new(font, "A", LogicalScreenPosition::new(3.0, 30.0))?;
838        let mut b = a.clone();
839        b.set_clip(ScreenClip::Rectangle(sim_engine::ScreenClipRect::new(
840            LogicalScreenPosition::new(0.0, 0.0),
841            LogicalScreenPosition::new(40.0, 40.0),
842        )?));
843        let camera = ActiveCamera2d::centered(1.0)?;
844        let initial = app.register_world("group-budget", move |world| {
845            world.spawn(camera)?;
846            world.spawn(a.clone())?;
847            world.spawn(b.clone())?;
848            world.spawn(a.clone())?;
849            Ok(())
850        })?;
851        let runner = app.build_headless(initial)?;
852        let snapshot = runner.extracted_frame().unwrap();
853        let mut references = ScreenReferences::default();
854        let check = |references: &mut ScreenReferences, batching, draws| {
855            preflight_with_target(
856                snapshot,
857                runner.image_assets(),
858                references,
859                FrameBudget::new(2, 8, 100, 65_536, 16 * 1024 * 1024, draws),
860                None,
861                super::super::geometry::DesktopScreenMode::Prepared,
862                batching,
863            )
864        };
865        check(&mut references, true, 3).unwrap();
866        assert!(matches!(
867            check(&mut references, false, 3),
868            Err(ScreenPresentationError::Composition(
869                FrameComposerError::BudgetExceeded {
870                    resource: FrameBudgetResource::Passes,
871                    actual: 4,
872                    ..
873                }
874            ))
875        ));
876        assert!(matches!(
877            check(&mut references, true, 2),
878            Err(ScreenPresentationError::Composition(
879                FrameComposerError::BudgetExceeded {
880                    resource: FrameBudgetResource::DrawCalls,
881                    actual: 3,
882                    ..
883                }
884            ))
885        ));
886        Ok(())
887    }
888
889    #[test]
890    fn screen_image_camera_preserves_offscreen_corners_and_vertical_orientation() {
891        for (width, height) in [(640.0, 360.0), (301.0, 901.0), (1.0, 1.0)] {
892            let viewport = LogicalViewport::new(width, height).unwrap();
893            let camera = screen_camera(viewport).unwrap();
894            let position = LogicalScreenPosition::new(-10.0, -20.0);
895            let size = LogicalScreenVector::new(width + 40.0, height + 60.0);
896            let rectangle = screen_rectangle(position, size);
897            let top_left = camera
898                .world_to_screen(
899                    Vec2::new(rectangle.min().x(), rectangle.max().y()),
900                    viewport,
901                )
902                .unwrap();
903            let bottom_right = camera
904                .world_to_screen(
905                    Vec2::new(rectangle.max().x(), rectangle.min().y()),
906                    viewport,
907                )
908                .unwrap();
909            assert_eq!(top_left, position);
910            assert_eq!(bottom_right.to_vec2(), position.to_vec2() + size.to_vec2());
911        }
912    }
913
914    #[test]
915    fn mixed_plan_preflight_counts_every_run_and_each_shared_texture_once() -> crate::LogicResult {
916        use crate::prelude::*;
917
918        let mut config = AppConfig::default();
919        config.set_render_limits(RenderLimits::default().with_max_screen_images(2));
920        let mut application = Application::<u8>::new(config)?;
921        let asset = application.register_image_rgba8(4, 1, &[255; 16])?;
922        let position = LogicalScreenPosition::new(-2.0, 4.0);
923        let size = LogicalScreenVector::new(12.0, 8.0);
924        let rectangle = ScreenRectangleVisual::new(position, size, Color::WHITE)?;
925        let image = ScreenImageVisual::new(asset, position, size)?;
926        let camera = ActiveCamera2d::centered(1.0)?;
927        let world = application.register_world("desktop-image-plan", move |world| {
928            world.spawn(camera)?;
929            for depth in [0.0, 2.0, 4.0] {
930                let mut visual = rectangle;
931                visual
932                    .set_draw_order_depth(depth)
933                    .map_err(|error| crate::world::WorldBuildError::user(error.to_string()))?;
934                world.spawn(visual)?;
935            }
936            for depth in [1.0, 3.0] {
937                let mut visual = image;
938                visual
939                    .set_draw_order_depth(depth)
940                    .map_err(|error| crate::world::WorldBuildError::user(error.to_string()))?;
941                world.spawn(visual)?;
942            }
943            Ok(())
944        })?;
945        let runner = application.build_headless(world)?;
946        let extracted = runner.extracted_frame().unwrap();
947        assert_eq!(
948            extracted.screen_draws(),
949            &[
950                ScreenDraw::Rectangles { run: 0 },
951                ScreenDraw::Image { index: 0 },
952                ScreenDraw::Rectangles { run: 1 },
953                ScreenDraw::Image { index: 1 },
954                ScreenDraw::Rectangles { run: 2 },
955            ]
956        );
957        let mut referenced = ScreenReferences::default();
958        let enough = FrameBudget::new(6, 100, 1000, 10000, 16, 100);
959        preflight(extracted, runner.image_assets(), &mut referenced, enough).unwrap();
960        assert_eq!(referenced.images, [asset]);
961        let passes = FrameBudget::new(5, 100, 1000, 10000, 16, 100);
962        assert!(matches!(
963            preflight(extracted, runner.image_assets(), &mut referenced, passes),
964            Err(ScreenPresentationError::Composition(
965                FrameComposerError::BudgetExceeded {
966                    resource: FrameBudgetResource::Passes,
967                    limit: 5,
968                    actual: 6
969                }
970            ))
971        ));
972        let textures = FrameBudget::new(6, 100, 1000, 10000, 15, 100);
973        assert!(matches!(
974            preflight(extracted, runner.image_assets(), &mut referenced, textures),
975            Err(ScreenPresentationError::Composition(
976                FrameComposerError::BudgetExceeded {
977                    resource: FrameBudgetResource::TextureBytes,
978                    limit: 15,
979                    actual: 16
980                }
981            ))
982        ));
983        let three_d = FrameBudget::new(7, 100, 1000, 10000, 80, 100);
984        preflight_with_target(
985            extracted,
986            runner.image_assets(),
987            &mut referenced,
988            three_d,
989            Some(64),
990            super::super::geometry::DesktopScreenMode::Streaming,
991            false,
992        )
993        .unwrap();
994        assert!(matches!(
995            preflight_with_target(
996                extracted,
997                runner.image_assets(),
998                &mut referenced,
999                enough,
1000                Some(64),
1001                super::super::geometry::DesktopScreenMode::Streaming,
1002                false,
1003            ),
1004            Err(ScreenPresentationError::Composition(
1005                FrameComposerError::BudgetExceeded {
1006                    resource: FrameBudgetResource::Passes,
1007                    actual: 7,
1008                    ..
1009                }
1010            ))
1011        ));
1012        let short_texture = FrameBudget::new(7, 100, 1000, 10000, 79, 100);
1013        assert!(matches!(
1014            preflight_with_target(
1015                extracted,
1016                runner.image_assets(),
1017                &mut referenced,
1018                short_texture,
1019                Some(64),
1020                super::super::geometry::DesktopScreenMode::Streaming,
1021                false,
1022            ),
1023            Err(ScreenPresentationError::Composition(
1024                FrameComposerError::BudgetExceeded {
1025                    resource: FrameBudgetResource::TextureBytes,
1026                    actual: 80,
1027                    ..
1028                }
1029            ))
1030        ));
1031        Ok(())
1032    }
1033}