still265 0.6.1

Pure-Rust HEVC/H.265 still-image encoder with BPG and HEIC support
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
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
//! Adaptive quantization (AQ) writer state, per-CU QP derivation, and QP delta
//! CABAC encoding.
//!
//! Ported from `bpgenc.c`'s `x265_glue.c` AQ integration (`aq_qg_target`,
//! `aq_cu_begin`, `aq_take_cu_qp_delta`, `encode_cu_qp_delta`). The prediction
//! mirror matches `bpg-hevc-decode::hevc::ctu::decode_quantization_parameters`.

use crate::cabac::CabacEncoder;
use crate::contexts::{Contexts, ctx};
use crate::internal::bpg_bitstream::BitWriter;

use super::types::chroma_qp_from_luma;

// `QG_LOG2` (= 5, 32x32) is only the *default* quantization-group size; the
// runtime size for an encode lives in [`AqState::qg_log2`] (4 for the
// `aq_qg = 16` opt-in) and must be used for every QG-grid computation here so
// the encoder mirror tracks the PPS `diff_cu_qp_delta_depth` it emitted.

/// Adaptive-quantization writer state — the encoder-side mirror of the decoder's
/// `decode_quantization_parameters` QP-prediction machine
/// (`bpg-hevc-decode::hevc::ctu`). Inert (`active == false`) for uniform-QP
/// encodes; otherwise every field tracks the decoder's
/// per-quantization-group state in decoding order so that the `cu_qp_delta` the
/// encoder emits resolves, on the decoder, back to the exact QP the encoder
/// quantized with.
///
/// The "decouple property": the encoder quantizes each TU with its target QP
/// **and** emits `cu_qp_delta = target − pred`. The decoder lands on `pred +
/// delta`, which equals `target` iff this prediction (`pred`) matches the
/// decoder's — so the prediction mirror is the only correctness-critical part,
/// verified by reconstruction equality. The QP a quantization group is *constant*
/// across all its coded CUs because the prediction uses QG-boundary neighbours
/// (not CU-boundary), exactly as the decoder does.
#[derive(Clone)]
pub(super) struct AqState {
    /// Adaptive QP active for this encode.
    pub(super) active: bool,
    /// log2 of the quantization-group size in luma samples (5 = 32x32 default,
    /// 4 = 16x16 opt-in), from [`crate::resolve_aq_qg_log2`]. Must agree with
    /// the PPS `diff_cu_qp_delta_depth` (`CTB_LOG2 − qg_log2`) — the decoder
    /// derives its QG grid from the PPS, and this mirror must match it.
    pub(super) qg_log2: u8,
    /// `6 * (bit_depth − 8)` — the QP bit-depth offset (H.265 8.6.1). All
    /// prediction arithmetic is in the *without-offset* `QpY` domain `[0,51]`
    /// (matching the decoder's `current_qpy`); quantization QPs add it back.
    pub(super) qp_bd_offset: i32,
    /// Slice luma QP (`QpY`, without offset) — the first-QG-in-slice prediction.
    pub(super) slice_qp_y: i32,
    /// `current_qpy` — last resolved `QpY` (without offset).
    pub(super) current_qpy: i32,
    /// `lastQpYinPrevQG` — `current_qpy` as of the previous quantization group.
    pub(super) last_qpy_prev_qg: i32,
    /// libbpg/FFmpeg-style rolling QP predictor, updated when a CU ends exactly
    /// on a QG boundary.
    pub(super) qpy_pred: i32,
    /// Whether the next QG is the first QP group in the slice.
    pub(super) first_qp_group: bool,
    /// Top-left luma position of the current quantization group (or −1 / unset).
    pub(super) qg_x: i32,
    pub(super) qg_y: i32,
    /// `IsCuQpDeltaCoded` — whether this QG has already carried its one delta.
    pub(super) coded: bool,
    /// `CuQpDeltaVal` — the delta resolved for the current QG (0 until coded).
    pub(super) cu_qp_delta: i32,
    /// `qPY_PRED` (the averaged neighbour prediction, without offset) for the CU
    /// currently being written — set in [`Encoder::aq_cu_begin`], consumed when
    /// the CU's first coded TU emits the delta.
    pub(super) pred: i32,
    /// Target `QpY` (without offset) for the CU currently being written.
    pub(super) cu_target: i32,
    /// Current CU geometry, needed to mirror the decoder's CU-level QP-map
    /// writes before and after the first coded TU carries `cu_qp_delta`.
    pub(super) cu_x: u32,
    pub(super) cu_y: u32,
    pub(super) cu_log2_size: u8,
    /// Memo for [`Encoder::aq_qg_target`]: the QG origin (`& !(QG-1)`) the cached
    /// `target` was computed for, or `(-1, -1)` when unset. The QG target is a
    /// pure function of QG position (slice QP + importance), so it is computed
    /// once per QG and reused across all of that QG's CUs (every recursion
    /// level) and the writer pass, instead of re-folding the importance map
    /// ~5–10× per QG.
    pub(super) target_qg: (i32, i32),
    pub(super) target: i32,
}

