Crate rusty_h264_encoder

Expand description

Pure-Rust H.264 encoder — raw I420 frames in, a conformant Annex-B stream out.

Every frame it emits decodes bit-exactly under ffmpeg across QP 0–51, intra and inter. The crate is #![forbid(unsafe_code)]; the optional SIMD kernels behind the asm feature keep their unsafe quarantined in rusty_h264-accel, so that guarantee holds either way.

Coding tools, default-on: I_16x16/I_4x4/I_PCM intra with λ-based RD/SATD mode decision; P-frames (P_Skip, 16×16/16×8/8×16) with quarter-pel motion compensation, rate-aware ME and a multi-reference DPB; CABAC entropy coding (Main profile — set RUSTY_H264_LEGACY_CAVLC=1 to restore the Constrained Baseline + CAVLC bitstream byte-for-byte); adaptive quantization; the per-GOP I-frame QP cascade; in-loop deblocking; and average-bitrate rate control. Opt-in via EncoderConfig: B-frames (fixed or content-adaptive), the 8×8 transform, mb-tree temporal AQ, sub-8×8 partitions and RD P_Skip.

Preset picks the speed/quality trade-off — Fast (SAD, integer-pel), Balanced (adds sub-pel refinement; the default) or Quality (full RD trial-encode). The bitstream is valid either way; only the effort differs.

use rusty_h264_encoder::{Encoder, EncoderConfig};
use rusty_h264_common::YuvFrame;

let cfg = EncoderConfig::new(16, 16);
let mut enc = Encoder::new(cfg).unwrap();
let frame = YuvFrame::black(16, 16);
let bitstream = enc.encode(&frame); // Annex-B bytes for one access unit
assert!(!bitstream.is_empty());

Re-exports§

pub use crate::mb16::EXT_MV;
pub use crate::mb16::ME_PROBE;
pub use crate::mb16::MVCMP;
pub use crate::mb16::MVCMP_FRAME;

Modules§

bitacct: The BIT ACCOUNTANT — codec-analyzer instrument #6, the rate-domain twin of the stage profiler.
mb16: I_16x16 macroblock encoding (DC prediction) — the compressing intra path.

Structs§

Encoder: A Constrained Baseline H.264 encoder.
EncoderConfig: Configuration for an crate::Encoder.
Pps: Picture parameter set for a CAVLC, single-slice-group CBP encoder.
RateControl: Frame-level average-bitrate controller.
Sps: Sequence parameter set, carrying only the fields a CBP encoder emits.

Enums§

EncodeError: Errors that can arise constructing or driving the encoder.
LookaheadMode: Resolution the mb-tree lookahead motion search runs at (speed/quality lever). Measured on CIF (mb-tree BD-rate vs off / encode wall vs FullRes): FullRes mand −0.19% tsrc −1.80% (1.0×) · Hybrid −0.19% / −1.47% (~1.7×) · HalfRes +0.12% / −1.28% (~4×).
Preset: Speed/quality trade-off, in the spirit of x264’s -preset. The bitstream is valid (and decodes bit-exactly) either way; only the encoder’s effort differs.

Constants§

DIA_DEFAULT_MASK: Default diamond rung mask ([16,8,4]).

Functions§

diastats_reset
diastats_snapshot
mbtree_satd_calls: Lookahead candidate evaluations so far (mb-tree cost instrument, H-36) — a deterministic stand-in for wall time, which this box cannot measure at the precision the content effect needs. reset before an encode, read after.
mbtree_satd_reset: Zeroes mbtree_satd_calls.
satdpath_reset
satdpath_snapshot
set_defer_subpel
set_dia_mask: Descent A: select which rungs of the [64,32,16,8,4] diamond ladder to walk.
set_me_fc: Fixed-centre batched diamond passes (both cost domains). Off = cascade.
set_me_sadfp: Track-B B2: SAD-domain full-pel search phase (SATD from sub-pel on) — x264’s cost split. Bitstream-changing; BD-gated; off = byte-identical to pre-B2.
set_me_sadfp_mode: B2 mode: 0 off, 1 dispatched per frame by the b2_mgain probe, 2 force-on.
set_mv_smooth: H-23: smooth (x264-shape) mvd cost model in ME. Off = Exp-Golomb step fn.
set_mv_smooth_mode: H-24 mv-cost mode: 0 off, 1 dispatched per frame by mgain, 2 force-on.
set_sp_fc: Fixed-centre batched HALF-PEL sub-pel ring (satd_x4p). Off = cascade.
set_sp_maxit: Track-B B3: sub-pel iteration budget (0 = unlimited = byte-identical) — the bounded walk x264’s subme levels have; pairs with B2. BD-gated.
set_split_mg: H-13 split-dispatch threshold in milli-units of the mgain probe (0 = always search splits, byte-identical to pre-gate). Default 30 (= 0.03).
set_split_t
set_subme: The x264-style SUB-PEL EFFORT LADDER (H-10): one level selects a priced (ring pattern × iteration budget) rung — closing the ~24-vs-9 eval-count gap vs x264 as a BUDGET choice instead of a blanket cut.
set_subpel_dispatch
set_subpel_pattern
set_turbo: The SUPERFAST-CLASS rung (H-11/H-12): the Quality preset at x264 superfast’s partition SHAPE — P16×16-only (splits gated off), everything else (sub-pel ladder, B2 dispatch) at defaults. Measured fair-run on foreman: 1.81× faster than default quality and STILL −0.9% BD vs x264 superfast itself. The further effort cuts (subme 2 + SAD-fp force) were measured and REJECTED from this rung: no speed on top of shape-only (0.27× vs 0.28×) while costing BD (+1.9% foreman / +8.4% bus) — compose them manually via set_subme / set_me_sadfp_mode if wanted. Split-heavy content (bus-class) pays more at this rung; the per-frame split DISPATCH (H-11 next-brick b) is the eventual no-tax answer. Env twin: RFF_SPLIT_T=10000000.
spstats_redundant
spstats_reset
spstats_snapshot