Skip to main content

threers_codec/hevc/
deblock.rs

1//! The HEVC in-loop deblocking filter (§8.7.2), for all-intra pictures.
2//!
3//! Structurally unlike H.264's. It works on an 8×8 grid rather than 4×4, so
4//! only every other transform edge is a candidate; it decides per four lines
5//! whether to filter at all, and then whether to filter *strongly*, from the
6//! second differences either side of the edge; and the whole picture's vertical
7//! edges are filtered before any horizontal one, rather than interleaving per
8//! block. The net effect is a filter that leaves real detail alone more readily
9//! than H.264's does.
10//!
11//! Scope here: every coding unit intra, one slice, filter offsets zero. That
12//! pins the boundary strength at 2 on every filtered edge (§8.7.2.4) and makes
13//! the whole inter derivation unreachable. As on the H.264 side, intra
14//! prediction reads unfiltered samples, so this is a pass over the finished
15//! picture rather than something the reconstruction loop interleaves with.
16
17use crate::hevc::deblock_tables::{BETA, TC};
18
19#[inline]
20fn clip1(v: i32) -> u8 {
21    v.clamp(0, 255) as u8
22}
23
24/// Which 8×8-grid edges exist, at four-sample granularity.
25///
26/// An edge is only a candidate where a transform block actually ends. Inside a
27/// 32×32 transform there is nothing to smooth at sample 8, 16 or 24, and
28/// filtering there would blur real content — so the tree's leaf boundaries have
29/// to be recorded as it is built.
30pub struct EdgeMap {
31    left: Vec<bool>,
32    top: Vec<bool>,
33    w4: usize,
34}
35
36impl EdgeMap {
37    pub fn new(cw: u32, ch: u32) -> Self {
38        let (w4, h4) = ((cw / 4) as usize, (ch / 4) as usize);
39        Self {
40            left: vec![false; w4 * h4],
41            top: vec![false; w4 * h4],
42            w4,
43        }
44    }
45
46    /// Record the left and top edges of one transform block.
47    pub fn mark(&mut self, x: u32, y: u32, size: u32) {
48        if x.is_multiple_of(8) && x > 0 {
49            for r in (y..y + size).step_by(4) {
50                let i = (r / 4) as usize * self.w4 + (x / 4) as usize;
51                if i < self.left.len() {
52                    self.left[i] = true;
53                }
54            }
55        }
56        if y.is_multiple_of(8) && y > 0 {
57            for c in (x..x + size).step_by(4) {
58                let i = (y / 4) as usize * self.w4 + (c / 4) as usize;
59                if i < self.top.len() {
60                    self.top[i] = true;
61                }
62            }
63        }
64    }
65
66    /// Copy another map's marks into this one at `(x0, y0)`.
67    ///
68    /// Tiles are encoded as pictures of their own, so each builds an edge map in
69    /// its own coordinates; the picture-level filter needs them in one.
70    pub fn paste(&mut self, src: &EdgeMap, w: u32, h: u32, x0: u32, y0: u32) {
71        for ty in (0..h).step_by(4) {
72            for tx in (0..w).step_by(4) {
73                let si = (ty / 4) as usize * src.w4 + (tx / 4) as usize;
74                let di = ((y0 + ty) / 4) as usize * self.w4 + ((x0 + tx) / 4) as usize;
75                if si < src.left.len() && di < self.left.len() {
76                    self.left[di] = src.left[si];
77                    self.top[di] = src.top[si];
78                }
79            }
80        }
81        // A tile's own left and top edges are picture-internal block edges, and
82        // the filter is allowed across them
83        // (`loop_filter_across_tiles_enabled_flag`), so they have to be marked —
84        // the tile could not know that, having been encoded as a picture whose
85        // edge they were.
86        if x0 > 0 {
87            for ty in (0..h).step_by(4) {
88                let di = ((y0 + ty) / 4) as usize * self.w4 + (x0 / 4) as usize;
89                if di < self.left.len() {
90                    self.left[di] = true;
91                }
92            }
93        }
94        if y0 > 0 {
95            for tx in (0..w).step_by(4) {
96                let di = (y0 / 4) as usize * self.w4 + ((x0 + tx) / 4) as usize;
97                if di < self.top.len() {
98                    self.top[di] = true;
99                }
100            }
101        }
102    }
103
104    fn has_left(&self, x: u32, y: u32) -> bool {
105        let i = (y / 4) as usize * self.w4 + (x / 4) as usize;
106        i < self.left.len() && self.left[i]
107    }
108
109    fn has_top(&self, x: u32, y: u32) -> bool {
110        let i = (y / 4) as usize * self.w4 + (x / 4) as usize;
111        i < self.top.len() && self.top[i]
112    }
113}
114
115/// Filter the picture in place.
116///
117/// `qp_at` returns the decoder's `QpY` for a luma position, and `qp_c` maps a
118/// luma QP to its chroma counterpart.
119pub fn deblock(
120    y: &mut [u8],
121    u: &mut [u8],
122    v: &mut [u8],
123    cw: u32,
124    ch: u32,
125    edges: &EdgeMap,
126    qp_at: impl Fn(u32, u32) -> i32,
127    qp_c: impl Fn(i32) -> i32,
128) {
129    // Every vertical edge in the picture, then every horizontal one — the
130    // second pass reads what the first wrote (§8.7.2.1).
131    for x in (8..cw).step_by(8) {
132        for yy in (0..ch).step_by(4) {
133            if edges.has_left(x, yy) {
134                let qp = (qp_at(x - 1, yy) + qp_at(x, yy) + 1) >> 1;
135                luma_segment(y, cw, x, yy, 1, cw as isize, qp);
136            }
137        }
138    }
139    for yy in (8..ch).step_by(8) {
140        for x in (0..cw).step_by(4) {
141            if edges.has_top(x, yy) {
142                let qp = (qp_at(x, yy - 1) + qp_at(x, yy) + 1) >> 1;
143                luma_segment(y, cw, x, yy, cw as isize, 1, qp);
144            }
145        }
146    }
147
148    // Chroma sits on its own 8×8 grid, which in 4:2:0 is every sixteenth luma
149    // sample, and is filtered only where the luma boundary strength is 2 — which
150    // for an all-intra picture means wherever a luma edge exists at all.
151    let (cwc, chc) = (cw / 2, ch / 2);
152    for plane in [&mut *u, &mut *v] {
153        for cx in (8..cwc).step_by(8) {
154            for cy in (0..chc).step_by(4) {
155                let (lx, ly) = (cx * 2, cy * 2);
156                if edges.has_left(lx, ly) {
157                    let qp = (qp_at(lx - 1, ly) + qp_at(lx, ly) + 1) >> 1;
158                    chroma_segment(plane, cwc, cx, cy, 1, cwc as isize, qp_c(qp));
159                }
160            }
161        }
162        for cy in (8..chc).step_by(8) {
163            for cx in (0..cwc).step_by(4) {
164                let (lx, ly) = (cx * 2, cy * 2);
165                if edges.has_top(lx, ly) {
166                    let qp = (qp_at(lx, ly - 1) + qp_at(lx, ly) + 1) >> 1;
167                    chroma_segment(plane, cwc, cx, cy, cwc as isize, 1, qp_c(qp));
168                }
169            }
170        }
171    }
172}
173
174/// One four-line segment of a luma edge (§8.7.2.5.3 and §8.7.2.5.7).
175fn luma_segment(plane: &mut [u8], w: u32, x: u32, y: u32, step: isize, along: isize, qp: i32) {
176    let beta = BETA[qp.clamp(0, 51) as usize];
177    // Boundary strength 2 shifts the clipping table two places along.
178    let tc = TC[(qp + 2).clamp(0, 53) as usize];
179    if beta == 0 {
180        return;
181    }
182    let base = (y * w + x) as isize;
183    let at = |plane: &[u8], line: isize, i: isize| {
184        plane[(base + line * along + i * step) as usize] as i32
185    };
186
187    // The decision reads only the first and last of the four lines: HEVC judges
188    // the whole segment on its ends, where H.264 judges every line separately.
189    let d2 = |plane: &[u8], line: isize, i: isize| {
190        (at(plane, line, i - 3) - 2 * at(plane, line, i - 2) + at(plane, line, i - 1)).abs()
191    };
192    let dp0 = d2(plane, 0, 0);
193    let dq0 = (at(plane, 0, 2) - 2 * at(plane, 0, 1) + at(plane, 0, 0)).abs();
194    let dp3 = d2(plane, 3, 0);
195    let dq3 = (at(plane, 3, 2) - 2 * at(plane, 3, 1) + at(plane, 3, 0)).abs();
196    let (dpq0, dpq3) = (dp0 + dq0, dp3 + dq3);
197    let (dp, dq) = (dp0 + dp3, dq0 + dq3);
198    if dpq0 + dpq3 >= beta {
199        return;
200    }
201
202    let strong_line = |plane: &[u8], line: isize, dpq: i32| {
203        let (p0, p3) = (at(plane, line, -1), at(plane, line, -4));
204        let (q0, q3) = (at(plane, line, 0), at(plane, line, 3));
205        2 * dpq < (beta >> 2)
206            && (p3 - p0).abs() + (q0 - q3).abs() < (beta >> 3)
207            && (p0 - q0).abs() < ((5 * tc + 1) >> 1)
208    };
209    let strong = strong_line(plane, 0, dpq0) && strong_line(plane, 3, dpq3);
210    let ep = dp < ((beta + (beta >> 1)) >> 3);
211    let eq = dq < ((beta + (beta >> 1)) >> 3);
212
213    for line in 0..4isize {
214        let o = base + line * along;
215        let s = |plane: &[u8], i: isize| plane[(o + i * step) as usize] as i32;
216        let (p0, p1, p2, p3) = (s(plane, -1), s(plane, -2), s(plane, -3), s(plane, -4));
217        let (q0, q1, q2, q3) = (s(plane, 0), s(plane, 1), s(plane, 2), s(plane, 3));
218        let mut set = |i: isize, val: i32| plane[(o + i * step) as usize] = clip1(val);
219
220        if strong {
221            // Up to three samples a side move, each held within ±2tC of where
222            // it started so a strong filter can never invent a new edge.
223            let c = |orig: i32, val: i32| val.clamp(orig - 2 * tc, orig + 2 * tc);
224            set(-1, c(p0, (p2 + 2 * p1 + 2 * p0 + 2 * q0 + q1 + 4) >> 3));
225            set(-2, c(p1, (p2 + p1 + p0 + q0 + 2) >> 2));
226            set(-3, c(p2, (2 * p3 + 3 * p2 + p1 + p0 + q0 + 4) >> 3));
227            set(0, c(q0, (p1 + 2 * p0 + 2 * q0 + 2 * q1 + q2 + 4) >> 3));
228            set(1, c(q1, (p0 + q0 + q1 + q2 + 2) >> 2));
229            set(2, c(q2, (p0 + q0 + q1 + 3 * q2 + 2 * q3 + 4) >> 3));
230        } else {
231            let delta = (9 * (q0 - p0) - 3 * (q1 - p1) + 8) >> 4;
232            if delta.abs() >= tc * 10 {
233                continue;
234            }
235            let d = delta.clamp(-tc, tc);
236            set(-1, p0 + d);
237            set(0, q0 - d);
238            if ep {
239                let dp = ((((p2 + p0 + 1) >> 1) - p1 + d) >> 1).clamp(-(tc >> 1), tc >> 1);
240                set(-2, p1 + dp);
241            }
242            if eq {
243                let dq = ((((q2 + q0 + 1) >> 1) - q1 - d) >> 1).clamp(-(tc >> 1), tc >> 1);
244                set(1, q1 + dq);
245            }
246        }
247    }
248}
249
250/// One four-line segment of a chroma edge (§8.7.2.5.5). Chroma never gets the
251/// strong filter and never moves more than one sample a side.
252fn chroma_segment(plane: &mut [u8], w: u32, x: u32, y: u32, step: isize, along: isize, qp_c: i32) {
253    let tc = TC[(qp_c + 2).clamp(0, 53) as usize];
254    if tc == 0 {
255        return;
256    }
257    let base = (y * w + x) as isize;
258    for line in 0..4isize {
259        let o = base + line * along;
260        let s = |i: isize| plane[(o + i * step) as usize] as i32;
261        let (p0, p1) = (s(-1), s(-2));
262        let (q0, q1) = (s(0), s(1));
263        let d = ((((q0 - p0) << 2) + p1 - q1 + 4) >> 3).clamp(-tc, tc);
264        plane[(o - step) as usize] = clip1(p0 + d);
265        plane[o as usize] = clip1(q0 - d);
266    }
267}
268
269#[cfg(test)]
270mod tests {
271    use super::*;
272
273    fn full_map(cw: u32, ch: u32, tu: u32) -> EdgeMap {
274        let mut m = EdgeMap::new(cw, ch);
275        for y in (0..ch).step_by(tu as usize) {
276            for x in (0..cw).step_by(tu as usize) {
277                m.mark(x, y, tu);
278            }
279        }
280        m
281    }
282
283    /// Below `Q = 16` β is zero and the filter cannot fire, whatever the picture.
284    #[test]
285    fn low_qp_is_a_no_op() {
286        let (cw, ch) = (64u32, 32u32);
287        let mut y: Vec<u8> = (0..cw * ch).map(|i| ((i * 43) % 256) as u8).collect();
288        let mut u = vec![70u8; (cw * ch / 4) as usize];
289        let mut v = vec![190u8; (cw * ch / 4) as usize];
290        let (y0, u0, v0) = (y.clone(), u.clone(), v.clone());
291        deblock(
292            &mut y,
293            &mut u,
294            &mut v,
295            cw,
296            ch,
297            &full_map(cw, ch, 8),
298            |_, _| 10,
299            |q| q,
300        );
301        assert_eq!(y, y0, "luma untouched");
302        assert_eq!((u, v), (u0, v0), "chroma untouched");
303    }
304
305    /// Nothing may move where no transform block ends.
306    ///
307    /// This is the check that a 32×32 transform is not quietly sliced up by the
308    /// 8×8 filter grid: with only the 32-sample edges marked, samples around
309    /// x = 8, 16 and 24 have to come through untouched however sharp they are.
310    #[test]
311    fn only_marked_edges_are_filtered() {
312        let (cw, ch) = (64u32, 32u32);
313        let mut y: Vec<u8> = (0..cw * ch)
314            .map(|i| if (i % cw) % 8 < 4 { 60u8 } else { 190u8 })
315            .collect();
316        let before = y.clone();
317        let mut u = vec![128u8; (cw * ch / 4) as usize];
318        let mut v = vec![128u8; (cw * ch / 4) as usize];
319        deblock(
320            &mut y,
321            &mut u,
322            &mut v,
323            cw,
324            ch,
325            &full_map(cw, ch, 32),
326            |_, _| 40,
327            |q| q,
328        );
329        for row in 0..ch {
330            for col in 0..cw {
331                let near_marked = col % 32 < 4 || col % 32 >= 29;
332                if !near_marked {
333                    let i = (row * cw + col) as usize;
334                    assert_eq!(y[i], before[i], "({col},{row}) is not near a marked edge");
335                }
336            }
337        }
338    }
339
340    /// A flat picture has no edge to find at any QP.
341    #[test]
342    fn flat_picture_survives_any_qp() {
343        let (cw, ch) = (64u32, 64u32);
344        for qp in [20, 30, 40, 51] {
345            let mut y = vec![144u8; (cw * ch) as usize];
346            let mut u = vec![88u8; (cw * ch / 4) as usize];
347            let mut v = vec![201u8; (cw * ch / 4) as usize];
348            deblock(
349                &mut y,
350                &mut u,
351                &mut v,
352                cw,
353                ch,
354                &full_map(cw, ch, 8),
355                |_, _| qp,
356                |q| q,
357            );
358            assert!(y.iter().all(|&s| s == 144), "luma moved at qp {qp}");
359            assert!(u.iter().all(|&s| s == 88), "cb moved at qp {qp}");
360            assert!(v.iter().all(|&s| s == 201), "cr moved at qp {qp}");
361        }
362    }
363}