Skip to main content

sim_engine/renderer/frame/
compose.rs

1use super::{
2    FrameComposer, FrameComposerError, FrameItem, FramePassOptions, FrameReport, FrameSourceKind,
3    FrameSourceStatistics, FrameStatistics, RetainedResourceAccounting, RetainedResourceKey,
4    ScalarLutPlan, account_new_retained_resources, retained_arc_key, retained_key,
5    scalar_lut_counts_with_inserted, validate_frame_budget,
6};
7use crate::renderer::{
8    BlendMode, COLOR_MAP_LUT_SIZE, Camera2d, CameraUniform, Color, ColorMap, CompositeUniform,
9    DynamicGpu, DynamicMesh2d, GlyphAtlas2d, GlyphBatch2d, GlyphRun2d, HeatmapUniform, Image2d,
10    ImageBatch2d, ImageBatchPlacement, ImageSampling, ImageTexelRect, ImageUniform,
11    ParticleField2d, ParticleGpu, PreparedDrawBatch, PreparedScene, PreparedScreenScene, Rect,
12    RenderTarget2d, ScalarFieldSampling, ScalarFieldTexture, Scene, ScreenScene, Vertex,
13    color_map_lut, prepared_scene_belongs_to, scalar_normalization_is_portable,
14    scalar_value_range_extent,
15};
16
17impl<'frame> FrameComposer<'frame> {
18    /// Adds a streaming world-space scene through its own camera.
19    pub fn draw_scene(
20        &mut self,
21        scene: &'frame Scene,
22        camera: Camera2d,
23        options: FramePassOptions,
24    ) -> Result<(), FrameComposerError> {
25        let statistics = scene.statistics();
26        let work = FrameStatistics {
27            pass_count: 1,
28            command_count: scene.command_count(),
29            vertex_count: statistics.estimated_tessellated_vertices(),
30            streaming_vertex_count: statistics.estimated_tessellated_vertices(),
31            reused_vertex_count: 0,
32            upload_bytes: statistics
33                .estimated_upload_bytes()
34                .saturating_add(std::mem::size_of::<CameraUniform>()),
35            streaming_upload_bytes: statistics.estimated_upload_bytes(),
36            texture_bytes: 0,
37            retained_cpu_bytes: 0,
38            retained_buffer_bytes: 0,
39            draw_calls: statistics.estimated_draw_batches(),
40            source_counts: FrameSourceStatistics::single(FrameSourceKind::StreamingScene),
41        };
42        self.push_accounted_item(
43            &[RetainedResourceAccounting::new(
44                retained_key(scene, 1),
45                scene.allocation_bytes(),
46                0,
47                0,
48            )],
49            work,
50            FrameItem::Scene {
51                scene,
52                camera,
53                options,
54                insertion: self.next_insertion,
55            },
56        )
57    }
58
59    /// Adds a streaming logical-screen scene unaffected by world cameras.
60    pub fn draw_screen_scene(
61        &mut self,
62        scene: &'frame ScreenScene,
63        options: FramePassOptions,
64    ) -> Result<(), FrameComposerError> {
65        let statistics = scene.statistics();
66        let work = FrameStatistics {
67            pass_count: 1,
68            command_count: scene.command_count(),
69            vertex_count: statistics.estimated_tessellated_vertices(),
70            streaming_vertex_count: statistics.estimated_tessellated_vertices(),
71            reused_vertex_count: 0,
72            upload_bytes: statistics
73                .estimated_upload_bytes()
74                .saturating_add(std::mem::size_of::<CameraUniform>()),
75            streaming_upload_bytes: statistics.estimated_upload_bytes(),
76            texture_bytes: 0,
77            retained_cpu_bytes: 0,
78            retained_buffer_bytes: 0,
79            draw_calls: statistics.estimated_draw_batches(),
80            source_counts: FrameSourceStatistics::single(FrameSourceKind::StreamingScene),
81        };
82        self.push_accounted_item(
83            &[RetainedResourceAccounting::new(
84                retained_key(scene, 2),
85                scene.allocation_bytes(),
86                0,
87                0,
88            )],
89            work,
90            FrameItem::ScreenScene {
91                scene,
92                options,
93                insertion: self.next_insertion,
94            },
95        )
96    }
97
98    /// Adds immutable prepared world-space geometry through its own camera.
99    pub fn draw_prepared_scene(
100        &mut self,
101        scene: &'frame PreparedScene,
102        camera: Camera2d,
103        options: FramePassOptions,
104    ) -> Result<(), FrameComposerError> {
105        if !prepared_scene_belongs_to(&self.renderer.renderer_identity, &scene.renderer_identity) {
106            return Err(FrameComposerError::RendererMismatch {
107                source: FrameSourceKind::PreparedScene,
108            });
109        }
110        let work = FrameStatistics {
111            pass_count: 1,
112            command_count: scene.command_count,
113            vertex_count: scene.vertex_count,
114            streaming_vertex_count: 0,
115            reused_vertex_count: scene.vertex_count,
116            upload_bytes: std::mem::size_of::<CameraUniform>(),
117            streaming_upload_bytes: 0,
118            texture_bytes: 0,
119            retained_cpu_bytes: 0,
120            retained_buffer_bytes: 0,
121            draw_calls: scene.draw_batches.len(),
122            source_counts: FrameSourceStatistics::single(FrameSourceKind::PreparedScene),
123        };
124        self.push_accounted_item(
125            &[
126                RetainedResourceAccounting::new(
127                    retained_arc_key(&scene.vertices, 13),
128                    scene
129                        .vertices
130                        .capacity()
131                        .saturating_mul(std::mem::size_of::<Vertex>()),
132                    0,
133                    0,
134                ),
135                RetainedResourceAccounting::new(
136                    retained_arc_key(&scene.vertex_buffer, 3),
137                    0,
138                    scene
139                        .vertex_count
140                        .max(1)
141                        .saturating_mul(std::mem::size_of::<Vertex>()),
142                    0,
143                ),
144                RetainedResourceAccounting::new(
145                    retained_key(&scene.draw_batches, 14),
146                    scene
147                        .draw_batches
148                        .capacity()
149                        .saturating_mul(std::mem::size_of::<PreparedDrawBatch>()),
150                    0,
151                    0,
152                ),
153            ],
154            work,
155            FrameItem::Prepared {
156                scene,
157                camera,
158                options,
159                insertion: self.next_insertion,
160            },
161        )
162    }
163
164    /// Adds immutable prepared logical-screen geometry.
165    pub fn draw_prepared_screen_scene(
166        &mut self,
167        scene: &'frame PreparedScreenScene,
168        options: FramePassOptions,
169    ) -> Result<(), FrameComposerError> {
170        if !prepared_scene_belongs_to(
171            &self.renderer.renderer_identity,
172            &scene.scene.renderer_identity,
173        ) {
174            return Err(FrameComposerError::RendererMismatch {
175                source: FrameSourceKind::PreparedScene,
176            });
177        }
178        let work = FrameStatistics {
179            pass_count: 1,
180            command_count: scene.scene.command_count,
181            vertex_count: scene.scene.vertex_count,
182            streaming_vertex_count: 0,
183            reused_vertex_count: scene.scene.vertex_count,
184            upload_bytes: std::mem::size_of::<CameraUniform>(),
185            streaming_upload_bytes: 0,
186            texture_bytes: 0,
187            retained_cpu_bytes: 0,
188            retained_buffer_bytes: 0,
189            draw_calls: scene.scene.draw_batches.len(),
190            source_counts: FrameSourceStatistics::single(FrameSourceKind::PreparedScene),
191        };
192        self.push_accounted_item(
193            &[
194                RetainedResourceAccounting::new(
195                    retained_arc_key(&scene.scene.vertices, 13),
196                    scene
197                        .scene
198                        .vertices
199                        .capacity()
200                        .saturating_mul(std::mem::size_of::<Vertex>()),
201                    0,
202                    0,
203                ),
204                RetainedResourceAccounting::new(
205                    retained_arc_key(&scene.scene.vertex_buffer, 3),
206                    0,
207                    scene
208                        .scene
209                        .vertex_count
210                        .max(1)
211                        .saturating_mul(std::mem::size_of::<Vertex>()),
212                    0,
213                ),
214                RetainedResourceAccounting::new(
215                    retained_key(&scene.scene.draw_batches, 14),
216                    scene
217                        .scene
218                        .draw_batches
219                        .capacity()
220                        .saturating_mul(std::mem::size_of::<PreparedDrawBatch>()),
221                    0,
222                    0,
223                ),
224            ],
225            work,
226            FrameItem::PreparedScreen {
227                scene,
228                options,
229                insertion: self.next_insertion,
230            },
231        )
232    }
233
234    /// Adds retained dynamic triangles through their own world camera.
235    ///
236    /// Camera-dependent topology is validated by [`FrameComposer::present`],
237    /// which rejects triangles crossing the full target clip volume or having
238    /// an ambiguous projected orientation. Item viewport/scissor clipping is
239    /// axis-aligned fragment clipping and remains supported.
240    pub fn draw_dynamic_mesh(
241        &mut self,
242        mesh: &'frame DynamicMesh2d,
243        camera: Camera2d,
244        options: FramePassOptions,
245    ) -> Result<(), FrameComposerError> {
246        if self.renderer.validate_dynamic_mesh(mesh).is_err() {
247            return Err(FrameComposerError::RendererMismatch {
248                source: FrameSourceKind::DynamicMesh,
249            });
250        }
251        let work = FrameStatistics {
252            pass_count: 1,
253            command_count: usize::from(!mesh.vertices.is_empty()),
254            vertex_count: mesh.vertices.len(),
255            streaming_vertex_count: 0,
256            reused_vertex_count: mesh.vertices.len(),
257            upload_bytes: std::mem::size_of::<CameraUniform>(),
258            streaming_upload_bytes: 0,
259            texture_bytes: 0,
260            retained_cpu_bytes: 0,
261            retained_buffer_bytes: 0,
262            draw_calls: usize::from(!mesh.vertices.is_empty()),
263            source_counts: FrameSourceStatistics::single(FrameSourceKind::DynamicMesh),
264        };
265        self.push_accounted_item(
266            &[RetainedResourceAccounting::new(
267                retained_arc_key(&mesh.vertex_buffer, 4),
268                mesh.recovery_memory_bytes(),
269                mesh.vertex_capacity
270                    .saturating_mul(std::mem::size_of::<DynamicGpu>()),
271                0,
272            )],
273            work,
274            FrameItem::Dynamic {
275                mesh,
276                camera,
277                options,
278                insertion: self.next_insertion,
279            },
280        )
281    }
282
283    /// Adds a budgeted instanced particle field through its own world camera.
284    pub fn draw_particle_field(
285        &mut self,
286        field: &'frame mut ParticleField2d,
287        camera: Camera2d,
288        options: FramePassOptions,
289    ) -> Result<(), FrameComposerError> {
290        if self.renderer.validate_particle_field(field).is_err() {
291            return Err(FrameComposerError::RendererMismatch {
292                source: FrameSourceKind::ParticleField,
293            });
294        }
295        let candidate_count = field
296            .instances
297            .len()
298            .min(field.budget.max_visibility_checks_per_frame)
299            .min(field.budget.instance_limit());
300        self.push_accounted_item(
301            &[RetainedResourceAccounting::new(
302                retained_arc_key(&field.instance_buffer, 5),
303                field.cpu_allocation_bytes(),
304                field.gpu_allocation_bytes(),
305                0,
306            )],
307            FrameStatistics {
308                pass_count: 1,
309                command_count: usize::from(!field.instances.is_empty()),
310                vertex_count: candidate_count.saturating_mul(6),
311                streaming_vertex_count: candidate_count.saturating_mul(6),
312                reused_vertex_count: 0,
313                upload_bytes: candidate_count
314                    .saturating_mul(std::mem::size_of::<ParticleGpu>())
315                    .saturating_add(std::mem::size_of::<CameraUniform>()),
316                streaming_upload_bytes: candidate_count
317                    .saturating_mul(std::mem::size_of::<ParticleGpu>()),
318                texture_bytes: 0,
319                retained_cpu_bytes: 0,
320                retained_buffer_bytes: 0,
321                draw_calls: usize::from(candidate_count > 0),
322                source_counts: FrameSourceStatistics::single(FrameSourceKind::ParticleField),
323            },
324            FrameItem::Particle {
325                field,
326                camera,
327                options,
328                insertion: self.next_insertion,
329            },
330        )
331    }
332
333    /// Adds a retained scalar heatmap scaled into the optional viewport.
334    pub fn draw_scalar_field(
335        &mut self,
336        texture: &'frame ScalarFieldTexture,
337        color_map: &'frame ColorMap,
338        (minimum, maximum): (f32, f32),
339        sampling: ScalarFieldSampling,
340        options: FramePassOptions,
341    ) -> Result<(), FrameComposerError> {
342        if self
343            .renderer
344            .validate_scalar_field_texture(texture)
345            .is_err()
346        {
347            return Err(FrameComposerError::RendererMismatch {
348                source: FrameSourceKind::ScalarField,
349            });
350        }
351        let value_extent = scalar_value_range_extent(minimum, maximum)
352            .ok_or(FrameComposerError::InvalidValueRange { minimum, maximum })?;
353        if !scalar_normalization_is_portable(texture, minimum, value_extent) {
354            return Err(FrameComposerError::InvalidValueRange { minimum, maximum });
355        }
356        let color_map_bytes = COLOR_MAP_LUT_SIZE as usize * 4;
357        let scalar_lut = ScalarLutPlan {
358            sort_key: (options.order(), self.next_insertion),
359            lut: color_map_lut(color_map),
360        };
361        self.scalar_luts
362            .try_reserve(1)
363            .map_err(|_| FrameComposerError::AllocationFailed {
364                requested_bytes: std::mem::size_of::<ScalarLutPlan>(),
365            })?;
366        let insertion = self
367            .scalar_luts
368            .partition_point(|planned| planned.sort_key < scalar_lut.sort_key);
369        let (lut_upload_count, lut_allocation_count) = scalar_lut_counts_with_inserted(
370            &self.scalar_luts,
371            insertion,
372            &scalar_lut.lut,
373            self.renderer
374                .color_map_cache
375                .as_ref()
376                .map(|cached| &cached.lut),
377        );
378        let additional_lut_uploads = lut_upload_count.saturating_sub(self.scalar_lut_upload_count);
379        let additional_lut_allocations =
380            lut_allocation_count.saturating_sub(self.scalar_lut_allocation_count);
381        self.push_accounted_item(
382            &[
383                RetainedResourceAccounting::new(
384                    retained_key(&texture.texture, 6),
385                    texture.recovery_memory_bytes(),
386                    0,
387                    texture.gpu_allocation_bytes(),
388                ),
389                RetainedResourceAccounting::new(
390                    retained_key(color_map, 15),
391                    color_map.allocation_bytes(),
392                    0,
393                    0,
394                ),
395            ],
396            FrameStatistics {
397                pass_count: 1,
398                command_count: 1,
399                vertex_count: 6,
400                streaming_vertex_count: 0,
401                reused_vertex_count: 0,
402                upload_bytes: std::mem::size_of::<HeatmapUniform>()
403                    .saturating_add(additional_lut_uploads.saturating_mul(color_map_bytes)),
404                streaming_upload_bytes: 0,
405                texture_bytes: additional_lut_allocations.saturating_mul(color_map_bytes),
406                retained_cpu_bytes: 0,
407                retained_buffer_bytes: 0,
408                draw_calls: 1,
409                source_counts: FrameSourceStatistics::single(FrameSourceKind::ScalarField),
410            },
411            FrameItem::Scalar {
412                texture,
413                color_map,
414                minimum,
415                maximum,
416                value_extent,
417                sampling,
418                options,
419                insertion: self.next_insertion,
420            },
421        )?;
422        self.scalar_luts.insert(insertion, scalar_lut);
423        self.scalar_lut_upload_count = lut_upload_count;
424        self.scalar_lut_allocation_count = lut_allocation_count;
425        Ok(())
426    }
427
428    /// Adds one image or atlas region scaled into the optional viewport.
429    ///
430    /// With no viewport the image covers the complete logical surface. `tint`
431    /// is normalized straight linear RGBA and multiplies decoded image color.
432    pub fn draw_image(
433        &mut self,
434        image: &'frame Image2d,
435        source: Option<ImageTexelRect>,
436        tint: Color,
437        sampling: ImageSampling,
438        options: FramePassOptions,
439    ) -> Result<(), FrameComposerError> {
440        if self.renderer.validate_image(image).is_err() {
441            return Err(FrameComposerError::RendererMismatch {
442                source: FrameSourceKind::Image,
443            });
444        }
445        if !tint.is_normalized() {
446            return Err(FrameComposerError::InvalidTint);
447        }
448        let source = source.unwrap_or_else(|| image.full_rect());
449        if !source.fits(image.width(), image.height()) {
450            return Err(FrameComposerError::InvalidImageRegion);
451        }
452        self.push_accounted_item(
453            &[RetainedResourceAccounting::new(
454                retained_arc_key(&image.resource_identity, 7),
455                image.recovery_memory_bytes(),
456                0,
457                image.gpu_allocation_bytes(),
458            )],
459            FrameStatistics {
460                pass_count: 1,
461                command_count: 1,
462                vertex_count: 6,
463                streaming_vertex_count: 0,
464                reused_vertex_count: 0,
465                upload_bytes: std::mem::size_of::<ImageUniform>(),
466                streaming_upload_bytes: 0,
467                texture_bytes: 0,
468                retained_cpu_bytes: 0,
469                retained_buffer_bytes: 0,
470                draw_calls: 1,
471                source_counts: FrameSourceStatistics::single(FrameSourceKind::Image),
472            },
473            FrameItem::Image {
474                image,
475                source,
476                tint,
477                sampling,
478                options,
479                insertion: self.next_insertion,
480            },
481        )
482    }
483
484    /// Adds one image or atlas region on an axis-aligned world-space rectangle.
485    ///
486    /// The rectangle follows the supplied camera's zoom, rotation, and
487    /// pseudo-depth projection. Its UV top edge maps to the rectangle's maximum
488    /// world Y edge. The optional frame viewport selects the camera viewport and
489    /// the item remains constrained by that viewport and clip.
490    #[allow(clippy::too_many_arguments)]
491    pub fn draw_world_image(
492        &mut self,
493        image: &'frame Image2d,
494        source: Option<ImageTexelRect>,
495        rectangle: Rect,
496        depth: f32,
497        camera: Camera2d,
498        tint: Color,
499        sampling: ImageSampling,
500        options: FramePassOptions,
501    ) -> Result<(), FrameComposerError> {
502        if self.renderer.validate_image(image).is_err() {
503            return Err(FrameComposerError::RendererMismatch {
504                source: FrameSourceKind::Image,
505            });
506        }
507        if !tint.is_normalized() {
508            return Err(FrameComposerError::InvalidTint);
509        }
510        let source = source.unwrap_or_else(|| image.full_rect());
511        if !source.fits(image.width(), image.height()) {
512            return Err(FrameComposerError::InvalidImageRegion);
513        }
514        let rectangle = rectangle.normalized();
515        if !rectangle.min().is_finite()
516            || !rectangle.max().is_finite()
517            || !rectangle.width().is_finite()
518            || !rectangle.height().is_finite()
519            || rectangle.width() <= 0.0
520            || rectangle.height() <= 0.0
521            || !depth.is_finite()
522        {
523            return Err(FrameComposerError::InvalidWorldImage);
524        }
525        self.push_accounted_item(
526            &[RetainedResourceAccounting::new(
527                retained_arc_key(&image.resource_identity, 7),
528                image.recovery_memory_bytes(),
529                0,
530                image.gpu_allocation_bytes(),
531            )],
532            FrameStatistics {
533                pass_count: 1,
534                command_count: 1,
535                vertex_count: 6,
536                streaming_vertex_count: 0,
537                reused_vertex_count: 0,
538                upload_bytes: std::mem::size_of::<ImageUniform>(),
539                streaming_upload_bytes: 0,
540                texture_bytes: 0,
541                retained_cpu_bytes: 0,
542                retained_buffer_bytes: 0,
543                draw_calls: 1,
544                source_counts: FrameSourceStatistics::single(FrameSourceKind::Image),
545            },
546            FrameItem::WorldImage {
547                image,
548                source,
549                rectangle,
550                depth,
551                camera,
552                tint,
553                sampling,
554                options,
555                insertion: self.next_insertion,
556            },
557        )
558    }
559
560    /// Adds a retained atlas batch as one instanced draw when non-empty.
561    /// Empty batches are valid frame items and emit no draw call.
562    pub fn draw_image_batch(
563        &mut self,
564        image: &'frame Image2d,
565        batch: &'frame ImageBatch2d,
566        sampling: ImageSampling,
567        options: FramePassOptions,
568    ) -> Result<(), FrameComposerError> {
569        self.draw_image_batch_placed(
570            image,
571            batch,
572            ImageBatchPlacement::default(),
573            sampling,
574            options,
575        )
576    }
577
578    /// Draws a retained batch with independent logical translation and tint.
579    /// The pass viewport and clip stay fixed while the content moves; negative
580    /// offsets and partially offscreen content are supported without re-upload.
581    pub fn draw_image_batch_placed(
582        &mut self,
583        image: &'frame Image2d,
584        batch: &'frame ImageBatch2d,
585        placement: ImageBatchPlacement,
586        sampling: ImageSampling,
587        options: FramePassOptions,
588    ) -> Result<(), FrameComposerError> {
589        if self.renderer.validate_image_batch(image, batch).is_err() {
590            return Err(FrameComposerError::RendererMismatch {
591                source: FrameSourceKind::Image,
592            });
593        }
594        self.push_retained_image_batch(
595            image,
596            batch,
597            placement,
598            sampling,
599            options,
600            FrameSourceKind::Image,
601        )
602    }
603
604    /// Adds one host-shaped retained glyph run as one instanced draw when non-empty.
605    ///
606    /// Positions are local logical pixels. Mixed font fallback is represented
607    /// by multiple runs submitted at the same order; stable insertion order is
608    /// preserved between them. An empty run is valid and emits no draw call.
609    pub fn draw_glyph_run(
610        &mut self,
611        atlas: &'frame GlyphAtlas2d,
612        run: &'frame GlyphRun2d,
613        sampling: ImageSampling,
614        options: FramePassOptions,
615    ) -> Result<(), FrameComposerError> {
616        self.draw_glyph_run_placed(
617            atlas,
618            run,
619            ImageBatchPlacement::default(),
620            sampling,
621            options,
622        )
623    }
624
625    /// Draws a shared glyph layout with independent logical translation and tint.
626    /// Glyph bearings and per-glyph tint are preserved; draw tint multiplies them.
627    /// The item clip is not translated. Existing default calls are equivalent
628    /// to zero translation and white tint.
629    pub fn draw_glyph_run_placed(
630        &mut self,
631        atlas: &'frame GlyphAtlas2d,
632        run: &'frame GlyphRun2d,
633        placement: ImageBatchPlacement,
634        sampling: ImageSampling,
635        options: FramePassOptions,
636    ) -> Result<(), FrameComposerError> {
637        if self.renderer.validate_glyph_run(atlas, run).is_err() {
638            return Err(FrameComposerError::RendererMismatch {
639                source: FrameSourceKind::Glyph,
640            });
641        }
642        let image = &atlas.image;
643        let batch = &run.batch;
644        let vertex_count = batch.sprite_count().saturating_mul(6);
645        self.push_accounted_item(
646            &[
647                RetainedResourceAccounting::new(
648                    retained_arc_key(&image.resource_identity, 7),
649                    image.recovery_memory_bytes(),
650                    0,
651                    image.gpu_allocation_bytes(),
652                ),
653                RetainedResourceAccounting::new(
654                    retained_key(atlas, 9),
655                    atlas
656                        .recovery_memory_bytes()
657                        .saturating_sub(image.recovery_memory_bytes()),
658                    0,
659                    0,
660                ),
661                RetainedResourceAccounting::new(
662                    retained_key(run, 10),
663                    run.recovery_memory_bytes(),
664                    run.gpu_allocation_bytes(),
665                    0,
666                ),
667            ],
668            FrameStatistics {
669                pass_count: 1,
670                command_count: usize::from(batch.sprite_count() > 0),
671                vertex_count,
672                streaming_vertex_count: 0,
673                reused_vertex_count: vertex_count,
674                upload_bytes: std::mem::size_of::<ImageUniform>(),
675                streaming_upload_bytes: 0,
676                texture_bytes: 0,
677                retained_cpu_bytes: 0,
678                retained_buffer_bytes: 0,
679                draw_calls: usize::from(batch.sprite_count() > 0),
680                source_counts: FrameSourceStatistics::single(FrameSourceKind::Glyph),
681            },
682            FrameItem::ImageBatch {
683                image,
684                batch,
685                spans: None,
686                placement,
687                sampling,
688                options,
689                insertion: self.next_insertion,
690            },
691        )
692    }
693
694    /// Draws an ordered many-placement glyph snapshot as one frame item.
695    ///
696    /// Adjacent placements with an identical local clip share one instanced draw.
697    /// Different clips produce ordered scissor draws without sorting glyphs. Each
698    /// local clip intersects the frame viewport and item clip. Other frame items
699    /// cannot interleave inside the snapshot; use separate batches for that case.
700    /// Empty snapshots are valid and emit no draw. No text shaping, per-glyph
701    /// upload or source-run lookup occurs during drawing.
702    pub fn draw_glyph_batch(
703        &mut self,
704        atlas: &'frame GlyphAtlas2d,
705        batch: &'frame GlyphBatch2d,
706        sampling: ImageSampling,
707        options: FramePassOptions,
708    ) -> Result<(), FrameComposerError> {
709        if self
710            .renderer
711            .validate_image_batch(&atlas.image, &batch.batch)
712            .is_err()
713        {
714            return Err(FrameComposerError::RendererMismatch {
715                source: FrameSourceKind::Glyph,
716            });
717        }
718        let image = &atlas.image;
719        let vertex_count = batch.glyph_count().saturating_mul(6);
720        self.push_accounted_item(
721            &[
722                RetainedResourceAccounting::new(
723                    retained_arc_key(&image.resource_identity, 7),
724                    image.recovery_memory_bytes(),
725                    0,
726                    image.gpu_allocation_bytes(),
727                ),
728                RetainedResourceAccounting::new(
729                    retained_key(atlas, 9),
730                    atlas
731                        .recovery_memory_bytes()
732                        .saturating_sub(image.recovery_memory_bytes()),
733                    0,
734                    0,
735                ),
736                RetainedResourceAccounting::new(
737                    retained_key(batch, 18),
738                    batch.recovery_memory_bytes(),
739                    batch.gpu_allocation_bytes(),
740                    0,
741                ),
742            ],
743            FrameStatistics {
744                pass_count: 1,
745                command_count: usize::from(batch.glyph_count() > 0),
746                vertex_count,
747                streaming_vertex_count: 0,
748                reused_vertex_count: vertex_count,
749                upload_bytes: std::mem::size_of::<ImageUniform>(),
750                streaming_upload_bytes: 0,
751                texture_bytes: 0,
752                retained_cpu_bytes: 0,
753                retained_buffer_bytes: 0,
754                draw_calls: batch.draw_count(),
755                source_counts: FrameSourceStatistics::single(FrameSourceKind::Glyph),
756            },
757            FrameItem::ImageBatch {
758                image,
759                batch: &batch.batch,
760                spans: Some(&batch.spans),
761                placement: ImageBatchPlacement::default(),
762                sampling,
763                options,
764                insertion: self.next_insertion,
765            },
766        )
767    }
768
769    fn push_retained_image_batch(
770        &mut self,
771        image: &'frame Image2d,
772        batch: &'frame ImageBatch2d,
773        placement: ImageBatchPlacement,
774        sampling: ImageSampling,
775        options: FramePassOptions,
776        source: FrameSourceKind,
777    ) -> Result<(), FrameComposerError> {
778        let vertex_count = batch.sprite_count().saturating_mul(6);
779        self.push_accounted_item(
780            &[
781                RetainedResourceAccounting::new(
782                    retained_arc_key(&image.resource_identity, 7),
783                    image.recovery_memory_bytes(),
784                    0,
785                    image.gpu_allocation_bytes(),
786                ),
787                RetainedResourceAccounting::new(
788                    retained_key(batch, 8),
789                    batch.recovery_memory_bytes(),
790                    batch.gpu_allocation_bytes(),
791                    0,
792                ),
793            ],
794            FrameStatistics {
795                pass_count: 1,
796                command_count: usize::from(batch.sprite_count() > 0),
797                vertex_count,
798                streaming_vertex_count: 0,
799                reused_vertex_count: vertex_count,
800                upload_bytes: std::mem::size_of::<ImageUniform>(),
801                streaming_upload_bytes: 0,
802                texture_bytes: 0,
803                retained_cpu_bytes: 0,
804                retained_buffer_bytes: 0,
805                draw_calls: usize::from(batch.sprite_count() > 0),
806                source_counts: FrameSourceStatistics::single(source),
807            },
808            FrameItem::ImageBatch {
809                image,
810                batch,
811                spans: None,
812                placement,
813                sampling,
814                options,
815                insertion: self.next_insertion,
816            },
817        )
818    }
819
820    /// Adds an offscreen target, scaled into the optional logical viewport.
821    pub fn draw_render_target(
822        &mut self,
823        target: &'frame RenderTarget2d,
824        blend_mode: BlendMode,
825        opacity: f32,
826        options: FramePassOptions,
827    ) -> Result<(), FrameComposerError> {
828        if self.renderer.validate_render_target(target).is_err() {
829            return Err(FrameComposerError::RendererMismatch {
830                source: FrameSourceKind::RenderTarget,
831            });
832        }
833        if !opacity.is_finite() || !(0.0..=1.0).contains(&opacity) {
834            return Err(FrameComposerError::InvalidOpacity);
835        }
836        self.push_accounted_item(
837            &[RetainedResourceAccounting::new(
838                retained_arc_key(&target.resource_identity, 11),
839                0,
840                0,
841                target.allocation_bytes,
842            )],
843            FrameStatistics {
844                pass_count: 1,
845                command_count: 1,
846                vertex_count: 6,
847                streaming_vertex_count: 0,
848                reused_vertex_count: 0,
849                upload_bytes: std::mem::size_of::<CompositeUniform>(),
850                streaming_upload_bytes: 0,
851                texture_bytes: 0,
852                retained_cpu_bytes: 0,
853                retained_buffer_bytes: 0,
854                draw_calls: 1,
855                source_counts: FrameSourceStatistics::single(FrameSourceKind::RenderTarget),
856            },
857            FrameItem::Target {
858                target,
859                blend_mode,
860                opacity,
861                options,
862                insertion: self.next_insertion,
863            },
864        )
865    }
866
867    /// Returns conservative work accepted so far without presenting it.
868    pub const fn planned_statistics(&self) -> FrameStatistics {
869        self.planned
870    }
871
872    /// Validates, orders, encodes, submits, and presents the complete frame.
873    pub fn present(self) -> Result<FrameReport, FrameComposerError> {
874        super::present::present_frame(self)
875    }
876
877    fn push_item(
878        &mut self,
879        work: FrameStatistics,
880        item: FrameItem<'frame>,
881    ) -> Result<(), FrameComposerError> {
882        let planned = self.planned.adding(work);
883        validate_frame_budget(self.budget, planned)?;
884        self.items
885            .try_reserve(1)
886            .map_err(|_| FrameComposerError::AllocationFailed {
887                requested_bytes: std::mem::size_of::<FrameItem<'frame>>(),
888            })?;
889        self.items.push(item);
890        self.planned = planned;
891        self.next_insertion = self.next_insertion.saturating_add(1);
892        Ok(())
893    }
894
895    pub(super) fn push_accounted_item(
896        &mut self,
897        resources: &[RetainedResourceAccounting],
898        mut work: FrameStatistics,
899        item: FrameItem<'frame>,
900    ) -> Result<(), FrameComposerError> {
901        let (accounted_work, missing) =
902            account_new_retained_resources(&self.retained_resources, resources, work);
903        work = accounted_work;
904        self.retained_resources.try_reserve(missing).map_err(|_| {
905            FrameComposerError::AllocationFailed {
906                requested_bytes: missing.saturating_mul(std::mem::size_of::<RetainedResourceKey>()),
907            }
908        })?;
909        self.push_item(work, item)?;
910        for resource in resources {
911            if !self.retained_resources.contains(&resource.key) {
912                self.retained_resources.push(resource.key);
913            }
914        }
915        Ok(())
916    }
917}