Skip to main content

sim_engine/renderer/frame/
cache.rs

1use super::*;
2
3#[cfg(test)]
4#[path = "cache_diagnostics.rs"]
5mod diagnostics;
6#[cfg(test)]
7#[path = "cache_sharing_tests.rs"]
8mod sharing_tests;
9#[cfg(test)]
10pub(in crate::renderer) use sharing_tests::assert_gpu_binding_sharing_contract;
11
12/// Idle retention limits for composition scratch and cached draw bindings.
13///
14/// Active work remains bounded by `FrameBudget`. When a frame exceeds these
15/// cache limits it still renders, but excess storage is released afterwards.
16/// Zero limits disable retention. Driver allocations and in-flight retirement
17/// are outside these library-owned byte counts.
18#[derive(Debug, Clone, Copy, PartialEq, Eq)]
19pub struct FrameCacheBudget {
20    max_cpu_bytes: usize,
21    max_uniform_bytes: usize,
22    max_texture_bytes: usize,
23    max_bindings: usize,
24    max_upload_staging_bytes: usize,
25}
26
27impl FrameCacheBudget {
28    /// Creates exact retention limits with packed uploads disabled. Zero is a
29    /// valid disabled cache; use `with_upload_staging_bytes` to opt into packing.
30    pub const fn new(
31        cpu_bytes: usize,
32        uniform_bytes: usize,
33        texture_bytes: usize,
34        bindings: usize,
35    ) -> Self {
36        Self {
37            max_cpu_bytes: cpu_bytes,
38            max_uniform_bytes: uniform_bytes,
39            max_texture_bytes: texture_bytes,
40            max_bindings: bindings,
41            max_upload_staging_bytes: 0,
42        }
43    }
44    /// Maximum idle CPU scratch, slot metadata and saved uniform bytes.
45    pub const fn max_cpu_bytes(self) -> usize {
46        self.max_cpu_bytes
47    }
48    /// Maximum retained GPU uniform buffer bytes.
49    pub const fn max_uniform_bytes(self) -> usize {
50        self.max_uniform_bytes
51    }
52    /// Maximum distinct texture bytes kept alive by cached bindings.
53    pub const fn max_texture_bytes(self) -> usize {
54        self.max_texture_bytes
55    }
56    /// Maximum cached per-item binding slots.
57    pub const fn max_bindings(self) -> usize {
58        self.max_bindings
59    }
60    /// Enables bounded packing of changed retained uniforms into one upload.
61    /// The cap limits the retained GPU transfer buffer and CPU payload separately;
62    /// payload and copy-record capacities also count toward `max_cpu_bytes`.
63    /// Zero disables batching. Small/oversized batches keep direct writes, so
64    /// this optional optimization does not change accepted frame budgets.
65    /// `new` disables batching; `default` permits 256 KiB.
66    pub const fn with_upload_staging_bytes(mut self, bytes: usize) -> Self {
67        self.max_upload_staging_bytes = bytes;
68        self
69    }
70    /// Maximum GPU transfer-buffer bytes for packed uniform uploads, separate
71    /// from the uniform-buffer limit. In-flight driver retirement is excluded.
72    pub const fn max_upload_staging_bytes(self) -> usize {
73        self.max_upload_staging_bytes
74    }
75}
76
77impl Default for FrameCacheBudget {
78    fn default() -> Self {
79        Self::new(8 * 1024 * 1024, 1024 * 1024, 256 * 1024 * 1024, 4096)
80            .with_upload_staging_bytes(256 * 1024)
81    }
82}
83
84/// Library-owned retained allocation sizes and the last composition's cache work.
85/// CPU byte counts use actual Vec capacities, uniform and transfer-storage bytes
86/// use buffer sizes, and texture bytes count each cached resource identity once.
87#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
88pub struct FrameCacheStatistics {
89    pub(super) cpu_bytes: usize,
90    pub(super) uniform_bytes: usize,
91    pub(super) texture_bytes: usize,
92    pub(super) binding_count: usize,
93    pub(super) created_buffers: usize,
94    pub(super) created_bind_groups: usize,
95    pub(super) reused_bind_groups: usize,
96    pub(super) shared_bind_groups: usize,
97    pub(super) uploaded_uniform_bytes: usize,
98    pub(super) uniform_upload_calls: usize,
99    pub(super) batched_uniform_copies: usize,
100    pub(super) batched_uniform_bytes: usize,
101    pub(super) upload_staging_bytes: usize,
102    pub(super) peak_upload_staging_bytes: usize,
103    pub(super) created_upload_staging_buffers: usize,
104    pub(super) peak_cpu_bytes: usize,
105    pub(super) peak_uniform_bytes: usize,
106    pub(super) peak_texture_bytes: usize,
107}
108
109impl FrameCacheStatistics {
110    /// Idle retained CPU allocation bytes, including spare capacities.
111    pub const fn cpu_bytes(self) -> usize {
112        self.cpu_bytes
113    }
114    /// Idle retained uniform buffer allocation bytes.
115    pub const fn uniform_bytes(self) -> usize {
116        self.uniform_bytes
117    }
118    /// Distinct nominal texture bytes kept alive by cached bindings.
119    pub const fn texture_bytes(self) -> usize {
120        self.texture_bytes
121    }
122    /// Number of populated reusable binding slots.
123    pub const fn binding_count(self) -> usize {
124        self.binding_count
125    }
126    /// Uniform buffers created by the previous composed frame.
127    pub const fn created_buffers(self) -> usize {
128        self.created_buffers
129    }
130    /// Bind groups created by the previous composed frame.
131    pub const fn created_bind_groups(self) -> usize {
132        self.created_bind_groups
133    }
134    /// Bind groups reused from retained slots or earlier items of this frame.
135    pub const fn reused_bind_groups(self) -> usize {
136        self.reused_bind_groups
137    }
138    /// Subset of reused bind groups shared with an earlier identical draw
139    /// binding in the same frame. Shared aliases are never retained in a second
140    /// mutable uniform slot. The bounded memo may miss older duplicates.
141    pub const fn shared_bind_groups(self) -> usize {
142        self.shared_bind_groups
143    }
144    /// Uniform bytes actually written by the previous composed frame.
145    pub const fn uploaded_uniform_bytes(self) -> usize {
146        self.uploaded_uniform_bytes
147    }
148    /// Actual uniform-payload queue writes, including a packed write as one
149    /// call. Copies from packed storage into uniform buffers are not uploads.
150    pub const fn uniform_upload_calls(self) -> usize {
151        self.uniform_upload_calls
152    }
153    /// GPU-to-GPU copies from packed storage to independent uniform buffers.
154    /// Their bytes are not counted a second time in `uploaded_uniform_bytes`.
155    pub const fn batched_uniform_copies(self) -> usize {
156        self.batched_uniform_copies
157    }
158    /// Additional GPU-to-GPU transfer bytes from packed storage. This is a
159    /// subset of uploaded uniform payload, not a second host upload. Batching
160    /// trades this bounded copy work for fewer queue staging allocations.
161    pub const fn batched_uniform_bytes(self) -> usize {
162        self.batched_uniform_bytes
163    }
164    /// Idle retained GPU transfer-buffer bytes, separate from uniform bytes.
165    pub const fn upload_staging_bytes(self) -> usize {
166        self.upload_staging_bytes
167    }
168    /// Conservative old/new GPU transfer-buffer overlap during the last frame.
169    pub const fn peak_upload_staging_bytes(self) -> usize {
170        self.peak_upload_staging_bytes
171    }
172    /// GPU transfer buffers created by the previous composed frame.
173    pub const fn created_upload_staging_buffers(self) -> usize {
174        self.created_upload_staging_buffers
175    }
176    /// Conservative CPU scratch bound: initial retained bytes plus twice the
177    /// final owned capacities, covering transient old/new Vec growth. This is
178    /// not an allocator high-water measurement and excludes driver staging.
179    pub const fn peak_cpu_bytes(self) -> usize {
180        self.peak_cpu_bytes
181    }
182    /// Conservative peak including buffers replaced during this frame.
183    pub const fn peak_uniform_bytes(self) -> usize {
184        self.peak_uniform_bytes
185    }
186    /// Conservative peak of distinct cached old/new texture references.
187    pub const fn peak_texture_bytes(self) -> usize {
188        self.peak_texture_bytes
189    }
190}
191
192#[derive(Clone)]
193enum BindingKey {
194    Camera,
195    Image {
196        identity: Arc<()>,
197        sampling: ImageSampling,
198        texture_bytes: usize,
199    },
200    Target {
201        identity: Arc<()>,
202        texture_bytes: usize,
203    },
204}
205
206/// Temporary descriptions borrow provenance. Only a new retained slot clones
207/// its identity; a warmed draw must not increment/decrement a shared Arc.
208#[derive(Clone, Copy)]
209enum BindingKeyRef<'a> {
210    Camera,
211    Image {
212        identity: &'a Arc<()>,
213        sampling: ImageSampling,
214        texture_bytes: usize,
215    },
216    Target {
217        identity: &'a Arc<()>,
218        texture_bytes: usize,
219    },
220}
221
222impl<'a> BindingKeyRef<'a> {
223    fn matches(self, other: BindingKeyRef<'_>) -> bool {
224        match (self, other) {
225            (Self::Camera, BindingKeyRef::Camera) => true,
226            (
227                Self::Image {
228                    identity: a,
229                    sampling: sa,
230                    ..
231                },
232                BindingKeyRef::Image {
233                    identity: b,
234                    sampling: sb,
235                    ..
236                },
237            ) => Arc::ptr_eq(a, b) && sa == sb,
238            (Self::Target { identity: a, .. }, BindingKeyRef::Target { identity: b, .. }) => {
239                Arc::ptr_eq(a, b)
240            }
241            _ => false,
242        }
243    }
244
245    fn texture(self) -> Option<(&'a Arc<()>, usize)> {
246        match self {
247            Self::Camera => None,
248            Self::Image {
249                identity,
250                texture_bytes,
251                ..
252            }
253            | Self::Target {
254                identity,
255                texture_bytes,
256            } => Some((identity, texture_bytes)),
257        }
258    }
259
260    fn into_owned(self) -> BindingKey {
261        match self {
262            Self::Camera => BindingKey::Camera,
263            Self::Image {
264                identity,
265                sampling,
266                texture_bytes,
267            } => BindingKey::Image {
268                identity: Arc::clone(identity),
269                sampling,
270                texture_bytes,
271            },
272            Self::Target {
273                identity,
274                texture_bytes,
275            } => BindingKey::Target {
276                identity: Arc::clone(identity),
277                texture_bytes,
278            },
279        }
280    }
281}
282
283impl BindingKey {
284    fn as_ref(&self) -> BindingKeyRef<'_> {
285        match self {
286            Self::Camera => BindingKeyRef::Camera,
287            Self::Image {
288                identity,
289                sampling,
290                texture_bytes,
291            } => BindingKeyRef::Image {
292                identity,
293                sampling: *sampling,
294                texture_bytes: *texture_bytes,
295            },
296            Self::Target {
297                identity,
298                texture_bytes,
299            } => BindingKeyRef::Target {
300                identity,
301                texture_bytes: *texture_bytes,
302            },
303        }
304    }
305
306    fn texture(&self) -> Option<(&Arc<()>, usize)> {
307        self.as_ref().texture()
308    }
309    fn matches(&self, other: BindingKeyRef<'_>) -> bool {
310        self.as_ref().matches(other)
311    }
312}
313
314type BindingDescription<'a> = (BindingKeyRef<'a>, &'a [u8]);
315
316#[derive(Clone, Copy)]
317struct SharedBinding<'a> {
318    description: BindingDescription<'a>,
319    index: usize,
320}
321
322/// Fixed stack scratch for one binding-construction loop. It borrows immutable
323/// ready descriptions, never GPU slots or the growing current bindings Vec.
324/// Recording a persistent hit is O(1); only a slot miss searches eight entries.
325#[derive(Default)]
326pub(super) struct FrameBindingSharing<'a> {
327    entries: [Option<SharedBinding<'a>>; 8],
328    next: usize,
329}
330
331impl<'a> FrameBindingSharing<'a> {
332    fn find(&self, (key, bytes): BindingDescription<'_>) -> Option<usize> {
333        self.entries.iter().flatten().find_map(|entry| {
334            (entry.description.0.matches(key) && entry.description.1 == bytes)
335                .then_some(entry.index)
336        })
337    }
338
339    fn remember(&mut self, description: Option<BindingDescription<'a>>, index: usize) {
340        if let Some(description) = description {
341            self.entries[self.next] = Some(SharedBinding { description, index });
342            self.next = (self.next + 1) % self.entries.len();
343        }
344    }
345}
346
347struct CachedBinding {
348    key: BindingKey,
349    binding: FrameBinding,
350    bytes: [u8; std::mem::size_of::<ImageUniform>()],
351    len: usize,
352}
353
354#[derive(Default)]
355pub(in crate::renderer) struct FrameCache {
356    pub(super) items: Vec<FrameItem<'static>>,
357    pub(super) retained_resources: Vec<RetainedResourceKey>,
358    pub(super) scalar_luts: Vec<ScalarLutPlan>,
359    pub(super) ready: Vec<ReadyItem<'static>>,
360    pub(super) bindings: Vec<FrameBinding>,
361    pub(super) batches: Vec<Vec<PreparedDrawBatch>>,
362    slots: Vec<Option<CachedBinding>>,
363    uniform_uploads: uniform_uploads::UniformUploadBatch,
364    budget: FrameCacheBudget,
365    statistics: FrameCacheStatistics,
366    initial_cpu_bytes: usize,
367}
368
369impl FrameCache {
370    pub(super) fn uploaded_uniform_bytes(&self) -> usize {
371        self.statistics.uploaded_uniform_bytes
372    }
373    pub(super) fn begin(&mut self) {
374        self.uniform_uploads.begin();
375        self.initial_cpu_bytes = self.cpu_bytes();
376        self.statistics.created_buffers = 0;
377        self.statistics.created_bind_groups = 0;
378        self.statistics.reused_bind_groups = 0;
379        self.statistics.shared_bind_groups = 0;
380        self.statistics.uploaded_uniform_bytes = 0;
381        self.statistics.uniform_upload_calls = 0;
382        self.statistics.batched_uniform_copies = 0;
383        self.statistics.batched_uniform_bytes = 0;
384        self.statistics.created_upload_staging_buffers = 0;
385        self.statistics.peak_upload_staging_bytes = self.uniform_uploads.allocation_bytes();
386        self.statistics.peak_cpu_bytes = self.initial_cpu_bytes;
387        self.statistics.peak_uniform_bytes = self.statistics.uniform_bytes;
388        self.statistics.peak_texture_bytes = self.statistics.texture_bytes;
389    }
390
391    fn cpu_bytes(&self) -> usize {
392        vec_bytes(&self.items)
393            .saturating_add(vec_bytes(&self.retained_resources))
394            .saturating_add(vec_bytes(&self.scalar_luts))
395            .saturating_add(vec_bytes(&self.ready))
396            .saturating_add(vec_bytes(&self.bindings))
397            .saturating_add(vec_bytes(&self.slots))
398            .saturating_add(vec_bytes(&self.batches))
399            .saturating_add(self.batches.iter().map(vec_bytes).sum::<usize>())
400            .saturating_add(self.uniform_uploads.cpu_bytes())
401    }
402
403    pub(super) fn finish(&mut self) {
404        // No pending references or payload from this presentation may become
405        // next frame's upload, including aborted/skipped frames.
406        self.uniform_uploads.begin();
407        let mut cpu_bytes = self.cpu_bytes();
408        self.statistics.peak_cpu_bytes = self
409            .initial_cpu_bytes
410            .saturating_add(cpu_bytes.saturating_mul(2));
411        if cpu_bytes > self.budget.max_cpu_bytes {
412            self.items = Vec::new();
413            self.retained_resources = Vec::new();
414            self.scalar_luts = Vec::new();
415            self.ready = Vec::new();
416            self.bindings = Vec::new();
417            self.batches = Vec::new();
418            self.uniform_uploads.clear();
419            cpu_bytes = self.cpu_bytes();
420        }
421        if cpu_bytes > self.budget.max_cpu_bytes {
422            self.slots = Vec::new();
423            self.statistics.uniform_bytes = 0;
424            self.statistics.texture_bytes = 0;
425            cpu_bytes = 0;
426        }
427        self.statistics.cpu_bytes = cpu_bytes;
428        self.statistics.upload_staging_bytes = self.uniform_uploads.allocation_bytes();
429        self.statistics.binding_count = self.slots.iter().flatten().count();
430    }
431
432    pub(in crate::renderer) fn clear(&mut self) {
433        let budget = self.budget;
434        *self = Self {
435            budget,
436            ..Self::default()
437        };
438    }
439
440    pub(super) fn reserve_slots(&mut self, count: usize) -> Result<(), FrameComposerError> {
441        let count = count.min(self.budget.max_bindings);
442        if count > self.slots.len() {
443            self.slots
444                .try_reserve_exact(count - self.slots.len())
445                .map_err(|_| FrameComposerError::AllocationFailed {
446                    requested_bytes: count
447                        .saturating_mul(std::mem::size_of::<Option<CachedBinding>>()),
448                })?;
449            self.slots.resize_with(count, || None);
450        }
451        Ok(())
452    }
453
454    pub(super) fn prepare_uniform_uploads(
455        &mut self,
456        ready: &[ReadyItem<'_>],
457        max_buffer_size: u64,
458    ) {
459        let mut size = 0usize;
460        let mut count = 0usize;
461        if self.budget.max_upload_staging_bytes != 0 {
462            for (item, cached) in ready.iter().zip(&self.slots) {
463                if let Some((key, bytes)) = binding_description(item)
464                    && let Some(cached) = cached
465                    && cached.key.matches(key)
466                    && cached.len == bytes.len()
467                    && cached.bytes[..cached.len] != *bytes
468                {
469                    let Some(next) = size.checked_add(bytes.len()) else {
470                        self.uniform_uploads.begin();
471                        return;
472                    };
473                    size = next;
474                    count += 1;
475                }
476            }
477        }
478        // Failure to reserve optional scratch falls back to the proven direct
479        // path. No slot snapshot or GPU contents change during this preflight.
480        self.uniform_uploads.prepare(
481            size,
482            count,
483            self.budget.max_upload_staging_bytes,
484            max_buffer_size,
485        );
486    }
487
488    pub(super) fn flush_uniform_uploads(
489        &mut self,
490        device: &wgpu::Device,
491        queue: &wgpu::Queue,
492        encoder: &mut wgpu::CommandEncoder,
493        bindings: &[FrameBinding],
494    ) {
495        let report = self.uniform_uploads.flush(device, queue, encoder, bindings);
496        self.statistics.created_upload_staging_buffers += report.created_buffers;
497        self.statistics.upload_staging_bytes = report.buffer_bytes;
498        self.statistics.peak_upload_staging_bytes = self
499            .statistics
500            .peak_upload_staging_bytes
501            .max(report.peak_buffer_bytes);
502        self.statistics.batched_uniform_copies += report.copy_count;
503        self.statistics.batched_uniform_bytes += report.uploaded_bytes;
504        self.statistics.uniform_upload_calls += usize::from(report.uploaded_bytes != 0);
505    }
506
507    fn other_owns_texture(&self, slot: usize, identity: &Arc<()>) -> bool {
508        self.slots.iter().enumerate().any(|(index, cached)| {
509            index != slot
510                && cached
511                    .as_ref()
512                    .and_then(|cached| cached.key.texture())
513                    .is_some_and(|(other, _)| Arc::ptr_eq(identity, other))
514        })
515    }
516
517    fn remove_slot(&mut self, index: usize) {
518        if let Some(old) = self.slots[index].take() {
519            self.statistics.uniform_bytes = self
520                .statistics
521                .uniform_bytes
522                .saturating_sub(old.binding._buffer.size() as usize);
523            if let Some((identity, bytes)) = old.key.texture()
524                && !self.other_owns_texture(index, identity)
525            {
526                self.statistics.texture_bytes = self.statistics.texture_bytes.saturating_sub(bytes);
527            }
528        }
529    }
530
531    pub(super) fn binding<'a>(
532        &mut self,
533        renderer: &mut WgpuRenderer,
534        item: &'a ReadyItem<'_>,
535        slot: usize,
536        sharing: &mut FrameBindingSharing<'a>,
537        bindings: &[FrameBinding],
538    ) -> FrameBinding {
539        let description = binding_description(item);
540        if let Some(binding) =
541            self.reuse_binding(&renderer.queue, description, slot, sharing, bindings)
542        {
543            return binding;
544        }
545        let binding = create_frame_binding(renderer, item);
546        self.retain_new_binding(binding, description, slot, sharing)
547    }
548
549    fn reuse_binding<'a>(
550        &mut self,
551        queue: &wgpu::Queue,
552        description: Option<BindingDescription<'a>>,
553        slot: usize,
554        sharing: &mut FrameBindingSharing<'a>,
555        bindings: &[FrameBinding],
556    ) -> Option<FrameBinding> {
557        if let Some((key, bytes)) = &description
558            && let Some(Some(cached)) = self.slots.get_mut(slot)
559            && cached.key.matches(*key)
560            && cached.len == bytes.len()
561        {
562            if &cached.bytes[..cached.len] != *bytes {
563                if !self.uniform_uploads.stage(slot, bytes) {
564                    queue.write_buffer(&cached.binding._buffer, 0, bytes);
565                    self.statistics.uniform_upload_calls += 1;
566                }
567                cached.bytes[..cached.len].copy_from_slice(bytes);
568                self.statistics.uploaded_uniform_bytes += bytes.len();
569            }
570            self.statistics.reused_bind_groups += 1;
571            sharing.remember(description, slot);
572            return Some(cached.binding.clone());
573        }
574        if let Some(description) = description
575            && let Some(index) = sharing.find(description)
576            && let Some(binding) = bindings.get(index)
577        {
578            // Do not publish this clone into `slots[slot]`: a later frame may
579            // write a different uniform into either independent item slot.
580            self.statistics.reused_bind_groups += 1;
581            self.statistics.shared_bind_groups += 1;
582            sharing.remember(Some(description), slot);
583            return Some(binding.clone());
584        }
585        None
586    }
587
588    fn retain_new_binding<'a>(
589        &mut self,
590        binding: FrameBinding,
591        description: Option<BindingDescription<'a>>,
592        slot: usize,
593        sharing: &mut FrameBindingSharing<'a>,
594    ) -> FrameBinding {
595        sharing.remember(description, slot);
596        let uniform_size = binding._buffer.size() as usize;
597        self.statistics.created_buffers += 1;
598        self.statistics.created_bind_groups += 1;
599        self.statistics.uploaded_uniform_bytes += uniform_size;
600        self.statistics.uniform_upload_calls += 1;
601        self.statistics.peak_uniform_bytes = self
602            .statistics
603            .peak_uniform_bytes
604            .saturating_add(uniform_size);
605        let Some((key, bytes)) = description else {
606            return binding;
607        };
608        if slot >= self.slots.len() {
609            return binding;
610        }
611        let new_texture = key.texture().map_or(0, |(identity, size)| {
612            if self.other_owns_texture(slot, identity)
613                || self.slots[slot]
614                    .as_ref()
615                    .and_then(|cached| cached.key.texture())
616                    .is_some_and(|(old, _)| Arc::ptr_eq(identity, old))
617            {
618                0
619            } else {
620                size
621            }
622        });
623        let retained_uniform = self
624            .statistics
625            .uniform_bytes
626            .saturating_sub(
627                self.slots[slot]
628                    .as_ref()
629                    .map_or(0, |old| old.binding._buffer.size() as usize),
630            )
631            .saturating_add(uniform_size);
632        let texture_peak = self.statistics.texture_bytes.saturating_add(new_texture);
633        self.statistics.peak_texture_bytes = self.statistics.peak_texture_bytes.max(texture_peak);
634        if retained_uniform > self.budget.max_uniform_bytes
635            || texture_peak > self.budget.max_texture_bytes
636        {
637            self.remove_slot(slot);
638            return binding;
639        }
640        self.remove_slot(slot);
641        if let Some((identity, size)) = key.texture()
642            && !self.other_owns_texture(slot, identity)
643        {
644            self.statistics.texture_bytes = self.statistics.texture_bytes.saturating_add(size);
645        }
646        self.statistics.uniform_bytes = self.statistics.uniform_bytes.saturating_add(uniform_size);
647        let mut stored = [0; std::mem::size_of::<ImageUniform>()];
648        stored[..bytes.len()].copy_from_slice(bytes);
649        self.slots[slot] = Some(CachedBinding {
650            key: key.into_owned(),
651            binding: binding.clone(),
652            bytes: stored,
653            len: bytes.len(),
654        });
655        binding
656    }
657}
658
659fn binding_description<'a>(item: &'a ReadyItem<'_>) -> Option<(BindingKeyRef<'a>, &'a [u8])> {
660    match item {
661        ReadyItem::Geometry(geometry) => Some((
662            BindingKeyRef::Camera,
663            bytemuck::bytes_of(&geometry.camera_uniform),
664        )),
665        ReadyItem::Particle { camera_uniform, .. } => {
666            Some((BindingKeyRef::Camera, bytemuck::bytes_of(camera_uniform)))
667        }
668        ReadyItem::Image {
669            image,
670            uniform,
671            sampling,
672            ..
673        }
674        | ReadyItem::ImageBatch {
675            image,
676            uniform,
677            sampling,
678            ..
679        } => Some((
680            BindingKeyRef::Image {
681                identity: &image.resource_identity,
682                sampling: *sampling,
683                texture_bytes: image.gpu_allocation_bytes(),
684            },
685            bytemuck::bytes_of(uniform),
686        )),
687        ReadyItem::Target {
688            target, uniform, ..
689        } => Some((
690            BindingKeyRef::Target {
691                identity: &target.resource_identity,
692                texture_bytes: target.allocation_bytes,
693            },
694            bytemuck::bytes_of(uniform),
695        )),
696        ReadyItem::Scalar { .. } => None,
697    }
698}
699
700fn vec_bytes<T>(values: &Vec<T>) -> usize {
701    values.capacity().saturating_mul(std::mem::size_of::<T>())
702}
703
704// The standard library's in-place Vec collection recycles equal-layout storage.
705// Every element is dropped, so no borrowed scene/particle reference survives.
706// Unlike lifetime casts this remains memory-safe if collection ever reallocates.
707#[allow(
708    clippy::unnecessary_filter_map,
709    reason = "filter cannot change the empty Vec's element lifetime"
710)]
711pub(super) fn recycle_items<'source, 'target>(
712    values: Vec<FrameItem<'source>>,
713) -> Vec<FrameItem<'target>> {
714    values
715        .into_iter()
716        .filter_map(|_| None::<FrameItem<'target>>)
717        .collect()
718}
719
720#[cfg(test)]
721#[allow(
722    clippy::unnecessary_filter_map,
723    reason = "filter cannot change the empty Vec's element lifetime"
724)]
725pub(super) fn recycle_ready<'source, 'target>(
726    values: Vec<ReadyItem<'source>>,
727) -> Vec<ReadyItem<'target>> {
728    values
729        .into_iter()
730        .filter_map(|_| None::<ReadyItem<'target>>)
731        .collect()
732}
733
734pub(super) fn recycle_ready_with_batches<'source, 'target>(
735    values: Vec<ReadyItem<'source>>,
736    batches: &mut Vec<Vec<PreparedDrawBatch>>,
737) -> Vec<ReadyItem<'target>> {
738    values
739        .into_iter()
740        .filter_map(|value| {
741            if let ReadyItem::Geometry(mut geometry) = value
742                && batches.len() < batches.capacity()
743            {
744                geometry.batches.clear();
745                batches.push(geometry.batches);
746            }
747            None::<ReadyItem<'target>>
748        })
749        .collect()
750}
751
752impl WgpuRenderer {
753    /// Returns renderer-owned idle composition cache limits.
754    pub fn frame_cache_budget(&self) -> FrameCacheBudget {
755        self.frame_cache.budget
756    }
757    /// Changes limits and releases the old cache. In-flight resource retirement
758    /// is handled by wgpu; the next frame warms storage under the new limits.
759    pub fn set_frame_cache_budget(&mut self, budget: FrameCacheBudget) {
760        self.frame_cache.clear();
761        self.frame_cache.budget = budget;
762    }
763    /// Releases cached composition allocations and GPU resource references.
764    pub fn clear_frame_cache(&mut self) {
765        self.frame_cache.clear();
766    }
767    /// Returns idle retained bytes and the previous composed frame's cache work.
768    /// This does not include queue/backend allocations, source geometry, or LUTs.
769    pub fn frame_cache_statistics(&self) -> FrameCacheStatistics {
770        self.frame_cache.statistics
771    }
772}
773
774#[cfg(test)]
775mod tests {
776    use super::*;
777
778    #[test]
779    fn empty_lifetime_recycling_retains_allocations_and_releases_mutable_borrows() {
780        let scene = Scene::new(Color::BLACK).unwrap();
781        let mut items = Vec::with_capacity(8);
782        items.push(FrameItem::Scene {
783            scene: &scene,
784            camera: Camera2d::default(),
785            options: FramePassOptions::default(),
786            insertion: 0,
787        });
788        let pointer = items.as_ptr().cast::<()>();
789        let recycled: Vec<FrameItem<'static>> = recycle_items(items);
790        assert!(recycled.is_empty());
791        assert_eq!(recycled.capacity(), 8);
792        assert_eq!(recycled.as_ptr().cast::<()>(), pointer);
793        let ready: Vec<ReadyItem<'_>> = Vec::with_capacity(8);
794        let pointer = ready.as_ptr().cast::<()>();
795        let recycled: Vec<ReadyItem<'static>> = recycle_ready(ready);
796        assert_eq!(recycled.capacity(), 8);
797        assert_eq!(recycled.as_ptr().cast::<()>(), pointer);
798    }
799
800    #[test]
801    fn zero_cache_budget_drops_idle_storage() {
802        let mut cache = FrameCache {
803            budget: FrameCacheBudget::new(0, 0, 0, 0),
804            ..FrameCache::default()
805        };
806        cache.items.reserve(4);
807        cache.retained_resources.reserve(4);
808        cache.finish();
809        assert_eq!(cache.statistics.cpu_bytes(), 0);
810        assert!(cache.statistics.peak_cpu_bytes() > 0);
811    }
812
813    #[test]
814    fn late_transform_failure_accounts_grown_batches_before_idle_eviction() {
815        let mut scene = Scene::new(Color::BLACK).unwrap();
816        for index in 0..256 {
817            scene
818                .set_screen_clip(Some(
819                    ScreenClipRect::from_min_size(
820                        LogicalScreenPosition::new((index % 2) as f32, 0.0),
821                        crate::LogicalScreenVector::new(32.0, 32.0),
822                    )
823                    .unwrap(),
824                ))
825                .unwrap();
826            scene
827                .try_line(
828                    Vec2::new(1.0e30, 0.0),
829                    Vec2::new(1.1e30, 0.0),
830                    1.0,
831                    Color::WHITE,
832                )
833                .unwrap();
834        }
835        let viewport = LogicalViewport::new(64.0, 64.0).unwrap();
836        let camera = Camera2d::new(Vec2::ZERO, 1.0e10).unwrap();
837        let uniform = CameraUniform::new(camera, viewport).unwrap();
838        let resolved = ResolvedViewport {
839            viewport,
840            origin: Vec2::ZERO,
841            scissor: ScissorRect {
842                x: 0,
843                y: 0,
844                width: 64,
845                height: 64,
846            },
847            item_clip: None,
848            item_clipped_out: false,
849        };
850        for budget in [
851            FrameCacheBudget::default(),
852            FrameCacheBudget::new(0, 0, 0, 0),
853        ] {
854            let mut cache = FrameCache {
855                budget,
856                ..FrameCache::default()
857            };
858            cache.begin();
859            // Production reserves the outer pool for the complete frame first.
860            cache.batches.try_reserve(1).unwrap();
861            let mut vertices = Vec::new();
862            let mut ready = Vec::new();
863            let mut statistics = FrameStatistics::default();
864            let mut aggregate = TessellationStats::default();
865            let result = with_streaming_batches(&mut cache.batches, |batches| {
866                prepare_streaming_scene_resolved(
867                    &scene,
868                    uniform,
869                    resolved,
870                    &mut vertices,
871                    &mut ready,
872                    &mut statistics,
873                    &mut aggregate,
874                    batches,
875                )
876            });
877            assert_eq!(
878                result,
879                Err(RendererFrameError::InvalidGeometryTransform.into())
880            );
881            assert!(vertices.is_empty() && ready.is_empty());
882            assert_eq!(statistics, FrameStatistics::default());
883            assert_eq!(aggregate, TessellationStats::default());
884            assert_eq!(cache.batches.len(), 1);
885            assert!(cache.batches[0].is_empty());
886            assert!(cache.batches[0].capacity() >= scene.command_count());
887            let owned = cache.cpu_bytes();
888            assert!(owned >= scene.command_count() * std::mem::size_of::<PreparedDrawBatch>());
889            cache.finish();
890            assert!(cache.statistics.peak_cpu_bytes() >= owned * 2);
891            if budget.max_cpu_bytes() == 0 {
892                assert_eq!(cache.statistics.cpu_bytes(), 0);
893                assert!(cache.batches.is_empty());
894            } else {
895                assert_eq!(cache.statistics.cpu_bytes(), owned);
896            }
897        }
898    }
899
900    #[test]
901    fn cache_retention_honors_exact_aggregate_bytes_and_slot_limit() {
902        let mut cache = FrameCache::default();
903        cache.items.reserve(4);
904        cache.retained_resources.reserve(4);
905        let exact_bytes = cache.cpu_bytes();
906        cache.budget = FrameCacheBudget::new(exact_bytes, 0, 0, 0);
907        cache.finish();
908        assert_eq!(cache.statistics.cpu_bytes(), exact_bytes);
909        cache.budget = FrameCacheBudget::new(exact_bytes - 1, 0, 0, 0);
910        cache.finish();
911        assert_eq!(cache.statistics.cpu_bytes(), 0);
912
913        cache.budget = FrameCacheBudget::new(4096, 256, 4096, 2);
914        cache.reserve_slots(3).unwrap();
915        assert_eq!(cache.slots.len(), 2);
916        assert!(cache.slots.iter().all(Option::is_none));
917    }
918
919    #[test]
920    fn bindings_compare_resource_provenance_and_sampling_not_content() {
921        let identity = Arc::new(());
922        let nearest = BindingKey::Image {
923            identity: Arc::clone(&identity),
924            sampling: ImageSampling::Nearest,
925            texture_bytes: 4,
926        };
927        assert!(nearest.matches(nearest.as_ref()));
928        assert!(!nearest.matches(BindingKeyRef::Image {
929            identity: &Arc::new(()),
930            sampling: ImageSampling::Nearest,
931            texture_bytes: 4,
932        }));
933        assert!(!nearest.matches(BindingKeyRef::Image {
934            identity: &identity,
935            sampling: ImageSampling::Linear,
936            texture_bytes: 4,
937        }));
938        assert!(!nearest.matches(BindingKeyRef::Target {
939            identity: &identity,
940            texture_bytes: 4
941        }));
942    }
943
944    #[test]
945    fn geometry_recycling_preserves_batch_and_ready_storage() {
946        let viewport = LogicalViewport::new(32.0, 32.0).unwrap();
947        let mut batches = Vec::with_capacity(4);
948        batches.push(PreparedDrawBatch {
949            vertex_range: 0..3,
950            screen_clip: None,
951        });
952        let batch_pointer = batches.as_ptr();
953        let mut ready = Vec::with_capacity(4);
954        ready.push(ReadyItem::Geometry(ReadyGeometry {
955            source: ReadySource::Streaming,
956            vertex_count: 3,
957            batches,
958            camera_uniform: CameraUniform::new(Camera2d::default(), viewport).unwrap(),
959            viewport: ResolvedViewport {
960                viewport,
961                origin: Vec2::ZERO,
962                scissor: ScissorRect {
963                    x: 0,
964                    y: 0,
965                    width: 32,
966                    height: 32,
967                },
968                item_clip: None,
969                item_clipped_out: false,
970            },
971        }));
972        let ready_pointer = ready.as_ptr().cast::<()>();
973        let mut pool = Vec::with_capacity(1);
974        let reused: Vec<ReadyItem<'static>> = recycle_ready_with_batches(ready, &mut pool);
975        assert!(reused.is_empty());
976        assert_eq!(reused.as_ptr().cast::<()>(), ready_pointer);
977        assert_eq!(pool.len(), 1);
978        assert!(pool[0].is_empty());
979        assert_eq!(pool[0].as_ptr(), batch_pointer);
980    }
981}