Skip to main content

gpui/
assets.rs

1use crate::{DevicePixels, Pixels, Result, SharedString, Size, size};
2use smallvec::SmallVec;
3
4use image::{Delay, Frame};
5use std::{
6    borrow::Cow,
7    fmt,
8    hash::Hash,
9    sync::atomic::{AtomicUsize, Ordering::SeqCst},
10};
11
12/// A source of assets for this app to use.
13pub trait AssetSource: 'static + Send + Sync {
14    /// Load the given asset from the source path.
15    fn load(&self, path: &str) -> Result<Option<Cow<'static, [u8]>>>;
16
17    /// List the assets at the given path.
18    fn list(&self, path: &str) -> Result<Vec<SharedString>>;
19}
20
21impl AssetSource for () {
22    fn load(&self, _path: &str) -> Result<Option<Cow<'static, [u8]>>> {
23        Ok(None)
24    }
25
26    fn list(&self, _path: &str) -> Result<Vec<SharedString>> {
27        Ok(vec![])
28    }
29}
30
31/// A unique identifier for the image cache
32#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
33pub struct ImageId(pub usize);
34
35#[derive(PartialEq, Eq, Hash, Clone)]
36#[expect(missing_docs)]
37pub struct RenderImageParams {
38    pub image_id: ImageId,
39    pub frame_index: usize,
40}
41
42/// A cached and processed image, in BGRA format
43pub struct RenderImage {
44    /// The ID associated with this image
45    pub id: ImageId,
46    /// The scale factor of this image on render.
47    pub(crate) scale_factor: f32,
48    data: SmallVec<[Frame; 1]>,
49    /// vue-native: one frame of a moving picture (a video, an animation). The
50    /// host's [`crate::ImageResampler`] is not asked about it: its next frame
51    /// is a new image, and a placeholder whose atlas tile the GPU fills has no
52    /// pixels worth reading.
53    dynamic: bool,
54    gpu_size: Option<Size<DevicePixels>>,
55    /// vue-native: the size the picture has, when its pixels are a smaller
56    /// copy of it ([`Self::with_natural_size`]). Layout and `object-fit` read
57    /// this, so an image an embedder swapped for the copy it is drawn from
58    /// lays out and fits exactly as the full decode did.
59    natural: Option<Size<DevicePixels>>,
60}
61
62impl PartialEq for RenderImage {
63    fn eq(&self, other: &Self) -> bool {
64        self.id == other.id
65    }
66}
67
68impl Eq for RenderImage {}
69
70impl RenderImage {
71    /// Create a new image from the given data.
72    pub fn new(data: impl Into<SmallVec<[Frame; 1]>>) -> Self {
73        static NEXT_ID: AtomicUsize = AtomicUsize::new(0);
74
75        Self {
76            id: ImageId(NEXT_ID.fetch_add(1, SeqCst)),
77            scale_factor: 1.0,
78            data: data.into(),
79            dynamic: false,
80            gpu_size: None,
81            natural: None,
82        }
83    }
84
85    /// An atlas-backed GPU picture with no placeholder CPU pixel allocation.
86    /// The host must upload its GPU tile before painting. Missing tiles are
87    /// skipped, rather than falling back to an invented CPU image.
88    pub fn from_gpu(size: Size<DevicePixels>) -> Self {
89        let mut image = Self::new(SmallVec::new());
90        image.gpu_size = Some(size);
91        image.dynamic = true;
92        image
93    }
94
95    /// vue-native: marks this single-frame image as a smaller copy of a picture
96    /// of `natural` pixels. [`Self::size`] and [`Self::as_bytes`] stay the copy's;
97    /// [`Self::natural_size`] (layout, `object-fit`) answers `natural`, so the copy
98    /// can stand in for the full decode in the asset cache
99    /// ([`crate::ImageSource::replace_cached`]).
100    pub fn with_natural_size(mut self, natural: Size<DevicePixels>) -> Self {
101        self.natural = Some(natural);
102        self
103    }
104
105    /// vue-native: the picture's own size in pixels: the one
106    /// [`Self::with_natural_size`] recorded, else the pixels' size.
107    pub fn natural_size(&self, frame_index: usize) -> Size<DevicePixels> {
108        self.natural.unwrap_or_else(|| self.size(frame_index))
109    }
110
111    /// vue-native: are these pixels a smaller copy of the picture
112    /// ([`Self::with_natural_size`])?
113    pub fn is_reduced(&self) -> bool {
114        self.natural.is_some()
115    }
116
117    /// vue-native: marks this image as one frame of a moving picture, which
118    /// [`crate::Window::paint_image`] draws as it is (see `dynamic`).
119    pub fn dynamic(mut self) -> Self {
120        self.dynamic = true;
121        self
122    }
123
124    /// vue-native: whether [`Self::dynamic`] marked this image.
125    pub fn is_dynamic(&self) -> bool {
126        self.dynamic
127    }
128
129    /// vue-native: the next frame of the same picture, `data` under THIS image's
130    /// id. One id is one atlas key, so
131    /// [`crate::Window::write_image_tile`] writes these pixels into the tile
132    /// this image already has, and a scene that samples that tile shows them on
133    /// its next present. Keeps [`Self::dynamic`] and the scale factor.
134    pub fn successor(&self, data: impl Into<SmallVec<[Frame; 1]>>) -> Self {
135        Self {
136            id: self.id,
137            scale_factor: self.scale_factor,
138            data: data.into(),
139            dynamic: self.dynamic,
140            gpu_size: None,
141            natural: None,
142        }
143    }
144
145    /// Convert this image into a byte slice.
146    pub fn as_bytes(&self, frame_index: usize) -> Option<&[u8]> {
147        self.data
148            .get(frame_index)
149            .map(|frame| frame.buffer().as_raw().as_slice())
150    }
151
152    /// Get the size of this image, in pixels.
153    pub fn size(&self, frame_index: usize) -> Size<DevicePixels> {
154        if frame_index == 0 { if let Some(size) = self.gpu_size { return size; } }
155        self.data
156            .get(frame_index)
157            .map(|frame| {
158                let (width, height) = frame.buffer().dimensions();
159                size(width.into(), height.into())
160            })
161            .unwrap_or_default()
162    }
163
164    /// Get the size of this image, in pixels for display, adjusted for the scale factor.
165    pub(crate) fn render_size(&self, frame_index: usize) -> Size<Pixels> {
166        self.natural_size(frame_index)
167            .map(|v| (v.0 as f32 / self.scale_factor).into())
168    }
169
170    /// Get the delay of this frame from the previous
171    pub fn delay(&self, frame_index: usize) -> Delay {
172        self.data
173            .get(frame_index)
174            .map(|frame| frame.delay())
175            .unwrap_or(Delay::from_numer_denom_ms(100, 1))
176    }
177
178    /// Get the number of frames for this image.
179    pub fn frame_count(&self) -> usize {
180        if self.gpu_size.is_some() { return 1; }
181        self.data.len()
182    }
183}
184
185impl fmt::Debug for RenderImage {
186    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
187        f.debug_struct("ImageData")
188            .field("id", &self.id)
189            .field("size", &self.data.first().map(|f| f.buffer().dimensions()))
190            .finish()
191    }
192}
193
194#[cfg(test)]
195mod tests {
196    use super::*;
197    use smallvec::SmallVec;
198
199    #[test]
200    fn gpu_image_keeps_intrinsics_without_a_cpu_placeholder() {
201        let dimensions=size(DevicePixels(16384),DevicePixels(16384));
202        let gpu=RenderImage::from_gpu(dimensions);
203        assert_eq!(gpu.size(0),dimensions);
204        assert_eq!(gpu.natural_size(0),dimensions);
205        assert_eq!(gpu.frame_count(),1);
206        assert_eq!(gpu.as_bytes(0),None);
207        assert_eq!(gpu.size(1),Size::default());
208        assert!(gpu.is_dynamic());
209    }
210
211    #[test]
212    fn empty_render_image_does_not_panic() {
213        let image = RenderImage::new(SmallVec::new());
214        assert_eq!(image.frame_count(), 0);
215        assert_eq!(image.size(0), Size::default());
216        assert_eq!(image.as_bytes(0), None);
217        assert_eq!(image.render_size(0), Size::default());
218        assert_eq!(image.delay(0), Delay::from_numer_denom_ms(100, 1));
219        let _ = format!("{image:?}");
220    }
221
222    #[test]
223    fn a_frame_of_a_moving_picture_is_marked_dynamic() {
224        let still = RenderImage::new(SmallVec::new());
225        assert!(!still.is_dynamic());
226        let frame = RenderImage::new(SmallVec::new()).dynamic();
227        assert!(frame.is_dynamic());
228        assert_ne!(still.id, frame.id);
229    }
230
231    #[test]
232    fn a_reduced_copy_lays_out_at_the_natural_size() {
233        let pixels = image::RgbaImage::new(4, 2);
234        let copy = RenderImage::new(SmallVec::from_const([Frame::new(pixels)]))
235            .with_natural_size(size(DevicePixels(400), DevicePixels(200)));
236        assert!(copy.is_reduced());
237        assert_eq!(copy.size(0), size(DevicePixels(4), DevicePixels(2)));
238        assert_eq!(copy.natural_size(0), size(DevicePixels(400), DevicePixels(200)));
239        assert_eq!(copy.render_size(0), size(Pixels::from(400.), Pixels::from(200.)));
240        let full = RenderImage::new(SmallVec::from_const([Frame::new(image::RgbaImage::new(3, 3))]));
241        assert!(!full.is_reduced());
242        assert_eq!(full.natural_size(0), full.size(0));
243    }
244}