Struct H264EncoderWrapper 

pub struct H264EncoderWrapper {

    encoder: *mut x264_t,
    pub width: i32,
    pub height: i32,
    current_crf: i32,
    pub is_i444: bool,
    pub bit_depth: u32,
    is_cbr: bool,
    current_bitrate: i32,
    current_vbv: i32,
    current_fps: FrameRate,
    threads: i32,
    min_qp: i32,
    max_qp: i32,
    references: ReferenceWindow,
    reference_frames: u32,
    last_reference: Reference,
    frame_num: WideFrameNum,
    current_min_qp: i32,
    held_qp: Option<i32>,
    last_qp: Option<u32>,
    rf_constant: f64,
    peak: Option<PeakOffset>,
    open_qp_max: i32,
    coded: Option<Coded>,
    last_capped: bool,
    bound_once: bool,
    last_key: Option<LastKey>,
    quant_offsets: Vec<f32>,
    mb_info: Vec<u8>,
    held_input: Option<*const u8>,
}

One long-lived libx264 session for a frame, holding the raw x264_t handle alongside a mirror of its live parameters so the encoder can be retuned per frame instead of rebuilt.

Rebuilding an x264 encoder is expensive and forces a fresh IDR, so a session keeps its instance across frames and only nudges CRF, bitrate, VBV, and frame rate live; the tracked current_* fields are that mirror, letting a reconfigure skip the FFI call whenever nothing actually changed. is_i444 (4:4:4 vs 4:2:0) is baked into the encoder’s color space at open, so a change to it is one of the few things that forces a full rebuild; is_cbr records which rate-control mode was chosen at open and gates which of the live reconfigures apply. The manual Send impl exists only because a raw pointer is not Send by default and the handle must move onto the encode thread; Drop closes it under the global open/close lock for the same reason that lock exists.

Fields

encoder: *mut x264_t

width: i32

height: i32

current_crf: i32

is_i444: bool

bit_depth: u32

The bits per sample the session was opened at, baked in as the chroma format is.

is_cbr: bool

current_bitrate: i32

current_vbv: i32

current_fps: FrameRate

threads: i32

Open-time parameters retained so a frame-rate change can reopen the session: x264’s live reconfigure cannot alter the frame rate, and CBR/VBV budgets are derived from it.

min_qp: i32

max_qp: i32

references: ReferenceWindow

The frames the decoder holds, so a lost one can be left out of the predictions and each frame can name what it predicts from.

reference_frames: u32

The most frames the decoded picture buffer keeps, 0 for the level’s (video_reference_frames), kept for a reopen.

last_reference: Reference

frame_num: WideFrameNum

The stream’s frame_num, widened from x264’s sixteen values to 4096.

current_min_qp: i32

The floor the rate control’s quantizer stands at now (reconfigure_floor), on the H.264 scale; 0 is x264’s own.

held_qp: Option<i32>

The quantizer the next frame is held at whatever the rate control (hold_quantizer).

last_qp: Option<u32>

The mean quantizer the rate control last coded a frame’s rows at, held frames aside.

rf_constant: f64

The live rate factor, which x264 reports a frame’s mean quantizer against (last_qp).

peak: Option<PeakOffset>

A capped CRF session’s peak (PeakOffset): x264’s own cap, a VBV, changes how it codes every frame whether the peak binds or not (a 720p scroll’s key frame at quantizer 27 for 22 under a 100 Mbit/s peak it never reached), and is taken only at open, so the session opens uncapped and the peak is held beside it. A key frame is aimed at half the bucket’s room, as x264’s VBV holds a frame to half its buffer’s fill: from the start where the last key frame says it would not fit (H264EncoderWrapper::aim_key), else by one encode more where its first comes out past the room (H264EncoderWrapper::fit_key). The quantizer ceiling it opened with, which the peak lowers to 51 while it binds.

open_qp_max: i32

coded: Option<Coded>

The frame the last encode coded (Coded), and whether it was coded coarser than the rate factor for the peak (coded_capped).

last_capped: bool

bound_once: bool