impl AqState {
    /// Reset the per-picture QG-prediction state to the slice start (first QG
    /// predicts from the slice QP). Called at each slice-data pass so the SAO
    /// two-pass re-entry doesn't inherit the previous pass's trailing QG state.
    /// The `target`/`target_qg` memo needs no reset — it is a pure function of QG
    /// position, so a stale entry self-corrects on the next position mismatch.
    pub(super) fn reset_for_slice(&mut self) {
        self.current_qpy = self.slice_qp_y;
        self.last_qpy_prev_qg = self.slice_qp_y;
        self.qpy_pred = self.slice_qp_y;
        self.first_qp_group = true;
        self.qg_x = -1;
        self.qg_y = -1;
        self.coded = false;
        self.cu_qp_delta = 0;
    }
}

impl<'a> super::Encoder<'a> {
    // --- Adaptive quantization (Phase B) -----------------------------------
    //
    // These mirror the decoder's `decode_quantization_parameters`
    // (`bpg-hevc-decode::hevc::ctu`) so the per-CU QP the encoder quantizes with
    // is exactly the QP the decoder reconstructs. All arithmetic is in the
    // *without-offset* `QpY` domain (matching the decoder's `current_qpy`);
    // quantization QPs add `qp_bd_offset` back.

    /// Target `QpY` (without offset, clamped `[0,51]`) for the quantization group
    /// containing `(x0, y0)`. Snapped to the QG grid (`& !(QG-1)`) so every CU in
    /// a QG resolves to the identical QP — the invariant the decoder enforces by
    /// predicting from QG-boundary neighbours. Driven by the preanalysis
    /// `importance` of the QG cell (low importance ⇒ higher QP ⇒ fewer bits).
    ///
    /// Memoized on [`AqState`]: the target is a pure function of QG position, so
    /// it is folded from the importance map once per QG and reused across all of
    /// that QG's CUs (every recursion level) and the writer pass.
    pub(super) fn aq_qg_target(&mut self, x0: u32, y0: u32) -> i32 {
        let mask = (1u32 << self.aq.qg_log2) - 1;
        let (qx, qy) = ((x0 & !mask) as i32, (y0 & !mask) as i32);
        if (qx, qy) != self.aq.target_qg {
            let offset = if let Some(map) = &self.aq_offset_map {
                // Experiment path: immutable external per-QG offset map.
                map.offset_at(qx as u32, qy as u32)
            } else {
                use crate::AqMode::*;
                use crate::preanalysis as pre;
                let analysis = &self.analysis;
                // With 16x16 QGs the variance-family modes read the optional
                // fine (per-16x16) grid; absent (32x32 default) they read the
                // coarse 32x32 analysis cells. Both expose the same signals,
                // so the offset functions themselves stay grid-agnostic.
                let fine = self.fine_aq.as_deref();
                let (qx, qy) = (qx as u32, qy as u32);
                let strength = self.aq_strength;
                let clamp = self.aq_clamp;
                let qg_log2 = self.aq.qg_log2;
                match self.aq_mode {
                    Off => 0,
                    LegacyShrink => {
                        // One-directional importance shrink (legacy default).
                        // Importance is a contextual (classification) signal
                        // with no fine-grid analogue; a 16x16 QG folds the
                        // 32x32 cell(s) it touches, exactly like any block
                        // smaller than a cell.
                        let imp = analysis.importance_at(qx, qy, qg_log2);
                        pre::aq_qp_offset(imp)
                    }
                    Perceptual => pre::aq_qp_offset_variance(
                        fine.map_or_else(
                            || analysis.variance_at(qx, qy),
                            |f| f.variance_at(qx, qy),
                        ),
                        fine.map_or_else(
                            || analysis.frame_mean_log2var(),
                            |f| f.frame_mean_log2var(),
                        ),
                        strength,
                        true,
                        clamp,
                    ),
                    PsnrProbe => pre::aq_qp_offset_variance(
                        fine.map_or_else(
                            || analysis.variance_at(qx, qy),
                            |f| f.variance_at(qx, qy),
                        ),
                        fine.map_or_else(
                            || analysis.frame_mean_log2var(),
                            |f| f.frame_mean_log2var(),
                        ),
                        strength,
                        false,
                        clamp,
                    ),
                    PerceptualChroma => pre::aq_qp_offset_chroma(
                        fine.map_or_else(
                            || analysis.variance_at(qx, qy),
                            |f| f.variance_at(qx, qy),
                        ),
                        fine.map_or_else(
                            || analysis.chroma_activity_at(qx, qy),
                            |f| f.chroma_activity_at(qx, qy),
                        ),
                        fine.map_or_else(
                            || analysis.frame_mean_log2activity(),
                            |f| f.frame_mean_log2activity(),
                        ),
                        strength,
                        clamp,
                    ),
                    AutoVariance | AutoVarianceBiased => pre::aq_qp_offset_autovar(
                        fine.map_or_else(
                            || analysis.autovar_qp_adj0_at(qx, qy),
                            |f| f.autovar_qp_adj0_at(qx, qy),
                        ),
                        fine.map_or_else(|| analysis.autovar_avg_adj(), |f| f.autovar_avg_adj()),
                        fine.map_or_else(
                            || analysis.autovar_avg_adj_final(),
                            |f| f.autovar_avg_adj_final(),
                        ),
                        strength,
                        self.aq_mode == AutoVarianceBiased,
                        clamp,
                    ),
                    PositiveProbe => pre::aq_qp_offset_positive(
                        fine.map_or_else(
                            || analysis.variance_at(qx, qy),
                            |f| f.variance_at(qx, qy),
                        ),
                        fine.map_or_else(
                            || analysis.frame_min_log2var(),
                            |f| f.frame_min_log2var(),
                        ),
                        fine.map_or_else(
                            || analysis.frame_max_log2var(),
                            |f| f.frame_max_log2var(),
                        ),
                        clamp,
                    ),
                    // Two-pass measured AQ always supplies an in-memory
                    // `aq_offset_map` for pass 2 (handled by the branch above);
                    // with no map it degrades to uniform.
                    TwoPassMeasured => 0,
                }
            };
            self.aq.target = (self.aq.slice_qp_y + offset).clamp(0, 51);
            self.aq.target_qg = (qx, qy);
        }
        self.aq.target
    }

