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