Crate rusty_h264_accel 

Optional hand-tuned x86 assembly acceleration using openh264’s BSD-2 kernels.

This crate is deliberately not #![forbid(unsafe_code)]: it links and calls hand-written assembly through FFI. It is the opt-in “speed over the pure-safe-Rust guarantee” path — the rest of the codec stays forbid(unsafe) and falls back to the scalar/wide implementations when this crate is not enabled.

openh264 asm is BSD-2 licensed; attribution lives in openh264/LICENSE.

The vendored kernels are x86-64 only. On every other architecture this crate compiles to an empty lib (the whole module is gated on target_arch = "x86_64") and callers fall back to the pure-Rust scalar path — selected by the accel cfg that the consumer crates’ build scripts set only for x86_64 + the asm feature. This is what lets a downstream default-features build (e.g. rff) succeed on arm64 macOS.

Structs

MeCtx

Functions

bs_motion_masks

Safe dispatcher: AVX2 when present, else the caller’s scalar twin. Returns None when AVX2 is unavailable so the caller keeps its own oracle path.

bs_motion_masks_two_list

Safe dispatcher for the two-list masks kernel; None when AVX2 is absent.

chroma8x8_pred

8×8 chroma intra prediction into pred (16-aligned, ≥64 bytes) via openh264’s WelsIChromaPred{V,Plane}_sse2. rec[base] = chroma MB top-left; reads the top row / left col from the aligned plane. mode: 2=Vertical, 3=Plane (the only modes with sse2; DC/Horizontal are C-only → caller uses scalar). Bit-identical to chroma8x8_pred.

dct_four_t4

Forward 4×4 core DCT of an 8×8 region (four 4×4 blocks) of the residual src - pred, via openh264’s WelsDctFourT4_sse2. Writes 64 i16 coefficients to dct: blocks in (0,0),(4,0),(0,4),(4,4) order, raster within each block. The integer core transform is bit-identical to our scalar forward_core (out0=s0+s1, out1=2·s3+s2, out2=s0-s1, out3=s3-2·s2), so quantizing these coefficients yields identical levels — a pure speedup, byte-for-byte.

deblock_chroma_eq4_h

Chroma strong filter (bS == 4) of a vertical edge, Cb+Cr, via DeblockChromaEq4H_ssse3.

deblock_chroma_eq4_v

Chroma strong filter (bS == 4) of a horizontal edge, Cb+Cr, via DeblockChromaEq4V_ssse3.

deblock_chroma_lt4_h

Chroma loop filter of a vertical edge (bS < 4), Cb+Cr, via DeblockChromaLt4H_ssse3 (p/q horizontal). *_p1 start at p1 = 2 cols left of q0; pPix = p1 + 2. tc as _v.

deblock_chroma_lt4_v

Chroma loop filter of a horizontal edge (bS < 4), Cb+Cr together, via DeblockChromaLt4V_ssse3 (p/q vertical). *_p1 start at p1 = 2 rows above q0; pPix = p1 + 2·stride. tc[i] per 2-sample segment (the spec chroma tc0+1; 0 = skip). Bit-identical to our filter_chroma_line.

deblock_luma_eq4_h

In-place loop filter of a vertical luma edge (bS == 4, strong) via transpose → DeblockLumaEq4V → transpose-back. p4 as in deblock_luma_lt4_h.

deblock_luma_eq4_v

In-place loop filter of a horizontal luma edge (bS == 4, strong) via openh264’s DeblockLumaEq4V_ssse3. p3 as in deblock_luma_lt4_v.

deblock_luma_lt4_h

In-place loop filter of a vertical luma edge (bS < 4) via transpose → DeblockLumaLt4V → transpose-back (openh264’s DeblockLumaLt4H C wrapper). p4 starts at p3 = column x−4 of the top row; the kernels transpose the 16×8 region, filter the now-horizontal edge, and write back. Bit-identical to our spec filter.

deblock_luma_lt4_v

In-place loop filter of a horizontal luma edge (bS < 4) via openh264’s DeblockLumaLt4V_ssse3. The “V” filter direction is vertical (p0 = pPix[-stride]), applied across a horizontal edge’s 16 columns; tc[i] per 4-column segment (−1 = skip). p3 starts at p3 = 4 rows above q0 (same column); pPix = q0 = +4·stride. Bit-identical to the spec filter (our filter_luma_line).

dequant_4x4

Safe dispatcher. None = no AVX2, caller keeps its scalar twin (the oracle).

hpel_fused

Builds the three half-pel planes from the edge-padded full-pel plane f (pw×ph, row stride pw). Returns false (no work done) when AVX2 is unavailable or the plane is too narrow for the vector interior — the caller falls back to its scalar/tile path.

i16x16_luma_pred

16×16 luma intra prediction into pred (must be 16-aligned, ≥256 bytes) via openh264’s WelsI16x16LumaPred{V,H,Dc,Plane}_sse2. rec[base] = MB top-left; the kernel reads the top row (rec[base−stride+i]) and/or left col (rec[base−1+i·stride]) and writes the 16×16 prediction. mode: 0=V, 1=H, 2=DC, 3=Plane — caller ensures the required neighbors exist (both for DC/Plane). Bit-identical to the spec predictor.

idct_four_t4_rec

mb_uniform

Safe dispatcher for [mb_uniform_avx2]; None means “no AVX2, use your scalar twin”.

mc_centre