Whether the peak has bound a frame of the session (holds_cleanup).

last_key: Option<LastKey>

The last key frame’s first attempt (aim_key).

quant_offsets: Vec<f32>

The quantizer offset of each macroblock of the next frame, empty where it has none (refine_blocks).

mb_info: Vec<u8>

The next frame’s macroblocks that did not change (constant_blocks), as x264’s mb_info flags; empty where the source cannot say.

held_input: Option<*const u8>

The picture x264 still reads after its last encode (held_input).

Implementations

impl H264EncoderWrapper

pub fn new( width: i32, height: i32, crf: i32, is_i444: bool, fps: f64, threads: i32, cbr_mode: bool, bitrate_kbps: i32, vbv_kbit: i32, min_qp: i32, max_qp: i32, ) -> Option<Self>

Open an x264 encoder tuned for real-time screen streaming, or None on failure.

Why this configuration. These frames are captured live and must ship immediately, so the encoder is optimized for latency over compression ratio: the ultrafast preset keeps encode time under the frame budget, and zerolatency bars the frame reordering and lookahead buffering that would otherwise add pipeline delay. Everything below then bends x264 toward the pipeline’s own keyframe and color model instead of its broadcast-oriented defaults.

1. Preset/tune: starts from the ultrafast preset with the zerolatency tune, then overrides resolution, frame rate (floored to 30 fps when under 1), and thread count.
2. Infinite GOP: i_keyint_max is set to x264’s infinite sentinel and adaptive scene-cut is disabled (i_scenecut_threshold = 0), so the encoder never injects an unrequested IDR on a scene change — keyframes are purely on-demand via the forced-IDR path, matching the strict infinite-GOP model.
3. Rate control:
   • CBR (cbr_mode): ABR targeting bitrate_kbps with a VBV cap pinned to the same value (buffer vbv_kbit, precomputed by the caller from the frame-time multiplier policy) and filler disabled. max_qp is the legibility floor (caps how ugly a rate-starved frame gets) and min_qp the waste ceiling (stops over-spending on easy content); both are clamped to 51, and the ceiling is 51 when unset because x264’s own default admits out-of-spec quantizers above it that exist only to force skips when the VBV underflows, which leaves rows of the picture frozen on old content. A budget the content cannot meet overshoots instead, as NVENC and libvpx do.
   • CRF (default): constant-quality with f_rf_constant = crf. A positive vbv_kbit and bitrate_kbps cap it at that peak with a buffer of that size, held beside x264 (PeakOffset): the session opens as an uncapped one, and where the peak binds the rate factor rises, up to 51, so content the cap starves overshoots it rather than freezes. A vbv_kbit or bitrate_kbps of 0 leaves it uncapped.
4. Color: I444 at full range or I420 at limited range, a VUI declaring that range with the BT.709 primaries, transfer, and matrix the sRGB source and the conversion carry, and the matching high444 / baseline profile.
5. Coding tools: CABAC and the 8x8 transform are disabled, matching the low-latency baseline profile — CAVLC entropy coding with no 8x8 DCT — for minimal encode cost. Motion search is the uneven multi-hexagon one over 64 pixels in place of ultrafast’s diamond over 16, which misses a scroll or a moved window wherever its starting prediction is poor (a slice’s first row, the edge of a still region) and codes the shifted pixels as new: at 2560x1600 it took a scrolling full-screen change from 5.0 to 3.5 Mbit/s at the same PSNR for 0.14 ms more of encode, and a quarter of the screen from 5.0 to 4.4 for 0.09 ms, the search running only on the macroblocks mb_info leaves.
6. Output: repeated headers (SPS/PPS before each keyframe) and Annex-B framing, with x264’s own logging silenced.
7. References: a decoded picture buffer of REFERENCE_FRAMES (i_dpb_size), or of reference_frames where the caller caps it (video_reference_frames), declaring the lowest level up to 5.2 that holds them (h264_reference_level: 5.0 at 1080p, where 4.2 holds four), so invalidate_reference can leave a frame a client lost out of the predictions with earlier frames still there to predict from, for a report up to eight frames late (133 ms at 60 fps). Motion search keeps its single reference.
8. frame_num: x264 counts it in sixteen values for that buffer, and a loss covering the frame where it wraps costs a key frame (ReferenceWindow), so the stream carries it a byte wider (WideFrameNum): 4096 values, one such frame in 68 s at 60 fps.

