Skip to main content

gpui/
app_effects.rs

1//! vue-native: an app's own `--shading` effects, as every renderer reads them. The CSS registry
2//! (`sk-effects`) reads the parameter schemas from the same [`AppEffects::manifest`] and numbers the
3//! effects the same way: `effect_id::COUNT + index`, in manifest order.
4
5use std::sync::{
6    Arc,
7    atomic::{AtomicU64, Ordering},
8};
9
10use anyhow::bail;
11use parking_lot::Mutex;
12
13/// Names a directory of compiled app effects (`effects.json` and the shaders beside it).
14/// A developer override: it wins over what the host installs with [`set_app_effects`].
15pub const APP_EFFECTS_DIR_ENV: &str = "SK_EFFECTS_DIR";
16
17/// The `effects.json` layout this build understands.
18pub const APP_EFFECTS_SCHEMA: u32 = 10;
19
20/// One generated shader of an [`AppEffect`].
21#[derive(Debug, Clone, PartialEq, Eq)]
22pub enum AppEffectSource {
23    /// `effects.json` names no file for this target.
24    Unlisted,
25    /// `effects.json` names a file the app's effects do not carry.
26    Missing(String),
27    /// The file and its text.
28    Present {
29        /// As `effects.json` names it.
30        file: String,
31        /// The generated source.
32        text: String,
33    },
34}
35
36impl AppEffectSource {
37    /// The file name and its text; `language` names the target in the error.
38    pub fn get(&self, language: &str) -> anyhow::Result<(&str, &str)> {
39        match self {
40            AppEffectSource::Unlisted => {
41                bail!("effects.json lists no {language} for it; rebuild the app with sk build")
42            }
43            AppEffectSource::Missing(file) => bail!("the app's effects have no {file}"),
44            AppEffectSource::Present { file, text } => Ok((file, text)),
45        }
46    }
47}
48
49/// One app effect as far as a renderer is concerned; parameter names, defaults and ranges belong
50/// to the CSS layer.
51#[derive(Debug, Clone, PartialEq, Eq)]
52pub struct AppEffect {
53    /// The CSS function name.
54    pub name: String,
55    /// Decides the blend state and whether the renderer breaks the pass for a snapshot.
56    pub needs_backdrop: bool,
57    /// Whether it draws its element's painting (`[SkContent]`), and nothing without it.
58    pub content: bool,
59    /// Whether it keeps a history (`[SkHistory]`), which a second pipeline
60    /// steps: blending off, a 16-bit float target.
61    pub history: bool,
62    /// For DirectX.
63    pub hlsl: AppEffectSource,
64    /// For wgpu.
65    pub wgsl: AppEffectSource,
66    /// For Metal.
67    pub metal: AppEffectSource,
68}
69
70/// An app's effects: its `effects.json` and the generated shaders it names.
71#[derive(Debug)]
72pub struct AppEffects {
73    /// Where they came from, for messages.
74    pub origin: String,
75    /// The `effects.json` text.
76    pub manifest: String,
77    effects: Vec<AppEffect>,
78}
79
80#[derive(serde::Deserialize)]
81struct RawManifest {
82    schema: u32,
83    effects: Vec<RawEffect>,
84}
85
86#[derive(serde::Deserialize)]
87struct RawEffect {
88    name: String,
89    backdrop: bool,
90    #[serde(default)]
91    content: bool,
92    #[serde(default)]
93    history: bool,
94    #[serde(default)]
95    hlsl: Option<String>,
96    #[serde(default)]
97    wgsl: Option<String>,
98    #[serde(default)]
99    metal: Option<String>,
100}
101
102impl AppEffects {
103    /// `files` maps the names `manifest` gives the generated shaders to their source.
104    pub fn new(
105        origin: impl Into<String>,
106        manifest: impl Into<String>,
107        files: impl IntoIterator<Item = (String, String)>,
108    ) -> Result<Self, String> {
109        let origin = origin.into();
110        let manifest = manifest.into();
111        let raw: RawManifest = serde_json::from_str(&manifest)
112            .map_err(|e| format!("{origin}: effects.json is not readable ({e})"))?;
113        if raw.schema != APP_EFFECTS_SCHEMA {
114            return Err(format!(
115                "{origin}: effects.json is schema {} but this build understands \
116                 {APP_EFFECTS_SCHEMA} — rebuild the app with the sk that matches this host",
117                raw.schema
118            ));
119        }
120        let files: std::collections::HashMap<String, String> = files.into_iter().collect();
121        let source = |file: Option<String>| match file {
122            None => AppEffectSource::Unlisted,
123            Some(file) => match files.get(&file).cloned() {
124                Some(text) => AppEffectSource::Present { file, text },
125                None => AppEffectSource::Missing(file),
126            },
127        };
128        let effects = raw
129            .effects
130            .into_iter()
131            .map(|effect| AppEffect {
132                hlsl: source(effect.hlsl),
133                wgsl: source(effect.wgsl),
134                metal: source(effect.metal),
135                needs_backdrop: effect.backdrop,
136                content: effect.content,
137                history: effect.history,
138                name: effect.name,
139            })
140            .collect();
141        Ok(Self {
142            origin,
143            manifest,
144            effects,
145        })
146    }
147
148    /// `<dir>/effects.json` and the `.hlsl`, `.wgsl` and `.metal` files beside it.
149    pub fn from_dir(dir: &std::path::Path) -> Result<Self, String> {
150        let manifest_path = dir.join("effects.json");
151        let manifest = std::fs::read_to_string(&manifest_path)
152            .map_err(|e| format!("{} could not be read ({e})", manifest_path.display()))?;
153        let mut files = Vec::new();
154        let entries = std::fs::read_dir(dir)
155            .map_err(|e| format!("{} could not be listed ({e})", dir.display()))?;
156        for entry in entries.flatten() {
157            let path = entry.path();
158            let shader = path
159                .extension()
160                .is_some_and(|ext| ext == "hlsl" || ext == "wgsl" || ext == "metal");
161            let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
162                continue;
163            };
164            if shader {
165                let text = std::fs::read_to_string(&path)
166                    .map_err(|e| format!("{} could not be read ({e})", path.display()))?;
167                files.push((name.to_string(), text));
168            }
169        }
170        Self::new(dir.display().to_string(), manifest, files)
171    }
172
173    /// In manifest order: effect id `effect_id::COUNT + index`.
174    pub fn effects(&self) -> &[AppEffect] {
175        &self.effects
176    }
177}
178
179struct Installed {
180    read: bool,
181    effects: Option<Arc<AppEffects>>,
182}
183
184static INSTALLED: Mutex<Installed> = Mutex::new(Installed {
185    read: false,
186    effects: None,
187});
188static GENERATION: AtomicU64 = AtomicU64::new(0);
189
190fn app_effects_dir() -> Option<std::path::PathBuf> {
191    std::env::var_os(APP_EFFECTS_DIR_ENV)
192        .filter(|dir| !dir.is_empty())
193        .map(std::path::PathBuf::from)
194}
195
196/// Hands the renderers and the CSS registry the app's effects (from its payload). Call it before
197/// the first window; false when [`APP_EFFECTS_DIR_ENV`] is set, which wins, or when the effects were
198/// already read.
199pub fn set_app_effects(effects: AppEffects) -> bool {
200    if app_effects_dir().is_some() {
201        return false;
202    }
203    let mut installed = INSTALLED.lock();
204    if installed.read {
205        return false;
206    }
207    installed.read = true;
208    installed.effects = Some(Arc::new(effects));
209    true
210}
211
212/// Replaces the app's effects in a running app (a dev rebuild). Every renderer rebuilds the app's
213/// pipelines on its next frame, and the CSS registry renumbers on its next read.
214pub fn reload_app_effects(effects: AppEffects) {
215    let mut installed = INSTALLED.lock();
216    installed.read = true;
217    installed.effects = Some(Arc::new(effects));
218    GENERATION.fetch_add(1, Ordering::Release);
219}
220
221/// Moves on every [`reload_app_effects`]; a renderer compares it once per frame.
222pub fn app_effects_generation() -> u64 {
223    GENERATION.load(Ordering::Acquire)
224}
225
226/// The app's effects: the last reload, else `$SK_EFFECTS_DIR` when set, else what the host
227/// installed, else none.
228pub fn app_effects() -> Option<Arc<AppEffects>> {
229    let mut installed = INSTALLED.lock();
230    if !installed.read {
231        installed.read = true;
232        installed.effects = app_effects_dir().and_then(|dir| {
233            AppEffects::from_dir(&dir)
234                .map_err(|error| {
235                    let message = format!(
236                        "{APP_EFFECTS_DIR_ENV} is set to `{}` but {error} — the app's own \
237                         `--shading` effects are unavailable",
238                        dir.display()
239                    );
240                    log::warn!("{message}");
241                    eprintln!("skathi: {message}");
242                })
243                .ok()
244                .map(Arc::new)
245        });
246    }
247    installed.effects.clone()
248}
249
250/// A renderer's pipelines for the app's effects, `effect_id::COUNT + index`. [`Self::sync`]
251/// rebuilds only the effects that changed since the last call; one whose new shader is unusable
252/// keeps its previous pipeline, and only an effect that never built is a hole.
253pub struct AppEffectPipelines<P> {
254    generation: Option<u64>,
255    slots: Vec<AppEffectSlot<P>>,
256}
257
258struct AppEffectSlot<P> {
259    /// What the slot was last asked to build; `pipeline` may come from an earlier version.
260    effect: AppEffect,
261    pipeline: Option<P>,
262}
263
264impl<P> Default for AppEffectPipelines<P> {
265    fn default() -> Self {
266        Self {
267            generation: None,
268            slots: Vec::new(),
269        }
270    }
271}
272
273impl<P> AppEffectPipelines<P> {
274    /// Catches up with [`reload_app_effects`]; false when nothing changed.
275    pub fn sync(&mut self, mut build: impl FnMut(&AppEffect) -> anyhow::Result<P>) -> bool {
276        let generation = app_effects_generation();
277        if self.generation == Some(generation) {
278            return false;
279        }
280        self.generation = Some(generation);
281        let app = app_effects();
282        let effects = app.as_deref().map(AppEffects::effects).unwrap_or_default();
283        let mut previous = std::mem::take(&mut self.slots);
284        for effect in effects {
285            let old = previous
286                .iter()
287                .position(|slot| slot.effect.name == effect.name)
288                .map(|index| previous.swap_remove(index));
289            let pipeline = match old {
290                Some(old) if old.effect == *effect => old.pipeline,
291                old => match (build(effect), old.and_then(|old| old.pipeline)) {
292                    (Ok(pipeline), _) => Some(pipeline),
293                    (Err(error), Some(previous)) => {
294                        advisory(
295                            generation,
296                            format!(
297                                "`--shading: {}(…)` keeps its previous shader — the new one is \
298                                 unusable: {error:#}",
299                                effect.name
300                            ),
301                        );
302                        Some(previous)
303                    }
304                    (Err(error), None) => {
305                        advisory(
306                            generation,
307                            format!("`--shading: {}(…)` is unavailable — {error:#}", effect.name),
308                        );
309                        None
310                    }
311                },
312            };
313            self.slots.push(AppEffectSlot {
314                effect: effect.clone(),
315                pipeline,
316            });
317        }
318        true
319    }
320
321    /// The pipeline of app effect `index`; None for a hole or past the end.
322    pub fn get(&self, index: usize) -> Option<&P> {
323        self.slots.get(index)?.pipeline.as_ref()
324    }
325
326    /// [`Self::get`], mutably.
327    pub fn get_mut(&mut self, index: usize) -> Option<&mut P> {
328        self.slots.get_mut(index)?.pipeline.as_mut()
329    }
330
331    /// Every pipeline built, holes skipped.
332    pub fn pipelines(&self) -> impl Iterator<Item = &P> {
333        self.slots.iter().filter_map(|slot| slot.pipeline.as_ref())
334    }
335}
336
337/// Once per message per reload: every window's renderer meets the same failure.
338fn advisory(generation: u64, message: String) {
339    static SEEN: Mutex<(u64, Vec<String>)> = Mutex::new((0, Vec::new()));
340    let mut seen = SEEN.lock();
341    if seen.0 != generation {
342        *seen = (generation, Vec::new());
343    }
344    if seen.1.contains(&message) {
345        return;
346    }
347    log::warn!("{message}");
348    eprintln!("skathi: {message}");
349    seen.1.push(message);
350}
351
352#[cfg(test)]
353mod tests {
354    use super::*;
355
356    #[test]
357    fn the_manifest_resolves_each_effect_to_its_shader_per_target() -> Result<(), String> {
358        let app = AppEffects::new(
359            "test",
360            r#"{"schema": 10, "kind": "user", "effects": [
361                {"name": "ripple", "backdrop": true, "hlsl": "ripple.hlsl", "wgsl": "ripple.wgsl"},
362                {"name": "plain", "backdrop": false, "hlsl": "plain.hlsl"}
363            ]}"#,
364            [("ripple.wgsl".to_string(), "// ripple".to_string())],
365        )?;
366        let [ripple, plain] = app.effects() else {
367            return Err(format!("{:?}", app.effects()));
368        };
369        assert!(ripple.needs_backdrop && !plain.needs_backdrop);
370        assert_eq!(
371            ripple.wgsl,
372            AppEffectSource::Present {
373                file: "ripple.wgsl".into(),
374                text: "// ripple".into()
375            }
376        );
377        assert_eq!(ripple.hlsl, AppEffectSource::Missing("ripple.hlsl".into()));
378        assert_eq!(plain.wgsl, AppEffectSource::Unlisted);
379        Ok(())
380    }
381}