ff-filter 0.13.0

Video and audio filter graph operations - the Rust way
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

//! Blend mode definitions for video compositing operations.

// ── BlendMode ────────────────────────────────────────────────────────────────

/// Specifies how two video layers are combined during compositing.
///
/// Variants are grouped into two families:
///
/// - **Photographic blend modes** (18) — operate on pixel values; both layers
///   are typically opaque.  Implemented via `FFmpeg`'s `blend` filter with the
///   `all_mode` option, except [`BlendMode::Normal`] which uses `overlay`.
///
/// - **Porter-Duff alpha compositing** (6) — operate on the alpha channel;
///   at least the top layer must carry an alpha channel (e.g. `rgba` or
///   `yuva420p` pixel format).
///
/// # Implementation status
///
/// All 14 arithmetic photographic modes and all 6 Porter-Duff operations are
/// fully implemented and covered by regression tests (issues #327–#347).
///
/// The four HSL-space modes — [`BlendMode::Hue`], [`BlendMode::Saturation`],
/// [`BlendMode::Color`], and [`BlendMode::Luminosity`] — are accepted by the
/// builder but produce no output at runtime: `FFmpeg`'s `blend` filter does not
/// include these mode names in the bundled version.  The builder returns
/// [`FilterError::BuildFailed`](crate::FilterError) when the filter graph
/// cannot be configured for these modes.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BlendMode {
    // ── Photographic blend modes ──────────────────────────────────────────
    /// Standard alpha-over composite (top * opacity + bottom * (1 − opacity)).
    ///
    /// Implemented via `FFmpeg`'s `overlay=format=auto:shortest=1`.
    Normal,

    /// Multiply per-channel pixel values; darkens the result.
    ///
    /// Maps to `blend all_mode=multiply`.
    Multiply,

    /// Inverse of multiply; lightens the result.
    ///
    /// Maps to `blend all_mode=screen`.
    Screen,

    /// Combines Multiply and Screen based on base-layer luminance.
    ///
    /// Maps to `blend all_mode=overlay`.
    Overlay,

    /// Gentle contrast enhancement; 50 % gray top layer is identity.
    ///
    /// Maps to `blend all_mode=softlight`.
    SoftLight,

    /// Harsher version of Overlay; driven by the top layer's luminance.
    ///
    /// Maps to `blend all_mode=hardlight`.
    HardLight,

    /// Brightens the base by dividing it by the inverse of the blend.
    ///
    /// Maps to `blend all_mode=dodge`.
    ColorDodge,

    /// Darkens the base; inverse of Color Dodge.
    ///
    /// Maps to `blend all_mode=burn`.
    ColorBurn,

    /// Retains the darker of the two pixels per channel.
    ///
    /// Maps to `blend all_mode=darken`.
    Darken,

    /// Retains the lighter of the two pixels per channel.
    ///
    /// Maps to `blend all_mode=lighten`.
    Lighten,

    /// Per-channel absolute difference.  Useful for alignment verification.
    ///
    /// Maps to `blend all_mode=difference`.
    Difference,

    /// Similar to Difference but with lower contrast in mid-tones.
    ///
    /// Maps to `blend all_mode=exclusion`.
    Exclusion,

    /// Linear addition, clamped at maximum.
    ///
    /// Maps to `blend all_mode=addition`.
    Add,

    /// Linear subtraction, clamped at minimum.
    ///
    /// Maps to `blend all_mode=subtract`.
    Subtract,

    /// Applies the top layer's hue to the base's saturation and luminance.
    ///
    /// Maps to `blend all_mode=hue`.
    ///
    /// **Note**: not supported by the bundled `FFmpeg` `blend` filter; graph
    /// construction succeeds but no output frame is produced at runtime.
    Hue,

    /// Applies the top layer's saturation to the base's hue and luminance.
    ///
    /// Maps to `blend all_mode=saturation`.
    ///
    /// **Note**: not supported by the bundled `FFmpeg` `blend` filter; graph
    /// construction succeeds but no output frame is produced at runtime.
    Saturation,

    /// Applies the top layer's hue + saturation to the base's luminance.
    ///
    /// Maps to `blend all_mode=color`.
    ///
    /// **Note**: not supported by the bundled `FFmpeg` `blend` filter; graph
    /// construction succeeds but no output frame is produced at runtime.
    Color,

    /// Applies the top layer's luminance to the base's hue and saturation.
    ///
    /// Maps to `blend all_mode=luminosity`.
    ///
    /// **Note**: not supported by the bundled `FFmpeg` `blend` filter; graph
    /// construction succeeds but no output frame is produced at runtime.
    Luminosity,

    // ── Porter-Duff alpha compositing ─────────────────────────────────────
    /// Top layer rendered over the bottom (standard alpha compositing).
    ///
    /// Implemented via `overlay=format=auto:shortest=1`.
    PorterDuffOver,

    /// Bottom layer rendered over the top; equivalent to `Over` with inputs swapped.
    PorterDuffUnder,

    /// Top layer masked by the bottom layer's alpha (intersection).
    PorterDuffIn,

    /// Top layer visible only where the bottom layer is transparent.
    PorterDuffOut,

    /// Top layer placed atop the bottom; visible only where the bottom is opaque.
    PorterDuffAtop,

    /// Pixels from exactly one layer (XOR of opaque regions).
    PorterDuffXor,
}