Struct PauseGate 

pub struct PauseGate { /* private fields */ }

Stops a branch taking frames, and takes the paused span out of the timeline of what it does take.

Video (PauseGate::new) or audio (PauseGate::for_audio) — one type rather than two, because a recording of both needs its two gates to remove the same span, and two implementations would be two chances for them to stop meaning the same thing. Which kind it takes is fixed at construction and declared, so wiring one to the wrong stream is a link error rather than a file whose sound has slid away from its picture.

What it is for

Pausing a recording. The file has to stay open and then continue, with no trace of the pause in it — a still picture lasting however long it was paused is not what anybody means by the word. So dropping the frames is only half of it: the frames that follow have to move back by as much as was skipped, or the gap simply moves downstream.

Not ControlMsg::Pause

That control stops queues pulling, which backpressures whatever feeds them. On a Tee branch it would reach back through the fan-out and stall the source for every other branch — pausing a recording would freeze the preview beside it. This drops frames instead, which nothing upstream can tell.

How long the pause was

Measured in the source’s own timestamps: the first frame dropped marks where the pause began, and the first frame forwarded after it marks where it ended. That is what makes this composable — it needs to know nothing about the rate, and it is correct even for a source whose rate varies.

It does assume frames keep arriving while paused, which is what it counts. A source that stops entirely cannot be measured this way — but neither does its own timeline advance while it is stopped, so the span this would have subtracted is one that was never there. The two agree.

Where it goes

In front of the encoder, on frames. Behind one, the encoder would spend the whole pause compressing frames that are about to be thrown away.

Directly in front of it, with nothing that buffers in between. What this forwards is a wrapper holding a reference to the picture rather than the pooled reference it was handed, and a frame reference keeps the buffer allocated while leaving the producer’s pool free to hand that slot out again — the distinction ChangeGate and both video compositors keep retire lists for. This needs none, because the wrapper never outlives the call that made it: the push downstream is synchronous, the encoder copies what it is given before returning, and the pooled reference this was handed is alive for the whole of that. A Queue between the two would end that — the wrapper would outlive the pooled reference, and the compositor would be free to draw into the slot it still names.

Cost

A reference to the frames it forwards and nothing at all for the ones it drops. No pixels are read, copied or converted.

Implementations

impl PauseGate

pub fn new(name: impl Into<String>) -> (Self, PauseGateHandle)

A gate on video frames. Starts running; nothing is paused until a handle says so.

pub fn for_audio(name: impl Into<String>) -> (Self, PauseGateHandle)

A gate on audio frames, for the other track of the same recording.

MemoryDomain::System because that is where audio is: there is no GPU-resident audio frame in this crate, and stating it rather than accepting any domain keeps the link check as sharp here as it is on the video side.

Trait Implementations

impl Element for PauseGate

fn name(&self) -> Arc<str>

Returns a cheap clone (refcount bump, not a deep copy) of this element’s name — crate::bus::BusEvent stores names as Arc<str> for exactly this reason: a hot path like crate::queue::Queue posting BusEvent::Dropped once per overflowed buffer shouldn’t pay for a fresh heap allocation every time it wants to report which element it is.

fn element_type(&self) -> ElementType

See ElementType.

fn pp_log(&self) -> &PpLog

This element’s identity for crate::bus::Bus::post — same id/name as Element::name, just already wrapped as the crate::pp_log::PpLog its pp_info!/pp_warn!/pp_error! macros need. A stored private field, not built fresh per call, for the same reason name() returns a cheap Arc<str> clone instead of a fresh String — see its own docs.

fn pp_log_mut(&mut self) -> &mut PpLog

Mutable access to the same field Element::pp_log reads — used by crate::pipeline::ChainBuilder to stamp the owning crate::pipeline::Pipeline’s id onto every element that passes through it, via element_pp_log. Not meant to be called from anywhere else.

fn graph_id(&self) -> Option<ElementId>

A pre-reserved graph identity for elements that expose dynamic attachment handles. Most elements receive an ID from ChainBuilder and keep the default None implementation.

fn attach_context(&mut self, _context: &Arc<Context>)

Hands this element the pipeline it is being wired into, at the moment and for the reason Element::pp_log_mut hands it the pipeline’s identity: the clock, the playback clock and the bus are the pipeline’s to give, not the caller’s to choose.

impl Sink for PauseGate

fn input_contract(&self) -> InputContract

Video frames. It reads a timestamp and forwards a reference, so where the pixels live is not its business.

fn consume(&mut self, buf: MediaBuffer) -> Result<()>

Processes one buffer synchronously on the caller’s thread.

fn control(&mut self, msg: ControlMsg) -> Result<()>

Reacts to a ControlMsg (pause/resume/stop) and, for anything with a downstream of its own, forwards it on — same shape as consume, just a separate channel from MediaBuffer so it can reach every element (not just ones that already know how to interpret a data buffer) and, at a crate::queue::Queue, jump ahead of whatever data is backed up instead of waiting behind it. No default: every Sink has to consciously decide what this means for it, rather than silently dropping it.

fn ready_consume(&mut self) -> bool

Returns whether calling Self::consume can make progress now.

impl Source for PauseGate

fn src_pads(&mut self) -> &mut [SrcPad]

Returns every output pad owned by this element.