Skip to main content

sim_engine/renderer/
frame.rs

1use super::*;
2
3/// Work category constrained by a [`FrameBudget`].
4#[derive(Debug, Clone, Copy, PartialEq, Eq)]
5pub enum FrameBudgetResource {
6    /// Number of ordered sources in one frame.
7    Passes,
8    /// Scene commands referenced by the frame.
9    Commands,
10    /// Generated or retained vertices referenced by the frame.
11    Vertices,
12    /// Bytes uploaded while preparing the frame.
13    UploadBytes,
14    /// Nominal retained texel-storage bytes referenced by images, fields, or targets.
15    TextureBytes,
16    /// Conservative number of GPU draw calls encoded by the frame.
17    DrawCalls,
18}
19
20/// Explicit upper bounds for one heterogeneous presentation frame.
21///
22/// The default is deliberately finite. Production hosts should select limits
23/// from their frame-time and memory budgets instead of treating it as a device
24/// capability query.
25#[derive(Debug, Clone, Copy, PartialEq, Eq)]
26pub struct FrameBudget {
27    max_passes: usize,
28    max_commands: usize,
29    max_vertices: usize,
30    max_upload_bytes: usize,
31    max_texture_bytes: usize,
32    max_draw_calls: usize,
33}
34
35impl FrameBudget {
36    /// Creates an exact set of frame-work limits.
37    pub const fn new(
38        max_passes: usize,
39        max_commands: usize,
40        max_vertices: usize,
41        max_upload_bytes: usize,
42        max_texture_bytes: usize,
43        max_draw_calls: usize,
44    ) -> Self {
45        Self {
46            max_passes,
47            max_commands,
48            max_vertices,
49            max_upload_bytes,
50            max_texture_bytes,
51            max_draw_calls,
52        }
53    }
54
55    /// Returns the maximum number of ordered sources.
56    pub const fn max_passes(self) -> usize {
57        self.max_passes
58    }
59
60    /// Returns the maximum referenced scene-command count.
61    pub const fn max_commands(self) -> usize {
62        self.max_commands
63    }
64
65    /// Returns the maximum referenced or generated vertex count.
66    pub const fn max_vertices(self) -> usize {
67        self.max_vertices
68    }
69
70    /// Returns the maximum bytes uploaded while presenting the frame.
71    pub const fn max_upload_bytes(self) -> usize {
72        self.max_upload_bytes
73    }
74
75    /// Returns the maximum referenced nominal texel-storage bytes.
76    pub const fn max_texture_bytes(self) -> usize {
77        self.max_texture_bytes
78    }
79
80    /// Returns the maximum conservative draw-call count.
81    pub const fn max_draw_calls(self) -> usize {
82        self.max_draw_calls
83    }
84}
85
86impl Default for FrameBudget {
87    fn default() -> Self {
88        Self::new(
89            64,
90            100_000,
91            4_000_000,
92            256 * 1024 * 1024,
93            512 * 1024 * 1024,
94            65_536,
95        )
96    }
97}
98
99/// Shared placement and ordering state for one frame item.
100#[derive(Debug, Clone, Copy, PartialEq, Default)]
101pub struct FramePassOptions {
102    order: i32,
103    viewport: Option<LogicalViewportRegion>,
104    clip: Option<ScreenClipRect>,
105}
106
107impl FramePassOptions {
108    /// Creates a full-surface, unclipped item at `order`.
109    pub const fn new(order: i32) -> Self {
110        Self {
111            order,
112            viewport: None,
113            clip: None,
114        }
115    }
116
117    /// Positions the item in a logical sub-viewport of the surface.
118    pub const fn with_viewport(mut self, viewport: LogicalViewportRegion) -> Self {
119        self.viewport = Some(viewport);
120        self
121    }
122
123    /// Intersects all source-local clips with an additional item-local clip.
124    pub const fn with_clip(mut self, clip: ScreenClipRect) -> Self {
125        self.clip = Some(clip);
126        self
127    }
128
129    /// Returns the stable ordering key. Lower values draw first.
130    pub const fn order(self) -> i32 {
131        self.order
132    }
133
134    /// Returns the optional positioned logical viewport.
135    pub const fn viewport(self) -> Option<LogicalViewportRegion> {
136        self.viewport
137    }
138
139    /// Returns the optional item-local logical clip.
140    pub const fn clip(self) -> Option<ScreenClipRect> {
141        self.clip
142    }
143}
144
145/// Renderer-owned source category used in structured composer errors.
146#[derive(Debug, Clone, Copy, PartialEq, Eq)]
147pub enum FrameSourceKind {
148    /// Streaming world-space or fixed-screen scene tessellated for this frame.
149    StreamingScene,
150    /// Immutable prepared world or screen geometry.
151    PreparedScene,
152    /// Mutable retained triangle geometry.
153    DynamicMesh,
154    /// Instanced retained particle resource.
155    ParticleField,
156    /// Renderer-owned scalar texture.
157    ScalarField,
158    /// Retained sRGB RGBA image or atlas.
159    Image,
160    /// Retained host-shaped glyph atlas and positioned run.
161    Glyph,
162    /// Offscreen color texture.
163    RenderTarget,
164}
165
166/// Ordered frame inputs grouped by their renderer source path.
167#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
168pub struct FrameSourceStatistics {
169    streaming_scenes: usize,
170    prepared_scenes: usize,
171    dynamic_meshes: usize,
172    particle_fields: usize,
173    scalar_fields: usize,
174    images: usize,
175    glyph_runs: usize,
176    render_targets: usize,
177}
178
179impl FrameSourceStatistics {
180    /// Returns streaming world and fixed-screen scenes.
181    pub const fn streaming_scenes(self) -> usize {
182        self.streaming_scenes
183    }
184
185    /// Returns immutable prepared world and fixed-screen scenes.
186    pub const fn prepared_scenes(self) -> usize {
187        self.prepared_scenes
188    }
189
190    /// Returns retained dynamic triangle meshes.
191    pub const fn dynamic_meshes(self) -> usize {
192        self.dynamic_meshes
193    }
194
195    /// Returns retained particle fields.
196    pub const fn particle_fields(self) -> usize {
197        self.particle_fields
198    }
199
200    /// Returns retained scalar fields.
201    pub const fn scalar_fields(self) -> usize {
202        self.scalar_fields
203    }
204
205    /// Returns image, world-image, and atlas-batch sources.
206    pub const fn images(self) -> usize {
207        self.images
208    }
209
210    /// Returns host-shaped glyph runs.
211    pub const fn glyph_runs(self) -> usize {
212        self.glyph_runs
213    }
214
215    /// Returns composed 2D or retained-3D color targets.
216    pub const fn render_targets(self) -> usize {
217        self.render_targets
218    }
219
220    /// Returns all accepted frame sources.
221    pub const fn total(self) -> usize {
222        self.streaming_scenes
223            .saturating_add(self.prepared_scenes)
224            .saturating_add(self.dynamic_meshes)
225            .saturating_add(self.particle_fields)
226            .saturating_add(self.scalar_fields)
227            .saturating_add(self.images)
228            .saturating_add(self.glyph_runs)
229            .saturating_add(self.render_targets)
230    }
231
232    const fn single(source: FrameSourceKind) -> Self {
233        let mut counts = Self {
234            streaming_scenes: 0,
235            prepared_scenes: 0,
236            dynamic_meshes: 0,
237            particle_fields: 0,
238            scalar_fields: 0,
239            images: 0,
240            glyph_runs: 0,
241            render_targets: 0,
242        };
243        match source {
244            FrameSourceKind::StreamingScene => counts.streaming_scenes = 1,
245            FrameSourceKind::PreparedScene => counts.prepared_scenes = 1,
246            FrameSourceKind::DynamicMesh => counts.dynamic_meshes = 1,
247            FrameSourceKind::ParticleField => counts.particle_fields = 1,
248            FrameSourceKind::ScalarField => counts.scalar_fields = 1,
249            FrameSourceKind::Image => counts.images = 1,
250            FrameSourceKind::Glyph => counts.glyph_runs = 1,
251            FrameSourceKind::RenderTarget => counts.render_targets = 1,
252        }
253        counts
254    }
255
256    const fn adding(self, other: Self) -> Self {
257        Self {
258            streaming_scenes: self.streaming_scenes.saturating_add(other.streaming_scenes),
259            prepared_scenes: self.prepared_scenes.saturating_add(other.prepared_scenes),
260            dynamic_meshes: self.dynamic_meshes.saturating_add(other.dynamic_meshes),
261            particle_fields: self.particle_fields.saturating_add(other.particle_fields),
262            scalar_fields: self.scalar_fields.saturating_add(other.scalar_fields),
263            images: self.images.saturating_add(other.images),
264            glyph_runs: self.glyph_runs.saturating_add(other.glyph_runs),
265            render_targets: self.render_targets.saturating_add(other.render_targets),
266        }
267    }
268}
269
270/// Failure while constructing or presenting a heterogeneous frame.
271#[derive(Debug, Clone, Copy, PartialEq)]
272pub enum FrameComposerError {
273    /// The one frame clear color was not normalized linear RGBA.
274    InvalidBackground,
275    /// A target-composition opacity was non-finite or outside `0.0..=1.0`.
276    InvalidOpacity,
277    /// An image tint was not normalized linear RGBA.
278    InvalidTint,
279    /// An atlas source rectangle did not fit its image.
280    InvalidImageRegion,
281    /// A world image rectangle or pseudo-depth was invalid.
282    InvalidWorldImage,
283    /// Scalar endpoints were invalid or their finite subtraction overflowed.
284    InvalidValueRange {
285        /// Lower scalar endpoint supplied by the host.
286        minimum: f32,
287        /// Upper scalar endpoint supplied by the host.
288        maximum: f32,
289    },
290    /// A retained source belongs to another renderer or recovery generation.
291    RendererMismatch {
292        /// Category of the rejected retained source.
293        source: FrameSourceKind,
294    },
295    /// A frame-work limit would be exceeded.
296    BudgetExceeded {
297        /// Work category whose limit was exceeded.
298        resource: FrameBudgetResource,
299        /// Configured upper bound.
300        limit: usize,
301        /// Conservative work after accepting the requested item.
302        actual: usize,
303    },
304    /// CPU storage for frame construction could not be reserved.
305    AllocationFailed {
306        /// Minimum additional bytes requested by the failed reservation.
307        requested_bytes: usize,
308    },
309    /// Validation, surface acquisition, or GPU-capacity work failed.
310    Frame(RendererFrameError),
311}
312
313impl fmt::Display for FrameComposerError {
314    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
315        match self {
316            Self::InvalidBackground => write!(formatter, "frame background must be normalized"),
317            Self::InvalidOpacity => write!(formatter, "frame opacity must be finite and in 0..=1"),
318            Self::InvalidTint => write!(formatter, "frame image tint must be normalized"),
319            Self::InvalidImageRegion => write!(formatter, "frame image region is out of bounds"),
320            Self::InvalidWorldImage => {
321                write!(formatter, "frame world image rectangle or depth is invalid")
322            }
323            Self::InvalidValueRange { minimum, maximum } => {
324                write!(formatter, "invalid frame scalar range {minimum}..{maximum}")
325            }
326            Self::RendererMismatch { source } => {
327                write!(formatter, "frame {source:?} belongs to another renderer")
328            }
329            Self::BudgetExceeded {
330                resource,
331                limit,
332                actual,
333            } => write!(
334                formatter,
335                "frame {resource:?} work exceeds its limit {limit}: {actual}"
336            ),
337            Self::AllocationFailed { requested_bytes } => write!(
338                formatter,
339                "could not reserve {requested_bytes} additional bytes for frame construction"
340            ),
341            Self::Frame(error) => write!(formatter, "frame presentation failed: {error}"),
342        }
343    }
344}
345
346impl Error for FrameComposerError {}
347
348impl From<RendererFrameError> for FrameComposerError {
349    fn from(error: RendererFrameError) -> Self {
350        Self::Frame(error)
351    }
352}
353
354/// Bounded work and retained allocations referenced by one composed frame.
355#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
356pub struct FrameStatistics {
357    pass_count: usize,
358    command_count: usize,
359    vertex_count: usize,
360    streaming_vertex_count: usize,
361    reused_vertex_count: usize,
362    upload_bytes: usize,
363    streaming_upload_bytes: usize,
364    texture_bytes: usize,
365    retained_cpu_bytes: usize,
366    retained_buffer_bytes: usize,
367    draw_calls: usize,
368    source_counts: FrameSourceStatistics,
369}
370
371impl FrameStatistics {
372    /// Returns ordered source count.
373    pub const fn pass_count(self) -> usize {
374        self.pass_count
375    }
376
377    /// Returns referenced scene-command count.
378    pub const fn command_count(self) -> usize {
379        self.command_count
380    }
381
382    /// Returns referenced or generated vertex count.
383    pub const fn vertex_count(self) -> usize {
384        self.vertex_count
385    }
386
387    /// Returns vertices generated or selected during this frame.
388    pub const fn streaming_vertex_count(self) -> usize {
389        self.streaming_vertex_count
390    }
391
392    /// Returns retained prepared or dynamic vertices reused without frame upload.
393    pub const fn reused_vertex_count(self) -> usize {
394        self.reused_vertex_count
395    }
396
397    /// Returns bytes uploaded for streaming vertices and per-item uniforms.
398    pub const fn upload_bytes(self) -> usize {
399        self.upload_bytes
400    }
401
402    /// Returns the subset uploaded for streaming geometry or instances.
403    pub const fn streaming_upload_bytes(self) -> usize {
404        self.streaming_upload_bytes
405    }
406
407    /// Returns nominal retained texel-storage bytes referenced by frame items.
408    ///
409    /// Repeated image, scalar-field, and render-target identities are
410    /// deduplicated. Opaque backend alignment, tiling, page allocation, and
411    /// metadata are excluded because wgpu does not expose them. Color-map LUT
412    /// bytes follow the renderer's one-entry cache:
413    /// adjacent equal LUTs share one allocation, while an `A, B, A` sequence
414    /// keeps three views/allocations alive until submission.
415    pub const fn texture_bytes(self) -> usize {
416        self.texture_bytes
417    }
418
419    /// Returns CPU recovery or source bytes held by unique referenced resources.
420    ///
421    /// Drawing the same scene, buffer, image, atlas, or run more than once does
422    /// not multiply this value. Distinct retained resources are summed even when
423    /// their contents happen to be equal.
424    pub const fn retained_cpu_bytes(self) -> usize {
425        self.retained_cpu_bytes
426    }
427
428    /// Returns GPU vertex or instance-buffer bytes held by unique referenced resources.
429    pub const fn retained_buffer_bytes(self) -> usize {
430        self.retained_buffer_bytes
431    }
432
433    /// Returns the conservative number of scheduled draw calls.
434    pub const fn draw_calls(self) -> usize {
435        self.draw_calls
436    }
437
438    /// Returns accepted ordered inputs grouped by renderer source path.
439    pub const fn source_counts(self) -> FrameSourceStatistics {
440        self.source_counts
441    }
442
443    fn adding(self, other: Self) -> Self {
444        Self {
445            pass_count: self.pass_count.saturating_add(other.pass_count),
446            command_count: self.command_count.saturating_add(other.command_count),
447            vertex_count: self.vertex_count.saturating_add(other.vertex_count),
448            streaming_vertex_count: self
449                .streaming_vertex_count
450                .saturating_add(other.streaming_vertex_count),
451            reused_vertex_count: self
452                .reused_vertex_count
453                .saturating_add(other.reused_vertex_count),
454            upload_bytes: self.upload_bytes.saturating_add(other.upload_bytes),
455            streaming_upload_bytes: self
456                .streaming_upload_bytes
457                .saturating_add(other.streaming_upload_bytes),
458            texture_bytes: self.texture_bytes.saturating_add(other.texture_bytes),
459            retained_cpu_bytes: self
460                .retained_cpu_bytes
461                .saturating_add(other.retained_cpu_bytes),
462            retained_buffer_bytes: self
463                .retained_buffer_bytes
464                .saturating_add(other.retained_buffer_bytes),
465            draw_calls: self.draw_calls.saturating_add(other.draw_calls),
466            source_counts: self.source_counts.adding(other.source_counts),
467        }
468    }
469
470    fn without_uploads(mut self) -> Self {
471        self.upload_bytes = 0;
472        self.streaming_upload_bytes = 0;
473        self
474    }
475}
476
477/// Outcome and diagnostics for one composed frame.
478#[derive(Debug, Clone, Copy, PartialEq, Eq)]
479pub struct FrameReport {
480    status: RenderStatus,
481    statistics: FrameStatistics,
482    metrics: RendererFrameMetrics,
483}
484
485impl FrameReport {
486    /// Returns whether the frame was drawn or temporarily skipped.
487    pub const fn status(self) -> RenderStatus {
488        self.status
489    }
490
491    /// Returns bounded work referenced by the frame.
492    pub const fn statistics(self) -> FrameStatistics {
493        self.statistics
494    }
495
496    /// Returns CPU-side timing and tessellation diagnostics.
497    pub const fn metrics(self) -> RendererFrameMetrics {
498        self.metrics
499    }
500
501    /// Returns command encoders submitted by this composed frame.
502    pub const fn command_encoder_count(self) -> usize {
503        match self.status {
504            RenderStatus::Drawn => 1,
505            RenderStatus::Skipped(_) => 0,
506        }
507    }
508
509    /// Returns GPU render passes encoded by this composed frame.
510    pub const fn render_pass_count(self) -> usize {
511        match self.status {
512            RenderStatus::Drawn => 1,
513            RenderStatus::Skipped(_) => 0,
514        }
515    }
516
517    /// Returns queue submissions performed by this composed frame.
518    pub const fn queue_submission_count(self) -> usize {
519        match self.status {
520            RenderStatus::Drawn => 1,
521            RenderStatus::Skipped(_) => 0,
522        }
523    }
524
525    /// Returns surface presents performed by this composed frame.
526    pub const fn surface_present_count(self) -> usize {
527        match self.status {
528            RenderStatus::Drawn => 1,
529            RenderStatus::Skipped(_) => 0,
530        }
531    }
532}
533
534/// One bounded, stably ordered surface frame under construction.
535///
536/// Calling [`FrameComposer::present`] performs all fallible geometry and
537/// ownership validation before acquiring the surface. A successful frame uses
538/// one clear, one command encoder, one queue submission, and one present.
539#[must_use = "a frame composer does no rendering until present is called"]
540pub struct FrameComposer<'frame> {
541    renderer: &'frame mut WgpuRenderer,
542    background: Color,
543    budget: FrameBudget,
544    items: Vec<FrameItem<'frame>>,
545    retained_resources: Vec<RetainedResourceKey>,
546    scalar_luts: Vec<ScalarLutPlan>,
547    scalar_lut_upload_count: usize,
548    scalar_lut_allocation_count: usize,
549    planned: FrameStatistics,
550    next_insertion: usize,
551}
552
553struct ScalarLutPlan {
554    sort_key: (i32, usize),
555    lut: [u8; COLOR_MAP_LUT_SIZE as usize * 4],
556}
557
558#[derive(Debug, Clone, Copy, PartialEq, Eq)]
559struct RetainedResourceKey {
560    address: usize,
561    class: u8,
562}
563
564#[derive(Debug, Clone, Copy)]
565struct RetainedResourceAccounting {
566    key: RetainedResourceKey,
567    cpu_bytes: usize,
568    buffer_bytes: usize,
569    texture_bytes: usize,
570}
571
572impl RetainedResourceAccounting {
573    const fn new(
574        key: RetainedResourceKey,
575        cpu_bytes: usize,
576        buffer_bytes: usize,
577        texture_bytes: usize,
578    ) -> Self {
579        Self {
580            key,
581            cpu_bytes,
582            buffer_bytes,
583            texture_bytes,
584        }
585    }
586}
587
588fn retained_key<T>(resource: &T, class: u8) -> RetainedResourceKey {
589    RetainedResourceKey {
590        address: std::ptr::from_ref(resource).cast::<()>() as usize,
591        class,
592    }
593}
594
595fn retained_arc_key<T>(resource: &Arc<T>, class: u8) -> RetainedResourceKey {
596    RetainedResourceKey {
597        address: Arc::as_ptr(resource).cast::<()>() as usize,
598        class,
599    }
600}
601
602fn account_new_retained_resources(
603    existing: &[RetainedResourceKey],
604    resources: &[RetainedResourceAccounting],
605    mut work: FrameStatistics,
606) -> (FrameStatistics, usize) {
607    let mut missing = 0usize;
608    for (index, resource) in resources.iter().enumerate() {
609        let already_in_request = resources[..index]
610            .iter()
611            .any(|previous| previous.key == resource.key);
612        if !already_in_request && !existing.contains(&resource.key) {
613            missing = missing.saturating_add(1);
614            work.retained_cpu_bytes = work.retained_cpu_bytes.saturating_add(resource.cpu_bytes);
615            work.retained_buffer_bytes = work
616                .retained_buffer_bytes
617                .saturating_add(resource.buffer_bytes);
618            work.texture_bytes = work.texture_bytes.saturating_add(resource.texture_bytes);
619        }
620    }
621    (work, missing)
622}
623
624fn scalar_lut_counts_with_inserted(
625    planned: &[ScalarLutPlan],
626    insertion: usize,
627    inserted: &[u8; COLOR_MAP_LUT_SIZE as usize * 4],
628    initial_cache: Option<&[u8; COLOR_MAP_LUT_SIZE as usize * 4]>,
629) -> (usize, usize) {
630    debug_assert!(insertion <= planned.len());
631    let mut previous: Option<&[u8; COLOR_MAP_LUT_SIZE as usize * 4]> = None;
632    let mut allocation_count = 0usize;
633    let mut first_matches_initial = false;
634    for merged_index in 0..=planned.len() {
635        let current = if merged_index == insertion {
636            inserted
637        } else {
638            let source_index = merged_index - usize::from(merged_index > insertion);
639            &planned[source_index].lut
640        };
641        if previous.is_none() {
642            first_matches_initial = initial_cache == Some(current);
643        }
644        if previous != Some(current) {
645            allocation_count = allocation_count.saturating_add(1);
646        }
647        previous = Some(current);
648    }
649    let upload_count = allocation_count.saturating_sub(usize::from(first_matches_initial));
650    (upload_count, allocation_count)
651}
652
653enum FrameItem<'frame> {
654    Scene {
655        scene: &'frame Scene,
656        camera: Camera2d,
657        options: FramePassOptions,
658        insertion: usize,
659    },
660    ScreenScene {
661        scene: &'frame ScreenScene,
662        options: FramePassOptions,
663        insertion: usize,
664    },
665    Prepared {
666        scene: &'frame PreparedScene,
667        camera: Camera2d,
668        options: FramePassOptions,
669        insertion: usize,
670    },
671    PreparedScreen {
672        scene: &'frame PreparedScreenScene,
673        options: FramePassOptions,
674        insertion: usize,
675    },
676    Dynamic {
677        mesh: &'frame DynamicMesh2d,
678        camera: Camera2d,
679        options: FramePassOptions,
680        insertion: usize,
681    },
682    Particle {
683        field: &'frame mut ParticleField2d,
684        camera: Camera2d,
685        options: FramePassOptions,
686        insertion: usize,
687    },
688    Scalar {
689        texture: &'frame ScalarFieldTexture,
690        color_map: &'frame ColorMap,
691        minimum: f32,
692        maximum: f32,
693        value_extent: f32,
694        sampling: ScalarFieldSampling,
695        options: FramePassOptions,
696        insertion: usize,
697    },
698    Image {
699        image: &'frame Image2d,
700        source: ImageTexelRect,
701        tint: Color,
702        sampling: ImageSampling,
703        options: FramePassOptions,
704        insertion: usize,
705    },
706    WorldImage {
707        image: &'frame Image2d,
708        source: ImageTexelRect,
709        rectangle: Rect,
710        depth: f32,
711        camera: Camera2d,
712        tint: Color,
713        sampling: ImageSampling,
714        options: FramePassOptions,
715        insertion: usize,
716    },
717    ImageBatch {
718        image: &'frame Image2d,
719        batch: &'frame ImageBatch2d,
720        sampling: ImageSampling,
721        options: FramePassOptions,
722        insertion: usize,
723    },
724    Target {
725        target: &'frame RenderTarget2d,
726        blend_mode: BlendMode,
727        opacity: f32,
728        options: FramePassOptions,
729        insertion: usize,
730    },
731}
732
733impl FrameItem<'_> {
734    fn sort_key(&self) -> (i32, usize) {
735        match self {
736            Self::Scene {
737                options, insertion, ..
738            }
739            | Self::ScreenScene {
740                options, insertion, ..
741            }
742            | Self::Prepared {
743                options, insertion, ..
744            }
745            | Self::PreparedScreen {
746                options, insertion, ..
747            }
748            | Self::Dynamic {
749                options, insertion, ..
750            }
751            | Self::Particle {
752                options, insertion, ..
753            }
754            | Self::Scalar {
755                options, insertion, ..
756            }
757            | Self::Image {
758                options, insertion, ..
759            }
760            | Self::WorldImage {
761                options, insertion, ..
762            }
763            | Self::ImageBatch {
764                options, insertion, ..
765            }
766            | Self::Target {
767                options, insertion, ..
768            } => (options.order(), *insertion),
769        }
770    }
771}
772
773impl WgpuRenderer {
774    /// Begins one bounded heterogeneous frame with a single clear color.
775    pub fn begin_frame(
776        &mut self,
777        background: Color,
778        budget: FrameBudget,
779    ) -> Result<FrameComposer<'_>, FrameComposerError> {
780        if !background.is_normalized() {
781            return Err(FrameComposerError::InvalidBackground);
782        }
783        Ok(FrameComposer {
784            renderer: self,
785            background,
786            budget,
787            items: Vec::new(),
788            retained_resources: Vec::new(),
789            scalar_luts: Vec::new(),
790            scalar_lut_upload_count: 0,
791            scalar_lut_allocation_count: 0,
792            planned: FrameStatistics::default(),
793            next_insertion: 0,
794        })
795    }
796}
797
798impl<'frame> FrameComposer<'frame> {
799    /// Adds a streaming world-space scene through its own camera.
800    pub fn draw_scene(
801        &mut self,
802        scene: &'frame Scene,
803        camera: Camera2d,
804        options: FramePassOptions,
805    ) -> Result<(), FrameComposerError> {
806        let statistics = scene.statistics();
807        let work = FrameStatistics {
808            pass_count: 1,
809            command_count: scene.command_count(),
810            vertex_count: statistics.estimated_tessellated_vertices(),
811            streaming_vertex_count: statistics.estimated_tessellated_vertices(),
812            reused_vertex_count: 0,
813            upload_bytes: statistics
814                .estimated_upload_bytes()
815                .saturating_add(std::mem::size_of::<CameraUniform>()),
816            streaming_upload_bytes: statistics.estimated_upload_bytes(),
817            texture_bytes: 0,
818            retained_cpu_bytes: 0,
819            retained_buffer_bytes: 0,
820            draw_calls: statistics.estimated_draw_batches(),
821            source_counts: FrameSourceStatistics::single(FrameSourceKind::StreamingScene),
822        };
823        self.push_accounted_item(
824            &[RetainedResourceAccounting::new(
825                retained_key(scene, 1),
826                scene.allocation_bytes(),
827                0,
828                0,
829            )],
830            work,
831            FrameItem::Scene {
832                scene,
833                camera,
834                options,
835                insertion: self.next_insertion,
836            },
837        )
838    }
839
840    /// Adds a streaming logical-screen scene unaffected by world cameras.
841    pub fn draw_screen_scene(
842        &mut self,
843        scene: &'frame ScreenScene,
844        options: FramePassOptions,
845    ) -> Result<(), FrameComposerError> {
846        let statistics = scene.statistics();
847        let work = FrameStatistics {
848            pass_count: 1,
849            command_count: scene.command_count(),
850            vertex_count: statistics.estimated_tessellated_vertices(),
851            streaming_vertex_count: statistics.estimated_tessellated_vertices(),
852            reused_vertex_count: 0,
853            upload_bytes: statistics
854                .estimated_upload_bytes()
855                .saturating_add(std::mem::size_of::<CameraUniform>()),
856            streaming_upload_bytes: statistics.estimated_upload_bytes(),
857            texture_bytes: 0,
858            retained_cpu_bytes: 0,
859            retained_buffer_bytes: 0,
860            draw_calls: statistics.estimated_draw_batches(),
861            source_counts: FrameSourceStatistics::single(FrameSourceKind::StreamingScene),
862        };
863        self.push_accounted_item(
864            &[RetainedResourceAccounting::new(
865                retained_key(scene, 2),
866                scene.allocation_bytes(),
867                0,
868                0,
869            )],
870            work,
871            FrameItem::ScreenScene {
872                scene,
873                options,
874                insertion: self.next_insertion,
875            },
876        )
877    }
878
879    /// Adds immutable prepared world-space geometry through its own camera.
880    pub fn draw_prepared_scene(
881        &mut self,
882        scene: &'frame PreparedScene,
883        camera: Camera2d,
884        options: FramePassOptions,
885    ) -> Result<(), FrameComposerError> {
886        if !prepared_scene_belongs_to(&self.renderer.renderer_identity, &scene.renderer_identity) {
887            return Err(FrameComposerError::RendererMismatch {
888                source: FrameSourceKind::PreparedScene,
889            });
890        }
891        let work = FrameStatistics {
892            pass_count: 1,
893            command_count: scene.command_count,
894            vertex_count: scene.vertex_count,
895            streaming_vertex_count: 0,
896            reused_vertex_count: scene.vertex_count,
897            upload_bytes: std::mem::size_of::<CameraUniform>(),
898            streaming_upload_bytes: 0,
899            texture_bytes: 0,
900            retained_cpu_bytes: 0,
901            retained_buffer_bytes: 0,
902            draw_calls: scene.draw_batches.len(),
903            source_counts: FrameSourceStatistics::single(FrameSourceKind::PreparedScene),
904        };
905        self.push_accounted_item(
906            &[
907                RetainedResourceAccounting::new(
908                    retained_arc_key(&scene.vertices, 13),
909                    scene
910                        .vertices
911                        .capacity()
912                        .saturating_mul(std::mem::size_of::<Vertex>()),
913                    0,
914                    0,
915                ),
916                RetainedResourceAccounting::new(
917                    retained_arc_key(&scene.vertex_buffer, 3),
918                    0,
919                    scene
920                        .vertex_count
921                        .max(1)
922                        .saturating_mul(std::mem::size_of::<Vertex>()),
923                    0,
924                ),
925                RetainedResourceAccounting::new(
926                    retained_key(&scene.draw_batches, 14),
927                    scene
928                        .draw_batches
929                        .capacity()
930                        .saturating_mul(std::mem::size_of::<PreparedDrawBatch>()),
931                    0,
932                    0,
933                ),
934            ],
935            work,
936            FrameItem::Prepared {
937                scene,
938                camera,
939                options,
940                insertion: self.next_insertion,
941            },
942        )
943    }
944
945    /// Adds immutable prepared logical-screen geometry.
946    pub fn draw_prepared_screen_scene(
947        &mut self,
948        scene: &'frame PreparedScreenScene,
949        options: FramePassOptions,
950    ) -> Result<(), FrameComposerError> {
951        if !prepared_scene_belongs_to(
952            &self.renderer.renderer_identity,
953            &scene.scene.renderer_identity,
954        ) {
955            return Err(FrameComposerError::RendererMismatch {
956                source: FrameSourceKind::PreparedScene,
957            });
958        }
959        let work = FrameStatistics {
960            pass_count: 1,
961            command_count: scene.scene.command_count,
962            vertex_count: scene.scene.vertex_count,
963            streaming_vertex_count: 0,
964            reused_vertex_count: scene.scene.vertex_count,
965            upload_bytes: std::mem::size_of::<CameraUniform>(),
966            streaming_upload_bytes: 0,
967            texture_bytes: 0,
968            retained_cpu_bytes: 0,
969            retained_buffer_bytes: 0,
970            draw_calls: scene.scene.draw_batches.len(),
971            source_counts: FrameSourceStatistics::single(FrameSourceKind::PreparedScene),
972        };
973        self.push_accounted_item(
974            &[
975                RetainedResourceAccounting::new(
976                    retained_arc_key(&scene.scene.vertices, 13),
977                    scene
978                        .scene
979                        .vertices
980                        .capacity()
981                        .saturating_mul(std::mem::size_of::<Vertex>()),
982                    0,
983                    0,
984                ),
985                RetainedResourceAccounting::new(
986                    retained_arc_key(&scene.scene.vertex_buffer, 3),
987                    0,
988                    scene
989                        .scene
990                        .vertex_count
991                        .max(1)
992                        .saturating_mul(std::mem::size_of::<Vertex>()),
993                    0,
994                ),
995                RetainedResourceAccounting::new(
996                    retained_key(&scene.scene.draw_batches, 14),
997                    scene
998                        .scene
999                        .draw_batches
1000                        .capacity()
1001                        .saturating_mul(std::mem::size_of::<PreparedDrawBatch>()),
1002                    0,
1003                    0,
1004                ),
1005            ],
1006            work,
1007            FrameItem::PreparedScreen {
1008                scene,
1009                options,
1010                insertion: self.next_insertion,
1011            },
1012        )
1013    }
1014
1015    /// Adds retained dynamic triangles through their own world camera.
1016    ///
1017    /// Camera-dependent topology is validated by [`FrameComposer::present`],
1018    /// which rejects triangles crossing the full target clip volume or having
1019    /// an ambiguous projected orientation. Item viewport/scissor clipping is
1020    /// axis-aligned fragment clipping and remains supported.
1021    pub fn draw_dynamic_mesh(
1022        &mut self,
1023        mesh: &'frame DynamicMesh2d,
1024        camera: Camera2d,
1025        options: FramePassOptions,
1026    ) -> Result<(), FrameComposerError> {
1027        if self.renderer.validate_dynamic_mesh(mesh).is_err() {
1028            return Err(FrameComposerError::RendererMismatch {
1029                source: FrameSourceKind::DynamicMesh,
1030            });
1031        }
1032        let work = FrameStatistics {
1033            pass_count: 1,
1034            command_count: usize::from(!mesh.vertices.is_empty()),
1035            vertex_count: mesh.vertices.len(),
1036            streaming_vertex_count: 0,
1037            reused_vertex_count: mesh.vertices.len(),
1038            upload_bytes: std::mem::size_of::<CameraUniform>(),
1039            streaming_upload_bytes: 0,
1040            texture_bytes: 0,
1041            retained_cpu_bytes: 0,
1042            retained_buffer_bytes: 0,
1043            draw_calls: usize::from(!mesh.vertices.is_empty()),
1044            source_counts: FrameSourceStatistics::single(FrameSourceKind::DynamicMesh),
1045        };
1046        self.push_accounted_item(
1047            &[RetainedResourceAccounting::new(
1048                retained_arc_key(&mesh.vertex_buffer, 4),
1049                mesh.recovery_memory_bytes(),
1050                mesh.vertex_capacity
1051                    .saturating_mul(std::mem::size_of::<DynamicGpu>()),
1052                0,
1053            )],
1054            work,
1055            FrameItem::Dynamic {
1056                mesh,
1057                camera,
1058                options,
1059                insertion: self.next_insertion,
1060            },
1061        )
1062    }
1063
1064    /// Adds a budgeted instanced particle field through its own world camera.
1065    pub fn draw_particle_field(
1066        &mut self,
1067        field: &'frame mut ParticleField2d,
1068        camera: Camera2d,
1069        options: FramePassOptions,
1070    ) -> Result<(), FrameComposerError> {
1071        if self.renderer.validate_particle_field(field).is_err() {
1072            return Err(FrameComposerError::RendererMismatch {
1073                source: FrameSourceKind::ParticleField,
1074            });
1075        }
1076        let candidate_count = field
1077            .instances
1078            .len()
1079            .min(field.budget.max_visibility_checks_per_frame)
1080            .min(field.budget.instance_limit());
1081        self.push_accounted_item(
1082            &[RetainedResourceAccounting::new(
1083                retained_arc_key(&field.instance_buffer, 5),
1084                field.cpu_allocation_bytes(),
1085                field.gpu_allocation_bytes(),
1086                0,
1087            )],
1088            FrameStatistics {
1089                pass_count: 1,
1090                command_count: usize::from(!field.instances.is_empty()),
1091                vertex_count: candidate_count.saturating_mul(6),
1092                streaming_vertex_count: candidate_count.saturating_mul(6),
1093                reused_vertex_count: 0,
1094                upload_bytes: candidate_count
1095                    .saturating_mul(std::mem::size_of::<ParticleGpu>())
1096                    .saturating_add(std::mem::size_of::<CameraUniform>()),
1097                streaming_upload_bytes: candidate_count
1098                    .saturating_mul(std::mem::size_of::<ParticleGpu>()),
1099                texture_bytes: 0,
1100                retained_cpu_bytes: 0,
1101                retained_buffer_bytes: 0,
1102                draw_calls: usize::from(candidate_count > 0),
1103                source_counts: FrameSourceStatistics::single(FrameSourceKind::ParticleField),
1104            },
1105            FrameItem::Particle {
1106                field,
1107                camera,
1108                options,
1109                insertion: self.next_insertion,
1110            },
1111        )
1112    }
1113
1114    /// Adds a retained scalar heatmap scaled into the optional viewport.
1115    pub fn draw_scalar_field(
1116        &mut self,
1117        texture: &'frame ScalarFieldTexture,
1118        color_map: &'frame ColorMap,
1119        (minimum, maximum): (f32, f32),
1120        sampling: ScalarFieldSampling,
1121        options: FramePassOptions,
1122    ) -> Result<(), FrameComposerError> {
1123        if self
1124            .renderer
1125            .validate_scalar_field_texture(texture)
1126            .is_err()
1127        {
1128            return Err(FrameComposerError::RendererMismatch {
1129                source: FrameSourceKind::ScalarField,
1130            });
1131        }
1132        let value_extent = scalar_value_range_extent(minimum, maximum)
1133            .ok_or(FrameComposerError::InvalidValueRange { minimum, maximum })?;
1134        if !scalar_normalization_is_portable(texture, minimum, value_extent) {
1135            return Err(FrameComposerError::InvalidValueRange { minimum, maximum });
1136        }
1137        let color_map_bytes = COLOR_MAP_LUT_SIZE as usize * 4;
1138        let scalar_lut = ScalarLutPlan {
1139            sort_key: (options.order(), self.next_insertion),
1140            lut: color_map_lut(color_map),
1141        };
1142        self.scalar_luts
1143            .try_reserve(1)
1144            .map_err(|_| FrameComposerError::AllocationFailed {
1145                requested_bytes: std::mem::size_of::<ScalarLutPlan>(),
1146            })?;
1147        let insertion = self
1148            .scalar_luts
1149            .partition_point(|planned| planned.sort_key < scalar_lut.sort_key);
1150        let (lut_upload_count, lut_allocation_count) = scalar_lut_counts_with_inserted(
1151            &self.scalar_luts,
1152            insertion,
1153            &scalar_lut.lut,
1154            self.renderer
1155                .color_map_cache
1156                .as_ref()
1157                .map(|cached| &cached.lut),
1158        );
1159        let additional_lut_uploads = lut_upload_count.saturating_sub(self.scalar_lut_upload_count);
1160        let additional_lut_allocations =
1161            lut_allocation_count.saturating_sub(self.scalar_lut_allocation_count);
1162        self.push_accounted_item(
1163            &[
1164                RetainedResourceAccounting::new(
1165                    retained_key(&texture.texture, 6),
1166                    texture.recovery_memory_bytes(),
1167                    0,
1168                    texture.gpu_allocation_bytes(),
1169                ),
1170                RetainedResourceAccounting::new(
1171                    retained_key(color_map, 15),
1172                    color_map.allocation_bytes(),
1173                    0,
1174                    0,
1175                ),
1176            ],
1177            FrameStatistics {
1178                pass_count: 1,
1179                command_count: 1,
1180                vertex_count: 6,
1181                streaming_vertex_count: 0,
1182                reused_vertex_count: 0,
1183                upload_bytes: std::mem::size_of::<HeatmapUniform>()
1184                    .saturating_add(additional_lut_uploads.saturating_mul(color_map_bytes)),
1185                streaming_upload_bytes: 0,
1186                texture_bytes: additional_lut_allocations.saturating_mul(color_map_bytes),
1187                retained_cpu_bytes: 0,
1188                retained_buffer_bytes: 0,
1189                draw_calls: 1,
1190                source_counts: FrameSourceStatistics::single(FrameSourceKind::ScalarField),
1191            },
1192            FrameItem::Scalar {
1193                texture,
1194                color_map,
1195                minimum,
1196                maximum,
1197                value_extent,
1198                sampling,
1199                options,
1200                insertion: self.next_insertion,
1201            },
1202        )?;
1203        self.scalar_luts.insert(insertion, scalar_lut);
1204        self.scalar_lut_upload_count = lut_upload_count;
1205        self.scalar_lut_allocation_count = lut_allocation_count;
1206        Ok(())
1207    }
1208
1209    /// Adds one image or atlas region scaled into the optional viewport.
1210    ///
1211    /// With no viewport the image covers the complete logical surface. `tint`
1212    /// is normalized straight linear RGBA and multiplies decoded image color.
1213    pub fn draw_image(
1214        &mut self,
1215        image: &'frame Image2d,
1216        source: Option<ImageTexelRect>,
1217        tint: Color,
1218        sampling: ImageSampling,
1219        options: FramePassOptions,
1220    ) -> Result<(), FrameComposerError> {
1221        if self.renderer.validate_image(image).is_err() {
1222            return Err(FrameComposerError::RendererMismatch {
1223                source: FrameSourceKind::Image,
1224            });
1225        }
1226        if !tint.is_normalized() {
1227            return Err(FrameComposerError::InvalidTint);
1228        }
1229        let source = source.unwrap_or_else(|| image.full_rect());
1230        if !source.fits(image.width(), image.height()) {
1231            return Err(FrameComposerError::InvalidImageRegion);
1232        }
1233        self.push_accounted_item(
1234            &[RetainedResourceAccounting::new(
1235                retained_arc_key(&image.resource_identity, 7),
1236                image.recovery_memory_bytes(),
1237                0,
1238                image.gpu_allocation_bytes(),
1239            )],
1240            FrameStatistics {
1241                pass_count: 1,
1242                command_count: 1,
1243                vertex_count: 6,
1244                streaming_vertex_count: 0,
1245                reused_vertex_count: 0,
1246                upload_bytes: std::mem::size_of::<ImageUniform>(),
1247                streaming_upload_bytes: 0,
1248                texture_bytes: 0,
1249                retained_cpu_bytes: 0,
1250                retained_buffer_bytes: 0,
1251                draw_calls: 1,
1252                source_counts: FrameSourceStatistics::single(FrameSourceKind::Image),
1253            },
1254            FrameItem::Image {
1255                image,
1256                source,
1257                tint,
1258                sampling,
1259                options,
1260                insertion: self.next_insertion,
1261            },
1262        )
1263    }
1264
1265    /// Adds one image or atlas region on an axis-aligned world-space rectangle.
1266    ///
1267    /// The rectangle follows the supplied camera's zoom, rotation, and
1268    /// pseudo-depth projection. Its UV top edge maps to the rectangle's maximum
1269    /// world Y edge. The optional frame viewport selects the camera viewport and
1270    /// the item remains constrained by that viewport and clip.
1271    #[allow(clippy::too_many_arguments)]
1272    pub fn draw_world_image(
1273        &mut self,
1274        image: &'frame Image2d,
1275        source: Option<ImageTexelRect>,
1276        rectangle: Rect,
1277        depth: f32,
1278        camera: Camera2d,
1279        tint: Color,
1280        sampling: ImageSampling,
1281        options: FramePassOptions,
1282    ) -> Result<(), FrameComposerError> {
1283        if self.renderer.validate_image(image).is_err() {
1284            return Err(FrameComposerError::RendererMismatch {
1285                source: FrameSourceKind::Image,
1286            });
1287        }
1288        if !tint.is_normalized() {
1289            return Err(FrameComposerError::InvalidTint);
1290        }
1291        let source = source.unwrap_or_else(|| image.full_rect());
1292        if !source.fits(image.width(), image.height()) {
1293            return Err(FrameComposerError::InvalidImageRegion);
1294        }
1295        let rectangle = rectangle.normalized();
1296        if !rectangle.min().is_finite()
1297            || !rectangle.max().is_finite()
1298            || !rectangle.width().is_finite()
1299            || !rectangle.height().is_finite()
1300            || rectangle.width() <= 0.0
1301            || rectangle.height() <= 0.0
1302            || !depth.is_finite()
1303        {
1304            return Err(FrameComposerError::InvalidWorldImage);
1305        }
1306        self.push_accounted_item(
1307            &[RetainedResourceAccounting::new(
1308                retained_arc_key(&image.resource_identity, 7),
1309                image.recovery_memory_bytes(),
1310                0,
1311                image.gpu_allocation_bytes(),
1312            )],
1313            FrameStatistics {
1314                pass_count: 1,
1315                command_count: 1,
1316                vertex_count: 6,
1317                streaming_vertex_count: 0,
1318                reused_vertex_count: 0,
1319                upload_bytes: std::mem::size_of::<ImageUniform>(),
1320                streaming_upload_bytes: 0,
1321                texture_bytes: 0,
1322                retained_cpu_bytes: 0,
1323                retained_buffer_bytes: 0,
1324                draw_calls: 1,
1325                source_counts: FrameSourceStatistics::single(FrameSourceKind::Image),
1326            },
1327            FrameItem::WorldImage {
1328                image,
1329                source,
1330                rectangle,
1331                depth,
1332                camera,
1333                tint,
1334                sampling,
1335                options,
1336                insertion: self.next_insertion,
1337            },
1338        )
1339    }
1340
1341    /// Adds a retained atlas batch as one instanced draw when non-empty.
1342    /// Empty batches are valid frame items and emit no draw call.
1343    pub fn draw_image_batch(
1344        &mut self,
1345        image: &'frame Image2d,
1346        batch: &'frame ImageBatch2d,
1347        sampling: ImageSampling,
1348        options: FramePassOptions,
1349    ) -> Result<(), FrameComposerError> {
1350        if self.renderer.validate_image_batch(image, batch).is_err() {
1351            return Err(FrameComposerError::RendererMismatch {
1352                source: FrameSourceKind::Image,
1353            });
1354        }
1355        self.push_retained_image_batch(image, batch, sampling, options, FrameSourceKind::Image)
1356    }
1357
1358    /// Adds one host-shaped retained glyph run as one instanced draw when non-empty.
1359    ///
1360    /// Positions are local logical pixels. Mixed font fallback is represented
1361    /// by multiple runs submitted at the same order; stable insertion order is
1362    /// preserved between them. An empty run is valid and emits no draw call.
1363    pub fn draw_glyph_run(
1364        &mut self,
1365        atlas: &'frame GlyphAtlas2d,
1366        run: &'frame GlyphRun2d,
1367        sampling: ImageSampling,
1368        options: FramePassOptions,
1369    ) -> Result<(), FrameComposerError> {
1370        if self.renderer.validate_glyph_run(atlas, run).is_err() {
1371            return Err(FrameComposerError::RendererMismatch {
1372                source: FrameSourceKind::Glyph,
1373            });
1374        }
1375        let image = &atlas.image;
1376        let batch = &run.batch;
1377        let vertex_count = batch.sprite_count().saturating_mul(6);
1378        self.push_accounted_item(
1379            &[
1380                RetainedResourceAccounting::new(
1381                    retained_arc_key(&image.resource_identity, 7),
1382                    image.recovery_memory_bytes(),
1383                    0,
1384                    image.gpu_allocation_bytes(),
1385                ),
1386                RetainedResourceAccounting::new(
1387                    retained_key(atlas, 9),
1388                    atlas
1389                        .recovery_memory_bytes()
1390                        .saturating_sub(image.recovery_memory_bytes()),
1391                    0,
1392                    0,
1393                ),
1394                RetainedResourceAccounting::new(
1395                    retained_key(run, 10),
1396                    run.recovery_memory_bytes(),
1397                    run.gpu_allocation_bytes(),
1398                    0,
1399                ),
1400            ],
1401            FrameStatistics {
1402                pass_count: 1,
1403                command_count: usize::from(batch.sprite_count() > 0),
1404                vertex_count,
1405                streaming_vertex_count: 0,
1406                reused_vertex_count: vertex_count,
1407                upload_bytes: std::mem::size_of::<ImageUniform>(),
1408                streaming_upload_bytes: 0,
1409                texture_bytes: 0,
1410                retained_cpu_bytes: 0,
1411                retained_buffer_bytes: 0,
1412                draw_calls: usize::from(batch.sprite_count() > 0),
1413                source_counts: FrameSourceStatistics::single(FrameSourceKind::Glyph),
1414            },
1415            FrameItem::ImageBatch {
1416                image,
1417                batch,
1418                sampling,
1419                options,
1420                insertion: self.next_insertion,
1421            },
1422        )
1423    }
1424
1425    fn push_retained_image_batch(
1426        &mut self,
1427        image: &'frame Image2d,
1428        batch: &'frame ImageBatch2d,
1429        sampling: ImageSampling,
1430        options: FramePassOptions,
1431        source: FrameSourceKind,
1432    ) -> Result<(), FrameComposerError> {
1433        let vertex_count = batch.sprite_count().saturating_mul(6);
1434        self.push_accounted_item(
1435            &[
1436                RetainedResourceAccounting::new(
1437                    retained_arc_key(&image.resource_identity, 7),
1438                    image.recovery_memory_bytes(),
1439                    0,
1440                    image.gpu_allocation_bytes(),
1441                ),
1442                RetainedResourceAccounting::new(
1443                    retained_key(batch, 8),
1444                    batch.recovery_memory_bytes(),
1445                    batch.gpu_allocation_bytes(),
1446                    0,
1447                ),
1448            ],
1449            FrameStatistics {
1450                pass_count: 1,
1451                command_count: usize::from(batch.sprite_count() > 0),
1452                vertex_count,
1453                streaming_vertex_count: 0,
1454                reused_vertex_count: vertex_count,
1455                upload_bytes: std::mem::size_of::<ImageUniform>(),
1456                streaming_upload_bytes: 0,
1457                texture_bytes: 0,
1458                retained_cpu_bytes: 0,
1459                retained_buffer_bytes: 0,
1460                draw_calls: usize::from(batch.sprite_count() > 0),
1461                source_counts: FrameSourceStatistics::single(source),
1462            },
1463            FrameItem::ImageBatch {
1464                image,
1465                batch,
1466                sampling,
1467                options,
1468                insertion: self.next_insertion,
1469            },
1470        )
1471    }
1472
1473    /// Adds an offscreen target, scaled into the optional logical viewport.
1474    pub fn draw_render_target(
1475        &mut self,
1476        target: &'frame RenderTarget2d,
1477        blend_mode: BlendMode,
1478        opacity: f32,
1479        options: FramePassOptions,
1480    ) -> Result<(), FrameComposerError> {
1481        if self.renderer.validate_render_target(target).is_err() {
1482            return Err(FrameComposerError::RendererMismatch {
1483                source: FrameSourceKind::RenderTarget,
1484            });
1485        }
1486        if !opacity.is_finite() || !(0.0..=1.0).contains(&opacity) {
1487            return Err(FrameComposerError::InvalidOpacity);
1488        }
1489        self.push_accounted_item(
1490            &[RetainedResourceAccounting::new(
1491                retained_arc_key(&target.resource_identity, 11),
1492                0,
1493                0,
1494                target.allocation_bytes,
1495            )],
1496            FrameStatistics {
1497                pass_count: 1,
1498                command_count: 1,
1499                vertex_count: 6,
1500                streaming_vertex_count: 0,
1501                reused_vertex_count: 0,
1502                upload_bytes: std::mem::size_of::<CompositeUniform>(),
1503                streaming_upload_bytes: 0,
1504                texture_bytes: 0,
1505                retained_cpu_bytes: 0,
1506                retained_buffer_bytes: 0,
1507                draw_calls: 1,
1508                source_counts: FrameSourceStatistics::single(FrameSourceKind::RenderTarget),
1509            },
1510            FrameItem::Target {
1511                target,
1512                blend_mode,
1513                opacity,
1514                options,
1515                insertion: self.next_insertion,
1516            },
1517        )
1518    }
1519
1520    /// Returns conservative work accepted so far without presenting it.
1521    pub const fn planned_statistics(&self) -> FrameStatistics {
1522        self.planned
1523    }
1524
1525    /// Validates, orders, encodes, submits, and presents the complete frame.
1526    pub fn present(self) -> Result<FrameReport, FrameComposerError> {
1527        present_frame(self)
1528    }
1529
1530    fn push_item(
1531        &mut self,
1532        work: FrameStatistics,
1533        item: FrameItem<'frame>,
1534    ) -> Result<(), FrameComposerError> {
1535        let planned = self.planned.adding(work);
1536        validate_frame_budget(self.budget, planned)?;
1537        self.items
1538            .try_reserve(1)
1539            .map_err(|_| FrameComposerError::AllocationFailed {
1540                requested_bytes: std::mem::size_of::<FrameItem<'frame>>(),
1541            })?;
1542        self.items.push(item);
1543        self.planned = planned;
1544        self.next_insertion = self.next_insertion.saturating_add(1);
1545        Ok(())
1546    }
1547
1548    fn push_accounted_item(
1549        &mut self,
1550        resources: &[RetainedResourceAccounting],
1551        mut work: FrameStatistics,
1552        item: FrameItem<'frame>,
1553    ) -> Result<(), FrameComposerError> {
1554        let (accounted_work, missing) =
1555            account_new_retained_resources(&self.retained_resources, resources, work);
1556        work = accounted_work;
1557        self.retained_resources.try_reserve(missing).map_err(|_| {
1558            FrameComposerError::AllocationFailed {
1559                requested_bytes: missing.saturating_mul(std::mem::size_of::<RetainedResourceKey>()),
1560            }
1561        })?;
1562        self.push_item(work, item)?;
1563        for resource in resources {
1564            if !self.retained_resources.contains(&resource.key) {
1565                self.retained_resources.push(resource.key);
1566            }
1567        }
1568        Ok(())
1569    }
1570}
1571
1572#[derive(Debug, Clone, Copy)]
1573struct ResolvedViewport {
1574    viewport: LogicalViewport,
1575    origin: Vec2,
1576    scissor: ScissorRect,
1577    item_clip: Option<ScissorRect>,
1578    item_clipped_out: bool,
1579}
1580
1581enum ReadySource<'frame> {
1582    Streaming,
1583    Prepared(&'frame wgpu::Buffer),
1584    Dynamic(&'frame wgpu::Buffer),
1585}
1586
1587struct ReadyGeometry<'frame> {
1588    source: ReadySource<'frame>,
1589    vertex_count: usize,
1590    batches: Vec<PreparedDrawBatch>,
1591    camera_uniform: CameraUniform,
1592    viewport: ResolvedViewport,
1593}
1594
1595enum ReadyItem<'frame> {
1596    Geometry(ReadyGeometry<'frame>),
1597    Particle {
1598        field: &'frame mut ParticleField2d,
1599        visible_count: usize,
1600        pending_statistics: ParticleStatistics,
1601        initial_cpu_allocation_bytes: usize,
1602        camera_uniform: CameraUniform,
1603        viewport: ResolvedViewport,
1604    },
1605    Scalar {
1606        texture: &'frame ScalarFieldTexture,
1607        color_map: &'frame ColorMap,
1608        uniform: HeatmapUniform,
1609        viewport: ResolvedViewport,
1610    },
1611    Image {
1612        image: &'frame Image2d,
1613        sampling: ImageSampling,
1614        uniform: ImageUniform,
1615        viewport: ResolvedViewport,
1616    },
1617    ImageBatch {
1618        image: &'frame Image2d,
1619        batch: &'frame ImageBatch2d,
1620        sampling: ImageSampling,
1621        uniform: ImageUniform,
1622        viewport: ResolvedViewport,
1623    },
1624    Target {
1625        target: &'frame RenderTarget2d,
1626        blend_mode: BlendMode,
1627        uniform: CompositeUniform,
1628        viewport: ResolvedViewport,
1629    },
1630}
1631
1632struct FrameBinding {
1633    _buffer: wgpu::Buffer,
1634    bind_group: wgpu::BindGroup,
1635}
1636
1637fn present_frame(composer: FrameComposer<'_>) -> Result<FrameReport, FrameComposerError> {
1638    let FrameComposer {
1639        renderer,
1640        background,
1641        budget,
1642        items,
1643        retained_resources: _,
1644        scalar_luts: _,
1645        scalar_lut_upload_count: _,
1646        scalar_lut_allocation_count: _,
1647        planned,
1648        next_insertion: _,
1649    } = composer;
1650    // Always return the transient allocation, including structured error
1651    // paths before surface acquisition.
1652    let mut streaming_vertices = std::mem::take(&mut renderer.vertices);
1653    streaming_vertices.clear();
1654    let result = present_frame_with_vertices(
1655        renderer,
1656        background,
1657        budget,
1658        items,
1659        planned,
1660        &mut streaming_vertices,
1661    );
1662    renderer.vertices = streaming_vertices;
1663    result
1664}
1665
1666fn present_frame_with_vertices<'frame>(
1667    renderer: &mut WgpuRenderer,
1668    background: Color,
1669    budget: FrameBudget,
1670    mut items: Vec<FrameItem<'frame>>,
1671    planned: FrameStatistics,
1672    streaming_vertices: &mut Vec<Vertex>,
1673) -> Result<FrameReport, FrameComposerError> {
1674    let frame_started_at = Instant::now();
1675    items.sort_unstable_by_key(FrameItem::sort_key);
1676
1677    let target_viewport = renderer
1678        .logical_viewport()
1679        .map_err(|_| RendererFrameError::InvalidViewport)?;
1680    let tessellation_started_at = Instant::now();
1681    preflight_frame_items(renderer, target_viewport, &items)?;
1682    let mut ready = Vec::new();
1683    ready
1684        .try_reserve(items.len())
1685        .map_err(|_| FrameComposerError::AllocationFailed {
1686            requested_bytes: items
1687                .len()
1688                .saturating_mul(std::mem::size_of::<ReadyItem<'_>>()),
1689        })?;
1690    let mut statistics = FrameStatistics::default();
1691    let mut tessellation_stats = TessellationStats::default();
1692    let mut geometry_reused = false;
1693    let mut geometry_streamed = false;
1694    let mut simulated_color_map_lut = renderer.color_map_cache.as_ref().map(|cache| cache.lut);
1695
1696    for item in items {
1697        match item {
1698            FrameItem::Scene {
1699                scene,
1700                camera,
1701                options,
1702                ..
1703            } => {
1704                prepare_streaming_scene(
1705                    scene,
1706                    camera,
1707                    options,
1708                    renderer,
1709                    target_viewport,
1710                    &mut *streaming_vertices,
1711                    &mut ready,
1712                    &mut statistics,
1713                    &mut tessellation_stats,
1714                )?;
1715                geometry_streamed = true;
1716            }
1717            FrameItem::ScreenScene { scene, options, .. } => {
1718                let viewport = resolve_viewport(renderer, target_viewport, options)?;
1719                let camera = screen_camera(viewport.viewport)
1720                    .map_err(|_| RendererFrameError::InvalidGeometryTransform)?;
1721                let camera_uniform = CameraUniform::new_in_region(
1722                    camera,
1723                    viewport.viewport,
1724                    viewport.origin,
1725                    target_viewport,
1726                )
1727                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1728                if !scene_estimate_fits_streaming_device(
1729                    scene.as_scene(),
1730                    &renderer.device,
1731                    streaming_vertices.len(),
1732                    renderer.vertex_capacity,
1733                ) {
1734                    return Err(RendererFrameError::GeometryCapacityTooLarge.into());
1735                }
1736                prepare_streaming_scene_resolved(
1737                    scene.as_scene(),
1738                    camera_uniform,
1739                    viewport,
1740                    &mut *streaming_vertices,
1741                    &mut ready,
1742                    &mut statistics,
1743                    &mut tessellation_stats,
1744                )?;
1745                geometry_streamed = true;
1746            }
1747            FrameItem::Prepared {
1748                scene,
1749                camera,
1750                options,
1751                ..
1752            } => {
1753                let viewport = resolve_viewport(renderer, target_viewport, options)?;
1754                prepare_retained_geometry(
1755                    ReadySource::Prepared(&scene.vertex_buffer),
1756                    scene.vertex_count,
1757                    scene.geometry_extents,
1758                    GeometryValidationSource::Tessellated(&scene.vertices),
1759                    Some(&scene.geometry_validation_cache),
1760                    &scene.draw_batches,
1761                    scene.command_count,
1762                    scene.tessellation,
1763                    camera,
1764                    viewport,
1765                    target_viewport,
1766                    &mut ready,
1767                    &mut statistics,
1768                    &mut tessellation_stats,
1769                )?;
1770                geometry_reused = true;
1771            }
1772            FrameItem::PreparedScreen { scene, options, .. } => {
1773                let viewport = resolve_viewport(renderer, target_viewport, options)?;
1774                let camera = screen_camera(viewport.viewport)
1775                    .map_err(|_| RendererFrameError::InvalidGeometryTransform)?;
1776                prepare_retained_geometry(
1777                    ReadySource::Prepared(&scene.scene.vertex_buffer),
1778                    scene.scene.vertex_count,
1779                    scene.scene.geometry_extents,
1780                    GeometryValidationSource::Tessellated(&scene.scene.vertices),
1781                    Some(&scene.scene.geometry_validation_cache),
1782                    &scene.scene.draw_batches,
1783                    scene.scene.command_count,
1784                    scene.scene.tessellation,
1785                    camera,
1786                    viewport,
1787                    target_viewport,
1788                    &mut ready,
1789                    &mut statistics,
1790                    &mut tessellation_stats,
1791                )?;
1792                geometry_reused = true;
1793            }
1794            FrameItem::Dynamic {
1795                mesh,
1796                camera,
1797                options,
1798                ..
1799            } => {
1800                let viewport = resolve_viewport(renderer, target_viewport, options)?;
1801                let batch = (!mesh.vertices.is_empty()).then_some(PreparedDrawBatch {
1802                    vertex_range: 0..mesh.vertices.len() as u32,
1803                    screen_clip: None,
1804                });
1805                prepare_retained_geometry(
1806                    ReadySource::Dynamic(&mesh.vertex_buffer),
1807                    mesh.vertices.len(),
1808                    mesh.geometry_extents,
1809                    GeometryValidationSource::Dynamic(&mesh.vertices),
1810                    Some(&mesh.geometry_validation_cache),
1811                    batch.as_slice(),
1812                    usize::from(!mesh.vertices.is_empty()),
1813                    TessellationStats::default(),
1814                    camera,
1815                    viewport,
1816                    target_viewport,
1817                    &mut ready,
1818                    &mut statistics,
1819                    &mut tessellation_stats,
1820                )?;
1821                geometry_streamed = true;
1822            }
1823            FrameItem::Particle {
1824                field,
1825                camera,
1826                options,
1827                ..
1828            } => {
1829                let viewport = resolve_viewport(renderer, target_viewport, options)?;
1830                prepare_particle_item(
1831                    field,
1832                    camera,
1833                    viewport,
1834                    target_viewport,
1835                    &mut ready,
1836                    &mut statistics,
1837                )?;
1838                geometry_streamed = true;
1839            }
1840            FrameItem::Scalar {
1841                texture,
1842                color_map,
1843                minimum,
1844                maximum,
1845                value_extent,
1846                sampling,
1847                options,
1848                ..
1849            } => {
1850                if !scalar_normalization_is_portable(texture, minimum, value_extent) {
1851                    return Err(FrameComposerError::InvalidValueRange { minimum, maximum });
1852                }
1853                let viewport = resolve_viewport(renderer, target_viewport, options)?;
1854                let region = LogicalViewportRegion::new(
1855                    LogicalScreenPosition::from_vec2(viewport.origin),
1856                    viewport.viewport,
1857                )
1858                .map_err(|_| RendererFrameError::InvalidViewport)?;
1859                let uniform = HeatmapUniform::new(
1860                    minimum,
1861                    value_extent,
1862                    texture.width(),
1863                    texture.height(),
1864                    sampling,
1865                )
1866                .in_region(region, target_viewport)
1867                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1868                let color_map_bytes = COLOR_MAP_LUT_SIZE as usize * 4;
1869                let lut = color_map_lut(color_map);
1870                let color_map_upload_bytes = if simulated_color_map_lut == Some(lut) {
1871                    0
1872                } else {
1873                    simulated_color_map_lut = Some(lut);
1874                    color_map_bytes
1875                };
1876                statistics = statistics.adding(FrameStatistics {
1877                    pass_count: 1,
1878                    command_count: 1,
1879                    vertex_count: 6,
1880                    streaming_vertex_count: 0,
1881                    reused_vertex_count: 0,
1882                    upload_bytes: std::mem::size_of::<HeatmapUniform>()
1883                        .saturating_add(color_map_upload_bytes),
1884                    streaming_upload_bytes: 0,
1885                    texture_bytes: 0,
1886                    retained_cpu_bytes: 0,
1887                    retained_buffer_bytes: 0,
1888                    draw_calls: 1,
1889                    source_counts: FrameSourceStatistics::default(),
1890                });
1891                ready.push(ReadyItem::Scalar {
1892                    texture,
1893                    color_map,
1894                    uniform,
1895                    viewport,
1896                });
1897                geometry_streamed = true;
1898            }
1899            FrameItem::Image {
1900                image,
1901                source,
1902                tint,
1903                sampling,
1904                options,
1905                ..
1906            } => {
1907                let viewport = resolve_viewport(renderer, target_viewport, options)?;
1908                let region = LogicalViewportRegion::new(
1909                    LogicalScreenPosition::from_vec2(viewport.origin),
1910                    viewport.viewport,
1911                )
1912                .map_err(|_| RendererFrameError::InvalidViewport)?;
1913                let destination = CompositeUniform::in_region(1.0, region, target_viewport)
1914                    .ok_or(RendererFrameError::InvalidGeometryTransform)?
1915                    .destination;
1916                let image_width = image.width() as f32;
1917                let image_height = image.height() as f32;
1918                let uv_min_x = (source.x() as f32 + 0.5) / image_width;
1919                let uv_min_y = (source.y() as f32 + 0.5) / image_height;
1920                let uv_max_x = (source.x() as f32 + source.width() as f32 - 0.5) / image_width;
1921                let uv_max_y = (source.y() as f32 + source.height() as f32 - 0.5) / image_height;
1922                let uniform = ImageUniform {
1923                    destination,
1924                    uv_rect: [uv_min_x, uv_min_y, uv_max_x, uv_max_y],
1925                    tint: tint.to_array(),
1926                    world_clip_x: [0.0; 4],
1927                    world_clip_y: [0.0; 4],
1928                    world_mode: [0.0; 4],
1929                };
1930                statistics = statistics.adding(FrameStatistics {
1931                    pass_count: 1,
1932                    command_count: 1,
1933                    vertex_count: 6,
1934                    streaming_vertex_count: 0,
1935                    reused_vertex_count: 0,
1936                    upload_bytes: std::mem::size_of::<ImageUniform>(),
1937                    streaming_upload_bytes: 0,
1938                    texture_bytes: image.gpu_allocation_bytes(),
1939                    retained_cpu_bytes: 0,
1940                    retained_buffer_bytes: 0,
1941                    draw_calls: 1,
1942                    source_counts: FrameSourceStatistics::default(),
1943                });
1944                ready.push(ReadyItem::Image {
1945                    image,
1946                    sampling,
1947                    uniform,
1948                    viewport,
1949                });
1950            }
1951            FrameItem::WorldImage {
1952                image,
1953                source,
1954                rectangle,
1955                depth,
1956                camera,
1957                tint,
1958                sampling,
1959                options,
1960                ..
1961            } => {
1962                let viewport = resolve_viewport(renderer, target_viewport, options)?;
1963                let camera_uniform = CameraUniform::new_in_region(
1964                    camera,
1965                    viewport.viewport,
1966                    viewport.origin,
1967                    target_viewport,
1968                )
1969                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1970                let minimum = rectangle.min();
1971                let maximum = rectangle.max();
1972                let world_corners = [
1973                    Vec2::new(minimum.x, maximum.y),
1974                    maximum,
1975                    minimum,
1976                    Vec2::new(maximum.x, minimum.y),
1977                ];
1978                let mut clip_corners = [Vec2::ZERO; 4];
1979                for (clip, world) in clip_corners.iter_mut().zip(world_corners) {
1980                    let screen = camera_uniform.world_to_screen(world, depth);
1981                    *clip = Vec2::new(
1982                        screen.x.mul_add(
1983                            camera_uniform.screen_to_clip[0],
1984                            camera_uniform.screen_to_clip[2],
1985                        ),
1986                        screen.y.mul_add(
1987                            camera_uniform.screen_to_clip[1],
1988                            camera_uniform.screen_to_clip[3],
1989                        ),
1990                    );
1991                    if ![clip.x, clip.y].into_iter().all(is_portable_shader_source) {
1992                        return Err(RendererFrameError::InvalidGeometryTransform.into());
1993                    }
1994                }
1995                let image_width = image.width() as f32;
1996                let image_height = image.height() as f32;
1997                let uniform = ImageUniform {
1998                    destination: [0.0; 4],
1999                    uv_rect: [
2000                        (source.x() as f32 + 0.5) / image_width,
2001                        (source.y() as f32 + 0.5) / image_height,
2002                        (source.x() as f32 + source.width() as f32 - 0.5) / image_width,
2003                        (source.y() as f32 + source.height() as f32 - 0.5) / image_height,
2004                    ],
2005                    tint: tint.to_array(),
2006                    world_clip_x: [
2007                        clip_corners[0].x,
2008                        clip_corners[1].x,
2009                        clip_corners[2].x,
2010                        clip_corners[3].x,
2011                    ],
2012                    world_clip_y: [
2013                        clip_corners[0].y,
2014                        clip_corners[1].y,
2015                        clip_corners[2].y,
2016                        clip_corners[3].y,
2017                    ],
2018                    world_mode: [1.0, 0.0, 0.0, 0.0],
2019                };
2020                statistics = statistics.adding(FrameStatistics {
2021                    pass_count: 1,
2022                    command_count: 1,
2023                    vertex_count: 6,
2024                    streaming_vertex_count: 0,
2025                    reused_vertex_count: 0,
2026                    upload_bytes: std::mem::size_of::<ImageUniform>(),
2027                    streaming_upload_bytes: 0,
2028                    texture_bytes: image.gpu_allocation_bytes(),
2029                    retained_cpu_bytes: 0,
2030                    retained_buffer_bytes: 0,
2031                    draw_calls: 1,
2032                    source_counts: FrameSourceStatistics::default(),
2033                });
2034                ready.push(ReadyItem::Image {
2035                    image,
2036                    sampling,
2037                    uniform,
2038                    viewport,
2039                });
2040            }
2041            FrameItem::ImageBatch {
2042                image,
2043                batch,
2044                sampling,
2045                options,
2046                ..
2047            } => {
2048                let viewport = resolve_viewport(renderer, target_viewport, options)?;
2049                let uniform = ImageUniform {
2050                    destination: [
2051                        2.0 / target_viewport.width(),
2052                        -2.0 / target_viewport.height(),
2053                        -1.0,
2054                        1.0,
2055                    ],
2056                    uv_rect: [viewport.origin.x, viewport.origin.y, 0.0, 0.0],
2057                    tint: Color::WHITE.to_array(),
2058                    world_clip_x: [0.0; 4],
2059                    world_clip_y: [0.0; 4],
2060                    world_mode: [0.0; 4],
2061                };
2062                if !image_sprites_are_safe_for_target(
2063                    batch.sprites(),
2064                    viewport.origin,
2065                    uniform.destination,
2066                ) {
2067                    return Err(RendererFrameError::InvalidGeometryTransform.into());
2068                }
2069                let vertex_count = batch.sprite_count().saturating_mul(6);
2070                statistics = statistics.adding(FrameStatistics {
2071                    pass_count: 1,
2072                    command_count: usize::from(batch.sprite_count() > 0),
2073                    vertex_count,
2074                    streaming_vertex_count: 0,
2075                    reused_vertex_count: vertex_count,
2076                    upload_bytes: std::mem::size_of::<ImageUniform>(),
2077                    streaming_upload_bytes: 0,
2078                    texture_bytes: image.gpu_allocation_bytes(),
2079                    retained_cpu_bytes: 0,
2080                    retained_buffer_bytes: 0,
2081                    draw_calls: usize::from(batch.sprite_count() > 0),
2082                    source_counts: FrameSourceStatistics::default(),
2083                });
2084                ready.push(ReadyItem::ImageBatch {
2085                    image,
2086                    batch,
2087                    sampling,
2088                    uniform,
2089                    viewport,
2090                });
2091                geometry_reused = true;
2092            }
2093            FrameItem::Target {
2094                target,
2095                blend_mode,
2096                opacity,
2097                options,
2098                ..
2099            } => {
2100                let viewport = resolve_viewport(renderer, target_viewport, options)?;
2101                let region = LogicalViewportRegion::new(
2102                    LogicalScreenPosition::from_vec2(viewport.origin),
2103                    viewport.viewport,
2104                )
2105                .map_err(|_| RendererFrameError::InvalidViewport)?;
2106                let uniform = CompositeUniform::in_region(opacity, region, target_viewport)
2107                    .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2108                statistics = statistics.adding(FrameStatistics {
2109                    pass_count: 1,
2110                    command_count: 1,
2111                    vertex_count: 6,
2112                    streaming_vertex_count: 0,
2113                    reused_vertex_count: 0,
2114                    upload_bytes: std::mem::size_of::<CompositeUniform>(),
2115                    streaming_upload_bytes: 0,
2116                    texture_bytes: target.allocation_bytes,
2117                    retained_cpu_bytes: 0,
2118                    retained_buffer_bytes: 0,
2119                    draw_calls: 1,
2120                    source_counts: FrameSourceStatistics::default(),
2121                });
2122                ready.push(ReadyItem::Target {
2123                    target,
2124                    blend_mode,
2125                    uniform,
2126                    viewport,
2127                });
2128            }
2129        }
2130    }
2131    statistics.texture_bytes = planned.texture_bytes;
2132    let (particle_cpu_before, particle_cpu_after) =
2133        ready
2134            .iter()
2135            .fold((0usize, 0usize), |(before, after), item| match item {
2136                ReadyItem::Particle {
2137                    field,
2138                    initial_cpu_allocation_bytes,
2139                    ..
2140                } => (
2141                    before.saturating_add(*initial_cpu_allocation_bytes),
2142                    after.saturating_add(field.cpu_allocation_bytes()),
2143                ),
2144                _ => (before, after),
2145            });
2146    statistics.retained_cpu_bytes = planned
2147        .retained_cpu_bytes
2148        .saturating_sub(particle_cpu_before)
2149        .saturating_add(particle_cpu_after);
2150    statistics.retained_buffer_bytes = planned.retained_buffer_bytes;
2151    statistics.source_counts = planned.source_counts;
2152    validate_frame_budget(budget, statistics)?;
2153    renderer.ensure_vertex_capacity(streaming_vertices.len())?;
2154
2155    let mut bindings = Vec::new();
2156    bindings
2157        .try_reserve(ready.len())
2158        .map_err(|_| FrameComposerError::AllocationFailed {
2159            requested_bytes: ready
2160                .len()
2161                .saturating_mul(std::mem::size_of::<FrameBinding>()),
2162        })?;
2163    let tessellation = tessellation_started_at.elapsed();
2164
2165    // Surface availability is resolved after all fallible CPU preparation but
2166    // before bind-group creation or queue writes. Repeated skipped frames must
2167    // not accumulate wgpu's deferred upload staging allocations.
2168    let acquire_started_at = Instant::now();
2169    let surface_texture = match renderer.surface.get_current_texture() {
2170        wgpu::CurrentSurfaceTexture::Success(texture)
2171        | wgpu::CurrentSurfaceTexture::Suboptimal(texture) => texture,
2172        wgpu::CurrentSurfaceTexture::Timeout => {
2173            set_particle_rendered(&mut ready, false);
2174            return Ok(frame_report(
2175                RenderStatus::Skipped(RendererSurfaceStatus::Timeout),
2176                statistics.without_uploads(),
2177                tessellation,
2178                Duration::ZERO,
2179                Duration::ZERO,
2180                acquire_started_at.elapsed(),
2181                Duration::ZERO,
2182                frame_started_at.elapsed(),
2183                geometry_reused,
2184                geometry_streamed,
2185                tessellation_stats,
2186            ));
2187        }
2188        wgpu::CurrentSurfaceTexture::Occluded => {
2189            set_particle_rendered(&mut ready, false);
2190            return Ok(frame_report(
2191                RenderStatus::Skipped(RendererSurfaceStatus::Occluded),
2192                statistics.without_uploads(),
2193                tessellation,
2194                Duration::ZERO,
2195                Duration::ZERO,
2196                acquire_started_at.elapsed(),
2197                Duration::ZERO,
2198                frame_started_at.elapsed(),
2199                geometry_reused,
2200                geometry_streamed,
2201                tessellation_stats,
2202            ));
2203        }
2204        wgpu::CurrentSurfaceTexture::Outdated => {
2205            let _ = renderer.resize(renderer.config.width, renderer.config.height);
2206            set_particle_rendered(&mut ready, false);
2207            return Ok(frame_report(
2208                RenderStatus::Skipped(RendererSurfaceStatus::Outdated),
2209                statistics.without_uploads(),
2210                tessellation,
2211                Duration::ZERO,
2212                Duration::ZERO,
2213                acquire_started_at.elapsed(),
2214                Duration::ZERO,
2215                frame_started_at.elapsed(),
2216                geometry_reused,
2217                geometry_streamed,
2218                tessellation_stats,
2219            ));
2220        }
2221        wgpu::CurrentSurfaceTexture::Lost => {
2222            return Err(RendererFrameError::Surface(RendererSurfaceStatus::Lost).into());
2223        }
2224        wgpu::CurrentSurfaceTexture::Validation => {
2225            return Err(RendererFrameError::Surface(RendererSurfaceStatus::Validation).into());
2226        }
2227    };
2228    let surface_acquire = acquire_started_at.elapsed();
2229
2230    let mut binding_upload = Duration::ZERO;
2231    let mut camera_uniform_upload = Duration::ZERO;
2232    for item in &ready {
2233        let binding_started_at = Instant::now();
2234        bindings.push(create_frame_binding(renderer, item));
2235        let elapsed = binding_started_at.elapsed();
2236        match item {
2237            ReadyItem::Geometry(_) | ReadyItem::Particle { .. } => {
2238                camera_uniform_upload += elapsed;
2239            }
2240            ReadyItem::Scalar { .. }
2241            | ReadyItem::Image { .. }
2242            | ReadyItem::ImageBatch { .. }
2243            | ReadyItem::Target { .. } => {
2244                binding_upload += elapsed;
2245            }
2246        }
2247    }
2248
2249    let upload_started_at = Instant::now();
2250    if !streaming_vertices.is_empty() {
2251        renderer.queue.write_buffer(
2252            &renderer.vertex_buffer,
2253            0,
2254            bytemuck::cast_slice(streaming_vertices),
2255        );
2256    }
2257    for item in &ready {
2258        if let ReadyItem::Particle {
2259            field,
2260            visible_count,
2261            ..
2262        } = item
2263        {
2264            let visible_instances =
2265                if field.visible_instances.is_empty() && *visible_count == field.instances.len() {
2266                    field.instances.as_slice()
2267                } else {
2268                    field.visible_instances.as_slice()
2269                };
2270            if !visible_instances.is_empty() {
2271                renderer.queue.write_buffer(
2272                    &field.instance_buffer,
2273                    0,
2274                    bytemuck::cast_slice(visible_instances),
2275                );
2276            }
2277        }
2278    }
2279    let upload = upload_started_at.elapsed() + binding_upload;
2280    let encode_started_at = Instant::now();
2281    let surface_view = surface_texture
2282        .texture
2283        .create_view(&wgpu::TextureViewDescriptor::default());
2284    let (view, resolve_target) = match &renderer.multisample_target {
2285        Some(target) => (&target.view, Some(&surface_view)),
2286        None => (&surface_view, None),
2287    };
2288    let mut encoder = renderer
2289        .device
2290        .create_command_encoder(&wgpu::CommandEncoderDescriptor {
2291            label: Some("sim-engine composed frame encoder"),
2292        });
2293    {
2294        let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
2295            label: Some("sim-engine composed frame pass"),
2296            color_attachments: &[Some(wgpu::RenderPassColorAttachment {
2297                view,
2298                depth_slice: None,
2299                resolve_target,
2300                ops: wgpu::Operations {
2301                    load: wgpu::LoadOp::Clear(background.to_wgpu()),
2302                    store: wgpu::StoreOp::Store,
2303                },
2304            })],
2305            depth_stencil_attachment: None,
2306            timestamp_writes: None,
2307            occlusion_query_set: None,
2308            multiview_mask: None,
2309        });
2310        for (item, binding) in ready.iter().zip(&bindings) {
2311            encode_ready_item(renderer, &mut pass, item, binding);
2312        }
2313    }
2314    renderer.queue.submit([encoder.finish()]);
2315    renderer.notify_before_present();
2316    renderer.queue.present(surface_texture);
2317    set_particle_rendered(&mut ready, true);
2318    let encode_submit_present = encode_started_at.elapsed();
2319    Ok(frame_report(
2320        RenderStatus::Drawn,
2321        statistics,
2322        tessellation,
2323        upload,
2324        camera_uniform_upload,
2325        surface_acquire,
2326        encode_submit_present,
2327        frame_started_at.elapsed(),
2328        geometry_reused,
2329        geometry_streamed,
2330        tessellation_stats,
2331    ))
2332}
2333
2334fn preflight_frame_items(
2335    renderer: &WgpuRenderer,
2336    target_viewport: LogicalViewport,
2337    items: &[FrameItem<'_>],
2338) -> Result<(), FrameComposerError> {
2339    for item in items {
2340        match item {
2341            FrameItem::Scene {
2342                camera, options, ..
2343            } => {
2344                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
2345                CameraUniform::new_in_region(
2346                    *camera,
2347                    viewport.viewport,
2348                    viewport.origin,
2349                    target_viewport,
2350                )
2351                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2352            }
2353            FrameItem::ScreenScene { options, .. } => {
2354                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
2355                let camera = screen_camera(viewport.viewport)
2356                    .map_err(|_| RendererFrameError::InvalidGeometryTransform)?;
2357                CameraUniform::new_in_region(
2358                    camera,
2359                    viewport.viewport,
2360                    viewport.origin,
2361                    target_viewport,
2362                )
2363                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2364            }
2365            FrameItem::Prepared {
2366                scene,
2367                camera,
2368                options,
2369                ..
2370            } => {
2371                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
2372                let uniform = CameraUniform::new_in_region(
2373                    *camera,
2374                    viewport.viewport,
2375                    viewport.origin,
2376                    target_viewport,
2377                )
2378                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2379                if !geometry_is_safe_for_cached(
2380                    Some(&scene.geometry_validation_cache),
2381                    scene.geometry_extents,
2382                    GeometryValidationSource::Tessellated(&scene.vertices),
2383                    uniform,
2384                ) {
2385                    return Err(RendererFrameError::InvalidGeometryTransform.into());
2386                }
2387            }
2388            FrameItem::PreparedScreen { scene, options, .. } => {
2389                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
2390                let camera = screen_camera(viewport.viewport)
2391                    .map_err(|_| RendererFrameError::InvalidGeometryTransform)?;
2392                let uniform = CameraUniform::new_in_region(
2393                    camera,
2394                    viewport.viewport,
2395                    viewport.origin,
2396                    target_viewport,
2397                )
2398                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2399                if !geometry_is_safe_for_cached(
2400                    Some(&scene.scene.geometry_validation_cache),
2401                    scene.scene.geometry_extents,
2402                    GeometryValidationSource::Tessellated(&scene.scene.vertices),
2403                    uniform,
2404                ) {
2405                    return Err(RendererFrameError::InvalidGeometryTransform.into());
2406                }
2407            }
2408            FrameItem::Dynamic {
2409                mesh,
2410                camera,
2411                options,
2412                ..
2413            } => {
2414                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
2415                let uniform = CameraUniform::new_in_region(
2416                    *camera,
2417                    viewport.viewport,
2418                    viewport.origin,
2419                    target_viewport,
2420                )
2421                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2422                if !geometry_is_safe_for_cached(
2423                    Some(&mesh.geometry_validation_cache),
2424                    mesh.geometry_extents,
2425                    GeometryValidationSource::Dynamic(&mesh.vertices),
2426                    uniform,
2427                ) {
2428                    return Err(RendererFrameError::InvalidGeometryTransform.into());
2429                }
2430            }
2431            FrameItem::Particle {
2432                camera, options, ..
2433            } => {
2434                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
2435                CameraUniform::new(*camera, viewport.viewport)
2436                    .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2437                CameraUniform::new_in_region(
2438                    *camera,
2439                    viewport.viewport,
2440                    viewport.origin,
2441                    target_viewport,
2442                )
2443                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2444            }
2445            FrameItem::Scalar {
2446                texture,
2447                minimum,
2448                maximum,
2449                value_extent,
2450                sampling,
2451                options,
2452                ..
2453            } => {
2454                if !scalar_normalization_is_portable(texture, *minimum, *value_extent) {
2455                    return Err(FrameComposerError::InvalidValueRange {
2456                        minimum: *minimum,
2457                        maximum: *maximum,
2458                    });
2459                }
2460                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
2461                let region = LogicalViewportRegion::new(
2462                    LogicalScreenPosition::from_vec2(viewport.origin),
2463                    viewport.viewport,
2464                )
2465                .map_err(|_| RendererFrameError::InvalidViewport)?;
2466                HeatmapUniform::new(
2467                    *minimum,
2468                    *value_extent,
2469                    texture.width(),
2470                    texture.height(),
2471                    *sampling,
2472                )
2473                .in_region(region, target_viewport)
2474                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2475            }
2476            FrameItem::Image { options, .. } => {
2477                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
2478                let region = LogicalViewportRegion::new(
2479                    LogicalScreenPosition::from_vec2(viewport.origin),
2480                    viewport.viewport,
2481                )
2482                .map_err(|_| RendererFrameError::InvalidViewport)?;
2483                CompositeUniform::in_region(1.0, region, target_viewport)
2484                    .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2485            }
2486            FrameItem::Target {
2487                opacity, options, ..
2488            } => {
2489                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
2490                let region = LogicalViewportRegion::new(
2491                    LogicalScreenPosition::from_vec2(viewport.origin),
2492                    viewport.viewport,
2493                )
2494                .map_err(|_| RendererFrameError::InvalidViewport)?;
2495                CompositeUniform::in_region(*opacity, region, target_viewport)
2496                    .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2497            }
2498            FrameItem::WorldImage {
2499                rectangle,
2500                depth,
2501                camera,
2502                options,
2503                ..
2504            } => {
2505                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
2506                let camera_uniform = CameraUniform::new_in_region(
2507                    *camera,
2508                    viewport.viewport,
2509                    viewport.origin,
2510                    target_viewport,
2511                )
2512                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2513                let minimum = rectangle.min();
2514                let maximum = rectangle.max();
2515                for world in [
2516                    Vec2::new(minimum.x, maximum.y),
2517                    maximum,
2518                    minimum,
2519                    Vec2::new(maximum.x, minimum.y),
2520                ] {
2521                    let screen = camera_uniform.world_to_screen(world, *depth);
2522                    let clip = Vec2::new(
2523                        screen.x.mul_add(
2524                            camera_uniform.screen_to_clip[0],
2525                            camera_uniform.screen_to_clip[2],
2526                        ),
2527                        screen.y.mul_add(
2528                            camera_uniform.screen_to_clip[1],
2529                            camera_uniform.screen_to_clip[3],
2530                        ),
2531                    );
2532                    if ![clip.x, clip.y].into_iter().all(is_portable_shader_source) {
2533                        return Err(RendererFrameError::InvalidGeometryTransform.into());
2534                    }
2535                }
2536            }
2537            FrameItem::ImageBatch { batch, options, .. } => {
2538                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
2539                let clip_transform = [
2540                    2.0 / target_viewport.width(),
2541                    -2.0 / target_viewport.height(),
2542                    -1.0,
2543                    1.0,
2544                ];
2545                if !image_sprites_are_safe_for_target(
2546                    batch.sprites(),
2547                    viewport.origin,
2548                    clip_transform,
2549                ) {
2550                    return Err(RendererFrameError::InvalidGeometryTransform.into());
2551                }
2552            }
2553        }
2554    }
2555    Ok(())
2556}
2557
2558fn image_sprites_are_safe_for_target(
2559    sprites: &[ImageSprite2d],
2560    viewport_origin: Vec2,
2561    clip_transform: [f32; 4],
2562) -> bool {
2563    if ![viewport_origin.x, viewport_origin.y]
2564        .into_iter()
2565        .chain(clip_transform)
2566        .all(is_portable_shader_source)
2567    {
2568        return false;
2569    }
2570    sprites.iter().all(|sprite| {
2571        let destination = sprite.destination();
2572        let origin = destination.origin().to_vec2();
2573        let size = destination.viewport().size();
2574        if ![origin.x, origin.y, size.x, size.y]
2575            .into_iter()
2576            .all(is_portable_shader_source)
2577        {
2578            return false;
2579        }
2580        let horizontal = shader_interval_sum_range([
2581            (f64::from(viewport_origin.x), f64::from(viewport_origin.x)),
2582            (f64::from(origin.x), f64::from(origin.x)),
2583            (0.0, f64::from(size.x)),
2584        ]);
2585        let vertical = shader_interval_sum_range([
2586            (f64::from(viewport_origin.y), f64::from(viewport_origin.y)),
2587            (f64::from(origin.y), f64::from(origin.y)),
2588            (0.0, f64::from(size.y)),
2589        ]);
2590        horizontal.is_some_and(|horizontal| {
2591            shader_clip_interval_is_safe(
2592                horizontal.0,
2593                horizontal.1,
2594                clip_transform[0],
2595                clip_transform[2],
2596            )
2597        }) && vertical.is_some_and(|vertical| {
2598            shader_clip_interval_is_safe(
2599                vertical.0,
2600                vertical.1,
2601                clip_transform[1],
2602                clip_transform[3],
2603            )
2604        })
2605    })
2606}
2607
2608fn set_particle_rendered(items: &mut [ReadyItem<'_>], presented: bool) {
2609    for item in items {
2610        if let ReadyItem::Particle {
2611            field,
2612            visible_count,
2613            pending_statistics,
2614            viewport,
2615            ..
2616        } = item
2617        {
2618            field.statistics = ParticleStatistics {
2619                rendered: if presented && !viewport.item_clipped_out {
2620                    *visible_count
2621                } else {
2622                    0
2623                },
2624                ..*pending_statistics
2625            };
2626        }
2627    }
2628}
2629
2630#[allow(clippy::too_many_arguments)]
2631fn prepare_particle_item<'frame>(
2632    field: &'frame mut ParticleField2d,
2633    camera: Camera2d,
2634    viewport: ResolvedViewport,
2635    target_viewport: LogicalViewport,
2636    ready: &mut Vec<ReadyItem<'frame>>,
2637    statistics: &mut FrameStatistics,
2638) -> Result<(), FrameComposerError> {
2639    let initial_cpu_allocation_bytes = field.cpu_allocation_bytes();
2640    let local_uniform = CameraUniform::new(camera, viewport.viewport)
2641        .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2642    let target_uniform =
2643        CameraUniform::new_in_region(camera, viewport.viewport, viewport.origin, target_viewport)
2644            .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2645    let instance_count = field.instances.len();
2646    let visibility_checked = instance_count.min(field.budget.max_visibility_checks_per_frame);
2647
2648    let (visible_count, selected_count) = if visibility_checked < instance_count {
2649        field.visible_instances.clear();
2650        validate_particle_staging_capacity(&field.visible_instances, visibility_checked)?;
2651        for candidate_index in 0..visibility_checked {
2652            let source_index =
2653                uniformly_sampled_index(candidate_index, instance_count, visibility_checked);
2654            let instance = field.instances[source_index];
2655            if !instance.is_safe_for(target_uniform, target_viewport) {
2656                return Err(RendererFrameError::InvalidGeometryTransform.into());
2657            }
2658            let Some(intersects) =
2659                instance.validated_viewport_intersection(local_uniform, viewport.viewport)
2660            else {
2661                return Err(RendererFrameError::InvalidGeometryTransform.into());
2662            };
2663            if intersects {
2664                field.visible_instances.push(instance);
2665            }
2666        }
2667        let visible_count = field.visible_instances.len();
2668        let selected_count = visible_count.min(field.budget.instance_limit());
2669        if selected_count < visible_count {
2670            let mut visible_index = 0;
2671            field.visible_instances.retain(|_| {
2672                let selected = particle_visible_index_is_selected(
2673                    visible_index,
2674                    visible_count,
2675                    selected_count,
2676                );
2677                visible_index += 1;
2678                selected
2679            });
2680        }
2681        (visible_count, selected_count)
2682    } else {
2683        let visible_count = visible_particle_count_for_frame(
2684            &field.instances,
2685            local_uniform,
2686            target_uniform,
2687            viewport.viewport,
2688            target_viewport,
2689        )?;
2690        let selected_count = visible_count.min(field.budget.instance_limit());
2691        if selected_count == field.instances.len() {
2692            field.visible_instances.clear();
2693        } else {
2694            field.visible_instances.clear();
2695            validate_particle_staging_capacity(&field.visible_instances, selected_count)?;
2696            let mut visible_index = 0;
2697            for instance in field.instances.iter().copied() {
2698                if !instance.intersects_viewport(local_uniform, viewport.viewport) {
2699                    continue;
2700                }
2701                let selected_index = field.visible_instances.len();
2702                if selected_index < selected_count
2703                    && particle_visible_index_is_selected(
2704                        visible_index,
2705                        visible_count,
2706                        selected_count,
2707                    )
2708                {
2709                    field.visible_instances.push(instance);
2710                }
2711                visible_index += 1;
2712            }
2713        }
2714        (visible_count, selected_count)
2715    };
2716    let pending_statistics = particle_statistics_with_budget(
2717        instance_count,
2718        visibility_checked,
2719        visible_count,
2720        selected_count,
2721        0,
2722    );
2723    *statistics = statistics.adding(FrameStatistics {
2724        pass_count: 1,
2725        command_count: usize::from(instance_count > 0),
2726        vertex_count: selected_count.saturating_mul(6),
2727        streaming_vertex_count: selected_count.saturating_mul(6),
2728        reused_vertex_count: 0,
2729        upload_bytes: selected_count
2730            .saturating_mul(std::mem::size_of::<ParticleGpu>())
2731            .saturating_add(std::mem::size_of::<CameraUniform>()),
2732        streaming_upload_bytes: selected_count.saturating_mul(std::mem::size_of::<ParticleGpu>()),
2733        texture_bytes: 0,
2734        retained_cpu_bytes: 0,
2735        retained_buffer_bytes: 0,
2736        draw_calls: usize::from(selected_count > 0),
2737        source_counts: FrameSourceStatistics::default(),
2738    });
2739    ready.push(ReadyItem::Particle {
2740        field,
2741        visible_count: selected_count,
2742        pending_statistics,
2743        initial_cpu_allocation_bytes,
2744        camera_uniform: target_uniform,
2745        viewport,
2746    });
2747    Ok(())
2748}
2749
2750fn visible_particle_count_for_frame(
2751    instances: &[ParticleGpu],
2752    local_camera: CameraUniform,
2753    target_camera: CameraUniform,
2754    viewport: LogicalViewport,
2755    target_viewport: LogicalViewport,
2756) -> Result<usize, RendererFrameError> {
2757    let mut visible = 0;
2758    for instance in instances {
2759        let Some(intersects) = instance.validated_viewport_intersection(local_camera, viewport)
2760        else {
2761            return Err(RendererFrameError::InvalidGeometryTransform);
2762        };
2763        if !instance.is_safe_for(target_camera, target_viewport) {
2764            return Err(RendererFrameError::InvalidGeometryTransform);
2765        }
2766        visible += usize::from(intersects);
2767    }
2768    Ok(visible)
2769}
2770
2771#[allow(clippy::too_many_arguments)]
2772fn prepare_streaming_scene<'frame>(
2773    scene: &Scene,
2774    camera: Camera2d,
2775    options: FramePassOptions,
2776    renderer: &WgpuRenderer,
2777    target_viewport: LogicalViewport,
2778    streaming_vertices: &mut Vec<Vertex>,
2779    ready: &mut Vec<ReadyItem<'frame>>,
2780    statistics: &mut FrameStatistics,
2781    aggregate: &mut TessellationStats,
2782) -> Result<(), FrameComposerError> {
2783    let viewport = resolve_viewport(renderer, target_viewport, options)?;
2784    let camera_uniform =
2785        CameraUniform::new_in_region(camera, viewport.viewport, viewport.origin, target_viewport)
2786            .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2787    if !scene_estimate_fits_streaming_device(
2788        scene,
2789        &renderer.device,
2790        streaming_vertices.len(),
2791        renderer.vertex_capacity,
2792    ) {
2793        return Err(RendererFrameError::GeometryCapacityTooLarge.into());
2794    }
2795    prepare_streaming_scene_resolved(
2796        scene,
2797        camera_uniform,
2798        viewport,
2799        streaming_vertices,
2800        ready,
2801        statistics,
2802        aggregate,
2803    )
2804}
2805
2806#[allow(clippy::too_many_arguments)]
2807fn prepare_streaming_scene_resolved<'frame>(
2808    scene: &Scene,
2809    camera_uniform: CameraUniform,
2810    viewport: ResolvedViewport,
2811    streaming_vertices: &mut Vec<Vertex>,
2812    ready: &mut Vec<ReadyItem<'frame>>,
2813    statistics: &mut FrameStatistics,
2814    aggregate: &mut TessellationStats,
2815) -> Result<(), FrameComposerError> {
2816    let vertex_start = streaming_vertices.len();
2817    let mut batches = Vec::new();
2818    let stats = tessellate_scene(scene, streaming_vertices, &mut batches)
2819        .map_err(RendererFrameError::from)?;
2820    let vertices = &streaming_vertices[vertex_start..];
2821    let extents = GeometryExtents::from_vertices(vertices);
2822    if !geometry_is_safe_for(
2823        extents,
2824        GeometryValidationSource::Tessellated(vertices),
2825        camera_uniform,
2826    ) {
2827        streaming_vertices.truncate(vertex_start);
2828        return Err(RendererFrameError::InvalidGeometryTransform.into());
2829    }
2830    *statistics = statistics.adding(FrameStatistics {
2831        pass_count: 1,
2832        command_count: scene.command_count(),
2833        vertex_count: stats.vertex_count,
2834        streaming_vertex_count: stats.vertex_count,
2835        reused_vertex_count: 0,
2836        upload_bytes: stats
2837            .upload_bytes
2838            .saturating_add(std::mem::size_of::<CameraUniform>()),
2839        streaming_upload_bytes: stats.upload_bytes,
2840        texture_bytes: 0,
2841        retained_cpu_bytes: 0,
2842        retained_buffer_bytes: 0,
2843        draw_calls: batches.len(),
2844        source_counts: FrameSourceStatistics::default(),
2845    });
2846    add_tessellation_stats(aggregate, stats);
2847    ready.push(ReadyItem::Geometry(ReadyGeometry {
2848        source: ReadySource::Streaming,
2849        vertex_count: vertices.len(),
2850        batches,
2851        camera_uniform,
2852        viewport,
2853    }));
2854    Ok(())
2855}
2856
2857#[allow(clippy::too_many_arguments)]
2858fn prepare_retained_geometry<'frame>(
2859    source: ReadySource<'frame>,
2860    vertex_count: usize,
2861    extents: GeometryExtents,
2862    geometry_validation: GeometryValidationSource<'_>,
2863    geometry_validation_cache: Option<&GeometryValidationCache>,
2864    batches: &[PreparedDrawBatch],
2865    command_count: usize,
2866    source_stats: TessellationStats,
2867    camera: Camera2d,
2868    viewport: ResolvedViewport,
2869    target_viewport: LogicalViewport,
2870    ready: &mut Vec<ReadyItem<'frame>>,
2871    statistics: &mut FrameStatistics,
2872    aggregate: &mut TessellationStats,
2873) -> Result<(), FrameComposerError> {
2874    let camera_uniform =
2875        CameraUniform::new_in_region(camera, viewport.viewport, viewport.origin, target_viewport)
2876            .ok_or(RendererFrameError::InvalidGeometryTransform)?;
2877    if !geometry_is_safe_for_cached(
2878        geometry_validation_cache,
2879        extents,
2880        geometry_validation,
2881        camera_uniform,
2882    ) {
2883        return Err(RendererFrameError::InvalidGeometryTransform.into());
2884    }
2885    let mut owned_batches = Vec::new();
2886    owned_batches
2887        .try_reserve(batches.len())
2888        .map_err(|_| FrameComposerError::AllocationFailed {
2889            requested_bytes: batches
2890                .len()
2891                .saturating_mul(std::mem::size_of::<PreparedDrawBatch>()),
2892        })?;
2893    owned_batches.extend_from_slice(batches);
2894    *statistics = statistics.adding(FrameStatistics {
2895        pass_count: 1,
2896        command_count,
2897        vertex_count,
2898        streaming_vertex_count: 0,
2899        reused_vertex_count: vertex_count,
2900        upload_bytes: std::mem::size_of::<CameraUniform>(),
2901        streaming_upload_bytes: 0,
2902        texture_bytes: 0,
2903        retained_cpu_bytes: 0,
2904        retained_buffer_bytes: 0,
2905        draw_calls: owned_batches.len(),
2906        source_counts: FrameSourceStatistics::default(),
2907    });
2908    add_tessellation_stats(aggregate, source_stats);
2909    ready.push(ReadyItem::Geometry(ReadyGeometry {
2910        source,
2911        vertex_count,
2912        batches: owned_batches,
2913        camera_uniform,
2914        viewport,
2915    }));
2916    Ok(())
2917}
2918
2919fn resolve_viewport(
2920    renderer: &WgpuRenderer,
2921    target: LogicalViewport,
2922    options: FramePassOptions,
2923) -> Result<ResolvedViewport, FrameComposerError> {
2924    let (viewport, origin) = match options.viewport() {
2925        Some(region) => (region.viewport(), region.origin().to_vec2()),
2926        None => (target, Vec2::ZERO),
2927    };
2928    let max = origin + viewport.size();
2929    if !origin.is_finite()
2930        || !max.is_finite()
2931        || origin.x < 0.0
2932        || origin.y < 0.0
2933        || max.x > target.width()
2934        || max.y > target.height()
2935    {
2936        return Err(RendererFrameError::InvalidViewport.into());
2937    }
2938    let scissor = logical_viewport_scissor(
2939        origin,
2940        viewport,
2941        renderer.scale_factor as f32,
2942        renderer.config.width,
2943        renderer.config.height,
2944    )
2945    .ok_or(RendererFrameError::InvalidViewport)?;
2946    let (item_clip, item_clipped_out) = match options.clip() {
2947        Some(clip) => {
2948            let resolved = screen_clip_to_scissor(clip, viewport, renderer.scale_factor as f32)
2949                .and_then(|clip| offset_scissor(clip, scissor));
2950            (resolved, resolved.is_none())
2951        }
2952        None => (None, false),
2953    };
2954    Ok(ResolvedViewport {
2955        viewport,
2956        origin,
2957        scissor,
2958        item_clip,
2959        item_clipped_out,
2960    })
2961}
2962
2963fn create_frame_binding(renderer: &mut WgpuRenderer, item: &ReadyItem<'_>) -> FrameBinding {
2964    match item {
2965        ReadyItem::Geometry(geometry) => create_camera_binding(renderer, &geometry.camera_uniform),
2966        ReadyItem::Particle { camera_uniform, .. } => {
2967            create_camera_binding(renderer, camera_uniform)
2968        }
2969        ReadyItem::Scalar {
2970            texture,
2971            color_map,
2972            uniform,
2973            ..
2974        } => {
2975            let color_map_view = renderer.color_map_view(color_map);
2976            let scalar_view = texture
2977                .texture
2978                .create_view(&wgpu::TextureViewDescriptor::default());
2979            let bytes = bytemuck::bytes_of(uniform);
2980            let buffer = renderer.device.create_buffer(&wgpu::BufferDescriptor {
2981                label: Some("sim-engine frame heatmap uniform"),
2982                size: bytes.len() as wgpu::BufferAddress,
2983                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
2984                mapped_at_creation: false,
2985            });
2986            renderer.queue.write_buffer(&buffer, 0, bytes);
2987            let bind_group = renderer
2988                .device
2989                .create_bind_group(&wgpu::BindGroupDescriptor {
2990                    label: Some("sim-engine frame heatmap bind group"),
2991                    layout: &renderer.heatmap_bind_group_layout,
2992                    entries: &[
2993                        wgpu::BindGroupEntry {
2994                            binding: 0,
2995                            resource: wgpu::BindingResource::TextureView(&scalar_view),
2996                        },
2997                        wgpu::BindGroupEntry {
2998                            binding: 1,
2999                            resource: wgpu::BindingResource::TextureView(&color_map_view),
3000                        },
3001                        wgpu::BindGroupEntry {
3002                            binding: 2,
3003                            resource: buffer.as_entire_binding(),
3004                        },
3005                    ],
3006                });
3007            FrameBinding {
3008                _buffer: buffer,
3009                bind_group,
3010            }
3011        }
3012        ReadyItem::Image {
3013            image,
3014            sampling,
3015            uniform,
3016            ..
3017        }
3018        | ReadyItem::ImageBatch {
3019            image,
3020            sampling,
3021            uniform,
3022            ..
3023        } => {
3024            let bytes = bytemuck::bytes_of(uniform);
3025            let buffer = renderer.device.create_buffer(&wgpu::BufferDescriptor {
3026                label: Some("sim-engine frame image uniform"),
3027                size: bytes.len() as wgpu::BufferAddress,
3028                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
3029                mapped_at_creation: false,
3030            });
3031            renderer.queue.write_buffer(&buffer, 0, bytes);
3032            let bind_group = renderer
3033                .device
3034                .create_bind_group(&wgpu::BindGroupDescriptor {
3035                    label: Some("sim-engine frame image bind group"),
3036                    layout: &renderer.image_renderer.bind_group_layout,
3037                    entries: &[
3038                        wgpu::BindGroupEntry {
3039                            binding: 0,
3040                            resource: wgpu::BindingResource::TextureView(&image.view),
3041                        },
3042                        wgpu::BindGroupEntry {
3043                            binding: 1,
3044                            resource: wgpu::BindingResource::Sampler(
3045                                renderer.image_renderer.sampler(*sampling),
3046                            ),
3047                        },
3048                        wgpu::BindGroupEntry {
3049                            binding: 2,
3050                            resource: buffer.as_entire_binding(),
3051                        },
3052                    ],
3053                });
3054            FrameBinding {
3055                _buffer: buffer,
3056                bind_group,
3057            }
3058        }
3059        ReadyItem::Target {
3060            target, uniform, ..
3061        } => {
3062            let bytes = bytemuck::bytes_of(uniform);
3063            let buffer = renderer.device.create_buffer(&wgpu::BufferDescriptor {
3064                label: Some("sim-engine frame composition uniform"),
3065                size: bytes.len() as wgpu::BufferAddress,
3066                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
3067                mapped_at_creation: false,
3068            });
3069            renderer.queue.write_buffer(&buffer, 0, bytes);
3070            let bind_group = renderer
3071                .device
3072                .create_bind_group(&wgpu::BindGroupDescriptor {
3073                    label: Some("sim-engine frame composition bind group"),
3074                    layout: &renderer.composition_pipelines.bind_group_layout,
3075                    entries: &[
3076                        wgpu::BindGroupEntry {
3077                            binding: 0,
3078                            resource: wgpu::BindingResource::TextureView(&target.view),
3079                        },
3080                        wgpu::BindGroupEntry {
3081                            binding: 1,
3082                            resource: buffer.as_entire_binding(),
3083                        },
3084                    ],
3085                });
3086            FrameBinding {
3087                _buffer: buffer,
3088                bind_group,
3089            }
3090        }
3091    }
3092}
3093
3094fn create_camera_binding(renderer: &WgpuRenderer, uniform: &CameraUniform) -> FrameBinding {
3095    let label = "sim-engine frame camera uniform";
3096    let bytes = bytemuck::bytes_of(uniform);
3097    let buffer = renderer.device.create_buffer(&wgpu::BufferDescriptor {
3098        label: Some(label),
3099        size: bytes.len() as wgpu::BufferAddress,
3100        usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
3101        mapped_at_creation: false,
3102    });
3103    renderer.queue.write_buffer(&buffer, 0, bytes);
3104    let bind_group = renderer
3105        .device
3106        .create_bind_group(&wgpu::BindGroupDescriptor {
3107            label: Some("sim-engine frame camera bind group"),
3108            layout: &renderer.camera_bind_group_layout,
3109            entries: &[wgpu::BindGroupEntry {
3110                binding: 0,
3111                resource: buffer.as_entire_binding(),
3112            }],
3113        });
3114    FrameBinding {
3115        _buffer: buffer,
3116        bind_group,
3117    }
3118}
3119
3120fn encode_ready_item<'pass>(
3121    renderer: &'pass WgpuRenderer,
3122    pass: &mut wgpu::RenderPass<'pass>,
3123    item: &'pass ReadyItem<'_>,
3124    binding: &'pass FrameBinding,
3125) {
3126    match item {
3127        ReadyItem::Geometry(geometry) => {
3128            if geometry.vertex_count == 0 {
3129                return;
3130            }
3131            let (pipeline, vertex_buffer) = match geometry.source {
3132                ReadySource::Streaming => (&renderer.pipeline, renderer.vertex_buffer.as_ref()),
3133                ReadySource::Prepared(buffer) => (&renderer.pipeline, buffer),
3134                ReadySource::Dynamic(buffer) => (&renderer.dynamic_pipeline, buffer),
3135            };
3136            pass.set_pipeline(pipeline);
3137            pass.set_bind_group(0, &binding.bind_group, &[]);
3138            pass.set_vertex_buffer(0, vertex_buffer.slice(..));
3139            for batch in &geometry.batches {
3140                let Some(scissor) = effective_scissor(
3141                    geometry.viewport,
3142                    batch.screen_clip,
3143                    renderer.scale_factor as f32,
3144                ) else {
3145                    continue;
3146                };
3147                pass.set_scissor_rect(scissor.x, scissor.y, scissor.width, scissor.height);
3148                pass.draw(batch.vertex_range.clone(), 0..1);
3149            }
3150        }
3151        ReadyItem::Particle {
3152            field,
3153            visible_count,
3154            viewport,
3155            ..
3156        } => {
3157            if *visible_count == 0 || viewport.item_clipped_out {
3158                return;
3159            }
3160            let scissor = viewport.item_clip.unwrap_or(viewport.scissor);
3161            pass.set_pipeline(&renderer.particle_pipeline);
3162            pass.set_bind_group(0, &binding.bind_group, &[]);
3163            pass.set_vertex_buffer(0, renderer.particle_unit_buffer.slice(..));
3164            pass.set_vertex_buffer(1, field.instance_buffer.slice(..));
3165            pass.set_scissor_rect(scissor.x, scissor.y, scissor.width, scissor.height);
3166            pass.draw(0..6, 0..*visible_count as u32);
3167        }
3168        ReadyItem::Scalar { viewport, .. } => {
3169            if viewport.item_clipped_out {
3170                return;
3171            }
3172            let scissor = viewport.item_clip.unwrap_or(viewport.scissor);
3173            pass.set_pipeline(&renderer.heatmap_pipeline);
3174            pass.set_bind_group(0, &binding.bind_group, &[]);
3175            pass.set_scissor_rect(scissor.x, scissor.y, scissor.width, scissor.height);
3176            pass.draw(0..6, 0..1);
3177        }
3178        ReadyItem::Image { viewport, .. } => {
3179            if viewport.item_clipped_out {
3180                return;
3181            }
3182            let scissor = viewport.item_clip.unwrap_or(viewport.scissor);
3183            pass.set_pipeline(&renderer.image_renderer.pipeline);
3184            pass.set_bind_group(0, &binding.bind_group, &[]);
3185            pass.set_scissor_rect(scissor.x, scissor.y, scissor.width, scissor.height);
3186            pass.draw(0..6, 0..1);
3187        }
3188        ReadyItem::ImageBatch {
3189            batch, viewport, ..
3190        } => {
3191            if batch.sprite_count() == 0 || viewport.item_clipped_out {
3192                return;
3193            }
3194            let scissor = viewport.item_clip.unwrap_or(viewport.scissor);
3195            pass.set_pipeline(&renderer.image_renderer.batch_pipeline);
3196            pass.set_bind_group(0, &binding.bind_group, &[]);
3197            pass.set_vertex_buffer(0, batch.instance_buffer.slice(..));
3198            pass.set_scissor_rect(scissor.x, scissor.y, scissor.width, scissor.height);
3199            pass.draw(0..6, 0..batch.sprite_count() as u32);
3200        }
3201        ReadyItem::Target {
3202            blend_mode,
3203            viewport,
3204            ..
3205        } => {
3206            if viewport.item_clipped_out {
3207                return;
3208            }
3209            let scissor = viewport.item_clip.unwrap_or(viewport.scissor);
3210            pass.set_pipeline(renderer.composition_pipelines.pipeline(*blend_mode));
3211            pass.set_bind_group(0, &binding.bind_group, &[]);
3212            pass.set_scissor_rect(scissor.x, scissor.y, scissor.width, scissor.height);
3213            pass.draw(0..6, 0..1);
3214        }
3215    }
3216}
3217
3218fn effective_scissor(
3219    viewport: ResolvedViewport,
3220    source_clip: Option<ScreenClipRect>,
3221    scale_factor: f32,
3222) -> Option<ScissorRect> {
3223    if viewport.item_clipped_out {
3224        return None;
3225    }
3226    let source = match source_clip {
3227        Some(clip) => screen_clip_to_scissor(clip, viewport.viewport, scale_factor)
3228            .and_then(|clip| offset_scissor(clip, viewport.scissor))?,
3229        None => viewport.scissor,
3230    };
3231    match viewport.item_clip {
3232        Some(item) => intersect_scissors(source, item),
3233        None => Some(source),
3234    }
3235}
3236
3237fn intersect_scissors(first: ScissorRect, second: ScissorRect) -> Option<ScissorRect> {
3238    let x = first.x.max(second.x);
3239    let y = first.y.max(second.y);
3240    let max_x = first
3241        .x
3242        .saturating_add(first.width)
3243        .min(second.x.saturating_add(second.width));
3244    let max_y = first
3245        .y
3246        .saturating_add(first.height)
3247        .min(second.y.saturating_add(second.height));
3248    (max_x > x && max_y > y).then_some(ScissorRect {
3249        x,
3250        y,
3251        width: max_x - x,
3252        height: max_y - y,
3253    })
3254}
3255
3256fn validate_frame_budget(
3257    budget: FrameBudget,
3258    statistics: FrameStatistics,
3259) -> Result<(), FrameComposerError> {
3260    let work = [
3261        (
3262            FrameBudgetResource::Passes,
3263            budget.max_passes,
3264            statistics.pass_count,
3265        ),
3266        (
3267            FrameBudgetResource::Commands,
3268            budget.max_commands,
3269            statistics.command_count,
3270        ),
3271        (
3272            FrameBudgetResource::Vertices,
3273            budget.max_vertices,
3274            statistics.vertex_count,
3275        ),
3276        (
3277            FrameBudgetResource::UploadBytes,
3278            budget.max_upload_bytes,
3279            statistics.upload_bytes,
3280        ),
3281        (
3282            FrameBudgetResource::TextureBytes,
3283            budget.max_texture_bytes,
3284            statistics.texture_bytes,
3285        ),
3286        (
3287            FrameBudgetResource::DrawCalls,
3288            budget.max_draw_calls,
3289            statistics.draw_calls,
3290        ),
3291    ];
3292    for (resource, limit, actual) in work {
3293        if actual > limit {
3294            return Err(FrameComposerError::BudgetExceeded {
3295                resource,
3296                limit,
3297                actual,
3298            });
3299        }
3300    }
3301    Ok(())
3302}
3303
3304fn add_tessellation_stats(aggregate: &mut TessellationStats, source: TessellationStats) {
3305    aggregate.command_count = aggregate.command_count.saturating_add(source.command_count);
3306    aggregate.rendered_command_count = aggregate
3307        .rendered_command_count
3308        .saturating_add(source.rendered_command_count);
3309    aggregate.dropped_command_count = aggregate
3310        .dropped_command_count
3311        .saturating_add(source.dropped_command_count);
3312    aggregate.command_counts = aggregate.command_counts.adding(source.command_counts);
3313    aggregate.rendered_counts = aggregate.rendered_counts.adding(source.rendered_counts);
3314    aggregate.dropped_counts = aggregate.dropped_counts.adding(source.dropped_counts);
3315    aggregate.vertex_count = aggregate.vertex_count.saturating_add(source.vertex_count);
3316    aggregate.draw_batch_count = aggregate
3317        .draw_batch_count
3318        .saturating_add(source.draw_batch_count);
3319    aggregate.upload_bytes = aggregate.upload_bytes.saturating_add(source.upload_bytes);
3320}
3321
3322#[allow(clippy::too_many_arguments)]
3323fn frame_report(
3324    status: RenderStatus,
3325    statistics: FrameStatistics,
3326    tessellation: Duration,
3327    upload: Duration,
3328    camera_uniform_upload: Duration,
3329    surface_acquire: Duration,
3330    encode_submit_present: Duration,
3331    total_cpu: Duration,
3332    geometry_reused: bool,
3333    geometry_streamed: bool,
3334    tessellation_stats: TessellationStats,
3335) -> FrameReport {
3336    let report = render_report(
3337        status,
3338        tessellation,
3339        upload,
3340        camera_uniform_upload,
3341        surface_acquire,
3342        encode_submit_present,
3343        total_cpu,
3344        geometry_reused,
3345        geometry_streamed,
3346        tessellation_stats,
3347    );
3348    FrameReport {
3349        status: report.status,
3350        statistics,
3351        metrics: report.metrics,
3352    }
3353}
3354
3355#[cfg(test)]
3356mod tests {
3357    use super::*;
3358
3359    #[test]
3360    fn scalar_lut_accounting_matches_one_entry_cache_runs() {
3361        const BYTES: usize = COLOR_MAP_LUT_SIZE as usize * 4;
3362        let a = [1; BYTES];
3363        let b = [2; BYTES];
3364        let adjacent = vec![
3365            ScalarLutPlan {
3366                sort_key: (0, 0),
3367                lut: a,
3368            },
3369            ScalarLutPlan {
3370                sort_key: (0, 2),
3371                lut: a,
3372            },
3373        ];
3374        assert_eq!(
3375            scalar_lut_counts_with_inserted(&adjacent, 1, &a, Some(&a)),
3376            (0, 1)
3377        );
3378        assert_eq!(
3379            scalar_lut_counts_with_inserted(&adjacent, 1, &b, Some(&a)),
3380            (2, 3),
3381            "A, B, A performs two uploads and keeps three LUT allocations alive"
3382        );
3383        assert_eq!(
3384            scalar_lut_counts_with_inserted(&adjacent[..1], 1, &b, None),
3385            (2, 2)
3386        );
3387    }
3388
3389    #[test]
3390    fn image_and_glyph_sprite_bounds_include_final_clip_arithmetic() {
3391        let source = ImageTexelRect::new(0, 0, 1, 1).unwrap();
3392        let safe = ImageSprite2d::new(
3393            source,
3394            LogicalViewportRegion::new(
3395                LogicalScreenPosition::new(0.0, 0.0),
3396                LogicalViewport::new(1.0, 1.0).unwrap(),
3397            )
3398            .unwrap(),
3399            Color::WHITE,
3400        )
3401        .unwrap();
3402        let overflowing = ImageSprite2d::new(
3403            source,
3404            LogicalViewportRegion::new(
3405                LogicalScreenPosition::new(-2.0e38, 0.0),
3406                LogicalViewport::new(3.0e38, 1.0).unwrap(),
3407            )
3408            .unwrap(),
3409            Color::WHITE,
3410        )
3411        .unwrap();
3412        let one_pixel_clip = [2.0, -2.0, -1.0, 1.0];
3413
3414        assert!(image_sprites_are_safe_for_target(
3415            &[safe],
3416            Vec2::ZERO,
3417            one_pixel_clip,
3418        ));
3419        assert!(!image_sprites_are_safe_for_target(
3420            &[overflowing],
3421            Vec2::ZERO,
3422            one_pixel_clip,
3423        ));
3424    }
3425
3426    #[test]
3427    fn frame_budget_accepts_exact_limit_and_rejects_one_over() {
3428        let budget = FrameBudget::new(1, 2, 3, 4, 5, 6);
3429        let exact = FrameStatistics {
3430            pass_count: 1,
3431            command_count: 2,
3432            vertex_count: 3,
3433            streaming_vertex_count: 0,
3434            reused_vertex_count: 0,
3435            upload_bytes: 4,
3436            streaming_upload_bytes: 0,
3437            texture_bytes: 5,
3438            retained_cpu_bytes: 7,
3439            retained_buffer_bytes: 8,
3440            draw_calls: 6,
3441            source_counts: FrameSourceStatistics::single(FrameSourceKind::StreamingScene),
3442        };
3443        assert_eq!(validate_frame_budget(budget, exact), Ok(()));
3444        assert_eq!(
3445            validate_frame_budget(
3446                budget,
3447                FrameStatistics {
3448                    draw_calls: 7,
3449                    ..exact
3450                }
3451            ),
3452            Err(FrameComposerError::BudgetExceeded {
3453                resource: FrameBudgetResource::DrawCalls,
3454                limit: 6,
3455                actual: 7,
3456            })
3457        );
3458    }
3459
3460    #[test]
3461    fn frame_statistics_group_sources_and_retained_memory_without_changing_budgets() {
3462        let streaming = FrameStatistics {
3463            pass_count: 1,
3464            retained_cpu_bytes: 128,
3465            source_counts: FrameSourceStatistics::single(FrameSourceKind::StreamingScene),
3466            ..FrameStatistics::default()
3467        };
3468        let glyph = FrameStatistics {
3469            pass_count: 1,
3470            retained_cpu_bytes: 256,
3471            retained_buffer_bytes: 512,
3472            source_counts: FrameSourceStatistics::single(FrameSourceKind::Glyph),
3473            ..FrameStatistics::default()
3474        };
3475
3476        let combined = streaming.adding(glyph);
3477
3478        assert_eq!(combined.pass_count(), 2);
3479        assert_eq!(combined.retained_cpu_bytes(), 384);
3480        assert_eq!(combined.retained_buffer_bytes(), 512);
3481        assert_eq!(combined.source_counts().streaming_scenes(), 1);
3482        assert_eq!(combined.source_counts().glyph_runs(), 1);
3483        assert_eq!(combined.source_counts().total(), 2);
3484        assert_eq!(
3485            validate_frame_budget(FrameBudget::new(2, 0, 0, 0, 0, 0), combined),
3486            Ok(())
3487        );
3488    }
3489
3490    #[test]
3491    fn repeated_retained_references_count_each_allocation_once() {
3492        let first = RetainedResourceKey {
3493            address: 0x1000,
3494            class: 3,
3495        };
3496        let second = RetainedResourceKey {
3497            address: 0x2000,
3498            class: 7,
3499        };
3500        let resources = [
3501            RetainedResourceAccounting::new(first, 128, 256, 0),
3502            RetainedResourceAccounting::new(first, 128, 256, 0),
3503            RetainedResourceAccounting::new(second, 64, 0, 512),
3504        ];
3505
3506        let (first_frame, missing) =
3507            account_new_retained_resources(&[], &resources, FrameStatistics::default());
3508        assert_eq!(missing, 2);
3509        assert_eq!(first_frame.retained_cpu_bytes(), 192);
3510        assert_eq!(first_frame.retained_buffer_bytes(), 256);
3511        assert_eq!(first_frame.texture_bytes(), 512);
3512
3513        let (repeated, missing) = account_new_retained_resources(
3514            &[first, second],
3515            &resources,
3516            FrameStatistics::default(),
3517        );
3518        assert_eq!(missing, 0);
3519        assert_eq!(repeated.retained_cpu_bytes(), 0);
3520        assert_eq!(repeated.retained_buffer_bytes(), 0);
3521        assert_eq!(repeated.texture_bytes(), 0);
3522    }
3523
3524    #[test]
3525    fn frame_report_exposes_single_present_contract_and_skipped_zeroes() {
3526        let drawn = FrameReport {
3527            status: RenderStatus::Drawn,
3528            statistics: FrameStatistics::default(),
3529            metrics: RendererFrameMetrics::default(),
3530        };
3531        assert_eq!(drawn.command_encoder_count(), 1);
3532        assert_eq!(drawn.render_pass_count(), 1);
3533        assert_eq!(drawn.queue_submission_count(), 1);
3534        assert_eq!(drawn.surface_present_count(), 1);
3535
3536        let skipped = FrameReport {
3537            status: RenderStatus::Skipped(RendererSurfaceStatus::Occluded),
3538            ..drawn
3539        };
3540        assert_eq!(skipped.command_encoder_count(), 0);
3541        assert_eq!(skipped.render_pass_count(), 0);
3542        assert_eq!(skipped.queue_submission_count(), 0);
3543        assert_eq!(skipped.surface_present_count(), 0);
3544
3545        let planned = FrameStatistics {
3546            upload_bytes: 128,
3547            streaming_upload_bytes: 96,
3548            vertex_count: 12,
3549            ..FrameStatistics::default()
3550        };
3551        let skipped_statistics = planned.without_uploads();
3552        assert_eq!(skipped_statistics.upload_bytes(), 0);
3553        assert_eq!(skipped_statistics.streaming_upload_bytes(), 0);
3554        assert_eq!(skipped_statistics.vertex_count(), 12);
3555    }
3556
3557    #[test]
3558    fn frame_items_sort_stably_by_order_then_insertion() {
3559        let scene = Scene::new(Color::BLACK).unwrap();
3560        let camera = Camera2d::default();
3561        let mut items = [
3562            FrameItem::Scene {
3563                scene: &scene,
3564                camera,
3565                options: FramePassOptions::new(4),
3566                insertion: 0,
3567            },
3568            FrameItem::Scene {
3569                scene: &scene,
3570                camera,
3571                options: FramePassOptions::new(-1),
3572                insertion: 1,
3573            },
3574            FrameItem::Scene {
3575                scene: &scene,
3576                camera,
3577                options: FramePassOptions::new(4),
3578                insertion: 2,
3579            },
3580        ];
3581        items.sort_unstable_by_key(FrameItem::sort_key);
3582        assert_eq!(
3583            items.iter().map(FrameItem::sort_key).collect::<Vec<_>>(),
3584            vec![(-1, 1), (4, 0), (4, 2)]
3585        );
3586    }
3587
3588    #[test]
3589    fn late_streaming_transform_rejection_rolls_back_appended_vertices() {
3590        let mut scene = Scene::new(Color::BLACK).unwrap();
3591        scene
3592            .try_line(
3593                Vec2::new(1.0e30, 0.0),
3594                Vec2::new(1.1e30, 0.0),
3595                1.0,
3596                Color::WHITE,
3597            )
3598            .unwrap();
3599        let viewport = LogicalViewport::new(64.0, 64.0).unwrap();
3600        let camera = Camera2d::new(Vec2::ZERO, 1.0e10).unwrap();
3601        let uniform = CameraUniform::new_in_region(camera, viewport, Vec2::ZERO, viewport).unwrap();
3602        let resolved = ResolvedViewport {
3603            viewport,
3604            origin: Vec2::ZERO,
3605            scissor: ScissorRect {
3606                x: 0,
3607                y: 0,
3608                width: 64,
3609                height: 64,
3610            },
3611            item_clip: None,
3612            item_clipped_out: false,
3613        };
3614        let mut vertices = Vec::new();
3615        let mut ready = Vec::new();
3616        let mut statistics = FrameStatistics::default();
3617        let mut aggregate = TessellationStats::default();
3618
3619        assert_eq!(
3620            prepare_streaming_scene_resolved(
3621                &scene,
3622                uniform,
3623                resolved,
3624                &mut vertices,
3625                &mut ready,
3626                &mut statistics,
3627                &mut aggregate,
3628            ),
3629            Err(FrameComposerError::Frame(
3630                RendererFrameError::InvalidGeometryTransform
3631            ))
3632        );
3633        assert!(vertices.is_empty());
3634        assert!(ready.is_empty());
3635        assert_eq!(statistics, FrameStatistics::default());
3636        assert_eq!(aggregate, TessellationStats::default());
3637    }
3638
3639    #[test]
3640    fn streaming_screen_scene_rejects_generated_subnormal_geometry() {
3641        let viewport = LogicalViewport::new(64.0, 64.0).unwrap();
3642        let mut scene = ScreenScene::new(Color::BLACK).unwrap();
3643        scene
3644            .try_circle(
3645                LogicalScreenPosition::new(32.0, 32.0),
3646                crate::LogicalPixels::new(f32::MIN_POSITIVE).unwrap(),
3647                ShapeStyle::filled(Color::WHITE),
3648            )
3649            .unwrap();
3650        let camera = screen_camera(viewport).unwrap();
3651        let uniform = CameraUniform::new_in_region(camera, viewport, Vec2::ZERO, viewport).unwrap();
3652        let resolved = ResolvedViewport {
3653            viewport,
3654            origin: Vec2::ZERO,
3655            scissor: ScissorRect {
3656                x: 0,
3657                y: 0,
3658                width: 64,
3659                height: 64,
3660            },
3661            item_clip: None,
3662            item_clipped_out: false,
3663        };
3664        let mut vertices = Vec::new();
3665        let mut ready = Vec::new();
3666        let mut statistics = FrameStatistics::default();
3667        let mut aggregate = TessellationStats::default();
3668
3669        assert_eq!(
3670            prepare_streaming_scene_resolved(
3671                scene.as_scene(),
3672                uniform,
3673                resolved,
3674                &mut vertices,
3675                &mut ready,
3676                &mut statistics,
3677                &mut aggregate,
3678            ),
3679            Err(FrameComposerError::Frame(
3680                RendererFrameError::InvalidGeometryTransform
3681            ))
3682        );
3683        assert!(vertices.is_empty());
3684        assert!(ready.is_empty());
3685    }
3686
3687    #[test]
3688    fn scissor_intersection_rejects_disjoint_rectangles() {
3689        let first = ScissorRect {
3690            x: 2,
3691            y: 3,
3692            width: 8,
3693            height: 9,
3694        };
3695        let overlapping = ScissorRect {
3696            x: 8,
3697            y: 10,
3698            width: 8,
3699            height: 8,
3700        };
3701        assert_eq!(
3702            intersect_scissors(first, overlapping),
3703            Some(ScissorRect {
3704                x: 8,
3705                y: 10,
3706                width: 2,
3707                height: 2,
3708            })
3709        );
3710        assert_eq!(
3711            intersect_scissors(
3712                first,
3713                ScissorRect {
3714                    x: 10,
3715                    y: 3,
3716                    width: 2,
3717                    height: 2,
3718                }
3719            ),
3720            None
3721        );
3722    }
3723
3724    #[test]
3725    fn target_destination_maps_logical_region_to_clip_space() {
3726        let target = LogicalViewport::new(800.0, 600.0).unwrap();
3727        let region = LogicalViewportRegion::new(
3728            LogicalScreenPosition::new(200.0, 150.0),
3729            LogicalViewport::new(400.0, 300.0).unwrap(),
3730        )
3731        .unwrap();
3732        let uniform = CompositeUniform::in_region(0.5, region, target).unwrap();
3733        assert_eq!(uniform.opacity[0], 0.5);
3734        assert_eq!(uniform.destination, [0.5, 0.5, 0.0, 0.0]);
3735    }
3736}