anyrender_vello_gpu 0.12.0

vello_gpu (formerly vello_hybrid) backend for anyrender
Documentation
use peniko::{Blob, WeakBlob};
use rustc_hash::FxHashMap;
use vello_common::TextureId;

const UNUSED_IMAGE_BUDGET: u64 = 64 * 1024 * 1024;

#[derive(Debug)]
struct CachedImage {
    blob: WeakBlob<u8>,
    texture_id: TextureId,
    may_have_transparency: bool,
    bytes: u64,
    last_used: u64,
}

/// Persistent image residency shared by successive scene painters.
#[derive(Debug)]
pub struct ImageCache {
    entries: FxHashMap<u64, CachedImage>,
    frame: u64,
    max_image_size: (u16, u16),
}

impl Default for ImageCache {
    fn default() -> Self {
        Self {
            entries: FxHashMap::default(),
            frame: 0,
            max_image_size: vello_common::multi_atlas::AtlasConfig::default().atlas_size,
        }
    }
}

impl ImageCache {
    /// Set the renderer's normalized atlas size before uploading images.
    ///
    /// The cache must be empty; clear it when replacing the renderer.
    pub fn set_max_image_size(&mut self, size: (u16, u16)) {
        assert!(size.0 > 0 && size.1 > 0 && self.entries.is_empty());
        self.max_image_size = size;
    }

    pub(crate) fn fits(&self, width: u32, height: u32) -> bool {
        width <= u32::from(self.max_image_size.0) && height <= u32::from(self.max_image_size.1)
    }
    /// Discard identities when their renderer resources are replaced.
    pub fn clear(&mut self) {
        self.entries.clear();
        self.frame = 0;
    }

    /// Returns the cached image's texture and transparency hint.
    pub(crate) fn get(&mut self, id: u64) -> Option<(TextureId, bool)> {
        let entry = self.entries.get_mut(&id)?;
        entry.last_used = self.frame;
        Some((entry.texture_id, entry.may_have_transparency))
    }

    pub(crate) fn insert(
        &mut self,
        blob: &Blob<u8>,
        texture_id: TextureId,
        may_have_transparency: bool,
        width: u32,
        height: u32,
    ) {
        self.entries.insert(
            blob.id(),
            CachedImage {
                blob: blob.downgrade(),
                texture_id,
                may_have_transparency,
                bytes: u64::from(width) * u64::from(height) * 4,
                last_used: self.frame,
            },
        );
    }

    pub(crate) fn finish_frame(&mut self) -> Vec<TextureId> {
        self.evict(UNUSED_IMAGE_BUDGET)
    }

    fn evict(&mut self, budget: u64) -> Vec<TextureId> {
        let mut evicted = Vec::new();
        self.entries.retain(|_, entry| {
            if entry.blob.upgrade().is_none() {
                evicted.push(entry.texture_id);
                false
            } else {
                true
            }
        });
        evicted.extend(self.evict_unused_over_budget(budget));
        self.advance_frame();
        evicted
    }

    fn evict_unused_over_budget(&mut self, budget: u64) -> Vec<TextureId> {
        let unused_bytes: u64 = self
            .entries
            .values()
            .filter(|entry| entry.last_used != self.frame)
            .map(|entry| entry.bytes)
            .sum();
        if unused_bytes <= budget {
            return Vec::new();
        }

        let mut unused: Vec<_> = self
            .entries
            .iter()
            .filter(|(_, entry)| entry.last_used != self.frame)
            .map(|(&id, entry)| (id, entry.last_used))
            .collect();
        unused.sort_unstable_by_key(|&(id, last_used)| (std::cmp::Reverse(last_used), id));
        let mut remaining = budget;
        let mut evicted = Vec::new();
        for (id, _) in unused {
            let entry = &self.entries[&id];
            if entry.bytes <= remaining {
                remaining -= entry.bytes;
            } else {
                evicted.push(self.entries.remove(&id).unwrap().texture_id);
            }
        }
        evicted
    }

