Struct StripeState 

pub struct StripeState {

    pub no_motion_frame_count: u32,
    pub paint_over_sent: bool,
    pub dirty_run: u32,
    pub change_mass: f32,
    pub moved: bool,
    pub key_owed: bool,
    pub unclean_frames: u32,
    pub cleanup_keyed: bool,
    pub motion: f32,
    pub burst_held: bool,
    pub clean_quality: bool,
    pub rc_bytes: usize,
    pub rc_debt: f64,
    pub idle_frames: u32,
    pub over_frames: u32,
    pub same_frames: u32,
    pub finest: Option<u32>,
    pub finest_frames: u32,
    pub settled: bool,
    pub fine_frames: u32,
    pub measured: Option<f32>,
    pub measuring: bool,
    pub level_checks: u32,
    pub measure_in: u32,
    pub sweep: Option<(f64, f64)>,
    pub sweep_frames: u32,
    pub sweep_coarser: u32,
    pub sweep_cost: f64,
    pub sweep_first: f64,
    pub sweep_held: bool,
    pub cleanup_debt: f64,
    pub cleanup_paced: bool,
    pub h264_encoder: Option<H264EncoderWrapper>,
    pub h264_burst_frames_remaining: i32,
    pub y_buf: Vec<u8>,
    pub u_buf: Vec<u8>,
    pub v_buf: Vec<u8>,
    pub yuv16: [Vec<u16>; 3],
    pub nv12: Vec<Nv12Planes>,
    pub packet_buf: Vec<u8>,
    pub last_hash: u64,
    pub consecutive_changes: u32,
    pub in_damage_block: bool,
    pub damage_block_frames_remaining: i32,
    pub hash_changed: bool,
    pub ledger: BlockLedger,
    pub refine: RefinePace,
    pub refresh: RefreshPace,
}

Everything one region of the frame must remember between frames: its reused buffers, its own live encoder, and the motion / paint-over / damage bookkeeping that drives its send decision.

A region is a JPEG stripe, the whole frame of a software H.264 session, or the frame of a full-frame session (pipeline::decide_hw_fullframe). JPEG stripes encode in parallel and an unchanged one is skipped on its own, which only works if each carries its own cross-frame history. So one instance lives per region for the whole session and nothing in it is rebuilt or recomputed from scratch each frame:

• Reused buffers: nv12 holds an 8-bit 4:2:0 x264 frame’s pictures, y_buf / u_buf / v_buf and yuv16 another frame’s YUV planes, and packet_buf the encoded output, grown in place rather than reallocated per frame.
• Encoder: h264_encoder is the software H.264 session — libx264 in a gpl build, OpenH264 otherwise — reused until its geometry (or, for x264, chroma format) changes.
• Cleanup / recovery: no_motion_frame_count counts consecutive static frames, paint_over_sent records that the region was cleaned up since it last changed, h264_burst_frames_remaining tracks a post-cleanup or recovery streaming burst (held at the paint-over quantizer where burst_held), and dirty_run, change_mass, unclean_frames, and motion (the share of recent frames in motion) are what pipeline::cleanup_due weighs to pick the cleanup’s moment and kind; clean_quality keeps a constant-quality session at the paint-over quality from a cleanup until the region changes again; rc_bytes (the bytes of the region’s last frame under its rate control), rc_debt (the bytes a cleanup’s rate control has spent past its target and not yet repaid), idle_frames (a constant-rate cleanup’s run of small frames short of the paint-over quality, of empty ones for x264), same_frames (of frames the size of the one before), finest and finest_frames (the finest quality index its rate control has coded at and the frames since), and over_frames (its run of frames over pipeline::OVERSHOOT_BUDGETS and no finer than finest) tell a cleanup that runs through the rate control when it has converged, stalled, or been pinned at its coarsest quantizer, fine_frames counts its run of frames at the paint-over quantizer or finer, measured, measuring, level_checks, and measure_in are the last measurement of the picture it is refining, whether the frame before was measured, the measurements in a row that found it level, and the frames to the next (pipeline::plateau), settled records that such a cleanup ran its course under a rate control it cannot hold a quantizer under, so no other starts before the region moves, and sweep (the next band’s start and the last band’s size, as shares of the picture) carries the band sweep a full-frame refresh falls back to (pipeline::decide_hw_fullframe), sweep_frames its bands so far, sweep_coarser the steps they are coded coarser than the refresh, sweep_held whether the last frame was one of them, and sweep_cost the bytes the whole picture would come to at the refresh’s quantizer, by its bands so far (sweep_first, by its first); cleanup_debt is the bytes a cleanup’s frames, the rate control’s and the bands, came to past the cleanup’s budget a frame, which it waits out (cleanup_paced: the last frame was one of them).
• Content-hash damage (only for sources without external damage, i.e. X11): last_hash is the previous frame’s content hash, consecutive_changes counts changed frames toward the damage-block threshold, and in_damage_block / damage_block_frames_remaining drive the sustained-motion damage block managed by content_dirty.

Fields

no_motion_frame_count: u32

paint_over_sent: bool

dirty_run: u32

change_mass: f32

moved: bool

Whether the region moved (Damage::is_motion) since its last cleanup.

key_owed: bool

