diff --git a/AGENTS.md b/AGENTS.md index ebb9f15e..3904152f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -530,6 +530,9 @@ fframes::svgr!( Vec { values.iter().flat_map(|v| v.to_ne_bytes()).collect() } +/// Name of the `uniform shader` child that receives what is already painted under the +/// element (a backdrop), in the element's own coordinates, so a shader can refract or +/// otherwise process the content beneath it. Only available when drawing straight onto a +/// surface; inside a recorded picture or an isolated layer it falls back to transparent. +pub const BACKDROP_CHILD: &str = "uBackdrop"; + +/// What is already painted under the element, as a shader in the element's local +/// coordinates: a snapshot of the surface mapped through the inverse of the current +/// local-to-device matrix. +fn backdrop_shader(canvas: &Canvas) -> Option { + // SAFETY: the surface handle is only used to take an immutable snapshot and is dropped + // before the canvas draws again; the canvas stays the sole writer. + let mut surface = unsafe { canvas.surface() }?; + let image = surface.image_snapshot(); + let device_to_local = canvas.local_to_device_as_3x3().invert()?; + image.to_shader( + (skia_safe::TileMode::Clamp, skia_safe::TileMode::Clamp), + skia_safe::SamplingOptions::new(skia_safe::FilterMode::Linear, skia_safe::MipmapMode::None), + Some(&device_to_local), + ) +} + /// Every `uniform shader` child must be bound; missing images are bound to a -/// transparent shader so the rest of the program still runs. +/// transparent shader so the rest of the program still runs. A child named +/// [`BACKDROP_CHILD`] with no image bound receives the backdrop. fn bind_children( effect: &RuntimeEffect, draw: &ShaderDraw, + canvas: &Canvas, cache: &mut RenderCache, ) -> Option> { let mut children = Vec::with_capacity(effect.children().len()); @@ -198,11 +225,31 @@ fn bind_children( }) }); + let image_shader = image_shader.or_else(|| { + if pixels.is_none() && child.name() == BACKDROP_CHILD { + let backdrop = backdrop_shader(canvas); + if backdrop.is_none() { + cache.shaders.warn_once( + &draw.shader, + format!( + "child `{}`: no surface to snapshot here, bound transparent", + child.name() + ), + ); + } + backdrop + } else { + None + } + }); + let shader = image_shader.unwrap_or_else(|| { - cache.shaders.warn_once( - &draw.shader, - format!("child `{}` has no image bound", child.name()), - ); + if child.name() != BACKDROP_CHILD { + cache.shaders.warn_once( + &draw.shader, + format!("child `{}` has no image bound", child.name()), + ); + } skia_safe::shaders::color(skia_safe::Color::TRANSPARENT) }); diff --git a/fframes-skia-renderer/tests/shaders.rs b/fframes-skia-renderer/tests/shaders.rs index a774cb1c..d7d039c3 100644 --- a/fframes-skia-renderer/tests/shaders.rs +++ b/fframes-skia-renderer/tests/shaders.rs @@ -180,6 +180,29 @@ fn image_children_are_sampled() { assert_near(canvas.pixel(50, 50), [0, 0, 255, 255]); } +#[test] +fn backdrop_child_samples_what_is_painted_underneath() { + // Reads the backdrop 50 units to the left, in the element's own coordinates. + let shader = Shader::sksl( + "uniform shader uBackdrop; + half4 main(float2 coord) { return uBackdrop.eval(coord - float2(50.0, 0.0)); }", + ); + let layer = shader.draw(&Frame::new(0, 0, 30), ShaderUniforms::new()); + + let mut canvas = Canvas::new(); + canvas.render(fframes::svgr!( + + + + + + )); + + // The left half is untouched; the right half now shows the red copied from the left. + assert_near(canvas.pixel(25, 50), [255, 0, 0, 255]); + assert_near(canvas.pixel(75, 50), [255, 0, 0, 255]); +} + #[test] fn invalid_shaders_report_errors_and_are_skipped() { let shader = Shader::sksl("half4 main(float2 coord) { return nope; }"); diff --git a/fframes/src/shader.rs b/fframes/src/shader.rs index 0b17ba2c..67d3992c 100644 --- a/fframes/src/shader.rs +++ b/fframes/src/shader.rs @@ -205,6 +205,12 @@ impl ShaderUniforms { /// `uniform shader name;` bound to an image, e.g. `ctx.get_image(..)` or a /// synced video frame. Sample it with `name.eval(coord)` where `coord` is /// in the image's pixels. Ignored in the editor. + /// + /// A child named `uBackdrop` that has no image bound receives what is already + /// painted under the element instead, in the element's own coordinates, so the + /// shader can refract or otherwise process the content beneath it. It is + /// transparent where there is no surface to snapshot (inside a recorded picture + /// or an isolated layer such as a group with opacity, a mask or a filter). #[allow(unused_variables)] pub fn image(self, name: impl Into>, image: &ImageData<'_>) -> Self { #[cfg(not(target_arch = "wasm32"))]