The x264_encoder_open call is serialized under X264_OPEN_CLOSE_LOCK because it mutates libx264 global state.

pub fn with_depth( width: i32, height: i32, crf: i32, is_i444: bool, bit_depth: u32, fps: f64, threads: i32, cbr_mode: bool, bitrate_kbps: i32, vbv_kbit: i32, min_qp: i32, max_qp: i32, reference_frames: u32, ) -> Option<Self>

new at bit_depth bits per sample: 10 opens a High 10 session, or High 4:4:4 Predictive at 10 bits, which reads its planes as 16-bit samples; its decoded picture buffer keeps at most reference_frames, 0 for the level’s (video_reference_frames).

pub fn ten_bit() -> bool

Whether the linked libx264 opens a 10-bit session, which is a property of how the library was built, asked once of a session too small to cost anything.

fn open( width: i32, height: i32, crf: i32, is_i444: bool, bit_depth: u32, fps: f64, threads: i32, cbr_mode: bool, bitrate_kbps: i32, vbv_kbit: i32, min_qp: i32, max_qp: i32, reference_frames: u32, key: Option<(i32, i32)>, ) -> Option<Self>

new, with a constant-rate session’s first frame given a budget of its own where key names one, (budget_kbit, level_idc): the rate is that budget a frame and the VBV buffer that budget, full, until restore_rate, and the level is pinned to the one the session it replaces declared, which the raised rate would otherwise lift.

pub fn reconfigure_crf(&mut self, new_crf: i32)

Retune the constant-quality CRF on the running encoder, so a quality change costs a parameter push rather than tearing down and rebuilding the session (a rebuild would force an IDR and drop encoder state).

It is a no-op in CBR mode, where rate is bitrate-controlled and CRF simply does not apply, and a no-op when the value is unchanged — the tracked current_crf is what makes that cheap early-out possible. Otherwise it reads the encoder’s live parameters, overwrites f_rf_constant, and pushes the change via x264_encoder_reconfig, advancing the tracked CRF only once the reconfig has actually succeeded so the mirror never drifts from the encoder.

fn set_rate_factor(&mut self, crf: i32, offset: f64) -> bool

Put the rate factor at crf plus a peak’s offset, the quantizer ceiling at 51 while an offset holds and at the session’s own otherwise; true where x264 took it.

pub fn reconfigure_rate(&mut self, bitrate_kbps: i32, vbv_kbit: i32, fps: f64)

Retune bitrate/VBV (CBR, or a capped CRF’s peak) and/or frame rate to match the live settings, structured to be called unconditionally every frame so the caller need not track what changed itself.

Because encode_cpu fires it on every frame, it first computes the would-be values and bails before touching the encoder when neither the bitrate/VBV nor the frame rate differs from what is live — that self-gating keeps a per-frame call nearly free.

A frame-rate change reopens the encoder rather than reconfiguring it: x264_encoder_reconfig does not apply i_fps_*, and the CBR/VBV per-frame budget is bitrate / fps, so a session left at its old rate ships roughly half the configured bitrate once fps halves. The reopen carries the new bitrate/VBV too, and a fresh session emits an IDR on its first frame; a failed reopen keeps the working session instead of nulling the handle. A CRF session’s peak, set, moved, or lifted, never reaches x264 (follow_peak). A CBR bitrate/VBV-only change otherwise stays a live x264_encoder_reconfig, and the tracked mirror advances only on success so it cannot drift from the encoder’s real state.

pub fn last_reference(&self) -> Reference

The frame the last encoded frame predicted from.

pub fn last_qp(&self) -> Option<u32>

The mean quantizer the rate control last coded a frame’s rows at, held frames aside.

pub fn peak_bound(&self) -> bool

