Struct VpxEncoder 

pub struct VpxEncoder {

    codec: Codec,
    ctx: vpx_codec_ctx_t,
    cfg: vpx_codec_enc_cfg_t,
    planes: Planes,
    threads: u32,
    quality: Quality,
    rate: RateSettings,
    omit_headers: bool,
    references: ReferenceSlots,
    last_reference: Reference,
    pending: Pending,
    plan: SlotPlan,
    held: Option<u32>,
    held_band: Option<(f64, f64)>,
    held_bytes: usize,
    band_map: Vec<u8>,
    refinement: Option<Refinement>,
    active_map: Vec<u8>,
    map_armed: bool,
    last_refresh: SlotRefresh,
    last_quality: Option<u32>,
    peak: Option<PeakBucket>,
    last_capped: bool,
    switch_refused: bool,
    open_buf: (u32, u32, u32),
    last_bytes: Option<usize>,
    held_key: Option<(usize, u32)>,
    cap: Option<usize>,
    raised: bool,
}

One libvpx session for one capture.

Fields

codec: Codec

ctx: vpx_codec_ctx_t

cfg: vpx_codec_enc_cfg_t

planes: Planes

threads: u32

quality: Quality

rate: RateSettings

omit_headers: bool

references: ReferenceSlots

last_reference: Reference

pending: Pending

plan: SlotPlan

The slot plan of the frame being encoded, recorded once its packet returns.

held: Option<u32>

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

held_band: Option<(f64, f64)>

The share of the picture, from and to in raster order, the held quantizer covers, the rest left as it is (hold_quantizer, VP8 only); None for the whole picture.

held_bytes: usize

The bytes of the last held frame, 0 before one (band_size).

band_map: Vec<u8>

One segment per macroblock for a held band (band_roi): 1 inside it, 0 outside.

refinement: Option<Refinement>

The blocks the next frame of the rate control’s refines (refine_blocks).

active_map: Vec<u8>

libvpx’s active map for the next frame, one byte a macroblock in raster order, 0 where the block is constant (constant_blocks); empty where no block is.

map_armed: bool

Whether the session’s encoder holds an active map, to be taken back before a frame that takes none.

last_refresh: SlotRefresh

The buffers the last coded frame refreshed: a constant block is a skip from the frame before only where the next frame predicts from one of them.

last_quality: Option<u32>

The quality index the rate control last coded a frame at, held frames aside.

peak: Option<PeakBucket>

A capped constant quality’s peak (PeakBucket), and whether the last frame was coded bound to it (coded_capped).

last_capped: bool

switch_refused: bool

Whether libvpx has refused a peak’s switch (switch_peak), said once.

open_buf: (u32, u32, u32)

The buffer the session opened with, (size, initial, optimal) in ms, which a pinned quantizer keeps.

last_bytes: Option<usize>

The bytes of the last frame the rate control coded, held frames aside.

held_key: Option<(usize, u32)>

The size and quality index of the last held key frame of a constant-rate session (super::held_key_start).

cap: Option<usize>

The bytes the next frame, a still screen’s cleanup, may come to (cap, VP9).

raised: bool

Whether the rate control runs at a cleanup frame’s rate, to be put back.

Implementations

impl VpxEncoder

pub fn new( settings: &CaptureSettings, codec: Codec, rgba: bool, ) -> Result<Self, String>

Open a VP8 or VP9 session on host frames in the byte order rgba names.

fn control( &mut self, id: vp8e_enc_control_id, value: c_int, ) -> Result<(), String>

fn program_refresh(&mut self) -> Result<(), String>

A constant-rate VP9 session refines a still screen through libvpx’s cyclic refresh, a share of the blocks a frame within the budget. Without it the rate control codes the whole screen finer in single frames: at 2 Mbit/s at 1080p up to 44 budgets each, a third over the rate for 30 s, for a picture 4.6 dB coarser. A pinned quantizer takes none, since the refresh codes its blocks at another.

fn program_layer(&mut self) -> Result<(), String>

The layers of a VP9 session, whose quantizer bounds libvpx reads from here rather than from the configuration once the flexible mode is on.

