ff_render/nodes/composite/

blend_mode.rs

//! `BlendMode` enum and `BlendModeNode` (CPU + GPU pixel-value blending).
//!
//! # Reference
//!
//! Every mode except the four HSL ones reproduces `FFmpeg`'s `blend` filter, so
//! a frame composited here matches the CPU compositor that ADR-0007 keeps as the
//! correctness reference. The formulas are transcribed from the `DEPTH == 32`
//! branch of `libavfilter/blend_modes.c` (identical in `release/7.1` and
//! `release/8.0`), which is already normalised to `[0, 1]`.
//!
//! `FFmpeg` names its two inputs `A` (the `top` pad) and `B` (the `bottom` pad).
//! `crates/ff-filter/src/filter_inner/build.rs` links the canvas to the `top` pad
//! and the layer to the `bottom` pad, so throughout this module and
//! `shaders/blend.wgsl`:
//!
//! ```text
//! FFmpeg A = base (canvas)      FFmpeg B = overlay (layer)
//! ```
//!
//! The `DEPTH == 32` branch applies no clamp, so several modes leave `[0, 1]`;
//! the final `clamp` in the shader and the `Rgba8Unorm` write reproduce
//! `FFmpeg`'s float-to-8-bit conversion. The 8-bit C path wraps instead, which is
//! deliberately not replicated. See ADR-0010.
//!
//! # Alpha
//!
//! Colour is composited against an **opaque black backdrop**, matching the CPU
//! compositor's `color=c=#000000` canvas, so the blend result is not reweighted
//! by the backdrop alpha the way W3C's `Cs' = (1 - ab) * Cs + ab * B(Cb, Cs)`
//! would. Alpha itself accumulates as src-over **coverage**,
//! `ao = as + ab * (1 - as)`: zero where nothing has drawn, rising toward one as
//! layers cover (#1750). [`BlendModeNode::process_cpu`] and `shaders/blend.wgsl`
//! carry the same two formulas.

use super::blend_math::{blend_rgb, composite_rgba};
use super::composite_op::CompositeOp;
#[cfg(feature = "wgpu")]
use super::helpers::{
    fullscreen_pipeline, linear_sampler, submit_render_pass, two_tex_sampler_uniform_bgl,
    upload_rgba_texture,
};
use crate::nodes::RenderNodeCpu;

// BlendMode

/// Pixel-value blend modes.
///
/// The discriminant is the value written into the shader's `mode` uniform, so
/// variants are only ever **appended**, never renumbered. Each doc comment gives
/// the normalised formula in terms of `base` and `overlay` (see the module docs
/// for how those map onto `FFmpeg`'s `A` and `B`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
#[repr(u32)]
pub enum BlendMode {
    /// Overlay replaces base.
    #[default]
    Normal = 0,
    /// base × overlay.
    Multiply = 1,
    /// 1 − (1−base)(1−overlay).
    Screen = 2,
    /// Multiply below 50% grey, Screen above.
    Overlay = 3,
    /// `base² + 2·overlay·base·(1−base)`.
    SoftLight = 4,
    /// Hard light — Overlay with base/overlay swapped.
    HardLight = 5,
    /// `base ≥ 1 ? base : min(1, overlay/(1−base))`.
    ColorDodge = 6,
    /// `base ≤ 0 ? base : max(0, 1−(1−overlay)/base)`.
    ColorBurn = 7,
    /// |base − overlay|.
    Difference = 8,
    /// base + overlay − 2·base·overlay.
    Exclusion = 9,
    /// clamp(base + overlay, 0, 1).
    Add = 10,
    /// clamp(base − overlay, 0, 1).
    Subtract = 11,
    /// min(base, overlay).
    Darken = 12,
    /// max(base, overlay).
    Lighten = 13,
    /// Overlay hue + base saturation + base lightness.
    Hue = 14,
    /// Base hue + overlay saturation + base lightness.
    Saturation = 15,
    /// Overlay hue + overlay saturation + base lightness.
    Color = 16,
    /// Base hue + base saturation + overlay lightness.
    Luminosity = 17,