    /// Set the per-CU quantization QPs (`cur_qp_y`/`cur_qp_c`, *with* offset) from
    /// the QG target, mirroring the decoder's luma + chroma QP derivation
    /// (`decode_quantization_parameters`, chroma via [`chroma_qp_from_luma`]).
    pub(super) fn aq_set_cu_qp(&mut self, x0: u32, y0: u32) {
        let target = self.aq_qg_target(x0, y0);
        let off = self.aq.qp_bd_offset;
        self.cur_qp_y = target + off;
        let qpi_c = (target + crate::chroma_qp_offset() as i32).clamp(-off, 57);
        self.cur_qp_c = chroma_qp_from_luma(qpi_c, self.cat) + off;
    }

    /// Read a neighbour CU's resolved `QpY` (without offset) from the per-4x4 QP
    /// map — the encoder analogue of the decoder's `get_qpy_at`.
    pub(super) fn aq_get_qpy_at(&self, x: u32, y: u32) -> i32 {
        let stride = self.frame.deblock_stride;
        let idx = ((y / 4) * stride + (x / 4)) as usize;
        self.frame
            .qp_map
            .get(idx)
            .map(|&q| q as i32)
            .unwrap_or(self.aq.slice_qp_y)
    }

    /// H.265 8.6.1 final-QP wrap (`((pred + delta + 52 + 2*off) % (52+off)) - off`).
    /// A no-op for in-range 8-bit QPs; matters only for the 10/12-bit offset.
    pub(super) fn aq_resolve_qpy(&self, pred: i32, delta: i32) -> i32 {
        let off = self.aq.qp_bd_offset;
        ((pred + delta + 52 + 2 * off) % (52 + off)) - off
    }