Whether a scheduled key frame fell due that waits for the region’s next motion (StripeState::scheduled_key).

unclean_frames: u32

cleanup_keyed: bool

Whether the last cleanup was a key frame (pipeline::lost_frame repeats its kind).

motion: f32

burst_held: bool

clean_quality: bool

rc_bytes: usize

rc_debt: f64

idle_frames: u32

over_frames: u32

same_frames: u32

finest: Option<u32>

finest_frames: u32

settled: bool

fine_frames: u32

measured: Option<f32>

measuring: bool

level_checks: u32

measure_in: u32

sweep: Option<(f64, f64)>

sweep_frames: u32

sweep_coarser: u32

sweep_cost: f64

sweep_first: f64

sweep_held: bool

cleanup_debt: f64

cleanup_paced: bool

h264_encoder: Option<H264EncoderWrapper>

h264_burst_frames_remaining: i32

y_buf: Vec<u8>

u_buf: Vec<u8>

v_buf: Vec<u8>

yuv16: [Vec<u16>; 3]

The planes of a 10-bit frame, as 16-bit samples.

nv12: Vec<Nv12Planes>

The two pictures an 8-bit 4:2:0 x264 session converts its frames into in turn, x264 reading the one before through the next encode (H264EncoderWrapper::held_input).

packet_buf: Vec<u8>

last_hash: u64

consecutive_changes: u32

in_damage_block: bool

damage_block_frames_remaining: i32

hash_changed: bool

Whether the last content_dirty hashed the region and found it changed: a damage block’s other frames read dirty without a hash.

ledger: BlockLedger

The region’s blocks, which held still and which are clean (ledger), for refining the ones that held still while others move.

refine: RefinePace

How many of them a frame refines (ledger::RefinePace), and how many coarse ones a capped constant quality refreshes once its peak lets go (ledger::RefreshPace).

refresh: RefreshPace

Implementations

impl StripeState

pub fn content_dirty( &mut self, bytes: &[u8], threshold: u32, duration: i32, ) -> bool

Stand in for the compositor damage that X11 capture does not provide: hash this stripe to decide whether it changed since last frame, and once it is clearly in motion, stop re-hashing it every frame by committing to a sustained-motion “damage block”.

The hash is not free, and a region that changes every frame would otherwise be re-hashed forever while always reporting dirty anyway. So after threshold consecutive changes the stripe enters a damage block that just reports dirty for duration frames and re-hashes only on its last two frames, to decide whether to extend the block or let it lapse — trading a little extra sending for far fewer hashes on exactly the regions that need them least:

1. Inside a damage block: the stripe is treated as dirty without re-hashing, and the block’s remaining-frame counter is decremented. The stripe is hashed on the block’s last two frames: if they differ the region is still moving and the block is renewed for another duration frames, otherwise the block exits and the change counter resets, so motion that stopped inside a block is read as stopped when that block ends, not a block later. This keeps a continuously-moving region streaming for duration frames per re-check rather than hashing every frame.
2. Outside a block: the stripe is hashed and compared to the previous frame. A change increments consecutive_changes, and reaching threshold consecutive changes opens a new damage block; an unchanged frame resets the counter to zero.

Returns true whenever the stripe is considered dirty (always true while inside a block).

pub fn hash_dirty(&mut self, hash: u64, threshold: u32, duration: i32) -> bool

content_dirty for a stripe hashed elsewhere (on the GPU, where the frame was uploaded): the same state, read off hash.

fn dirty_by( &mut self, fast_hash: impl FnOnce() -> u64, threshold: u32, duration: i32, ) -> bool

impl StripeState

pub fn lost_frame(&mut self)

A consumer lost a frame of this region’s stream (invalidate_reference). A cleanup already sent may be among the frames it lost, and the frame predicting past them is coded at the stream’s own quality, from whatever frame is left to predict from: over a gate that held a low frame rate’s frames back on a long path, the anchor, seconds old, whose picture shows through the recovery as a ghost. A region that was clean is due its cleanup again, of the kind it lost (a key frame clears what the anchor left), or the picture would stay as the loss left it until the region next changes.

pub fn withheld_frame(&mut self)

A frame of this region’s stream was withheld (ReferenceReport::Withheld). A cleanup running through the rate control codes past it, its next frames predicting from what the consumers hold; one that ended or sweeps is due again as after a loss. Started over at each drop of a rate budget, NVENC’s cleanup of a texture at 0.1 Mbit/s never reached the one held frame that ends it.

pub fn scheduled_key(&mut self, due: bool, moved: bool) -> bool

Whether this frame codes the region’s scheduled key frame, due being the schedule’s (periodic_idr_due). One that falls due while the region holds still, or changes only a little, waits for a frame that moved: a key frame is coded at the rate control’s own quality, so on a still screen it would throw away the picture the cleanup refined every interval, where a decoder holding that picture gains nothing from it, and motion coarsens the picture anyway. A key frame coded for any other reason pays the debt (decide_hw_fullframe).

pub fn take_report(&mut self, report: ReferenceReport)

What a report of the consumers does to this region’s cleanup (lost_frame, withheld_frame).

Trait Implementations

impl Default for StripeState

fn default() -> StripeState

Returns the “default value” for a type.