Whether the peak of a capped CRF session binds it: the rate factor stands above the session’s own (PeakOffset).

pub fn capped(&self) -> bool

Whether the session runs its CRF under a peak (PeakOffset).

pub fn idle(&mut self, settings: &CaptureSettings)

A tick that codes no frame, under the live settings: the peak follows them and its bucket drains as for an empty frame, the rate factor stepping back toward the session’s own, so a still screen lets the peak go.

pub fn coded_capped(&self) -> bool

Whether the last frame was coded coarser than the session’s rate factor for its peak: under a raised rate factor, or a key frame coded again within the bucket (fit_key).

pub fn refresh_blocks( &mut self, qp: Option<i32>, now: &BlockPlan, finer: f32, key: &BlockPlan, key_finer: f32, wait: &BlockPlan, )

Code the next frame as a refresh of coarse blocks (ledger::BlockLedger::refresh_keyed): held at quantizer qp where one is named, the macroblocks now names finer steps finer (X264_REFRESH_FINER), the ones of them a key frame left coarse (key) key_finer steps finer, and the ones wait names past the coarsest quantizer, where x264 codes a block its reference holds (constant_blocks) as a skip.

fn follow_peak(&mut self, bitrate_kbps: i32, vbv_kbit: i32, fps: f64)

Cap a CRF session at a peak of bitrate_kbps with a buffer of vbv_kbit, or lift its cap where either is 0, live and outside x264 (PeakOffset).

pub fn reconfigure_floor(&mut self, min_qp: i32)

Move the floor of a constant-rate session’s quantizer live, min_qp on the H.264 scale and 0 for x264’s own, through x264_encoder_reconfig with the bounds the carried patch lets it take. A floor at the paint-over quality while the screen moves holds the rate control from spending a generous budget on coding motion finer than the still picture it leaves (a 1440p scroll at 30 Mbit/s: 22.3 Mbit/s at 57 dB against 13.5 at 46 dB), lifted while a still screen is cleaned up, which then reaches what the rate control gives it; the blocks a moving frame refines code below the floor, as the patch keeps the caller’s offsets. An x264 without the patches keeps the bounds it opened with.

pub fn hold_quantizer(&mut self, qp: i32)

Encode the next frame at quantizer qp whatever the rate control, leaving the session’s own for the frame after: x264’s per-picture forced quantizer.

Under a constant rate x264’s row-level VBV control moves a forced quantizer back toward the rate control’s own for the frame, so a held key frame there, a fresh start for the decoder anyway, starts a fresh session (open_for_held_key) whose rate control plans that frame with HELD_KEY_BUDGET_S of the target, which also bounds its size, and takes the session’s own rate back for the frame after.

fn open_for_held_key(&mut self) -> bool

Replace the session with one whose first frame, the held key frame about to be encoded, has the budget of HELD_KEY_BUDGET_S of the target; true where it opened, and restore_rate is owed after the frame.

pub fn refine_blocks(&mut self, plan: &BlockPlan, offset: f32)

Code the macroblocks of the next frame that plan refines offset quantizer steps off the frame’s own, and the rest at it: the ledger’s refinement of blocks that held still while others move (ledger). The plan’s blocks are the macroblocks of this session’s picture.

pub fn constant_blocks(&mut self, unchanged: impl Iterator<Item = bool>)

Mark the macroblocks of the next frame that did not change since the frame before (unchanged, in raster order), which x264 codes as skips without analysing them where its reference holds them at the frame’s quantizer or finer.

fn restore_rate(&mut self)

Put the session’s own rate and VBV buffer back after a held key frame.

fn fold_frame(&mut self, frame: Coded)

Take a frame just coded into a capped CRF’s peak, and move the rate factor where the peak says to.

pub fn invalidate_reference(&mut self, frame_id: u16) -> bool

Leave frame frame_id and every frame after it out of the predictions. False when x264 refuses, and the caller codes a key frame instead.

pub fn encode_with_headers( &mut self, y: &[u8], u: &[u8], v: &[u8], y_stride: i32, u_stride: i32, v_stride: i32, frame_id: u16, force_idr: bool, omit_headers: bool, output_buf: &mut Vec<u8>, ) -> bool