    // The remaining `FFmpeg` `all_mode` set (#1669). Bitwise `And`/`Or`/`Xor` are
    // the one exception to the `DEPTH == 32` reference: there the C operates on
    // the IEEE-754 bit pattern, which is not an image operation, so these follow
    // the 8-bit definition that the compositor's `Rgba8Unorm` working format
    // means.
    /// Bitwise `and` of the two 8-bit samples.
    And = 18,
    /// `(base + overlay)/2`.
    Average = 19,
    /// `1 − base − overlay`.
    Bleach = 20,
    /// `overlay == 0 ? 1 : base/overlay`.
    Divide = 21,
    /// `|1 − base − overlay|`.
    Extremity = 22,
    /// `overlay == 0 ? 0 : 1 − min((1−base)²/overlay, 1)`.
    Freeze = 23,
    /// `sqrt(max(base,0)·max(overlay,0))`.
    Geometric = 24,
    /// `base ≥ 1 ? base : min(1, overlay²/(1−base))`.
    Glow = 25,
    /// `0.5 + base − overlay` (`FFmpeg`'s `difference128`).
    GrainExtract = 26,
    /// `base + overlay − 0.5` (`FFmpeg`'s `addition128`).
    GrainMerge = 27,
    /// `base < 1 − overlay ? 0 : 1`.
    HardMix = 28,
    /// `base ≥ 1 ? 1 : min(1, base > 0.5 ? overlay/(2−2·base) : 2·base·overlay)`.
    HardOverlay = 29,
    /// `base + overlay == 0 ? 0 : 2·base·overlay/(base + overlay)`.
    Harmonic = 30,
    /// `base == 0 ? 0 : 1 − min((1−overlay)²/base, 1)`.
    Heat = 31,
    /// `(2 − cos(base·π) − cos(overlay·π))/4`.
    Interpolate = 32,
    /// `overlay + 2·base − 1`.
    ///
    /// The C branches on `overlay < 0.5`, but both arms collapse to the same
    /// expression once `MAX == 2·HALF`, which holds in the `DEPTH == 32` branch.
    /// The 8-bit path differs by one LSB.
    LinearLight = 33,
    /// `8·(base−0.5)·overlay + 0.5`.
    Multiply128 = 34,
    /// `1 − |1 − base − overlay|`.
    Negation = 35,
    /// Bitwise `or` of the two 8-bit samples.
    Or = 36,
    /// `min(base, overlay) − max(base, overlay) + 1`.
    Phoenix = 37,
    /// `overlay < 0.5 ? min(base, 2·overlay) : max(base, 2·overlay − 1)`.
    PinLight = 38,
    /// `overlay ≥ 1 ? overlay : min(1, base²/(1−overlay))`.
    Reflect = 39,
    /// `base > overlay ? (overlay ≥ 1 ? 0 : (base−overlay)/(1−overlay))`
    /// `: (overlay ≤ 0 ? 0 : (overlay−base)/overlay)`.
    SoftDifference = 40,
    /// `2 − base − overlay`.
    Stain = 41,
    /// `base < 0.5 ? burn(2·base, overlay) : dodge(2·base − 1, overlay)`.
    VividLight = 42,
    /// Bitwise `xor` of the two 8-bit samples.
    Xor = 43,
}

// BlendModeNode

#[cfg(feature = "wgpu")]
struct BlendPipeline {
    render_pipeline: wgpu::RenderPipeline,
    bind_group_layout: wgpu::BindGroupLayout,
    sampler: wgpu::Sampler,
    uniform_buf: wgpu::Buffer,
}

/// Apply a Photoshop-compatible blend mode to two input textures.
///
/// `input_count() = 2` — `inputs[0]` is the base layer, `inputs[1]` is the
/// overlay.  The `opacity` field attenuates the overlay's contribution.
///
/// For the CPU path the overlay data must be stored in `overlay_rgba`.
pub struct BlendModeNode {
    /// Blend algorithm.
    pub mode: BlendMode,
    /// Porter-Duff operator applied after the blend. Defaults to
    /// [`CompositeOp::Over`], which is what the node did before #1670.
    pub composite_op: CompositeOp,
    /// Overlay opacity (0.0 = invisible, 1.0 = fully applied).
    pub opacity: f32,
    /// Overlay frame as RGBA bytes (required for CPU path).
    pub overlay_rgba: Vec<u8>,
    /// Width of `overlay_rgba`.
    pub overlay_width: u32,
    /// Height of `overlay_rgba`.
    pub overlay_height: u32,
    #[cfg(feature = "wgpu")]
    pipeline: std::sync::OnceLock<BlendPipeline>,
}