fn program_rate(&mut self, rate: RateSettings, q: u32)

Write rate and the quantizer q (the codec’s own domain) into the configuration: a constant rate holds the target and VBV with the quantizer bounds the settings name, a pinned quantizer names a rate it never reaches with both bounds at the quantizer, and a capped one targets its peak in the constant rate’s buffer with the quantizer its floor.

fn reconfigure(&mut self) -> Result<(), String>

Apply the configuration to the running session.

pub fn codec(&self) -> Codec

pub fn library(&self) -> &'static str

The library behind the session, as the logs name it.

pub fn is_fullcolor(&self) -> bool

Whether the session carries 4:4:4 (VP9 profile 1, or 3 at 10 bits).

pub fn bit_depth(&self) -> u32

The bits per sample the session codes: 10 in VP9 profiles 2 and 3.

pub fn is_full_range(&self) -> bool

VP9 keeps the limited range of its 4:2:0 in profile 1, so the decoder hint a client sends for it stays true; VP8 has no other.

pub fn last_reference(&self) -> Reference

The frame the last encoded frame predicted from.

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

Leave frame frame_id and every frame after it out of the predictions; the next frame predicts from an earlier buffer, or is a key frame when none is left.

pub fn acknowledge_reference(&mut self, frame_id: u16, held: bool)

Every consumer holds frame frame_id, or where not held was sent it (ReferenceSlots::acknowledge).

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

The quality index the rate control last coded a frame at, held frames aside.

pub fn capped(&self) -> bool

Whether the constant quality runs under a peak (RateSettings::capped).

pub fn peak_bound(&self) -> bool

Whether that peak binds the session, its quantizer free above the pinned one.

pub fn coded_capped(&self) -> bool

Whether the last frame was coded bound to the peak.

pub fn idle(&mut self)

A tick that codes no frame (FrameEncoder::idle): the peak’s bucket drains, and a session bound to it counts the tick at its floor, nothing being coded coarser.

fn programmed(&self) -> RateSettings

The rate settings the session runs: a capped constant quality’s as an uncapped one’s while its peak does not bind.

pub fn follows_cap(&self) -> bool

Whether a still screen’s cleanup frame is coded at the rate its cap runs at (cap): VP9 at a constant rate, whose cleanup runs through its rate control, which takes a new target live.

pub fn cap(&mut self, bytes: usize)

Code the next frame, a still screen’s cleanup, at the rate that spends bytes in pipeline::CLEANUP_FRAME_S, its buffer as long in time as the session’s; the frame after goes back to the session’s rate. At 60 fps 0.5 Mbit/s VP9 refined 1080p text by 1 dB a second at its own rate (32.5 dB 8 s after the stop), and to 55 dB in 8 s at a 2 Mbit/s path’s.

pub fn last_size(&self) -> Option<usize>

The bytes of the last frame the rate control coded, held frames aside, where a constant-rate cleanup runs through that rate control (holds_quantizer).

pub fn holds_quantizer(&self) -> bool

Whether the cleanup of a still screen holds a frame at its quantizer: at a constant quantizer, and at a constant rate for VP8, whose rate control leaves a still screen as it is (a screen of text at 2 Mbit/s at 1080p stayed at 33.6 dB, where the held refresh reached 42.8). VP9’s refines one, so its constant-rate cleanup runs through the rate control instead: 43.6 dB in 2.5 s with no frame over 75 kB, where the held refresh was one of 347 kB.

pub fn hold_quantizer(&mut self, crf: u32, band: Option<(f64, f64)>)

Encode the next frame at the quantizer the quality index crf selects, whatever the rate control, and put the session’s own rate control back for the frame after: the cleanup of a still screen. A held key frame of a constant-rate session starts at the quantizer the last one says fits HELD_KEY_BUDGET_S of the target (held_key_start), and one that comes out past it is coded again, as a key frame, at the coarser quantizer held_key_retry picks. band, the share of the picture from and to in raster order, confines the quantizer to the macroblocks it covers where the session holds a band (band_size), and the rest of the frame is left as the reference has it.

pub fn band_size(&self) -> Option<usize>