Encode one YUV frame into H.264 and frame it for the wire, reporting whether the encoder actually emitted a bitstream this call.

The boolean return is load-bearing: x264_encoder_encode can legitimately produce nothing on a given call, and the caller must forward a frame only when real bytes exist — never an empty or header-only packet. Framing is conditional because the transport needs the pipeline’s small wire header to route the frame, while omit_headers consumers take the bare Annex-B elementary stream.

1. Picture setup: wraps the borrowed Y/U/V planes and their strides in an x264_picture_t with the encoder’s CSP, stamps the presentation timestamp with the session’s count of encoded frames (the one an invalidation names), and requests an IDR when force_idr is set or no reference is left to predict from (otherwise X264_TYPE_AUTO).
2. Encode: calls x264_encoder_encode; a non-positive returned size means no frame was emitted this call, so the function returns false without writing output.
3. Framing: output_buf is cleared and refilled. Unless omit_headers is set, the wire header is prepended with a frame kind read from the actual output picture type rather than from force_idr, because the encoder may not honor a keyframe request and the client keys its decode-recovery on the kind it truly received. With omit_headers the output is bare Annex-B.
4. Payload: every NAL payload is appended to output_buf after the optional header, its frame_num widened (WideFrameNum), so the bytes past the wire header are always a contiguous Annex-B access unit.

pub fn encode_nv12_with_headers( &mut self, planes: &Nv12Planes, frame_id: u16, force_idr: bool, omit_headers: bool, output_buf: &mut Vec<u8>, ) -> bool

encode_with_headers for an 8-bit 4:2:0 session’s NV12 picture, which x264 encodes in place where it is laid out for it: x264 reads it through the next encode, which takes it as the previous input, so it is left unchanged until that encode returns or until release_input (held_input).

pub fn held_input(&self) -> Option<*const u8>

The picture x264 still reads, as the previous input, after its last encode returned: the Nv12Planes::id of the last one it was handed in place, None where the last encode copied its picture.

pub fn release_input(&mut self)

Stop x264 reading the picture it holds (held_input), so its buffers can change.

fn encode_input( &mut self, input: Input<'_>, frame_id: u16, force_idr: bool, omit_headers: bool, output_buf: &mut Vec<u8>, ) -> bool

pub fn holds_cleanup(&self, crf: i32) -> bool

Whether the bucket of a capped CRF’s peak has room in one frame for a cleanup at rate factor crf (encode_cpu_from): for as much as the last key frame’s first attempt (LastKey) would come to at it, a cleanup of a still page coding much of it again, and after a refresh held at a quantizer all of it. True uncapped, on a session no peak has bound, which codes as an uncapped one, or before a key frame.

fn aim_key(&self) -> Option<f64>

The quantizer a capped CRF’s key frame is held at from the start, where the last key frame’s first attempt (LastKey) says one at the rate factor now would overflow the room the bucket has left: aimed at half that room, at KEY_STEPS quantizer steps a halving (PeakOffset), one encode. None where it would fit, or where no key frame came before, whose first attempt fit_key measures instead.

fn fit_key( &mut self, input: Input<'_>, frame_id: u16, omit_headers: bool, output_buf: &mut Vec<u8>, ) -> (bool, Option<f64>)

Code a capped CRF’s key frame that overflows the room its peak has left once more, held at a quantizer aimed at half that room from the first attempt’s size, at KEY_STEPS quantizer steps a halving (PeakOffset); the second attempt is the one that goes out, overflowing or not, so a key frame costs at most two encodes. Returns whether the frame coded, and the quantizer it was held at where it was coded again.

fn encode_picture( &mut self, input: Input<'_>, frame_id: u16, force_idr: bool, omit_headers: bool, output_buf: &mut Vec<u8>, ) -> bool

encode_input past the choice of session.

Trait Implementations

impl Drop for H264EncoderWrapper

Available on crate feature gpl only.

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Send for H264EncoderWrapper

Available on crate feature gpl only.