Skip to main content

sim_engine/renderer/frame/
mod.rs

1use super::RendererPreparationMetrics;
2use super::glyph_batch::GlyphBatchSpan;
3use std::error::Error;
4use std::fmt;
5use std::sync::Arc;
6use std::time::Duration;
7use std::time::Instant;
8
9#[cfg(test)]
10use super::ImageSprite2d;
11use super::{
12    BlendMode, COLOR_MAP_LUT_SIZE, Camera2d, CameraUniform, Color, ColorMap, CompositeUniform,
13    DynamicMesh2d, GeometryExtents, GeometryValidationCache, GeometryValidationSource, GpuTimingId,
14    HeatmapUniform, Image2d, ImageBatch2d, ImageBatchPlacement, ImageSampling, ImageTexelRect,
15    ImageUniform, LogicalScreenPosition, LogicalViewport, LogicalViewportRegion, ParticleField2d,
16    ParticleGpu, ParticleStatistics, PreparedDrawBatch, PreparedScene, PreparedScreenScene, Rect,
17    RenderStatus, RenderTarget2d, RendererFrameError, RendererFrameMetrics, ScalarFieldSampling,
18    ScalarFieldTexture, Scene, ScissorRect, ScreenClipRect, ScreenScene, TessellationStats, Vec2,
19    Vertex, WgpuRenderer, geometry_is_safe_for, geometry_is_safe_for_cached, image,
20    is_portable_shader_source, logical_viewport_scissor, offset_scissor,
21    particle_statistics_with_budget, particle_visible_index_is_selected, render_report,
22    scalar_normalization_is_portable, scene_estimate_fits_streaming_device, screen_camera,
23    screen_clip_to_scissor, tessellate_scene, uniformly_sampled_index,
24    validate_particle_staging_capacity,
25};
26
27mod cache;
28mod compose;
29mod encoding;
30#[cfg(test)]
31pub(super) use encoding::assert_gpu_encoding_contract;
32#[cfg(test)]
33pub(super) use encoding::encode_glyph_batch_for_test;
34pub(super) use encoding::encode_screen_primitives;
35#[cfg(test)]
36pub(super) use encoding::encode_screen_primitives_for_test;
37mod present;
38mod primitives;
39mod streaming;
40#[cfg(test)]
41mod tests;
42mod uniform_uploads;
43pub(super) use cache::FrameCache;
44#[cfg(test)]
45pub(super) use cache::assert_gpu_binding_sharing_contract;
46pub use cache::{FrameCacheBudget, FrameCacheStatistics};
47#[cfg(test)]
48pub(super) use uniform_uploads::assert_gpu_uniform_upload_contract;
49
50/// Work category constrained by a [`FrameBudget`].
51#[derive(Debug, Clone, Copy, PartialEq, Eq)]
52pub enum FrameBudgetResource {
53    /// Number of ordered sources in one frame.
54    Passes,
55    /// Scene commands referenced by the frame.
56    Commands,
57    /// Generated or retained vertices referenced by the frame.
58    Vertices,
59    /// Bytes uploaded while preparing the frame.
60    UploadBytes,
61    /// Nominal retained texel-storage bytes referenced by images, fields, or targets.
62    TextureBytes,
63    /// Conservative number of GPU draw calls encoded by the frame.
64    DrawCalls,
65}
66
67/// Explicit upper bounds for one heterogeneous presentation frame.
68///
69/// The default is deliberately finite. Production hosts should select limits
70/// from their frame-time and memory budgets instead of treating it as a device
71/// capability query.
72#[derive(Debug, Clone, Copy, PartialEq, Eq)]
73pub struct FrameBudget {
74    max_passes: usize,
75    max_commands: usize,
76    max_vertices: usize,
77    max_upload_bytes: usize,
78    max_texture_bytes: usize,
79    max_draw_calls: usize,
80}
81
82impl FrameBudget {
83    /// Creates an exact set of frame-work limits.
84    pub const fn new(
85        max_passes: usize,
86        max_commands: usize,
87        max_vertices: usize,
88        max_upload_bytes: usize,
89        max_texture_bytes: usize,
90        max_draw_calls: usize,
91    ) -> Self {
92        Self {
93            max_passes,
94            max_commands,
95            max_vertices,
96            max_upload_bytes,
97            max_texture_bytes,
98            max_draw_calls,
99        }
100    }
101
102    /// Returns the maximum number of ordered sources.
103    pub const fn max_passes(self) -> usize {
104        self.max_passes
105    }
106
107    /// Returns the maximum referenced scene-command count.
108    pub const fn max_commands(self) -> usize {
109        self.max_commands
110    }
111
112    /// Returns the maximum referenced or generated vertex count.
113    pub const fn max_vertices(self) -> usize {
114        self.max_vertices
115    }
116
117    /// Returns the maximum bytes uploaded while presenting the frame.
118    pub const fn max_upload_bytes(self) -> usize {
119        self.max_upload_bytes
120    }
121
122    /// Returns the maximum referenced nominal texel-storage bytes.
123    pub const fn max_texture_bytes(self) -> usize {
124        self.max_texture_bytes
125    }
126
127    /// Returns the maximum conservative draw-call count.
128    pub const fn max_draw_calls(self) -> usize {
129        self.max_draw_calls
130    }
131}
132
133impl Default for FrameBudget {
134    fn default() -> Self {
135        Self::new(
136            64,
137            100_000,
138            4_000_000,
139            256 * 1024 * 1024,
140            512 * 1024 * 1024,
141            65_536,
142        )
143    }
144}
145
146/// Shared placement and ordering state for one frame item.
147#[derive(Debug, Clone, Copy, PartialEq, Default)]
148pub struct FramePassOptions {
149    order: i32,
150    viewport: Option<LogicalViewportRegion>,
151    clip: Option<ScreenClipRect>,
152}
153
154impl FramePassOptions {
155    /// Creates a full-surface, unclipped item at `order`.
156    pub const fn new(order: i32) -> Self {
157        Self {
158            order,
159            viewport: None,
160            clip: None,
161        }
162    }
163
164    /// Positions the item in a logical sub-viewport of the surface.
165    pub const fn with_viewport(mut self, viewport: LogicalViewportRegion) -> Self {
166        self.viewport = Some(viewport);
167        self
168    }
169
170    /// Intersects all source-local clips with an additional item-local clip.
171    pub const fn with_clip(mut self, clip: ScreenClipRect) -> Self {
172        self.clip = Some(clip);
173        self
174    }
175
176    /// Returns the stable ordering key. Lower values draw first.
177    pub const fn order(self) -> i32 {
178        self.order
179    }
180
181    /// Returns the optional positioned logical viewport.
182    pub const fn viewport(self) -> Option<LogicalViewportRegion> {
183        self.viewport
184    }
185
186    /// Returns the optional item-local logical clip.
187    pub const fn clip(self) -> Option<ScreenClipRect> {
188        self.clip
189    }
190}
191
192/// Renderer-owned source category used in structured composer errors.
193#[derive(Debug, Clone, Copy, PartialEq, Eq)]
194pub enum FrameSourceKind {
195    /// Streaming world-space or fixed-screen scene tessellated for this frame.
196    StreamingScene,
197    /// Immutable prepared world or screen geometry.
198    PreparedScene,
199    /// Mutable retained triangle geometry.
200    DynamicMesh,
201    /// Instanced retained particle resource.
202    ParticleField,
203    /// Renderer-owned scalar texture.
204    ScalarField,
205    /// Retained sRGB RGBA image or atlas.
206    Image,
207    /// Retained host-shaped glyph atlas and positioned run.
208    Glyph,
209    /// Offscreen color texture.
210    RenderTarget,
211}
212
213/// Ordered frame inputs grouped by their renderer source path.
214#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
215pub struct FrameSourceStatistics {
216    streaming_scenes: usize,
217    prepared_scenes: usize,
218    dynamic_meshes: usize,
219    particle_fields: usize,
220    scalar_fields: usize,
221    images: usize,
222    glyph_runs: usize,
223    render_targets: usize,
224}
225
226impl FrameSourceStatistics {
227    /// Returns streaming world and fixed-screen scenes.
228    pub const fn streaming_scenes(self) -> usize {
229        self.streaming_scenes
230    }
231
232    /// Returns immutable prepared world and fixed-screen scenes.
233    pub const fn prepared_scenes(self) -> usize {
234        self.prepared_scenes
235    }
236
237    /// Returns retained dynamic triangle meshes.
238    pub const fn dynamic_meshes(self) -> usize {
239        self.dynamic_meshes
240    }
241
242    /// Returns retained particle fields.
243    pub const fn particle_fields(self) -> usize {
244        self.particle_fields
245    }
246
247    /// Returns retained scalar fields.
248    pub const fn scalar_fields(self) -> usize {
249        self.scalar_fields
250    }
251
252    /// Returns image, world-image, and atlas-batch sources.
253    pub const fn images(self) -> usize {
254        self.images
255    }
256
257    /// Returns host-shaped glyph runs.
258    pub const fn glyph_runs(self) -> usize {
259        self.glyph_runs
260    }
261
262    /// Returns composed 2D or retained-3D color targets.
263    pub const fn render_targets(self) -> usize {
264        self.render_targets
265    }
266
267    /// Returns all accepted frame sources.
268    pub const fn total(self) -> usize {
269        self.streaming_scenes
270            .saturating_add(self.prepared_scenes)
271            .saturating_add(self.dynamic_meshes)
272            .saturating_add(self.particle_fields)
273            .saturating_add(self.scalar_fields)
274            .saturating_add(self.images)
275            .saturating_add(self.glyph_runs)
276            .saturating_add(self.render_targets)
277    }
278
279    const fn single(source: FrameSourceKind) -> Self {
280        let mut counts = Self {
281            streaming_scenes: 0,
282            prepared_scenes: 0,
283            dynamic_meshes: 0,
284            particle_fields: 0,
285            scalar_fields: 0,
286            images: 0,
287            glyph_runs: 0,
288            render_targets: 0,
289        };
290        match source {
291            FrameSourceKind::StreamingScene => counts.streaming_scenes = 1,
292            FrameSourceKind::PreparedScene => counts.prepared_scenes = 1,
293            FrameSourceKind::DynamicMesh => counts.dynamic_meshes = 1,
294            FrameSourceKind::ParticleField => counts.particle_fields = 1,
295            FrameSourceKind::ScalarField => counts.scalar_fields = 1,
296            FrameSourceKind::Image => counts.images = 1,
297            FrameSourceKind::Glyph => counts.glyph_runs = 1,
298            FrameSourceKind::RenderTarget => counts.render_targets = 1,
299        }
300        counts
301    }
302
303    const fn adding(self, other: Self) -> Self {
304        Self {
305            streaming_scenes: self.streaming_scenes.saturating_add(other.streaming_scenes),
306            prepared_scenes: self.prepared_scenes.saturating_add(other.prepared_scenes),
307            dynamic_meshes: self.dynamic_meshes.saturating_add(other.dynamic_meshes),
308            particle_fields: self.particle_fields.saturating_add(other.particle_fields),
309            scalar_fields: self.scalar_fields.saturating_add(other.scalar_fields),
310            images: self.images.saturating_add(other.images),
311            glyph_runs: self.glyph_runs.saturating_add(other.glyph_runs),
312            render_targets: self.render_targets.saturating_add(other.render_targets),
313        }
314    }
315}
316
317/// Failure while constructing or presenting a heterogeneous frame.
318#[derive(Debug, Clone, Copy, PartialEq)]
319pub enum FrameComposerError {
320    /// The one frame clear color was not normalized linear RGBA.
321    InvalidBackground,
322    /// A target-composition opacity was non-finite or outside `0.0..=1.0`.
323    InvalidOpacity,
324    /// An image tint was not normalized linear RGBA.
325    InvalidTint,
326    /// An atlas source rectangle did not fit its image.
327    InvalidImageRegion,
328    /// A world image rectangle or pseudo-depth was invalid.
329    InvalidWorldImage,
330    /// Scalar endpoints were invalid or their finite subtraction overflowed.
331    InvalidValueRange {
332        /// Lower scalar endpoint supplied by the host.
333        minimum: f32,
334        /// Upper scalar endpoint supplied by the host.
335        maximum: f32,
336    },
337    /// A retained source belongs to another renderer or recovery generation.
338    RendererMismatch {
339        /// Category of the rejected retained source.
340        source: FrameSourceKind,
341    },
342    /// A frame-work limit would be exceeded.
343    BudgetExceeded {
344        /// Work category whose limit was exceeded.
345        resource: FrameBudgetResource,
346        /// Configured upper bound.
347        limit: usize,
348        /// Conservative work after accepting the requested item.
349        actual: usize,
350    },
351    /// CPU storage for frame construction could not be reserved.
352    AllocationFailed {
353        /// Minimum additional bytes requested by the failed reservation.
354        requested_bytes: usize,
355    },
356    /// Validation, surface acquisition, or GPU-capacity work failed.
357    Frame(RendererFrameError),
358}
359
360impl fmt::Display for FrameComposerError {
361    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
362        match self {
363            Self::InvalidBackground => write!(formatter, "frame background must be normalized"),
364            Self::InvalidOpacity => write!(formatter, "frame opacity must be finite and in 0..=1"),
365            Self::InvalidTint => write!(formatter, "frame image tint must be normalized"),
366            Self::InvalidImageRegion => write!(formatter, "frame image region is out of bounds"),
367            Self::InvalidWorldImage => {
368                write!(formatter, "frame world image rectangle or depth is invalid")
369            }
370            Self::InvalidValueRange { minimum, maximum } => {
371                write!(formatter, "invalid frame scalar range {minimum}..{maximum}")
372            }
373            Self::RendererMismatch { source } => {
374                write!(formatter, "frame {source:?} belongs to another renderer")
375            }
376            Self::BudgetExceeded {
377                resource,
378                limit,
379                actual,
380            } => write!(
381                formatter,
382                "frame {resource:?} work exceeds its limit {limit}: {actual}"
383            ),
384            Self::AllocationFailed { requested_bytes } => write!(
385                formatter,
386                "could not reserve {requested_bytes} additional bytes for frame construction"
387            ),
388            Self::Frame(error) => write!(formatter, "frame presentation failed: {error}"),
389        }
390    }
391}
392
393impl Error for FrameComposerError {}
394
395impl From<RendererFrameError> for FrameComposerError {
396    fn from(error: RendererFrameError) -> Self {
397        Self::Frame(error)
398    }
399}
400
401/// Bounded work and retained allocations referenced by one composed frame.
402#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
403pub struct FrameStatistics {
404    pass_count: usize,
405    command_count: usize,
406    vertex_count: usize,
407    streaming_vertex_count: usize,
408    reused_vertex_count: usize,
409    upload_bytes: usize,
410    streaming_upload_bytes: usize,
411    texture_bytes: usize,
412    retained_cpu_bytes: usize,
413    retained_buffer_bytes: usize,
414    draw_calls: usize,
415    source_counts: FrameSourceStatistics,
416}
417
418impl FrameStatistics {
419    /// Returns ordered source count.
420    pub const fn pass_count(self) -> usize {
421        self.pass_count
422    }
423
424    /// Returns referenced scene-command count.
425    pub const fn command_count(self) -> usize {
426        self.command_count
427    }
428
429    /// Returns referenced or generated vertex count.
430    pub const fn vertex_count(self) -> usize {
431        self.vertex_count
432    }
433
434    /// Returns streaming vertices selected by draws during this frame.
435    /// Repeated references may share one within-frame upload; use
436    /// [`Self::streaming_upload_bytes`] for the actual transferred payload.
437    pub const fn streaming_vertex_count(self) -> usize {
438        self.streaming_vertex_count
439    }
440
441    /// Returns retained prepared or dynamic vertices reused without frame upload.
442    pub const fn reused_vertex_count(self) -> usize {
443        self.reused_vertex_count
444    }
445
446    /// Returns bytes uploaded for streaming vertices and per-item uniforms.
447    pub const fn upload_bytes(self) -> usize {
448        self.upload_bytes
449    }
450
451    /// Returns the subset uploaded for streaming geometry or instances.
452    pub const fn streaming_upload_bytes(self) -> usize {
453        self.streaming_upload_bytes
454    }
455
456    /// Returns nominal retained texel-storage bytes referenced by frame items.
457    ///
458    /// Repeated image, scalar-field, and render-target identities are
459    /// deduplicated. Opaque backend alignment, tiling, page allocation, and
460    /// metadata are excluded because wgpu does not expose them. Color-map LUT
461    /// bytes follow the renderer's one-entry cache:
462    /// adjacent equal LUTs share one allocation, while an `A, B, A` sequence
463    /// keeps three views/allocations alive until submission.
464    pub const fn texture_bytes(self) -> usize {
465        self.texture_bytes
466    }
467
468    /// Returns CPU recovery or source bytes held by unique referenced resources.
469    ///
470    /// Drawing the same scene, buffer, image, atlas, or run more than once does
471    /// not multiply this value. Distinct retained resources are summed even when
472    /// their contents happen to be equal.
473    pub const fn retained_cpu_bytes(self) -> usize {
474        self.retained_cpu_bytes
475    }
476
477    /// Returns GPU vertex or instance-buffer bytes held by unique referenced resources.
478    pub const fn retained_buffer_bytes(self) -> usize {
479        self.retained_buffer_bytes
480    }
481
482    /// Returns the conservative number of scheduled draw calls.
483    pub const fn draw_calls(self) -> usize {
484        self.draw_calls
485    }
486
487    /// Returns accepted ordered inputs grouped by renderer source path.
488    pub const fn source_counts(self) -> FrameSourceStatistics {
489        self.source_counts
490    }
491
492    fn adding(self, other: Self) -> Self {
493        Self {
494            pass_count: self.pass_count.saturating_add(other.pass_count),
495            command_count: self.command_count.saturating_add(other.command_count),
496            vertex_count: self.vertex_count.saturating_add(other.vertex_count),
497            streaming_vertex_count: self
498                .streaming_vertex_count
499                .saturating_add(other.streaming_vertex_count),
500            reused_vertex_count: self
501                .reused_vertex_count
502                .saturating_add(other.reused_vertex_count),
503            upload_bytes: self.upload_bytes.saturating_add(other.upload_bytes),
504            streaming_upload_bytes: self
505                .streaming_upload_bytes
506                .saturating_add(other.streaming_upload_bytes),
507            texture_bytes: self.texture_bytes.saturating_add(other.texture_bytes),
508            retained_cpu_bytes: self
509                .retained_cpu_bytes
510                .saturating_add(other.retained_cpu_bytes),
511            retained_buffer_bytes: self
512                .retained_buffer_bytes
513                .saturating_add(other.retained_buffer_bytes),
514            draw_calls: self.draw_calls.saturating_add(other.draw_calls),
515            source_counts: self.source_counts.adding(other.source_counts),
516        }
517    }
518
519    fn without_uploads(mut self) -> Self {
520        self.upload_bytes = 0;
521        self.streaming_upload_bytes = 0;
522        self
523    }
524}
525
526/// Outcome and diagnostics for one composed frame.
527#[derive(Debug, Clone, Copy, PartialEq, Eq)]
528pub struct FrameReport {
529    status: RenderStatus,
530    statistics: FrameStatistics,
531    metrics: RendererFrameMetrics,
532    gpu_timing_id: Option<GpuTimingId>,
533}
534
535impl FrameReport {
536    /// Returns whether the frame was drawn or temporarily skipped.
537    pub const fn status(self) -> RenderStatus {
538        self.status
539    }
540
541    /// Returns bounded work referenced by the frame.
542    pub const fn statistics(self) -> FrameStatistics {
543        self.statistics
544    }
545
546    /// Returns CPU-side timing and tessellation diagnostics.
547    pub const fn metrics(self) -> RendererFrameMetrics {
548        self.metrics
549    }
550
551    /// Correlation key for this submitted pass's optional asynchronous GPU time.
552    /// Skipped frames never reserve a key. `None` also covers disabled/unavailable
553    /// timing or a full diagnostics ring; inspect renderer timing statistics.
554    pub const fn gpu_timing_id(self) -> Option<GpuTimingId> {
555        self.gpu_timing_id
556    }
557
558    /// Returns command encoders submitted by this composed frame.
559    pub const fn command_encoder_count(self) -> usize {
560        match self.status {
561            RenderStatus::Drawn => 1,
562            RenderStatus::Skipped(_) => 0,
563        }
564    }
565
566    /// Returns GPU render passes encoded by this composed frame.
567    pub const fn render_pass_count(self) -> usize {
568        match self.status {
569            RenderStatus::Drawn => 1,
570            RenderStatus::Skipped(_) => 0,
571        }
572    }
573
574    /// Returns queue submissions performed by this composed frame.
575    pub const fn queue_submission_count(self) -> usize {
576        match self.status {
577            RenderStatus::Drawn => 1,
578            RenderStatus::Skipped(_) => 0,
579        }
580    }
581
582    /// Returns surface presents performed by this composed frame.
583    pub const fn surface_present_count(self) -> usize {
584        match self.status {
585            RenderStatus::Drawn => 1,
586            RenderStatus::Skipped(_) => 0,
587        }
588    }
589}
590
591/// One bounded, stably ordered surface frame under construction.
592///
593/// Calling [`FrameComposer::present`] performs all fallible geometry and
594/// ownership validation before acquiring the surface. A successful frame uses
595/// one clear, one command encoder, one queue submission, and one present.
596#[must_use = "a frame composer does no rendering until present is called"]
597pub struct FrameComposer<'frame> {
598    renderer: &'frame mut WgpuRenderer,
599    background: Color,
600    budget: FrameBudget,
601    items: Vec<FrameItem<'frame>>,
602    retained_resources: Vec<RetainedResourceKey>,
603    scalar_luts: Vec<ScalarLutPlan>,
604    scalar_lut_upload_count: usize,
605    scalar_lut_allocation_count: usize,
606    planned: FrameStatistics,
607    next_insertion: usize,
608    cache: FrameCache,
609}
610
611impl Drop for FrameComposer<'_> {
612    fn drop(&mut self) {
613        self.cache.items = cache::recycle_items(std::mem::take(&mut self.items));
614        self.retained_resources.clear();
615        self.scalar_luts.clear();
616        self.cache.retained_resources = std::mem::take(&mut self.retained_resources);
617        self.cache.scalar_luts = std::mem::take(&mut self.scalar_luts);
618        self.cache.finish();
619        self.renderer.frame_cache = std::mem::take(&mut self.cache);
620    }
621}
622
623struct ScalarLutPlan {
624    sort_key: (i32, usize),
625    lut: [u8; COLOR_MAP_LUT_SIZE as usize * 4],
626}
627
628#[derive(Debug, Clone, Copy, PartialEq, Eq)]
629struct RetainedResourceKey {
630    address: usize,
631    class: u8,
632}
633
634#[derive(Debug, Clone, Copy)]
635struct RetainedResourceAccounting {
636    key: RetainedResourceKey,
637    cpu_bytes: usize,
638    buffer_bytes: usize,
639    texture_bytes: usize,
640}
641
642impl RetainedResourceAccounting {
643    const fn new(
644        key: RetainedResourceKey,
645        cpu_bytes: usize,
646        buffer_bytes: usize,
647        texture_bytes: usize,
648    ) -> Self {
649        Self {
650            key,
651            cpu_bytes,
652            buffer_bytes,
653            texture_bytes,
654        }
655    }
656}
657
658fn retained_key<T>(resource: &T, class: u8) -> RetainedResourceKey {
659    RetainedResourceKey {
660        address: std::ptr::from_ref(resource).cast::<()>() as usize,
661        class,
662    }
663}
664
665fn retained_arc_key<T>(resource: &Arc<T>, class: u8) -> RetainedResourceKey {
666    RetainedResourceKey {
667        address: Arc::as_ptr(resource).cast::<()>() as usize,
668        class,
669    }
670}
671
672fn account_new_retained_resources(
673    existing: &[RetainedResourceKey],
674    resources: &[RetainedResourceAccounting],
675    mut work: FrameStatistics,
676) -> (FrameStatistics, usize) {
677    let mut missing = 0usize;
678    for (index, resource) in resources.iter().enumerate() {
679        let already_in_request = resources[..index]
680            .iter()
681            .any(|previous| previous.key == resource.key);
682        if !already_in_request && !existing.contains(&resource.key) {
683            missing = missing.saturating_add(1);
684            work.retained_cpu_bytes = work.retained_cpu_bytes.saturating_add(resource.cpu_bytes);
685            work.retained_buffer_bytes = work
686                .retained_buffer_bytes
687                .saturating_add(resource.buffer_bytes);
688            work.texture_bytes = work.texture_bytes.saturating_add(resource.texture_bytes);
689        }
690    }
691    (work, missing)
692}
693
694fn scalar_lut_counts_with_inserted(
695    planned: &[ScalarLutPlan],
696    insertion: usize,
697    inserted: &[u8; COLOR_MAP_LUT_SIZE as usize * 4],
698    initial_cache: Option<&[u8; COLOR_MAP_LUT_SIZE as usize * 4]>,
699) -> (usize, usize) {
700    debug_assert!(insertion <= planned.len());
701    let mut previous: Option<&[u8; COLOR_MAP_LUT_SIZE as usize * 4]> = None;
702    let mut allocation_count = 0usize;
703    let mut first_matches_initial = false;
704    for merged_index in 0..=planned.len() {
705        let current = if merged_index == insertion {
706            inserted
707        } else {
708            let source_index = merged_index - usize::from(merged_index > insertion);
709            &planned[source_index].lut
710        };
711        if previous.is_none() {
712            first_matches_initial = initial_cache == Some(current);
713        }
714        if previous != Some(current) {
715            allocation_count = allocation_count.saturating_add(1);
716        }
717        previous = Some(current);
718    }
719    let upload_count = allocation_count.saturating_sub(usize::from(first_matches_initial));
720    (upload_count, allocation_count)
721}
722
723enum FrameItem<'frame> {
724    Scene {
725        scene: &'frame Scene,
726        camera: Camera2d,
727        options: FramePassOptions,
728        insertion: usize,
729    },
730    ScreenScene {
731        scene: &'frame ScreenScene,
732        options: FramePassOptions,
733        insertion: usize,
734    },
735    Prepared {
736        scene: &'frame PreparedScene,
737        camera: Camera2d,
738        options: FramePassOptions,
739        insertion: usize,
740    },
741    PreparedScreen {
742        scene: &'frame PreparedScreenScene,
743        options: FramePassOptions,
744        insertion: usize,
745    },
746    ScreenPrimitives {
747        batch: &'frame super::ScreenPrimitiveBatch2d,
748        options: FramePassOptions,
749        insertion: usize,
750    },
751    Dynamic {
752        mesh: &'frame DynamicMesh2d,
753        camera: Camera2d,
754        options: FramePassOptions,
755        insertion: usize,
756    },
757    Particle {
758        field: &'frame mut ParticleField2d,
759        camera: Camera2d,
760        options: FramePassOptions,
761        insertion: usize,
762    },
763    Scalar {
764        texture: &'frame ScalarFieldTexture,
765        color_map: &'frame ColorMap,
766        minimum: f32,
767        maximum: f32,
768        value_extent: f32,
769        sampling: ScalarFieldSampling,
770        options: FramePassOptions,
771        insertion: usize,
772    },
773    Image {
774        image: &'frame Image2d,
775        source: ImageTexelRect,
776        tint: Color,
777        sampling: ImageSampling,
778        options: FramePassOptions,
779        insertion: usize,
780    },
781    WorldImage {
782        image: &'frame Image2d,
783        source: ImageTexelRect,
784        rectangle: Rect,
785        depth: f32,
786        camera: Camera2d,
787        tint: Color,
788        sampling: ImageSampling,
789        options: FramePassOptions,
790        insertion: usize,
791    },
792    ImageBatch {
793        image: &'frame Image2d,
794        batch: &'frame ImageBatch2d,
795        spans: Option<&'frame [GlyphBatchSpan]>,
796        placement: ImageBatchPlacement,
797        sampling: ImageSampling,
798        options: FramePassOptions,
799        insertion: usize,
800    },
801    Target {
802        target: &'frame RenderTarget2d,
803        blend_mode: BlendMode,
804        opacity: f32,
805        options: FramePassOptions,
806        insertion: usize,
807    },
808}
809
810impl FrameItem<'_> {
811    fn sort_key(&self) -> (i32, usize) {
812        match self {
813            Self::Scene {
814                options, insertion, ..
815            }
816            | Self::ScreenScene {
817                options, insertion, ..
818            }
819            | Self::Prepared {
820                options, insertion, ..
821            }
822            | Self::PreparedScreen {
823                options, insertion, ..
824            }
825            | Self::ScreenPrimitives {
826                options, insertion, ..
827            }
828            | Self::Dynamic {
829                options, insertion, ..
830            }
831            | Self::Particle {
832                options, insertion, ..
833            }
834            | Self::Scalar {
835                options, insertion, ..
836            }
837            | Self::Image {
838                options, insertion, ..
839            }
840            | Self::WorldImage {
841                options, insertion, ..
842            }
843            | Self::ImageBatch {
844                options, insertion, ..
845            }
846            | Self::Target {
847                options, insertion, ..
848            } => (options.order(), *insertion),
849        }
850    }
851}
852
853impl WgpuRenderer {
854    /// Begins one bounded heterogeneous frame with a single clear color.
855    pub fn begin_frame(
856        &mut self,
857        background: Color,
858        budget: FrameBudget,
859    ) -> Result<FrameComposer<'_>, FrameComposerError> {
860        if !background.is_normalized() {
861            return Err(FrameComposerError::InvalidBackground);
862        }
863        let mut cache = std::mem::take(&mut self.frame_cache);
864        cache.begin();
865        let items = std::mem::take(&mut cache.items);
866        let retained_resources = std::mem::take(&mut cache.retained_resources);
867        let scalar_luts = std::mem::take(&mut cache.scalar_luts);
868        Ok(FrameComposer {
869            renderer: self,
870            background,
871            budget,
872            items,
873            retained_resources,
874            scalar_luts,
875            scalar_lut_upload_count: 0,
876            scalar_lut_allocation_count: 0,
877            planned: FrameStatistics::default(),
878            next_insertion: 0,
879            cache,
880        })
881    }
882}
883
884#[derive(Debug, Clone, Copy)]
885struct ResolvedViewport {
886    viewport: LogicalViewport,
887    origin: Vec2,
888    scissor: ScissorRect,
889    item_clip: Option<ScissorRect>,
890    item_clipped_out: bool,
891}
892
893enum ReadySource<'frame> {
894    Streaming,
895    Prepared(&'frame wgpu::Buffer),
896    Dynamic(&'frame wgpu::Buffer),
897    ScreenPrimitives(&'frame wgpu::Buffer),
898}
899
900struct ReadyGeometry<'frame> {
901    source: ReadySource<'frame>,
902    vertex_count: usize,
903    batches: Vec<PreparedDrawBatch>,
904    camera_uniform: CameraUniform,
905    viewport: ResolvedViewport,
906}
907
908enum ReadyItem<'frame> {
909    Geometry(ReadyGeometry<'frame>),
910    Particle {
911        field: &'frame mut ParticleField2d,
912        visible_count: usize,
913        pending_statistics: ParticleStatistics,
914        initial_cpu_allocation_bytes: usize,
915        camera_uniform: CameraUniform,
916        viewport: ResolvedViewport,
917    },
918    Scalar {
919        texture: &'frame ScalarFieldTexture,
920        color_map: &'frame ColorMap,
921        uniform: HeatmapUniform,
922        viewport: ResolvedViewport,
923    },
924    Image {
925        image: &'frame Image2d,
926        sampling: ImageSampling,
927        uniform: ImageUniform,
928        viewport: ResolvedViewport,
929    },
930    ImageBatch {
931        image: &'frame Image2d,
932        batch: &'frame ImageBatch2d,
933        spans: Option<&'frame [GlyphBatchSpan]>,
934        sampling: ImageSampling,
935        uniform: ImageUniform,
936        viewport: ResolvedViewport,
937    },
938    Target {
939        target: &'frame RenderTarget2d,
940        blend_mode: BlendMode,
941        uniform: CompositeUniform,
942        viewport: ResolvedViewport,
943    },
944}
945
946#[derive(Clone)]
947struct FrameBinding {
948    _buffer: wgpu::Buffer,
949    bind_group: wgpu::BindGroup,
950}
951
952fn preflight_frame_items(
953    renderer: &WgpuRenderer,
954    target_viewport: LogicalViewport,
955    items: &[FrameItem<'_>],
956    preparation: &mut RendererPreparationMetrics,
957) -> Result<(), FrameComposerError> {
958    for item in items {
959        let retained_image = matches!(
960            item,
961            FrameItem::Image { .. } | FrameItem::WorldImage { .. } | FrameItem::ImageBatch { .. }
962        );
963        let retained_started = Instant::now();
964        match item {
965            FrameItem::Scene {
966                camera, options, ..
967            } => {
968                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
969                CameraUniform::new_in_region(
970                    *camera,
971                    viewport.viewport,
972                    viewport.origin,
973                    target_viewport,
974                )
975                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
976            }
977            FrameItem::ScreenScene { options, .. } => {
978                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
979                let camera = screen_camera(viewport.viewport)
980                    .map_err(|_| RendererFrameError::InvalidGeometryTransform)?;
981                CameraUniform::new_in_region(
982                    camera,
983                    viewport.viewport,
984                    viewport.origin,
985                    target_viewport,
986                )
987                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
988            }
989            FrameItem::ScreenPrimitives { batch, options, .. } => {
990                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
991                primitives::validate(
992                    batch,
993                    viewport,
994                    target_viewport,
995                    renderer.scale_factor as f32,
996                    preparation,
997                )?;
998            }
999            FrameItem::Prepared {
1000                scene,
1001                camera,
1002                options,
1003                ..
1004            } => {
1005                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
1006                let uniform = CameraUniform::new_in_region(
1007                    *camera,
1008                    viewport.viewport,
1009                    viewport.origin,
1010                    target_viewport,
1011                )
1012                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1013                let validation_started = Instant::now();
1014                let safe = geometry_is_safe_for_cached(
1015                    Some(&scene.geometry_validation_cache),
1016                    scene.geometry_extents,
1017                    GeometryValidationSource::Tessellated(&scene.vertices),
1018                    uniform,
1019                );
1020                preparation.geometry_validation += validation_started.elapsed();
1021                if !safe {
1022                    return Err(RendererFrameError::InvalidGeometryTransform.into());
1023                }
1024            }
1025            FrameItem::PreparedScreen { scene, options, .. } => {
1026                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
1027                let camera = screen_camera(viewport.viewport)
1028                    .map_err(|_| RendererFrameError::InvalidGeometryTransform)?;
1029                let uniform = CameraUniform::new_in_region(
1030                    camera,
1031                    viewport.viewport,
1032                    viewport.origin,
1033                    target_viewport,
1034                )
1035                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1036                let validation_started = Instant::now();
1037                let safe = geometry_is_safe_for_cached(
1038                    Some(&scene.scene.geometry_validation_cache),
1039                    scene.scene.geometry_extents,
1040                    GeometryValidationSource::Tessellated(&scene.scene.vertices),
1041                    uniform,
1042                );
1043                preparation.geometry_validation += validation_started.elapsed();
1044                if !safe {
1045                    return Err(RendererFrameError::InvalidGeometryTransform.into());
1046                }
1047            }
1048            FrameItem::Dynamic {
1049                mesh,
1050                camera,
1051                options,
1052                ..
1053            } => {
1054                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
1055                let uniform = CameraUniform::new_in_region(
1056                    *camera,
1057                    viewport.viewport,
1058                    viewport.origin,
1059                    target_viewport,
1060                )
1061                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1062                let validation_started = Instant::now();
1063                let safe = geometry_is_safe_for_cached(
1064                    Some(&mesh.geometry_validation_cache),
1065                    mesh.geometry_extents,
1066                    GeometryValidationSource::Dynamic(&mesh.vertices),
1067                    uniform,
1068                );
1069                preparation.geometry_validation += validation_started.elapsed();
1070                if !safe {
1071                    return Err(RendererFrameError::InvalidGeometryTransform.into());
1072                }
1073            }
1074            FrameItem::Particle {
1075                camera, options, ..
1076            } => {
1077                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
1078                CameraUniform::new(*camera, viewport.viewport)
1079                    .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1080                CameraUniform::new_in_region(
1081                    *camera,
1082                    viewport.viewport,
1083                    viewport.origin,
1084                    target_viewport,
1085                )
1086                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1087            }
1088            FrameItem::Scalar {
1089                texture,
1090                minimum,
1091                maximum,
1092                value_extent,
1093                sampling,
1094                options,
1095                ..
1096            } => {
1097                if !scalar_normalization_is_portable(texture, *minimum, *value_extent) {
1098                    return Err(FrameComposerError::InvalidValueRange {
1099                        minimum: *minimum,
1100                        maximum: *maximum,
1101                    });
1102                }
1103                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
1104                let region = LogicalViewportRegion::new(
1105                    LogicalScreenPosition::from_vec2(viewport.origin),
1106                    viewport.viewport,
1107                )
1108                .map_err(|_| RendererFrameError::InvalidViewport)?;
1109                HeatmapUniform::new(
1110                    *minimum,
1111                    *value_extent,
1112                    texture.width(),
1113                    texture.height(),
1114                    *sampling,
1115                )
1116                .in_region(region, target_viewport)
1117                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1118            }
1119            FrameItem::Image { options, .. } => {
1120                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
1121                let region = LogicalViewportRegion::new(
1122                    LogicalScreenPosition::from_vec2(viewport.origin),
1123                    viewport.viewport,
1124                )
1125                .map_err(|_| RendererFrameError::InvalidViewport)?;
1126                CompositeUniform::in_region(1.0, region, target_viewport)
1127                    .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1128            }
1129            FrameItem::Target {
1130                opacity, options, ..
1131            } => {
1132                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
1133                let region = LogicalViewportRegion::new(
1134                    LogicalScreenPosition::from_vec2(viewport.origin),
1135                    viewport.viewport,
1136                )
1137                .map_err(|_| RendererFrameError::InvalidViewport)?;
1138                CompositeUniform::in_region(*opacity, region, target_viewport)
1139                    .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1140            }
1141            FrameItem::WorldImage {
1142                rectangle,
1143                depth,
1144                camera,
1145                options,
1146                ..
1147            } => {
1148                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
1149                let camera_uniform = CameraUniform::new_in_region(
1150                    *camera,
1151                    viewport.viewport,
1152                    viewport.origin,
1153                    target_viewport,
1154                )
1155                .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1156                let minimum = rectangle.min();
1157                let maximum = rectangle.max();
1158                for world in [
1159                    Vec2::new(minimum.x, maximum.y),
1160                    maximum,
1161                    minimum,
1162                    Vec2::new(maximum.x, minimum.y),
1163                ] {
1164                    let screen = camera_uniform.world_to_screen(world, *depth);
1165                    let clip = Vec2::new(
1166                        screen.x.mul_add(
1167                            camera_uniform.screen_to_clip[0],
1168                            camera_uniform.screen_to_clip[2],
1169                        ),
1170                        screen.y.mul_add(
1171                            camera_uniform.screen_to_clip[1],
1172                            camera_uniform.screen_to_clip[3],
1173                        ),
1174                    );
1175                    if ![clip.x, clip.y].into_iter().all(is_portable_shader_source) {
1176                        return Err(RendererFrameError::InvalidGeometryTransform.into());
1177                    }
1178                }
1179            }
1180            FrameItem::ImageBatch {
1181                batch,
1182                options,
1183                placement,
1184                ..
1185            } => {
1186                let viewport = resolve_viewport(renderer, target_viewport, *options)?;
1187                let uniform = image::batch_uniform(target_viewport, viewport.origin, *placement)?;
1188                if !batch.sprites_are_safe_for_target(
1189                    Vec2::new(uniform.uv_rect[0], uniform.uv_rect[1]),
1190                    uniform.destination,
1191                ) {
1192                    return Err(RendererFrameError::InvalidGeometryTransform.into());
1193                }
1194            }
1195        }
1196        if retained_image {
1197            preparation.retained_draws += retained_started.elapsed();
1198        }
1199    }
1200    Ok(())
1201}
1202
1203#[cfg(test)]
1204fn image_sprites_are_safe_for_target(
1205    sprites: &[ImageSprite2d],
1206    viewport_origin: Vec2,
1207    clip_transform: [f32; 4],
1208) -> bool {
1209    image::sprites_are_safe_for_target(sprites, viewport_origin, clip_transform)
1210}
1211
1212fn set_particle_rendered(items: &mut [ReadyItem<'_>], presented: bool) {
1213    for item in items {
1214        if let ReadyItem::Particle {
1215            field,
1216            visible_count,
1217            pending_statistics,
1218            viewport,
1219            ..
1220        } = item
1221        {
1222            field.statistics = ParticleStatistics {
1223                rendered: if presented && !viewport.item_clipped_out {
1224                    *visible_count
1225                } else {
1226                    0
1227                },
1228                ..*pending_statistics
1229            };
1230        }
1231    }
1232}
1233
1234#[allow(clippy::too_many_arguments)]
1235fn prepare_particle_item<'frame>(
1236    field: &'frame mut ParticleField2d,
1237    camera: Camera2d,
1238    viewport: ResolvedViewport,
1239    target_viewport: LogicalViewport,
1240    ready: &mut Vec<ReadyItem<'frame>>,
1241    statistics: &mut FrameStatistics,
1242) -> Result<(), FrameComposerError> {
1243    let initial_cpu_allocation_bytes = field.cpu_allocation_bytes();
1244    let local_uniform = CameraUniform::new(camera, viewport.viewport)
1245        .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1246    let target_uniform =
1247        CameraUniform::new_in_region(camera, viewport.viewport, viewport.origin, target_viewport)
1248            .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1249    let instance_count = field.instances.len();
1250    let visibility_checked = instance_count.min(field.budget.max_visibility_checks_per_frame);
1251
1252    let (visible_count, selected_count) = if visibility_checked < instance_count {
1253        field.visible_instances.clear();
1254        validate_particle_staging_capacity(&field.visible_instances, visibility_checked)?;
1255        for candidate_index in 0..visibility_checked {
1256            let source_index =
1257                uniformly_sampled_index(candidate_index, instance_count, visibility_checked);
1258            let instance = field.instances[source_index];
1259            if !instance.is_safe_for(target_uniform, target_viewport) {
1260                return Err(RendererFrameError::InvalidGeometryTransform.into());
1261            }
1262            let Some(intersects) =
1263                instance.validated_viewport_intersection(local_uniform, viewport.viewport)
1264            else {
1265                return Err(RendererFrameError::InvalidGeometryTransform.into());
1266            };
1267            if intersects {
1268                field.visible_instances.push(instance);
1269            }
1270        }
1271        let visible_count = field.visible_instances.len();
1272        let selected_count = visible_count.min(field.budget.instance_limit());
1273        if selected_count < visible_count {
1274            let mut visible_index = 0;
1275            field.visible_instances.retain(|_| {
1276                let selected = particle_visible_index_is_selected(
1277                    visible_index,
1278                    visible_count,
1279                    selected_count,
1280                );
1281                visible_index += 1;
1282                selected
1283            });
1284        }
1285        (visible_count, selected_count)
1286    } else {
1287        let visible_count = visible_particle_count_for_frame(
1288            &field.instances,
1289            local_uniform,
1290            target_uniform,
1291            viewport.viewport,
1292            target_viewport,
1293        )?;
1294        let selected_count = visible_count.min(field.budget.instance_limit());
1295        if selected_count == field.instances.len() {
1296            field.visible_instances.clear();
1297        } else {
1298            field.visible_instances.clear();
1299            validate_particle_staging_capacity(&field.visible_instances, selected_count)?;
1300            let mut visible_index = 0;
1301            for instance in field.instances.iter().copied() {
1302                if !instance.intersects_viewport(local_uniform, viewport.viewport) {
1303                    continue;
1304                }
1305                let selected_index = field.visible_instances.len();
1306                if selected_index < selected_count
1307                    && particle_visible_index_is_selected(
1308                        visible_index,
1309                        visible_count,
1310                        selected_count,
1311                    )
1312                {
1313                    field.visible_instances.push(instance);
1314                }
1315                visible_index += 1;
1316            }
1317        }
1318        (visible_count, selected_count)
1319    };
1320    let pending_statistics = particle_statistics_with_budget(
1321        instance_count,
1322        visibility_checked,
1323        visible_count,
1324        selected_count,
1325        0,
1326    );
1327    *statistics = statistics.adding(FrameStatistics {
1328        pass_count: 1,
1329        command_count: usize::from(instance_count > 0),
1330        vertex_count: selected_count.saturating_mul(6),
1331        streaming_vertex_count: selected_count.saturating_mul(6),
1332        reused_vertex_count: 0,
1333        upload_bytes: selected_count
1334            .saturating_mul(std::mem::size_of::<ParticleGpu>())
1335            .saturating_add(std::mem::size_of::<CameraUniform>()),
1336        streaming_upload_bytes: selected_count.saturating_mul(std::mem::size_of::<ParticleGpu>()),
1337        texture_bytes: 0,
1338        retained_cpu_bytes: 0,
1339        retained_buffer_bytes: 0,
1340        draw_calls: usize::from(selected_count > 0),
1341        source_counts: FrameSourceStatistics::default(),
1342    });
1343    ready.push(ReadyItem::Particle {
1344        field,
1345        visible_count: selected_count,
1346        pending_statistics,
1347        initial_cpu_allocation_bytes,
1348        camera_uniform: target_uniform,
1349        viewport,
1350    });
1351    Ok(())
1352}
1353
1354fn visible_particle_count_for_frame(
1355    instances: &[ParticleGpu],
1356    local_camera: CameraUniform,
1357    target_camera: CameraUniform,
1358    viewport: LogicalViewport,
1359    target_viewport: LogicalViewport,
1360) -> Result<usize, RendererFrameError> {
1361    let mut visible = 0;
1362    for instance in instances {
1363        let Some(intersects) = instance.validated_viewport_intersection(local_camera, viewport)
1364        else {
1365            return Err(RendererFrameError::InvalidGeometryTransform);
1366        };
1367        if !instance.is_safe_for(target_camera, target_viewport) {
1368            return Err(RendererFrameError::InvalidGeometryTransform);
1369        }
1370        visible += usize::from(intersects);
1371    }
1372    Ok(visible)
1373}
1374
1375// Keep grown scratch reachable on every structured failure, both for reuse
1376// and for the cache's conservative owned-capacity peak accounting.
1377fn with_streaming_batches(
1378    pool: &mut Vec<Vec<PreparedDrawBatch>>,
1379    prepare: impl FnOnce(&mut Vec<PreparedDrawBatch>) -> Result<(), FrameComposerError>,
1380) -> Result<(), FrameComposerError> {
1381    let mut batches = pool.pop().unwrap_or_default();
1382    let result = prepare(&mut batches);
1383    if batches.capacity() > 0 {
1384        batches.clear();
1385        pool.push(batches);
1386    }
1387    result
1388}
1389
1390#[allow(clippy::too_many_arguments)]
1391fn prepare_streaming_scene<'frame>(
1392    scene: &'frame Scene,
1393    camera: Camera2d,
1394    options: FramePassOptions,
1395    renderer: &WgpuRenderer,
1396    target_viewport: LogicalViewport,
1397    streaming_vertices: &mut Vec<Vertex>,
1398    ready: &mut Vec<ReadyItem<'frame>>,
1399    statistics: &mut FrameStatistics,
1400    aggregate: &mut TessellationStats,
1401    batches: &mut Vec<PreparedDrawBatch>,
1402    proofs: &mut streaming::StreamingSceneProofs<'frame>,
1403) -> Result<(), FrameComposerError> {
1404    let viewport = resolve_viewport(renderer, target_viewport, options)?;
1405    let camera_uniform =
1406        CameraUniform::new_in_region(camera, viewport.viewport, viewport.origin, target_viewport)
1407            .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1408    if !scene_estimate_fits_streaming_device(
1409        scene,
1410        &renderer.device,
1411        streaming_vertices.len(),
1412        renderer.vertex_capacity,
1413    ) {
1414        return Err(RendererFrameError::GeometryCapacityTooLarge.into());
1415    }
1416    proofs.prepare(
1417        scene,
1418        camera_uniform,
1419        viewport,
1420        streaming_vertices,
1421        ready,
1422        statistics,
1423        aggregate,
1424        batches,
1425    )
1426}
1427
1428#[allow(clippy::too_many_arguments)]
1429fn prepare_streaming_scene_resolved<'frame>(
1430    scene: &Scene,
1431    camera_uniform: CameraUniform,
1432    viewport: ResolvedViewport,
1433    streaming_vertices: &mut Vec<Vertex>,
1434    ready: &mut Vec<ReadyItem<'frame>>,
1435    statistics: &mut FrameStatistics,
1436    aggregate: &mut TessellationStats,
1437    batches: &mut Vec<PreparedDrawBatch>,
1438    preparation: &mut RendererPreparationMetrics,
1439) -> Result<(), FrameComposerError> {
1440    let vertex_start = streaming_vertices.len();
1441    let tessellation_started = Instant::now();
1442    let stats =
1443        tessellate_scene(scene, streaming_vertices, batches).map_err(RendererFrameError::from)?;
1444    preparation.tessellation += tessellation_started.elapsed();
1445    let validation_started = Instant::now();
1446    let vertices = &streaming_vertices[vertex_start..];
1447    let extents = GeometryExtents::from_vertices(vertices);
1448    if !geometry_is_safe_for(
1449        extents,
1450        GeometryValidationSource::Tessellated(vertices),
1451        camera_uniform,
1452    ) {
1453        streaming_vertices.truncate(vertex_start);
1454        return Err(RendererFrameError::InvalidGeometryTransform.into());
1455    }
1456    preparation.geometry_validation += validation_started.elapsed();
1457    *statistics = statistics.adding(FrameStatistics {
1458        pass_count: 1,
1459        command_count: scene.command_count(),
1460        vertex_count: stats.vertex_count,
1461        streaming_vertex_count: stats.vertex_count,
1462        reused_vertex_count: 0,
1463        upload_bytes: stats
1464            .upload_bytes
1465            .saturating_add(std::mem::size_of::<CameraUniform>()),
1466        streaming_upload_bytes: stats.upload_bytes,
1467        texture_bytes: 0,
1468        retained_cpu_bytes: 0,
1469        retained_buffer_bytes: 0,
1470        draw_calls: batches.len(),
1471        source_counts: FrameSourceStatistics::default(),
1472    });
1473    add_tessellation_stats(aggregate, stats);
1474    ready.push(ReadyItem::Geometry(ReadyGeometry {
1475        source: ReadySource::Streaming,
1476        vertex_count: vertices.len(),
1477        batches: std::mem::take(batches),
1478        camera_uniform,
1479        viewport,
1480    }));
1481    Ok(())
1482}
1483
1484#[allow(clippy::too_many_arguments)]
1485fn prepare_retained_geometry<'frame>(
1486    source: ReadySource<'frame>,
1487    vertex_count: usize,
1488    extents: GeometryExtents,
1489    geometry_validation: GeometryValidationSource<'_>,
1490    geometry_validation_cache: Option<&GeometryValidationCache>,
1491    batches: &[PreparedDrawBatch],
1492    command_count: usize,
1493    source_stats: TessellationStats,
1494    camera: Camera2d,
1495    viewport: ResolvedViewport,
1496    target_viewport: LogicalViewport,
1497    ready: &mut Vec<ReadyItem<'frame>>,
1498    statistics: &mut FrameStatistics,
1499    aggregate: &mut TessellationStats,
1500    mut owned_batches: Vec<PreparedDrawBatch>,
1501    preparation: &mut RendererPreparationMetrics,
1502) -> Result<(), FrameComposerError> {
1503    let camera_uniform =
1504        CameraUniform::new_in_region(camera, viewport.viewport, viewport.origin, target_viewport)
1505            .ok_or(RendererFrameError::InvalidGeometryTransform)?;
1506    let validation_started = Instant::now();
1507    let geometry_is_safe = geometry_is_safe_for_cached(
1508        geometry_validation_cache,
1509        extents,
1510        geometry_validation,
1511        camera_uniform,
1512    );
1513    preparation.geometry_validation += validation_started.elapsed();
1514    if !geometry_is_safe {
1515        return Err(RendererFrameError::InvalidGeometryTransform.into());
1516    }
1517    owned_batches
1518        .try_reserve(batches.len())
1519        .map_err(|_| FrameComposerError::AllocationFailed {
1520            requested_bytes: batches
1521                .len()
1522                .saturating_mul(std::mem::size_of::<PreparedDrawBatch>()),
1523        })?;
1524    owned_batches.extend_from_slice(batches);
1525    *statistics = statistics.adding(FrameStatistics {
1526        pass_count: 1,
1527        command_count,
1528        vertex_count,
1529        streaming_vertex_count: 0,
1530        reused_vertex_count: vertex_count,
1531        upload_bytes: std::mem::size_of::<CameraUniform>(),
1532        streaming_upload_bytes: 0,
1533        texture_bytes: 0,
1534        retained_cpu_bytes: 0,
1535        retained_buffer_bytes: 0,
1536        draw_calls: owned_batches.len(),
1537        source_counts: FrameSourceStatistics::default(),
1538    });
1539    add_tessellation_stats(aggregate, source_stats);
1540    ready.push(ReadyItem::Geometry(ReadyGeometry {
1541        source,
1542        vertex_count,
1543        batches: owned_batches,
1544        camera_uniform,
1545        viewport,
1546    }));
1547    Ok(())
1548}
1549
1550fn resolve_viewport(
1551    renderer: &WgpuRenderer,
1552    target: LogicalViewport,
1553    options: FramePassOptions,
1554) -> Result<ResolvedViewport, FrameComposerError> {
1555    let (viewport, origin) = match options.viewport() {
1556        Some(region) => (region.viewport(), region.origin().to_vec2()),
1557        None => (target, Vec2::ZERO),
1558    };
1559    let max = origin + viewport.size();
1560    if !origin.is_finite()
1561        || !max.is_finite()
1562        || origin.x < 0.0
1563        || origin.y < 0.0
1564        || max.x > target.width()
1565        || max.y > target.height()
1566    {
1567        return Err(RendererFrameError::InvalidViewport.into());
1568    }
1569    let scissor = logical_viewport_scissor(
1570        origin,
1571        viewport,
1572        renderer.scale_factor as f32,
1573        renderer.config.width,
1574        renderer.config.height,
1575    )
1576    .ok_or(RendererFrameError::InvalidViewport)?;
1577    let (item_clip, item_clipped_out) = match options.clip() {
1578        Some(clip) => {
1579            let resolved = screen_clip_to_scissor(clip, viewport, renderer.scale_factor as f32)
1580                .and_then(|clip| offset_scissor(clip, scissor));
1581            (resolved, resolved.is_none())
1582        }
1583        None => (None, false),
1584    };
1585    Ok(ResolvedViewport {
1586        viewport,
1587        origin,
1588        scissor,
1589        item_clip,
1590        item_clipped_out,
1591    })
1592}
1593
1594fn create_frame_binding(renderer: &mut WgpuRenderer, item: &ReadyItem<'_>) -> FrameBinding {
1595    match item {
1596        ReadyItem::Geometry(geometry) => create_camera_binding(renderer, &geometry.camera_uniform),
1597        ReadyItem::Particle { camera_uniform, .. } => {
1598            create_camera_binding(renderer, camera_uniform)
1599        }
1600        ReadyItem::Scalar {
1601            texture,
1602            color_map,
1603            uniform,
1604            ..
1605        } => {
1606            let color_map_view = renderer.color_map_view(color_map);
1607            let scalar_view = texture
1608                .texture
1609                .create_view(&wgpu::TextureViewDescriptor::default());
1610            let bytes = bytemuck::bytes_of(uniform);
1611            let buffer = renderer.device.create_buffer(&wgpu::BufferDescriptor {
1612                label: Some("sim-engine frame heatmap uniform"),
1613                size: bytes.len() as wgpu::BufferAddress,
1614                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
1615                mapped_at_creation: false,
1616            });
1617            renderer.queue.write_buffer(&buffer, 0, bytes);
1618            let bind_group = renderer
1619                .device
1620                .create_bind_group(&wgpu::BindGroupDescriptor {
1621                    label: Some("sim-engine frame heatmap bind group"),
1622                    layout: &renderer.heatmap_bind_group_layout,
1623                    entries: &[
1624                        wgpu::BindGroupEntry {
1625                            binding: 0,
1626                            resource: wgpu::BindingResource::TextureView(&scalar_view),
1627                        },
1628                        wgpu::BindGroupEntry {
1629                            binding: 1,
1630                            resource: wgpu::BindingResource::TextureView(&color_map_view),
1631                        },
1632                        wgpu::BindGroupEntry {
1633                            binding: 2,
1634                            resource: buffer.as_entire_binding(),
1635                        },
1636                    ],
1637                });
1638            FrameBinding {
1639                _buffer: buffer,
1640                bind_group,
1641            }
1642        }
1643        ReadyItem::Image {
1644            image,
1645            sampling,
1646            uniform,
1647            ..
1648        }
1649        | ReadyItem::ImageBatch {
1650            image,
1651            sampling,
1652            uniform,
1653            ..
1654        } => {
1655            let bytes = bytemuck::bytes_of(uniform);
1656            let buffer = renderer.device.create_buffer(&wgpu::BufferDescriptor {
1657                label: Some("sim-engine frame image uniform"),
1658                size: bytes.len() as wgpu::BufferAddress,
1659                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
1660                mapped_at_creation: false,
1661            });
1662            renderer.queue.write_buffer(&buffer, 0, bytes);
1663            let bind_group = renderer
1664                .device
1665                .create_bind_group(&wgpu::BindGroupDescriptor {
1666                    label: Some("sim-engine frame image bind group"),
1667                    layout: &renderer.image_renderer.bind_group_layout,
1668                    entries: &[
1669                        wgpu::BindGroupEntry {
1670                            binding: 0,
1671                            resource: wgpu::BindingResource::TextureView(&image.view),
1672                        },
1673                        wgpu::BindGroupEntry {
1674                            binding: 1,
1675                            resource: wgpu::BindingResource::Sampler(
1676                                renderer.image_renderer.sampler(*sampling),
1677                            ),
1678                        },
1679                        wgpu::BindGroupEntry {
1680                            binding: 2,
1681                            resource: buffer.as_entire_binding(),
1682                        },
1683                    ],
1684                });
1685            FrameBinding {
1686                _buffer: buffer,
1687                bind_group,
1688            }
1689        }
1690        ReadyItem::Target {
1691            target, uniform, ..
1692        } => {
1693            let bytes = bytemuck::bytes_of(uniform);
1694            let buffer = renderer.device.create_buffer(&wgpu::BufferDescriptor {
1695                label: Some("sim-engine frame composition uniform"),
1696                size: bytes.len() as wgpu::BufferAddress,
1697                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
1698                mapped_at_creation: false,
1699            });
1700            renderer.queue.write_buffer(&buffer, 0, bytes);
1701            let bind_group = renderer
1702                .device
1703                .create_bind_group(&wgpu::BindGroupDescriptor {
1704                    label: Some("sim-engine frame composition bind group"),
1705                    layout: &renderer.composition_pipelines.bind_group_layout,
1706                    entries: &[
1707                        wgpu::BindGroupEntry {
1708                            binding: 0,
1709                            resource: wgpu::BindingResource::TextureView(&target.view),
1710                        },
1711                        wgpu::BindGroupEntry {
1712                            binding: 1,
1713                            resource: buffer.as_entire_binding(),
1714                        },
1715                    ],
1716                });
1717            FrameBinding {
1718                _buffer: buffer,
1719                bind_group,
1720            }
1721        }
1722    }
1723}
1724
1725fn ready_uniform_bytes(item: &ReadyItem<'_>) -> usize {
1726    match item {
1727        ReadyItem::Geometry(_) | ReadyItem::Particle { .. } => std::mem::size_of::<CameraUniform>(),
1728        ReadyItem::Scalar { .. } => std::mem::size_of::<HeatmapUniform>(),
1729        ReadyItem::Image { .. } | ReadyItem::ImageBatch { .. } => {
1730            std::mem::size_of::<ImageUniform>()
1731        }
1732        ReadyItem::Target { .. } => std::mem::size_of::<CompositeUniform>(),
1733    }
1734}
1735
1736fn create_camera_binding(renderer: &WgpuRenderer, uniform: &CameraUniform) -> FrameBinding {
1737    let label = "sim-engine frame camera uniform";
1738    let bytes = bytemuck::bytes_of(uniform);
1739    let buffer = renderer.device.create_buffer(&wgpu::BufferDescriptor {
1740        label: Some(label),
1741        size: bytes.len() as wgpu::BufferAddress,
1742        usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
1743        mapped_at_creation: false,
1744    });
1745    renderer.queue.write_buffer(&buffer, 0, bytes);
1746    let bind_group = renderer
1747        .device
1748        .create_bind_group(&wgpu::BindGroupDescriptor {
1749            label: Some("sim-engine frame camera bind group"),
1750            layout: &renderer.camera_bind_group_layout,
1751            entries: &[wgpu::BindGroupEntry {
1752                binding: 0,
1753                resource: buffer.as_entire_binding(),
1754            }],
1755        });
1756    FrameBinding {
1757        _buffer: buffer,
1758        bind_group,
1759    }
1760}
1761
1762fn effective_scissor(
1763    viewport: ResolvedViewport,
1764    source_clip: Option<ScreenClipRect>,
1765    scale_factor: f32,
1766) -> Option<ScissorRect> {
1767    if viewport.item_clipped_out {
1768        return None;
1769    }
1770    let source = match source_clip {
1771        Some(clip) => screen_clip_to_scissor(clip, viewport.viewport, scale_factor)
1772            .and_then(|clip| offset_scissor(clip, viewport.scissor))?,
1773        None => viewport.scissor,
1774    };
1775    match viewport.item_clip {
1776        Some(item) => intersect_scissors(source, item),
1777        None => Some(source),
1778    }
1779}
1780
1781fn intersect_scissors(first: ScissorRect, second: ScissorRect) -> Option<ScissorRect> {
1782    let x = first.x.max(second.x);
1783    let y = first.y.max(second.y);
1784    let max_x = first
1785        .x
1786        .saturating_add(first.width)
1787        .min(second.x.saturating_add(second.width));
1788    let max_y = first
1789        .y
1790        .saturating_add(first.height)
1791        .min(second.y.saturating_add(second.height));
1792    (max_x > x && max_y > y).then_some(ScissorRect {
1793        x,
1794        y,
1795        width: max_x - x,
1796        height: max_y - y,
1797    })
1798}
1799
1800fn validate_frame_budget(
1801    budget: FrameBudget,
1802    statistics: FrameStatistics,
1803) -> Result<(), FrameComposerError> {
1804    let work = [
1805        (
1806            FrameBudgetResource::Passes,
1807            budget.max_passes,
1808            statistics.pass_count,
1809        ),
1810        (
1811            FrameBudgetResource::Commands,
1812            budget.max_commands,
1813            statistics.command_count,
1814        ),
1815        (
1816            FrameBudgetResource::Vertices,
1817            budget.max_vertices,
1818            statistics.vertex_count,
1819        ),
1820        (
1821            FrameBudgetResource::UploadBytes,
1822            budget.max_upload_bytes,
1823            statistics.upload_bytes,
1824        ),
1825        (
1826            FrameBudgetResource::TextureBytes,
1827            budget.max_texture_bytes,
1828            statistics.texture_bytes,
1829        ),
1830        (
1831            FrameBudgetResource::DrawCalls,
1832            budget.max_draw_calls,
1833            statistics.draw_calls,
1834        ),
1835    ];
1836    for (resource, limit, actual) in work {
1837        if actual > limit {
1838            return Err(FrameComposerError::BudgetExceeded {
1839                resource,
1840                limit,
1841                actual,
1842            });
1843        }
1844    }
1845    Ok(())
1846}
1847
1848fn add_tessellation_stats(aggregate: &mut TessellationStats, source: TessellationStats) {
1849    aggregate.command_count = aggregate.command_count.saturating_add(source.command_count);
1850    aggregate.rendered_command_count = aggregate
1851        .rendered_command_count
1852        .saturating_add(source.rendered_command_count);
1853    aggregate.dropped_command_count = aggregate
1854        .dropped_command_count
1855        .saturating_add(source.dropped_command_count);
1856    aggregate.command_counts = aggregate.command_counts.adding(source.command_counts);
1857    aggregate.rendered_counts = aggregate.rendered_counts.adding(source.rendered_counts);
1858    aggregate.dropped_counts = aggregate.dropped_counts.adding(source.dropped_counts);
1859    aggregate.vertex_count = aggregate.vertex_count.saturating_add(source.vertex_count);
1860    aggregate.draw_batch_count = aggregate
1861        .draw_batch_count
1862        .saturating_add(source.draw_batch_count);
1863    aggregate.upload_bytes = aggregate.upload_bytes.saturating_add(source.upload_bytes);
1864}
1865
1866#[allow(clippy::too_many_arguments)]
1867fn frame_report(
1868    status: RenderStatus,
1869    statistics: FrameStatistics,
1870    tessellation: Duration,
1871    upload: Duration,
1872    camera_uniform_upload: Duration,
1873    surface_acquire: Duration,
1874    encode_submit_present: Duration,
1875    total_cpu: Duration,
1876    geometry_reused: bool,
1877    geometry_streamed: bool,
1878    tessellation_stats: TessellationStats,
1879) -> FrameReport {
1880    let report = render_report(
1881        status,
1882        tessellation,
1883        upload,
1884        camera_uniform_upload,
1885        surface_acquire,
1886        encode_submit_present,
1887        total_cpu,
1888        geometry_reused,
1889        geometry_streamed,
1890        tessellation_stats,
1891    );
1892    FrameReport {
1893        status: report.status,
1894        statistics,
1895        metrics: report.metrics,
1896        gpu_timing_id: None,
1897    }
1898}