The bytes of the last held frame (0 before one), where the session holds a band of a frame at a quantizer: VP8, through libvpx’s region-of-interest map (band_roi), at a rate that leaves a band room in a frame. A VP8 frame codes every macroblock’s mode even where it skips them all, about a third of a bit each at 720p and 1080p, so below BAND_BITS_PER_MB of frame budget a band a frame is mostly that and the sweep cannot keep the rate: 1080p text at 0.25 Mbit/s (half a bit) ended at 29.5 dB in bands against 42.0 held whole, where 720p at 0.25 (1.2 bits) ended at 41.5 against 42.0 with the worst wait at the target 5.0 s against 18.5. The refresh is held whole below it.

fn band_roi( &mut self, band: Option<(f64, f64)>, unfiltered: bool, ) -> Result<(), String>

Hand libvpx the region map of a held band (band, from and to in raster order of the macroblocks, as NVENC’s delta map counts them), or clear it with None. The band is coded at the frame’s own quantizer, the one held, with the static threshold the session keeps (VP8_STATIC_THRESHOLD) and, where unfiltered, no loop filter (VP8_UNFILTERED_QINDEX); every other macroblock is skipped, a static threshold no prediction error reaches making it a copy of the reference, so the frame carries the band and nothing else. VP8’s segments take a quantizer delta of 63 at most, so the band is not held finer than a coarse rest the way NVENC’s map holds it: the rest is skipped outright, which no quantizer of its own would do better.

pub fn refine_blocks(&mut self, refinement: &Refinement)

Code the blocks refinement names in the next frame of the rate control’s at its target quality (ledger), through libvpx’s region-of-interest map (refine_roi).

fn refine_roi(&mut self, refinement: Option<&Refinement>) -> Result<(), String>

Hand libvpx the region map of refinement, or clear it with None: segment 1 the blocks it refines, coded the steps of libvpx’s quantizer between the rate control’s last and the target finer than the frame (which libvpx translates to its internal index), segment 0 the rest at the frame’s own. VP8 maps its 16x16 macroblocks and skips a refined block with no static threshold, since an unchanged block under the session’s own (VP8_STATIC_THRESHOLD) would be copied rather than coded finer; VP9 maps its 8x8 blocks, and runs the map in place of its cyclic refresh for the frame.

fn pin_quantizer(&mut self, crf: u32) -> Result<(), String>

Pin the configuration’s quantizer bounds to the one the quality index crf selects.

pub fn reconfigure_rate( &mut self, settings: &CaptureSettings, ) -> Result<(), String>

Re-program the rate control when a rate or frame-rate setting changed, live.

pub fn encode_host( &mut self, pixels: &[u8], stride: usize, rgba: bool, frame_number: u64, crf: u32, force_idr: bool, ) -> Result<Vec<u8>, String>

Encode one packed host frame at the quality index crf, as a key frame when force_idr or when no reference is left to predict from.

fn switch_peak(&mut self)

Program the rate control the peak’s new state asks for (programmed): the constant rate at the peak once it binds, the pinned quantizer once it lets go. A configuration libvpx refuses leaves the session as it ran, the peak’s state put back with it, said once; the frame that asked for the switch is kept either way.

pub fn constant_blocks(&mut self, constant: &[bool])

Mark the macroblocks of the next frame that held still and are clean (constant, in raster order, empty for none), which libvpx codes as skips without analysis through its active map: VP8 picks ZEROMV from the frame before at once, VP9 codes the superblock whose every block is marked as one skip. The map goes to the encoder with the next frame alone (arm_active_map), and only where that frame predicts from the one before; a frame coded without a map of its own takes none.

fn arm_active_map(&mut self, takes: bool) -> Result<(), String>

Hand the encoder the frame’s active map where takes it and the session holds one, and take back the map it holds otherwise: libvpx keeps a map until it is replaced, and an all-active map still costs VP9 a segmentation map a frame.

fn encode_frame( &mut self, pixels: &[u8], stride: usize, rgba: bool, frame_number: u64, force_idr: bool, ) -> Result<Vec<u8>, String>

Encode one packed host frame at the quantizer the configuration holds.

Trait Implementations

impl Drop for VpxEncoder

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 VpxEncoder