    fn advance_frame(&mut self) {
        if self.frame == u64::MAX {
            for entry in self.entries.values_mut() {
                entry.last_used = 0;
            }
            self.frame = 1;
        } else {
            self.frame += 1;
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn image_size_limit() {
        let mut cache = ImageCache::default();
        assert!(cache.fits(4096, 4096));
        assert!(!cache.fits(4097, 1));
        assert!(!cache.fits(1, u16::MAX as u32 + 1));
        cache.set_max_image_size((100, 200));
        assert!(cache.fits(100, 200));
        assert!(!cache.fits(101, 200));
        assert!(!cache.fits(100, 201));
    }

    #[test]
    fn empty_frames() {
        let mut cache = ImageCache::default();
        assert!(cache.evict(0).is_empty());
        assert_eq!(cache.frame, 1);
    }

    #[test]
    fn current_images_are_kept_even_over_budget() {
        let mut cache = ImageCache::default();
        let blob = Blob::from(vec![0]);
        cache.insert(&blob, TextureId(1), true, 100, 100);
        assert!(cache.evict(0).is_empty());
        assert_eq!(cache.get(blob.id()), Some((TextureId(1), true)));
        assert!(cache.evict(0).is_empty());
    }

    #[test]
    fn unused_images_are_retained_in_lru_order() {
        let mut cache = ImageCache::default();
        let first = Blob::from(vec![0]);
        let second = Blob::from(vec![0]);
        cache.insert(&first, TextureId(1), true, 2, 2);
        cache.insert(&second, TextureId(2), true, 2, 2);
        cache.evict(32);
        cache.get(second.id());
        cache.evict(32);
        assert_eq!(cache.evict(16), vec![TextureId(1)]);
        assert_eq!(cache.get(first.id()), None);
        assert_eq!(cache.get(second.id()), Some((TextureId(2), true)));
    }

    #[test]
    fn clear_invalidates_ids_and_resets_frame() {
        let mut cache = ImageCache::default();
        let blob = Blob::from(vec![0]);
        cache.insert(&blob, TextureId(1), true, 1, 1);
        cache.evict(4);
        cache.clear();
        assert_eq!(cache.get(blob.id()), None);
        assert_eq!(cache.frame, 0);
    }

    #[test]
    fn oversized_unused_image_does_not_displace_smaller_images() {
        let mut cache = ImageCache::default();
        let first = Blob::from(vec![0]);
        let second = Blob::from(vec![0]);
        cache.insert(&first, TextureId(1), true, 10, 10);
        cache.insert(&second, TextureId(2), true, 1, 1);
        cache.evict(4);
        assert_eq!(cache.evict(4), vec![TextureId(1)]);
        assert_eq!(cache.get(second.id()), Some((TextureId(2), true)));
    }

    #[test]
    fn dropped_blob_is_evicted_next_frame_within_budget() {
        let mut cache = ImageCache::default();
        let blob = Blob::from(vec![0]);
        let id = blob.id();
        let weak = blob.downgrade();
        cache.insert(&blob, TextureId(1), true, 1, 1);
        assert_eq!(blob.strong_count(), 1);
        assert!(cache.finish_frame().is_empty());
        drop(blob);
        assert!(weak.upgrade().is_none());
        assert_eq!(cache.finish_frame(), vec![TextureId(1)]);
        assert_eq!(cache.get(id), None);
        assert!(cache.finish_frame().is_empty());
    }

    #[test]
    fn dropped_current_blob_is_evicted_after_rendering() {
        let mut cache = ImageCache::default();
        let blob = Blob::from(vec![0]);
        cache.insert(&blob, TextureId(1), true, 1, 1);
        drop(blob);
        assert_eq!(cache.finish_frame(), vec![TextureId(1)]);
        assert!(cache.entries.is_empty());
    }

    #[test]
    fn surviving_clone_keeps_unused_image_resident() {
        let mut cache = ImageCache::default();
        let blob = Blob::from(vec![0]);
        let clone = blob.clone();
        cache.insert(&blob, TextureId(1), true, 1, 1);
        cache.finish_frame();
        drop(blob);
        assert!(cache.finish_frame().is_empty());
        assert_eq!(cache.get(clone.id()), Some((TextureId(1), true)));
        drop(clone);
        assert_eq!(cache.finish_frame(), vec![TextureId(1)]);
    }
}