impl BlendModeNode {
    #[must_use]
    pub fn new(
        mode: BlendMode,
        opacity: f32,
        overlay_rgba: Vec<u8>,
        overlay_width: u32,
        overlay_height: u32,
    ) -> Self {
        Self {
            mode,
            composite_op: CompositeOp::Over,
            opacity,
            overlay_rgba,
            overlay_width,
            overlay_height,
            #[cfg(feature = "wgpu")]
            pipeline: std::sync::OnceLock::new(),
        }
    }
}

impl RenderNodeCpu for BlendModeNode {
    #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
    fn process_cpu(&self, rgba: &mut [u8], _w: u32, _h: u32) {
        if self.overlay_rgba.len() != rgba.len() {
            log::warn!(
                "BlendModeNode::process_cpu skipped: size mismatch base={} overlay={}",
                rgba.len(),
                self.overlay_rgba.len()
            );
            return;
        }
        for (base, ov) in rgba
            .as_chunks_mut::<4>()
            .0
            .iter_mut()
            .zip(self.overlay_rgba.as_chunks::<4>().0.iter())
        {
            let br = f32::from(base[0]) / 255.0;
            let bg = f32::from(base[1]) / 255.0;
            let bb = f32::from(base[2]) / 255.0;
            let or = f32::from(ov[0]) / 255.0;
            let og = f32::from(ov[1]) / 255.0;
            let ob = f32::from(ov[2]) / 255.0;
            let oa = f32::from(ov[3]) / 255.0;
            let ba = f32::from(base[3]) / 255.0;

            let blended = blend_rgb(self.mode, [br, bg, bb], [or, og, ob]);
            // Premultiply the straight blend result, then composite (#1670).
            // Mirrors `blend.wgsl`'s tail; an out-of-range `opacity` extrapolates
            // and the `as u8` casts saturate, matching the shader's texture write.
            let sa = oa * self.opacity;
            let s = [blended[0] * sa, blended[1] * sa, blended[2] * sa];
            let (co, out_a) = composite_rgba(self.composite_op, s, sa, [br, bg, bb], ba);
            base[0] = (co[0].clamp(0.0, 1.0) * 255.0 + 0.5) as u8;
            base[1] = (co[1].clamp(0.0, 1.0) * 255.0 + 0.5) as u8;
            base[2] = (co[2].clamp(0.0, 1.0) * 255.0 + 0.5) as u8;
            base[3] = (out_a * 255.0 + 0.5) as u8;
        }
    }
}

// GPU: BlendModeNode

#[cfg(feature = "wgpu")]
impl BlendModeNode {
    #[allow(clippy::too_many_lines)]
    fn get_or_create_pipeline(&self, ctx: &crate::context::RenderContext) -> &BlendPipeline {
        self.pipeline.get_or_init(|| {
            let device = &ctx.device;
            let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
                label: Some("Blend shader"),
                source: wgpu::ShaderSource::Wgsl(include_str!("../../shaders/blend.wgsl").into()),
            });
            let bgl = two_tex_sampler_uniform_bgl(device, "Blend");
            let render_pipeline = fullscreen_pipeline(device, &shader, "Blend", &bgl);
            let sampler = linear_sampler(device, "Blend");
            let uniform_buf = device.create_buffer(&wgpu::BufferDescriptor {
                label: Some("Blend uniforms"),
                size: 16,
                usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
                mapped_at_creation: false,
            });
            BlendPipeline {
                render_pipeline,
                bind_group_layout: bgl,
                sampler,
                uniform_buf,
            }
        })
    }
}

#[cfg(feature = "wgpu")]
impl crate::nodes::RenderNode for BlendModeNode {
    fn input_count(&self) -> usize {
        2
    }

