Skip to main content

aylis_core/
image_cache.rs

1//! O cache de imagens dos renderizadores: o que já foi feito de uma [`Image`] (decodificada,
2//! enviada à placa de vídeo) para não refazer a cada pintura.
3//!
4//! Uma entrada sai quando o app solta a imagem (ninguém mais pede aquele id) ou, passando dos
5//! [limites](ImageCacheLimits), a usada há mais tempo. Os limites valem para o processo todo
6//! e vêm do `image_cache` do `.aylisproj`.
7
8use std::collections::HashMap;
9use std::sync::atomic::{AtomicBool, AtomicU32, AtomicUsize, Ordering};
10use std::sync::{Arc, Mutex, Weak};
11
12use crate::image::{Image, WeakImage};
13
14/// Quanto os renderizadores guardam de imagens prontas que o app ainda segura. Passar do
15/// limite não erra nada na tela: a imagem que sai é refeita (decodificada ou reenviada à
16/// placa) quando aparecer de novo, o que custa tempo de pintura.
17#[derive(Clone, Copy, Debug, PartialEq, Eq)]
18pub struct ImageCacheLimits {
19    /// Megabytes de imagens em pixels (quadros de vídeo, prévias, câmera, os blocos de um
20    /// desenho) guardadas na placa. Precisa caber o que fica na tela ao mesmo tempo; um
21    /// desenho 4K inteiro visível ocupa ~33 MB.
22    pub pixels_mb: u32,
23    /// Quantas imagens de arquivo (PNG, JPEG, SVG...) ficam guardadas, decodificadas e na
24    /// placa. Precisa caber as que aparecem juntas numa tela (ícones, miniaturas, uma galeria).
25    pub files: u32,
26    /// Megabytes das camadas guardadas ([`LayerCache`]): o desenho de um controle com
27    /// `cache_layer`, ou das páginas numa transição, guardado como imagem para andar e
28    /// esmaecer sem repintar os filhos. Precisa caber as que andam juntas (uma transição de
29    /// aba em 4K são duas de ~33 MB). `0`: nenhuma fica guardada (tudo é repintado a cada
30    /// quadro).
31    pub layers_mb: u32,
32}
33
34impl ImageCacheLimits {
35    pub const DEFAULT: Self = Self { pixels_mb: 96, files: 256, layers_mb: 128 };
36    /// Os menores e maiores valores aceitos: abaixo, uma tela comum já refaria imagens a cada
37    /// pintura; acima, o cache poderia tomar a memória da placa.
38    pub const PIXELS_MB_RANGE: (u32, u32) = (8, 4096);
39    pub const FILES_RANGE: (u32, u32) = (16, 65_536);
40    pub const LAYERS_MB_RANGE: (u32, u32) = (0, 4096);
41
42    /// Os limites dentro das faixas aceitas.
43    pub fn clamped(self) -> Self {
44        Self {
45            pixels_mb: self.pixels_mb.clamp(Self::PIXELS_MB_RANGE.0, Self::PIXELS_MB_RANGE.1),
46            files: self.files.clamp(Self::FILES_RANGE.0, Self::FILES_RANGE.1),
47            layers_mb: self.layers_mb.clamp(Self::LAYERS_MB_RANGE.0, Self::LAYERS_MB_RANGE.1),
48        }
49    }
50
51    /// Os bytes de [`layers_mb`](Self::layers_mb).
52    pub fn layers_bytes(self) -> usize {
53        self.layers_mb as usize * (1 << 20)
54    }
55
56    /// Os bytes de [`pixels_mb`](Self::pixels_mb).
57    pub fn pixels_bytes(self) -> usize {
58        self.pixels_mb as usize * (1 << 20)
59    }
60}
61
62impl Default for ImageCacheLimits {
63    fn default() -> Self {
64        Self::DEFAULT
65    }
66}
67
68static PIXELS_MB: AtomicU32 = AtomicU32::new(ImageCacheLimits::DEFAULT.pixels_mb);
69static FILES: AtomicU32 = AtomicU32::new(ImageCacheLimits::DEFAULT.files);
70static LAYERS_MB: AtomicU32 = AtomicU32::new(ImageCacheLimits::DEFAULT.layers_mb);
71static AUTO_LAYERS: AtomicBool = AtomicBool::new(true);
72
73/// Até quantos KB um quadro de câmera ou de vídeo (pixels novos a cada quadro) reaproveita o
74/// bitmap do quadro anterior na placa, em vez de criar outro (o `frame_reuse_kb` do
75/// `image_cache`). Medido em 14/11 no Direct2D (`medicoes/d2d_frames.json`): abaixo de ~1 MB
76/// reaproveitar é mais rápido (36 câmeras de 320 × 180: de 7,3 para 1,7 ms por quadro); acima,
77/// copiar num bitmap grande custa mais que criar outro. `0` desliga.
78pub const DEFAULT_FRAME_REUSE_KB: u32 = 1024;
79/// A faixa aceita de [`frame_reuse_kb`] (até um quadro 4K, ~32 MB).
80pub const FRAME_REUSE_KB_RANGE: (u32, u32) = (0, 32 * 1024);
81
82static FRAME_REUSE_KB: AtomicU32 = AtomicU32::new(DEFAULT_FRAME_REUSE_KB);
83
84/// Veja [`DEFAULT_FRAME_REUSE_KB`].
85pub fn frame_reuse_kb() -> u32 {
86    FRAME_REUSE_KB.load(Ordering::Relaxed)
87}
88
89/// Troca o limite (o projeto faz isso ao abrir); fora da faixa, ajustado.
90pub fn set_frame_reuse_kb(kb: u32) {
91    FRAME_REUSE_KB.store(kb.clamp(FRAME_REUSE_KB_RANGE.0, FRAME_REUSE_KB_RANGE.1), Ordering::Relaxed);
92}
93
94/// O valor da propriedade `frame_reuse_kb` do form como limite próprio: negativo é "o do
95/// projeto" (`None`); fora da faixa, ajustado.
96pub fn form_frame_reuse(value: i64) -> Option<u32> {
97    (value >= 0).then(|| value.min(FRAME_REUSE_KB_RANGE.1 as i64) as u32)
98}
99
100/// O limite que vale numa janela, em três níveis: o forçado no diagnóstico
101/// (`AYLIS_FRAME_REUSE_KB`, só em depuração), o do form (`frame_reuse_kb` ≥ 0) e o do
102/// projeto ([`frame_reuse_kb`], que o `RenderSettings` troca em execução).
103pub fn frame_reuse_limit(forced: Option<u32>, form: Option<u32>) -> u32 {
104    forced.or(form).unwrap_or_else(frame_reuse_kb)
105}
106
107/// Se um quadro de `width × height` (4 bytes por pixel) reaproveita o bitmap do anterior com o
108/// limite `kb`.
109pub fn reuses_frame(width: u32, height: u32, kb: u32) -> bool {
110    kb > 0 && (width as u64) * (height as u64) * 4 <= kb as u64 * 1024
111}
112
113/// Os limites em vigor.
114pub fn limits() -> ImageCacheLimits {
115    ImageCacheLimits { pixels_mb: PIXELS_MB.load(Ordering::Relaxed), files: FILES.load(Ordering::Relaxed), layers_mb: LAYERS_MB.load(Ordering::Relaxed) }
116}
117
118/// Troca os limites (o projeto faz isso ao abrir); valores fora da faixa são ajustados.
119pub fn set_limits(limits: ImageCacheLimits) {
120    let l = limits.clamped();
121    PIXELS_MB.store(l.pixels_mb, Ordering::Relaxed);
122    FILES.store(l.files, Ordering::Relaxed);
123    LAYERS_MB.store(l.layers_mb, Ordering::Relaxed);
124}
125
126/// As camadas automáticas: as páginas numa transição e o contêiner que recorta os filhos com
127/// o lugar ou a transparência animando vão para uma camada guardada sem o app pedir (o
128/// `cache_layer` pedido no controle vale sempre). É o padrão do projeto (`auto_layers` do
129/// `image_cache`); cada form pode trocar pela propriedade `layer_cache` ([`LayerCaching`]).
130pub fn auto_layers() -> bool {
131    AUTO_LAYERS.load(Ordering::Relaxed)
132}
133
134/// Veja [`auto_layers`]; o projeto faz isso ao abrir.
135pub fn set_auto_layers(on: bool) {
136    AUTO_LAYERS.store(on, Ordering::Relaxed);
137}
138
139/// A propriedade `layer_cache` do form: se as camadas automáticas valem nele.
140#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
141pub enum LayerCaching {
142    /// O padrão do projeto ([`auto_layers`]).
143    #[default]
144    Project,
145    On,
146    Off,
147}
148
149impl LayerCaching {
150    pub const ALL: [LayerCaching; 3] = [LayerCaching::Project, LayerCaching::On, LayerCaching::Off];
151
152    /// Ligadas ou não, com o padrão do projeto no lugar de `Project`.
153    pub fn enabled(self) -> bool {
154        match self {
155            LayerCaching::Project => auto_layers(),
156            LayerCaching::On => true,
157            LayerCaching::Off => false,
158        }
159    }
160}
161
162impl crate::prop::PropEnum for LayerCaching {
163    const NAMES: &'static [&'static str] = &["project", "on", "off"];
164
165    fn from_index(index: usize) -> Option<Self> {
166        LayerCaching::ALL.get(index).copied()
167    }
168
169    fn index(self) -> usize {
170        self as usize
171    }
172}
173
174struct Layer<T> {
175    owner: u64,
176    value: T,
177    bytes: usize,
178    used: u64,
179}
180
181/// As camadas guardadas de um renderizador ([`Canvas::begin_cached`](crate::Canvas::begin_cached)),
182/// pela chave completa (a do núcleo com o tamanho e a escala em pixels). Cada uma lembra a
183/// chave que o núcleo passou (`owner`), para o núcleo soltar a de um controle quando ela deixa
184/// de valer ([`forget`](Self::forget)). Passando de [`ImageCacheLimits::layers_mb`], sai a
185/// usada há mais tempo; uma camada maior que o limite inteiro nem é montada
186/// ([`accepts`](Self::accepts)).
187pub struct LayerCache<T> {
188    entries: HashMap<u64, Layer<T>>,
189    clock: u64,
190    bytes: usize,
191    counters: Option<Arc<Counters>>,
192}
193
194impl<T> Default for LayerCache<T> {
195    fn default() -> Self {
196        Self { entries: HashMap::new(), clock: 0, bytes: 0, counters: None }
197    }
198}
199
200impl<T> LayerCache<T> {
201    /// Um cache que aparece no painel de memória ([`stats`]) com este nome.
202    pub fn named(name: &'static str) -> Self {
203        let counters = Arc::new(Counters { name, images: AtomicUsize::new(0), bytes: AtomicUsize::new(0) });
204        REGISTRY.lock().unwrap_or_else(|e| e.into_inner()).push(Arc::downgrade(&counters));
205        Self { counters: Some(counters), ..Self::default() }
206    }
207
208    fn publish(&self) {
209        if let Some(c) = &self.counters {
210            c.images.store(self.entries.len(), Ordering::Relaxed);
211            c.bytes.store(self.bytes, Ordering::Relaxed);
212        }
213    }
214
215    /// Se vale montar uma camada de `bytes`: com o limite em zero, ou menor que ela, não (quem
216    /// chama desenha direto, sem a imagem fora da tela).
217    pub fn accepts(bytes: usize) -> bool {
218        bytes > 0 && bytes <= limits().layers_bytes()
219    }
220
221    /// A camada pela chave completa, marcada como usada agora. Se o limite baixou em execução
222    /// (o `layers_mb` do `RenderSettings`), o excedente sai aqui, as usadas há mais tempo
223    /// primeiro (a pedida também, se não couber: quem chama desenha de novo).
224    pub fn get(&mut self, key: u64) -> Option<&T> {
225        let max = limits().layers_bytes();
226        if self.bytes > max {
227            while self.bytes > max {
228                let Some(oldest) = self.entries.iter().min_by_key(|(_, e)| e.used).map(|(k, _)| *k) else { break };
229                if let Some(e) = self.entries.remove(&oldest) {
230                    self.bytes -= e.bytes;
231                }
232            }
233            self.publish();
234        }
235        self.clock += 1;
236        let clock = self.clock;
237        self.entries.get_mut(&key).map(|e| {
238            e.used = clock;
239            &e.value
240        })
241    }
242
243    /// Guarda a camada; passando do limite, tira as usadas há mais tempo (nunca a que entrou).
244    pub fn insert(&mut self, owner: u64, key: u64, value: T, bytes: usize) {
245        let max = limits().layers_bytes();
246        if bytes > max {
247            return;
248        }
249        self.clock += 1;
250        if let Some(old) = self.entries.insert(key, Layer { owner, value, bytes, used: self.clock }) {
251            self.bytes -= old.bytes;
252        }
253        self.bytes += bytes;
254        while self.bytes > max {
255            let Some(oldest) = self.entries.iter().filter(|(k, _)| **k != key).min_by_key(|(_, e)| e.used).map(|(k, _)| *k) else { break };
256            if let Some(e) = self.entries.remove(&oldest) {
257                self.bytes -= e.bytes;
258            }
259        }
260        self.publish();
261    }
262
263    /// Solta as camadas montadas com a chave `owner` do núcleo (a camada deixou de valer: a
264    /// transição acabou, o desenho de dentro mudou).
265    pub fn forget(&mut self, owner: u64) {
266        let mut freed = 0;
267        self.entries.retain(|_, e| {
268            let keep = e.owner != owner;
269            if !keep {
270                freed += e.bytes;
271            }
272            keep
273        });
274        if freed > 0 {
275            self.bytes -= freed;
276            self.publish();
277        }
278    }
279
280    pub fn clear(&mut self) {
281        self.entries.clear();
282        self.bytes = 0;
283        self.publish();
284    }
285
286    pub fn len(&self) -> usize {
287        self.entries.len()
288    }
289
290    pub fn is_empty(&self) -> bool {
291        self.entries.is_empty()
292    }
293
294    /// A soma dos bytes guardados.
295    pub fn bytes(&self) -> usize {
296        self.bytes
297    }
298}
299
300struct Entry<T> {
301    image: WeakImage,
302    value: T,
303    bytes: usize,
304    used: u64,
305}
306
307/// Quanto um cache com nome guarda agora, para o painel de memória ([`stats`]).
308struct Counters {
309    name: &'static str,
310    images: AtomicUsize,
311    bytes: AtomicUsize,
312}
313
314/// Os contadores dos caches com nome que existem (os que sumiram ficam mortos e saem).
315static REGISTRY: Mutex<Vec<Weak<Counters>>> = Mutex::new(Vec::new());
316
317/// Um cache no painel de memória: o nome, quantas imagens e quantos bytes guarda.
318#[derive(Clone, Debug, PartialEq, Eq)]
319pub struct CacheStat {
320    pub name: &'static str,
321    pub images: usize,
322    pub bytes: usize,
323}
324
325/// O que cada cache com nome guarda agora (os de mesmo nome somados, como os de duas
326/// janelas), na ordem em que apareceram. Para o painel de memória do app em depuração e o
327/// Profiler da IDE.
328pub fn stats() -> Vec<CacheStat> {
329    let mut registry = REGISTRY.lock().unwrap_or_else(|e| e.into_inner());
330    registry.retain(|w| w.strong_count() > 0);
331    let mut out: Vec<CacheStat> = Vec::new();
332    for c in registry.iter().filter_map(Weak::upgrade) {
333        let (images, bytes) = (c.images.load(Ordering::Relaxed), c.bytes.load(Ordering::Relaxed));
334        match out.iter_mut().find(|s| s.name == c.name) {
335            Some(s) => {
336                s.images += images;
337                s.bytes += bytes;
338            }
339            None => out.push(CacheStat { name: c.name, images, bytes }),
340        }
341    }
342    out
343}
344
345/// O que um renderizador fez de cada imagem, pelo [`Image::id`], com a imagem fraca ao lado.
346pub struct ImageCache<T> {
347    entries: HashMap<u64, Entry<T>>,
348    clock: u64,
349    bytes: usize,
350    counters: Option<Arc<Counters>>,
351}
352
353impl<T> Default for ImageCache<T> {
354    fn default() -> Self {
355        Self { entries: HashMap::new(), clock: 0, bytes: 0, counters: None }
356    }
357}
358
359impl<T> ImageCache<T> {
360    /// Um cache que aparece no painel de memória ([`stats`]) com este nome ("Direct2D ·
361    /// pixels na placa").
362    pub fn named(name: &'static str) -> Self {
363        let counters = Arc::new(Counters { name, images: AtomicUsize::new(0), bytes: AtomicUsize::new(0) });
364        REGISTRY.lock().unwrap_or_else(|e| e.into_inner()).push(Arc::downgrade(&counters));
365        Self { counters: Some(counters), ..Self::default() }
366    }
367
368    /// Atualiza os contadores do painel depois de uma mudança.
369    fn publish(&self) {
370        if let Some(c) = &self.counters {
371            c.images.store(self.entries.len(), Ordering::Relaxed);
372            c.bytes.store(self.bytes, Ordering::Relaxed);
373        }
374    }
375
376    /// O valor guardado da imagem, marcado como usado agora.
377    pub fn get(&mut self, image: &Image) -> Option<&T> {
378        self.clock += 1;
379        let clock = self.clock;
380        self.entries.get_mut(&image.id()).map(|e| {
381            e.used = clock;
382            &e.value
383        })
384    }
385
386    /// O valor pelo id, sem marcar uso (quem termina de carregar depois, como o navegador).
387    pub fn get_by_id_mut(&mut self, id: u64) -> Option<&mut T> {
388        self.entries.get_mut(&id).map(|e| &mut e.value)
389    }
390
391    /// Guarda o valor da imagem (`bytes`: quanto ocupa, para o limite em bytes). Antes, solta
392    /// o das imagens mortas; depois, enquanto passar de `max_count` entradas ou `max_bytes`,
393    /// tira a usada há mais tempo (nunca a que acabou de entrar).
394    pub fn insert(&mut self, image: &Image, value: T, bytes: usize, max_count: usize, max_bytes: usize) {
395        self.forget_dropped();
396        self.clock += 1;
397        if let Some(old) = self.entries.insert(image.id(), Entry { image: image.downgrade(), value, bytes, used: self.clock }) {
398            self.bytes -= old.bytes;
399        }
400        self.bytes += bytes;
401        while self.entries.len() > 1 && (self.entries.len() > max_count || self.bytes > max_bytes) {
402            let Some(oldest) = self.entries.iter().filter(|(id, _)| **id != image.id()).min_by_key(|(_, e)| e.used).map(|(id, _)| *id) else { break };
403            if let Some(e) = self.entries.remove(&oldest) {
404                self.bytes -= e.bytes;
405            }
406        }
407        self.publish();
408    }
409
410    /// Como [`forget_dropped`](Self::forget_dropped), devolvendo os valores das imagens
411    /// soltas: o renderizador reaproveita o bitmap de um quadro de câmera no quadro seguinte.
412    pub fn drain_dropped(&mut self) -> Vec<T> {
413        let dead: Vec<u64> = self.entries.iter().filter(|(_, e)| !e.image.is_alive()).map(|(id, _)| *id).collect();
414        let mut out = Vec::with_capacity(dead.len());
415        for id in dead {
416            if let Some(e) = self.entries.remove(&id) {
417                self.bytes -= e.bytes;
418                out.push(e.value);
419            }
420        }
421        self.publish();
422        out
423    }
424
425    /// Solta o que é de imagens que o app já soltou.
426    pub fn forget_dropped(&mut self) {
427        let mut freed = 0;
428        self.entries.retain(|_, e| {
429            let alive = e.image.is_alive();
430            if !alive {
431                freed += e.bytes;
432            }
433            alive
434        });
435        self.bytes -= freed;
436        self.publish();
437    }
438
439    pub fn clear(&mut self) {
440        self.entries.clear();
441        self.bytes = 0;
442        self.publish();
443    }
444
445    pub fn len(&self) -> usize {
446        self.entries.len()
447    }
448
449    pub fn is_empty(&self) -> bool {
450        self.entries.is_empty()
451    }
452
453    /// A soma dos `bytes` guardados.
454    pub fn bytes(&self) -> usize {
455        self.bytes
456    }
457}
458
459#[cfg(test)]
460mod tests {
461    use super::*;
462
463    /// O quadro solto sai com o valor (o bitmap que o renderizador reaproveita), e o vivo fica.
464    #[test]
465    fn the_dropped_frames_come_back_with_their_values() {
466        let mut cache: ImageCache<&str> = ImageCache::default();
467        let alive = Image::bgra(2, 2, vec![0; 16]);
468        let dropped = Image::bgra(2, 2, vec![1; 16]);
469        cache.insert(&alive, "vivo", 16, usize::MAX, usize::MAX);
470        cache.insert(&dropped, "solto", 16, usize::MAX, usize::MAX);
471        drop(dropped);
472        assert_eq!(cache.drain_dropped(), vec!["solto"]);
473        assert_eq!((cache.len(), cache.bytes()), (1, 16));
474        assert!(cache.drain_dropped().is_empty());
475        assert_eq!(cache.get(&alive), Some(&"vivo"));
476    }
477}