Enum FrameInclusion 

pub enum FrameInclusion {
    Never,
    Always,
    Sampled {
        interval: u32,
    },
    TargetFps {
        target: f32,
        fallback_interval: u32,
    },
}

Controls whether the source FrameEnvelope is included in the OutputEnvelope.

Default is Never — output contains only perception artifacts. Use Always when downstream consumers need access to the pixel data (e.g., annotation overlays, frame archival, or visual debugging).

Sampled provides a middle ground: frames are included every interval outputs, keeping metadata (detections, tracks, signals) at full rate while reducing the cost of host materialization and downstream pixel processing in the sink thread. For example, Sampled { interval: 6 } on a 30 fps source yields ~5 fps of frame delivery while perception runs at full rate.

Because FrameEnvelope is Arc-backed, inclusion is zero-copy.

Variants

Never

Never include frames in output (default).

Always

Always include the source frame in output.

Sampled

Include the source frame every interval outputs.

Perception artifacts (detections, tracks, signals, provenance) flow at full rate regardless. Only the pixel payload is gated.

An interval of 1 behaves like Always. An interval of 0 behaves like Never.

Fields

interval: u32

Include a frame every N-th output envelope.

TargetFps

Include frames at a target preview FPS, resolved dynamically from the observed source rate.

During a warmup window (first ~30 frames), fallback_interval is used. Once the source FPS is estimated, the interval is computed as round(source_fps / target_fps) and the variant is resolved in-place to Sampled.

This avoids hardcoding an assumed source FPS at config time.

Fields

target: f32

Desired preview frames per second.

fallback_interval: u32

Interval to use before the source rate is known.

Implementations

impl FrameInclusion

pub fn sampled(interval: u32) -> Self

Create a sampled frame inclusion policy with edge-case normalization.

• interval == 0 → Never
• interval == 1 → Always
• interval > 1 → Sampled

Prefer this over constructing Sampled directly to avoid footgun values that silently alias other variants.

pub fn target_fps(target: f32, fallback_interval: u32) -> Self

Create a target-FPS frame inclusion that resolves dynamically from the observed source rate.

Until the source rate is known (warmup window), falls back to fallback_interval. Once observed, resolves to Sampled.

fallback_interval is normalized: 0 → Never, 1 → Always.

pub fn from_target_fps(target_fps: f32, assumed_source_fps: f32) -> Self

Compute a sampled frame inclusion from a target preview FPS and an assumed source FPS.

The interval is round(source / target), clamped to valid range.

For runtime-adaptive behavior, prefer target_fps which resolves from observed source rate instead of a static assumption.

Examples

assert_eq!(
    FrameInclusion::from_target_fps(5.0, 30.0),
    FrameInclusion::Sampled { interval: 6 },
);
assert_eq!(
    FrameInclusion::from_target_fps(60.0, 30.0),
    FrameInclusion::Always,
);

pub fn effective_interval(&self) -> u32

The effective sample interval.

• Never → 0
• Always → 1
• Sampled → the configured interval
• TargetFps → the fallback interval (actual interval is determined at runtime)

pub fn resolve_with_source_fps(self, source_fps: f32) -> Self

Resolve a TargetFps variant to a concrete Sampled interval given the observed source FPS.

Returns the resolved variant. Non-TargetFps variants are returned unchanged.

Trait Implementations

impl Clone for FrameInclusion

fn clone(&self) -> FrameInclusion

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FrameInclusion

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for FrameInclusion

fn default() -> FrameInclusion

Returns the “default value” for a type.

impl PartialEq for FrameInclusion

fn eq(&self, other: &FrameInclusion) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for FrameInclusion

impl StructuralPartialEq for FrameInclusion