    fn process(
        &self,
        inputs: &[&wgpu::Texture],
        outputs: &[&wgpu::Texture],
        ctx: &crate::context::RenderContext,
    ) {
        let Some(tex_base) = inputs.first() else {
            log::warn!("BlendModeNode::process called with no inputs");
            return;
        };
        let Some(output) = outputs.first() else {
            log::warn!("BlendModeNode::process called with no outputs");
            return;
        };
        let pd = self.get_or_create_pipeline(ctx);

        // Upload overlay frame.
        let ov_tex = upload_rgba_texture(
            ctx,
            &self.overlay_rgba,
            self.overlay_width,
            self.overlay_height,
            "Blend overlay",
        );

        // Write uniforms: [mode_u32, opacity_f32, pad, pad] = 16 bytes.
        let uniforms = super::blend_uniform_bytes(self.mode, self.composite_op, self.opacity);
        ctx.queue.write_buffer(&pd.uniform_buf, 0, &uniforms);

        let base_view = tex_base.create_view(&wgpu::TextureViewDescriptor::default());
        let ov_view = ov_tex.create_view(&wgpu::TextureViewDescriptor::default());
        let out_view = output.create_view(&wgpu::TextureViewDescriptor::default());

        let bind_group = ctx.device.create_bind_group(&wgpu::BindGroupDescriptor {
            label: Some("Blend BG"),
            layout: &pd.bind_group_layout,
            entries: &[
                wgpu::BindGroupEntry {
                    binding: 0,
                    resource: wgpu::BindingResource::TextureView(&base_view),
                },
                wgpu::BindGroupEntry {
                    binding: 1,
                    resource: wgpu::BindingResource::TextureView(&ov_view),
                },
                wgpu::BindGroupEntry {
                    binding: 2,
                    resource: wgpu::BindingResource::Sampler(&pd.sampler),
                },
                wgpu::BindGroupEntry {
                    binding: 3,
                    resource: pd.uniform_buf.as_entire_binding(),
                },
            ],
        });

        submit_render_pass(ctx, &pd.render_pipeline, &bind_group, &out_view, "Blend");
    }
}

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

    #[test]
    fn blend_mode_multiply_should_produce_product_of_base_and_overlay() {
        // 50% grey × 50% grey = 25% grey (pixel-exact per acceptance criteria).
        let grey50 = vec![128u8, 128, 128, 255];
        let node = BlendModeNode::new(BlendMode::Multiply, 1.0, grey50.clone(), 1, 1);
        let mut rgba = grey50;
        node.process_cpu(&mut rgba, 1, 1);
        // 128/255 * 128/255 * 255 ≈ 64.25 → 64 or 65.
        let expected = (128.0_f32 / 255.0 * 128.0 / 255.0 * 255.0 + 0.5) as u8;
        let diff = (rgba[0] as i32 - expected as i32).abs();
        assert!(
            diff <= 1,
            "Multiply 50%×50% grey: expected ~{expected}, got {}",
            rgba[0]
        );
    }

    #[test]
    fn blend_mode_screen_should_be_brighter_than_either_input() {
        let base = vec![100u8, 100, 100, 255];
        let overlay = vec![150u8, 150, 150, 255];
        let node = BlendModeNode::new(BlendMode::Screen, 1.0, overlay, 1, 1);
        let mut rgba = base;
        node.process_cpu(&mut rgba, 1, 1);
        assert!(
            rgba[0] > 150,
            "Screen must be brighter than max input; got {}",
            rgba[0]
        );
    }

    #[test]
    fn blend_mode_normal_at_full_opacity_should_replace_base_with_overlay() {
        let base = vec![50u8, 50, 50, 255];
        let overlay = vec![200u8, 100, 50, 255];
        let node = BlendModeNode::new(BlendMode::Normal, 1.0, overlay, 1, 1);
        let mut rgba = base;
        node.process_cpu(&mut rgba, 1, 1);
        assert!(
            (rgba[0] as i32 - 200).abs() <= 1,
            "R should match overlay; got {}",
            rgba[0]
        );
        assert!(
            (rgba[1] as i32 - 100).abs() <= 1,
            "G should match overlay; got {}",
            rgba[1]
        );
    }

    #[test]
    fn blend_mode_normal_at_zero_opacity_should_leave_base_unchanged() {
        let base = vec![50u8, 80, 120, 255];
        let overlay = vec![200u8, 200, 200, 255];
        let node = BlendModeNode::new(BlendMode::Normal, 0.0, overlay, 1, 1);
        let mut rgba = base.clone();
        node.process_cpu(&mut rgba, 1, 1);
        assert!(
            (rgba[0] as i32 - 50).abs() <= 1,
            "R should match base; got {}",
            rgba[0]
        );
    }

    #[test]
    fn blend_mode_difference_of_equal_pixels_should_be_black() {
        let grey = vec![128u8, 128, 128, 255];
        let node = BlendModeNode::new(BlendMode::Difference, 1.0, grey.clone(), 1, 1);
        let mut rgba = grey;
        node.process_cpu(&mut rgba, 1, 1);
        assert!(
            rgba[0] <= 1,
            "Difference of same pixel must be ~black; got {}",
            rgba[0]
        );
    }

    #[test]
    fn blend_mode_add_should_clamp_at_white() {
        let bright = vec![200u8, 200, 200, 255];
        let node = BlendModeNode::new(BlendMode::Add, 1.0, bright.clone(), 1, 1);
        let mut rgba = bright;
        node.process_cpu(&mut rgba, 1, 1);
        assert_eq!(rgba[0], 255, "Add of two bright values must clamp to 255");
    }

    #[test]
    fn blend_mode_darken_should_return_minimum_channel() {
        let base = vec![100u8, 200, 50, 255];
        let overlay = vec![150u8, 50, 100, 255];
        let node = BlendModeNode::new(BlendMode::Darken, 1.0, overlay, 1, 1);
        let mut rgba = base;
        node.process_cpu(&mut rgba, 1, 1);
        assert!(
            (rgba[0] as i32 - 100).abs() <= 1,
            "Darken R: min(100,150)=100; got {}",
            rgba[0]
        );
        assert!(
            (rgba[1] as i32 - 50).abs() <= 1,
            "Darken G: min(200,50)=50; got {}",
            rgba[1]
        );
        assert!(
            (rgba[2] as i32 - 50).abs() <= 1,
            "Darken B: min(50,100)=50; got {}",
            rgba[2]
        );
    }

    #[test]
    fn blend_mode_size_mismatch_should_be_noop() {
        let overlay = vec![200u8; 8];
        let node = BlendModeNode::new(BlendMode::Normal, 1.0, overlay, 2, 1);
        let original = vec![50u8, 80, 120, 255];
        let mut rgba = original.clone();
        node.process_cpu(&mut rgba, 1, 1);
        assert_eq!(rgba, original, "size mismatch must leave base unchanged");
    }

    /// The discriminant is the value written into the shader's `mode` uniform, so
    /// renumbering a variant silently changes what `blend.wgsl` renders for it.
    /// This pins every code; a new variant needs a row here and a matching `case`
    /// in the shader.
    #[test]
    fn blend_mode_discriminants_should_match_the_shader_mode_codes() {
        let expected = [
            (BlendMode::Normal, 0),
            (BlendMode::Multiply, 1),
            (BlendMode::Screen, 2),
            (BlendMode::Overlay, 3),
            (BlendMode::SoftLight, 4),
            (BlendMode::HardLight, 5),
            (BlendMode::ColorDodge, 6),
            (BlendMode::ColorBurn, 7),
            (BlendMode::Difference, 8),
            (BlendMode::Exclusion, 9),
            (BlendMode::Add, 10),
            (BlendMode::Subtract, 11),
            (BlendMode::Darken, 12),
            (BlendMode::Lighten, 13),
            (BlendMode::Hue, 14),
            (BlendMode::Saturation, 15),
            (BlendMode::Color, 16),
            (BlendMode::Luminosity, 17),
            (BlendMode::And, 18),
            (BlendMode::Average, 19),
            (BlendMode::Bleach, 20),
            (BlendMode::Divide, 21),
            (BlendMode::Extremity, 22),
            (BlendMode::Freeze, 23),
            (BlendMode::Geometric, 24),
            (BlendMode::Glow, 25),
            (BlendMode::GrainExtract, 26),
            (BlendMode::GrainMerge, 27),
            (BlendMode::HardMix, 28),
            (BlendMode::HardOverlay, 29),
            (BlendMode::Harmonic, 30),
            (BlendMode::Heat, 31),
            (BlendMode::Interpolate, 32),
            (BlendMode::LinearLight, 33),
            (BlendMode::Multiply128, 34),
            (BlendMode::Negation, 35),
            (BlendMode::Or, 36),
            (BlendMode::Phoenix, 37),
            (BlendMode::PinLight, 38),
            (BlendMode::Reflect, 39),
            (BlendMode::SoftDifference, 40),
            (BlendMode::Stain, 41),
            (BlendMode::VividLight, 42),
            (BlendMode::Xor, 43),
        ];
        for (mode, code) in expected {
            assert_eq!(mode as u32, code, "{mode:?} moved to a different mode code");
        }
        assert_eq!(expected.len(), 44);
    }
}