    /// Reset the per-quantization-group delta state, mirroring the decoder's
    /// `coding_quadtree` reset at every node `>=` the QG size (and at CTU start).
    /// Called from the writer at each `write_cu` node with
    /// `log2_cb_size >= qg_log2` — the decoder's condition is
    /// `log2_cb_size >= log2_ctb_size − diff_cu_qp_delta_depth`.
    pub(super) fn aq_qg_reset(&mut self) {
        self.aq.coded = false;
        self.aq.cu_qp_delta = 0;
    }

    /// At a coding-unit (leaf) start in the writer: compute `qPY_PRED` from the
    /// QG-boundary neighbours and the current (possibly already-coded) QG delta,
    /// exactly as `decode_quantization_parameters`, and record the CU's target.
    pub(super) fn aq_cu_begin(&mut self, cu_x: u32, cu_y: u32, cu_log2_size: u8) {
        self.aq.cu_x = cu_x;
        self.aq.cu_y = cu_y;
        self.aq.cu_log2_size = cu_log2_size;
        let qg_mask = (1u32 << self.aq.qg_log2) - 1;
        let x_qg = (cu_x & !qg_mask) as i32;
        let y_qg = (cu_y & !qg_mask) as i32;
        if x_qg != self.aq.qg_x || y_qg != self.aq.qg_y {
            self.aq.last_qpy_prev_qg = self.aq.current_qpy;
            self.aq.qg_x = x_qg;
            self.aq.qg_y = y_qg;
        }

        // libbpg/FFmpeg get_qPy_pred(): start from the slice QP for the first
        // QP group, otherwise from the rolling qPy_pred saved at QG boundaries.
        let pred0 = if self.aq.first_qp_group || (x_qg == 0 && y_qg == 0) {
            self.aq.slice_qp_y
        } else {
            self.aq.qpy_pred
        };

        let ctb_size = 1u32 << super::types::CTB_LOG2;
        let ctb_x = cu_x / ctb_size;
        let ctb_y = cu_y / ctb_size;
        let ctb_mask = ctb_size - 1;

        // qpYA/qpYB availability follows libbpg: the CU base and QG base must
        // both be nonzero within the current CTB.
        let qp_y_a = if x_qg > 0 && (cu_x & ctb_mask) != 0 && ((x_qg as u32) & ctb_mask) != 0 {
            let left_x = (x_qg as u32) - 1;
            let left_ctb_x = left_x / ctb_size;
            if left_ctb_x == ctb_x {
                self.aq_get_qpy_at(left_x, y_qg as u32)
            } else {
                pred0
            }
        } else {
            pred0
        };

        let qp_y_b = if y_qg > 0 && (cu_y & ctb_mask) != 0 && ((y_qg as u32) & ctb_mask) != 0 {
            let above_y = (y_qg as u32) - 1;
            if above_y / ctb_size == ctb_y {
                self.aq_get_qpy_at(x_qg as u32, above_y)
            } else {
                pred0
            }
        } else {
            pred0
        };

        let pred = (qp_y_a + qp_y_b + 1) >> 1;
        self.aq.pred = pred;
        self.aq.current_qpy = self.aq_resolve_qpy(pred, self.aq.cu_qp_delta);
        self.aq.cu_target = self.aq_qg_target(cu_x, cu_y);
        self.frame
            .store_block_qp(cu_x, cu_y, 1u32 << cu_log2_size, self.aq.current_qpy as i8);
    }

