Skip to main content

gpui/
effect_textures.rs

1//! vue-native: the images a `--shading` effect samples, its `SkTexture`
2//! parameters.
3//!
4//! CSS names an image by URL; the embedder numbers each URL and resolves a
5//! number to an image while painting ([`set_effect_texture_resolver`]). The
6//! scene keeps one [`EffectTextureSet`] per distinct combination and an
7//! [`EffectQuad`] names its set in the high bits of `flags`, so quads that
8//! sample the same images still draw in one instanced call.
9
10use std::{
11    borrow::Cow,
12    collections::HashMap,
13    sync::{Arc, RwLock, Weak},
14};
15
16#[cfg(feature = "schemars")]
17use schemars::JsonSchema;
18use serde::{Deserialize, Serialize};
19
20use crate::{App, EffectQuad, EffectSpec, ImageId, RenderImage, Window};
21
22/// `SkTexture` parameters an effect may declare. They bind at HLSL t3..t6,
23/// WGSL `@group(2) @binding(3..6)` and Metal `texture(3..6)`, with the
24/// repeating sampler at s2, `@binding(9)` and `sampler(2)`.
25pub const EFFECT_TEXTURE_SLOTS: usize = 4;
26
27/// Bits of [`EffectQuad::flags`] above this hold the quad's texture set, plus
28/// one; zero samples no image.
29pub const EFFECT_FLAG_TEXTURE_SET_SHIFT: u32 = 16;
30
31/// One `SkTexture` parameter of an [`EffectSpec`].
32#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
33#[cfg_attr(feature = "schemars", derive(JsonSchema))]
34pub struct EffectTextureParam {
35    /// The image, numbered by the embedder; 0 when CSS gave none.
36    pub source: u32,
37    /// The first of the two parameter slots the painter fills with the
38    /// image's width and height in texels, zero while it is missing.
39    pub size_param: u8,
40    /// Sampled as stored. Otherwise the renderer premultiplies it.
41    pub linear: bool,
42}
43
44/// An image an effect quad samples.
45#[derive(Clone, Debug)]
46pub struct EffectTexture {
47    /// Frame 0 is sampled.
48    pub image: Arc<RenderImage>,
49    /// See [`EffectTextureParam::linear`].
50    pub linear: bool,
51}
52
53/// One quad's images, by binding.
54pub type EffectTextureSet = [Option<EffectTexture>; EFFECT_TEXTURE_SLOTS];
55
56/// Resolves [`EffectTextureParam::source`]: `None` while the image loads or
57/// when it cannot, and the effect then reads its fallback.
58pub type EffectTextureResolver = fn(u32, &mut Window, &mut App) -> Option<Arc<RenderImage>>;
59
60static RESOLVER: RwLock<Option<EffectTextureResolver>> = RwLock::new(None);
61
62/// Installs the embedder's resolver; without one every texture is missing.
63pub fn set_effect_texture_resolver(resolver: EffectTextureResolver) {
64    *RESOLVER.write().unwrap_or_else(|e| e.into_inner()) = Some(resolver);
65}
66
67/// The images `spec` names that are ready, or `None` when it names none.
68pub(crate) fn resolve_effect_textures(
69    spec: &EffectSpec,
70    window: &mut Window,
71    cx: &mut App,
72) -> Option<Arc<EffectTextureSet>> {
73    if spec
74        .textures
75        .iter()
76        .all(|t| t.is_none_or(|t| t.source == 0))
77    {
78        return None;
79    }
80    let resolver = (*RESOLVER.read().unwrap_or_else(|e| e.into_inner()))?;
81    let mut set = EffectTextureSet::default();
82    for (slot, param) in spec.textures.iter().enumerate() {
83        let Some(param) = param.filter(|p| p.source != 0) else {
84            continue;
85        };
86        if let Some(image) = resolver(param.source, window, cx)
87            && image.as_bytes(0).is_some()
88        {
89            set[slot] = Some(EffectTexture {
90                image,
91                linear: param.linear,
92            });
93        }
94    }
95    set.iter().any(Option::is_some).then(|| Arc::new(set))
96}
97
98/// Writes each image's size into its size slots: zero for a missing one.
99pub(crate) fn write_effect_texture_sizes(
100    spec: &EffectSpec,
101    textures: Option<&EffectTextureSet>,
102    params: &mut [f32],
103) {
104    for (slot, param) in spec.textures.iter().enumerate() {
105        let Some(param) = param else { continue };
106        let size = textures
107            .and_then(|set| set[slot].as_ref())
108            .map(|t| t.image.size(0))
109            .map_or([0., 0.], |s| [s.width.0 as f32, s.height.0 as f32]);
110        let at = param.size_param as usize;
111        if let Some(target) = params.get_mut(at..at + 2) {
112            target.copy_from_slice(&size);
113        }
114    }
115}
116
117pub(crate) type EffectTextureKey = [Option<(ImageId, bool)>; EFFECT_TEXTURE_SLOTS];
118
119pub(crate) fn effect_texture_key(set: &EffectTextureSet) -> EffectTextureKey {
120    std::array::from_fn(|i| set[i].as_ref().map(|t| (t.image.id, t.linear)))
121}
122
123impl EffectQuad {
124    /// The index of this quad's set in [`crate::Scene::effect_texture_sets`].
125    pub fn texture_set(&self) -> Option<usize> {
126        (self.flags >> EFFECT_FLAG_TEXTURE_SET_SHIFT)
127            .checked_sub(1)
128            .map(|index| index as usize)
129    }
130}
131
132impl EffectTexture {
133    /// The BGRA8 texels to upload, premultiplied unless the texture is linear,
134    /// with their width and height.
135    pub fn texels(&self) -> Option<(u32, u32, Cow<'_, [u8]>)> {
136        let bytes = self.image.as_bytes(0)?;
137        let size = self.image.size(0);
138        let (width, height) = (size.width.0 as u32, size.height.0 as u32);
139        if width == 0 || height == 0 || bytes.len() < (width * height * 4) as usize {
140            return None;
141        }
142        if self.linear || bytes.chunks_exact(4).all(|p| p[3] == 255) {
143            return Some((width, height, Cow::Borrowed(bytes)));
144        }
145        let mut premultiplied = bytes.to_vec();
146        for pixel in premultiplied.chunks_exact_mut(4) {
147            let alpha = pixel[3] as u32;
148            for channel in &mut pixel[..3] {
149                *channel = ((*channel as u32 * alpha + 127) / 255) as u8;
150            }
151        }
152        Some((width, height, Cow::Owned(premultiplied)))
153    }
154}
155
156/// Frames a texture stays on the GPU unsampled before it is freed.
157const EFFECT_TEXTURE_KEEP_FRAMES: u64 = 240;
158
159/// A renderer's uploaded effect textures, keyed by image and colour handling.
160pub struct EffectTextureCache<T> {
161    entries: HashMap<(ImageId, bool), CachedEffectTexture<T>>,
162    frame: u64,
163}
164
165struct CachedEffectTexture<T> {
166    texture: Option<T>,
167    image: Weak<RenderImage>,
168    used: u64,
169}
170
171impl<T> Default for EffectTextureCache<T> {
172    fn default() -> Self {
173        Self {
174            entries: HashMap::new(),
175            frame: 0,
176        }
177    }
178}
179
180impl<T> EffectTextureCache<T> {
181    /// Call once per drawn frame, before [`Self::get`]: frees what has gone
182    /// unused for a while or whose image is gone.
183    pub fn begin_frame(&mut self) {
184        self.frame += 1;
185        let frame = self.frame;
186        self.entries.retain(|_, entry| {
187            frame - entry.used <= EFFECT_TEXTURE_KEEP_FRAMES && entry.image.strong_count() > 0
188        });
189    }
190
191    /// The texture for `texture`, uploading it through `upload` (width,
192    /// height, BGRA8 texels) when this image has none yet. An upload that
193    /// fails is not retried while the image lives; its quads read black.
194    pub fn get(
195        &mut self,
196        texture: &EffectTexture,
197        upload: impl FnOnce(u32, u32, &[u8]) -> anyhow::Result<T>,
198    ) -> Option<&T> {
199        let key = (texture.image.id, texture.linear);
200        let current = Arc::as_ptr(&texture.image);
201        let stale = self
202            .entries
203            .get(&key)
204            .is_none_or(|entry| entry.image.as_ptr() != current);
205        if stale {
206            let uploaded = texture.texels().and_then(|(width, height, texels)| {
207                upload(width, height, &texels)
208                    .inspect_err(|error| log::error!("uploading an effect texture: {error:#}"))
209                    .ok()
210            });
211            self.entries.insert(
212                key,
213                CachedEffectTexture {
214                    texture: uploaded,
215                    image: Arc::downgrade(&texture.image),
216                    used: self.frame,
217                },
218            );
219        }
220        let entry = self.entries.get_mut(&key)?;
221        entry.used = self.frame;
222        entry.texture.as_ref()
223    }
224
225    /// Frees every texture, as when the device is lost.
226    pub fn clear(&mut self) {
227        self.entries.clear();
228    }
229}
230
231#[cfg(test)]
232mod tests {
233    use super::*;
234    use image::{Frame, RgbaImage};
235
236    fn image(pixels: &[[u8; 4]]) -> Arc<RenderImage> {
237        let buffer = RgbaImage::from_raw(pixels.len() as u32, 1, pixels.concat()).unwrap();
238        Arc::new(RenderImage::new(vec![Frame::new(buffer)]))
239    }
240
241    #[test]
242    fn colour_texels_are_premultiplied_and_linear_ones_are_not() {
243        let image = image(&[[200, 100, 50, 128], [10, 20, 30, 255]]);
244        let colour = EffectTexture {
245            image: image.clone(),
246            linear: false,
247        };
248        let (_, _, texels) = colour.texels().unwrap();
249        assert_eq!(&texels[..4], &[100, 50, 25, 128]);
250        assert_eq!(&texels[4..], &[10, 20, 30, 255]);
251        let data = EffectTexture {
252            image,
253            linear: true,
254        };
255        assert_eq!(&data.texels().unwrap().2[..4], &[200, 100, 50, 128]);
256    }
257
258    #[test]
259    fn quads_sampling_different_images_draw_in_separate_batches() {
260        use crate::{PrimitiveBatch, Scene, bounds, point, px, size};
261
262        let set = |image: &Arc<RenderImage>| {
263            let mut set = EffectTextureSet::default();
264            set[0] = Some(EffectTexture {
265                image: image.clone(),
266                linear: false,
267            });
268            Some(Arc::new(set))
269        };
270        let (a, b) = (image(&[[0, 0, 0, 255]]), image(&[[9, 9, 9, 255]]));
271        let quad = |x: f32| EffectQuad {
272            effect_id: 3,
273            bounds: bounds(point(px(x), px(0.)), size(px(10.), px(10.))).scale(1.),
274            content_mask: crate::ContentMask {
275                bounds: bounds(point(px(0.), px(0.)), size(px(500.), px(500.))).scale(1.),
276                ..Default::default()
277            },
278            ..Default::default()
279        };
280        let mut scene = Scene::default();
281        for (x, textures) in [(0., set(&a)), (20., set(&b)), (40., set(&a)), (60., None)] {
282            scene.insert_primitive(crate::Primitive::EffectQuad(quad(x), textures));
283        }
284        scene.finish();
285        assert_eq!(
286            scene.effect_texture_sets.len(),
287            2,
288            "one set per distinct image"
289        );
290        let batches: Vec<_> = scene
291            .batches()
292            .filter_map(|batch| match batch {
293                PrimitiveBatch::EffectQuads { range, .. } => Some(range.len()),
294                _ => None,
295            })
296            .collect();
297        assert_eq!(batches, [1, 2, 1], "{batches:?}");
298
299        let mut replayed = Scene::default();
300        replayed.insert_primitive(crate::Primitive::EffectQuad(quad(0.), set(&b)));
301        replayed.replay(0..scene.paint_operations.len(), &scene);
302        replayed.finish();
303        let sampled: Vec<_> = replayed
304            .effect_quads
305            .iter()
306            .map(|quad| {
307                quad.texture_set().map(|set| {
308                    replayed.effect_texture_sets[set][0]
309                        .as_ref()
310                        .unwrap()
311                        .image
312                        .id
313                })
314            })
315            .collect();
316        assert!(sampled.contains(&Some(a.id)) && sampled.contains(&None));
317        assert_eq!(sampled.iter().filter(|s| **s == Some(b.id)).count(), 2);
318    }
319
320    #[test]
321    fn the_cache_uploads_an_image_once_and_again_when_it_is_replaced() {
322        let mut cache = EffectTextureCache::<u32>::default();
323        let mut uploads = 0;
324        let first = EffectTexture {
325            image: image(&[[0, 0, 0, 255]]),
326            linear: false,
327        };
328        for _ in 0..3 {
329            cache.begin_frame();
330            cache.get(&first, |_, _, _| {
331                uploads += 1;
332                Ok(uploads)
333            });
334        }
335        assert_eq!(uploads, 1);
336        let next = EffectTexture {
337            image: Arc::new(first.image.successor(vec![Frame::new(
338                RgbaImage::from_raw(1, 1, vec![1, 2, 3, 255]).unwrap(),
339            )])),
340            linear: false,
341        };
342        cache.begin_frame();
343        assert_eq!(cache.get(&next, |_, _, _| Ok(7)), Some(&7));
344        drop(next);
345        drop(first);
346        cache.begin_frame();
347        assert!(
348            cache.entries.is_empty(),
349            "a dropped image frees its texture"
350        );
351    }
352}