Skip to main content

sim_engine/renderer/
frame.rs

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