    /// Finish the QP state update that libbpg performs after both
    /// `hls_coding_unit` and split `hls_coding_quadtree` nodes: when the node's
    /// bottom-right corner lands on a QG boundary, its resolved QP becomes the
    /// rolling prediction for later QGs. The split-node case matters on
    /// partially outside picture edges, where forced splits can otherwise leave
    /// the predictor one QG behind stock/libbpg.
    pub(super) fn aq_node_end(&mut self, x0: u32, y0: u32, log2_size: u8) {
        let mask = (1u32 << self.aq.qg_log2) - 1;
        let size = 1u32 << log2_size;
        if ((x0 + size) & mask) == 0 && ((y0 + size) & mask) == 0 {
            self.aq.qpy_pred = self.aq.current_qpy;
        }
    }

    /// At the CU's first coded TU: resolve and record the QG's `cu_qp_delta`
    /// (`target − qPY_PRED`), marking the QG coded, and return the delta for the
    /// caller to emit into CABAC. Mirrors the decoder's
    /// `decode_transform_unit` → re-run of `decode_quantization_parameters`.
    pub(super) fn aq_take_cu_qp_delta(&mut self) -> i32 {
        let delta = self.aq.cu_target - self.aq.pred;
        self.aq.coded = true;
        if self.aq.first_qp_group || (self.aq.qg_x == 0 && self.aq.qg_y == 0) {
            self.aq.first_qp_group = false;
        }
        self.aq.cu_qp_delta = delta;
        self.aq.current_qpy = self.aq_resolve_qpy(self.aq.pred, delta);
        self.frame.store_block_qp(
            self.aq.cu_x,
            self.aq.cu_y,
            1u32 << self.aq.cu_log2_size,
            self.aq.current_qpy as i8,
        );
        delta
    }
}

/// Emit `cu_qp_delta_abs` + sign for adaptive QP (H.265 7.3.8.11), the exact
/// inverse of the decoder's `decode_cu_qp_delta_abs` + sign bypass: a
/// truncated-unary prefix (<=5 bins; ctx `CU_QP_DELTA_ABS` for bin 0, `+1` for
/// the rest), an EGk(0) bypass suffix when the prefix saturates at 5, then one
/// bypass sign bin when the magnitude is non-zero.
pub(super) fn encode_cu_qp_delta(
    enc: &mut CabacEncoder,
    w: &mut BitWriter,
    ctxs: &mut Contexts,
    delta: i32,
) {
    let abs = delta.unsigned_abs();
    let prefix = abs.min(5);
    enc.encode_bin(w, (prefix >= 1) as u8, ctxs.get(ctx::CU_QP_DELTA_ABS));
    if prefix >= 1 {
        for _ in 1..prefix {
            enc.encode_bin(w, 1, ctxs.get(ctx::CU_QP_DELTA_ABS + 1));
        }
        if prefix < 5 {
            enc.encode_bin(w, 0, ctxs.get(ctx::CU_QP_DELTA_ABS + 1));
        }
    }
    if abs >= 5 {
        encode_egk0_bypass(enc, w, abs - 5);
    }
    if abs >= 1 {
        enc.encode_bin_ep(w, (delta < 0) as u8);
    }
}

/// Emit `value` as an order-0 Exp-Golomb code in bypass mode — the inverse of the
/// decoder's `decode_egk_bypass(0)`: `m` unary one-bits (`m = floor(log2(value+1))`)
/// terminated by a zero, then the `m`-bit binary remainder, all MSB-first.
pub(super) fn encode_egk0_bypass(enc: &mut CabacEncoder, w: &mut BitWriter, value: u32) {
    let mut m = 0u32;
    while (1u32 << (m + 1)) - 1 <= value {
        m += 1;
    }
    for _ in 0..m {
        enc.encode_bin_ep(w, 1);
    }
    enc.encode_bin_ep(w, 0);
    if m > 0 {
        let suffix = value - ((1u32 << m) - 1);
        enc.encode_bins_ep(w, suffix, m);
    }
}