Centre half-pel luma plane (McHorVer22, the (2,2) separable 6-tap) of a w×h block, via openh264’s 2-stage HorFirst (horizontal 6-tap → full-precision i16 tap buffer) + VerLastAlign (vertical 6-tap → clip((·+512)>>10)). width-16 = two width-8 halves. The 2D 6-tap is separable, so H-first matches our V-first luma_centre exactly. t[half·8 + row·ts] feeds each half’s HorFirst (the tile’s 2-col/2-row border = the pSrc−2 shift). Bit-identical.

mc_chroma_w4

Eighth-pel chroma bilinear MC of a 4-wide block (McChromaWidthEq4_mmx) — same formula and abcd weights as mc_chroma_w8, for the narrower block.

mc_chroma_w8

Eighth-pel chroma bilinear MC of an 8-wide block (McChromaWidthEq8_sse2): dst[r,c] = (A·s[r,c] + B·s[r,c+1] + C·s[r+1,c] + D·s[r+1,c+1] + 32) >> 6, where abcd = [A,B,C,D] = [(8−fx)(8−fy), fx(8−fy), (8−fx)fy, fx·fy] (g_kuiABCD). src is the edge-clamped 9×(height+1) tile (stride src_stride ≥ 9); the kernel reads 9 cols (movq at src and src+1) × height+1 rows. Bit-identical to the scalar bilinear in inter::mc_chroma.

mc_hor20

Horizontal half-pel luma plane (McHorVer20, the (2,0) 6-tap) of a w×h block. src[off] is the first output pixel in the (border-padded) tile, stride ts; the kernel reads src[off−2 .. off+3] per row. Writes the contiguous w·h result into dst. w ∈ {8,16}. Bit-identical to our luma_h.

mc_ver02

Vertical half-pel luma plane (McHorVer02, the (0,2) 6-tap) of a w×h block. width-16 = two width-8 halves into a stride-16 scratch (no sse2 02WidthEq16). Reads src[off−2·ts .. off+3·ts] per column. Bit-identical to our luma_v. w ∈ {8,16}.

pixel_avg

Per-pixel average of two w×h blocks at independent strides: dst[i] = (a[i] + b[i] + 1) >> 1, written contiguously at stride w.

quant_four_4x4

In-place quantization of four 4×4 DCT-coefficient blocks (64 i16) via openh264’s WelsQuantFour4x4_sse2: level = sign·(((|c| + FF)·MF) >> 16) with the per-position FF/MF tables (8 entries each, reused for both halves). NOTE: this is openh264’s quantizer (deadzone added before the multiply, fixed >>16), structurally different from our (|c|·MF + F) >> qbits — so it is NOT bit-identical to our quantize. Exposed for the kernel ranking + an openh264-semantics path; dct must be 16-byte aligned.

sad_8x16

SAD of an 8×16 luma block. Bit-identical to Σ|a−b|.

sad_16x8

SAD of a 16×8 luma block. Bit-identical to Σ|a−b|.

sad_16x16

SAD of a 16×16 luma block against another via openh264’s SSE2 psadbw kernel. Trivially bit-identical to Σ|a−b|. stride* in samples.

sad_x4

SADs of one w×h source block vs four offsets o into base (stride rs), for every ME partition shape. Values are exactly Σ|a−b| per candidate. None without AVX2 or for an uncovered shape.

satd_4x4

SATD (sum of absolute Hadamard-transformed differences) of two 4×4 blocks via openh264’s SSE2 kernel. stride* are in samples (bytes). Bit-identical to openh264’s WelsSampleSatd4x4_c ((Σ|H·d| + 1) >> 1).

satd_8x8

SATD of a 8×8 block pair via openh264’s Hadamard kernel (AVX2 when available, else SSE2 — bit-identical). Equal to the sum of the constituent 4×4 SATDs.

satd_8x16

SATD of a 8×16 block pair via openh264’s Hadamard kernel (AVX2 when available, else SSE2 — bit-identical). Equal to the sum of the constituent 4×4 SATDs.

satd_16x8

SATD of a 16×8 block pair via openh264’s Hadamard kernel (AVX2 when available, else SSE2 — bit-identical). Equal to the sum of the constituent 4×4 SATDs.

satd_16x16

SATD of a 16×16 block pair via openh264’s Hadamard kernel (AVX2 when available, else SSE2 — bit-identical). Equal to the sum of the constituent 4×4 SATDs.

satd_avg

Fused SATD(src, (a+b+1)>>1) of a w×h block — Σ|H·d|, the SAME value satd_px computes on the materialized average (NOT the (Σ+1)>>1 the WelsSampleSatd* wrappers return). None when AVX2 is unavailable or the size is unsupported — the caller then materializes and takes the old path, so a non-AVX2 machine is byte-identical by construction.

satd_avg_x4

Four fused avg+SATDs of one w×h source block: (plane_a, off_a, plane_b, off_b) per candidate, shared stride — the quarter-pel ring for every ME partition shape. None without AVX2 or for an uncovered shape.

satd_x4

Σ|H·d| SATDs of one w×h source block vs four offsets o into base (stride rs) — the diamond’s shape, for every ME partition. The exact scalar-Hadamard value (satd_px domain, NOT the (Σ+1)>>1 the Wels wrappers return). None without AVX2 or for an uncovered shape.

satd_x4p

Four SATDs (Σ|H·d|) of one w×h source block vs four INDEPENDENT plane operands (shared stride) — the sub-pel ring’s shape, now for every ME partition. None without AVX2 or for an uncovered shape.

x4_shape

True iff the x4 family covers this ME partition shape.