class PipelineStage

Removes a source stream.

Required: caller must verify that `source` is currently a source for this stage.

Advances the destination stream by releasing any frames before the given `frame`. This is a

declaration that the caller will not attempt to `Read` any frame before the given `frame`. If

the stage has allocated packets for frames before `frame`, it can free those packets now. After

the destination stream is advanced, the source streams are advanced, recursively.

This must *not* be called while the stage is _locked_, i.e., until the packet returned by the

last `Read` call is destroyed, nor while the stage is _stopped_, i.e., when

`presentation_time_to_frac_frame()` returns `std::nullopt`.

Reads the destination stream of this stage, and returns the acquired packet. The parameters

`start_frame` and `frame_count` represent a range of frames on the destination stream's frame

timeline.

This must *not* be called while the stage is _locked_, i.e., until the packet returned by the

last `Read` call is destroyed, nor while the stage is _stopped_, i.e., when

`presentation_time_to_frac_frame()` returns `std::nullopt`.

## Returned Packet

Returns `std::nullopt` if no data is available for the requested frame range. Otherwise,

returns a packet representing all or part of the requested range. If the start frame on the

returned packet is greater than `start_frame`, then the stream has no data for those initial

frames, which may be treated as silence. Conversely, if the end frame of the returned packet is

less than `start_frame + frame_count`, this indicates the full frame range is not available on

a single contiguous packet. Clients should call `Read` again, with `start_frame` set to the end

of the previous packet, to see if the stream has more frames.

The returned packet contains an integral number of frames satisfying the following conditions:

* `packet.start() > start_frame - Fixed(1)`

* `packet.end()

<

= start_frame + Fixed(frame_count)`

* `packet.length()

<

= frame_count`

The start frame of the returned packet is the position of the left edge of the first frame in

the packet. For example, given `Read(Fixed(10), 5)`, if the stream's frames happen to be

aligned on positions 9.1, 10.1, 11.1, etc., then `Read` will return a packet with the start

frame of 9.1, and the length of 5.

The stage will remain _locked_ until the returned packet is destroyed.

## The Passage of Time

Each stage maintains a current frame position, which always moves forward. The position is

explicitly advanced to a destination `frame` via an `Advance(frame)` call. Similarly, a `Read`

call advances the position as follows:

* When `Read` is called, the position is advanced to `start_frame` (iff the next readable frame

iess than `start_frame`).

* If `std::nullopt` is returned, the position is advanced to `start_frame + frame_count`.

* Otherwise, the position is advanced to `packet.start() + packet.frames_consumed_` when the

returned packet is destroyed.

Put differently, time advances when `Read` is called, when a packet is consumed, and on

explicit calls to `Advance`. Time does not go backwards, hence, each call to `Read` must have

`start_frame` that is not lesser than the last advanced frame.

Sets the stage's thread. This must be called from `thread()`, unless `thread()` is a detached

thread, in which case this may be called from any thread.

Returns corresponding frame for a given `presentation_time`.

Required: caller must verify that `presentation_time_to_frac_frame` is valid.

Returns corresponding presentation time for a given `frame`.

Required: caller must verify that `presentation_time_to_frac_frame` is valid.

Updates `presentation_time_to_frac_frame`. See discussion in ../docs/timelines.md.

If `f` is not `std::nullopt`, it must be an invertible function.

Returns the stage's name. This is used for diagnostics only.

The name may not be a unique identifier.

Returns the stage's format.

Returns the stage's next readable frame.

Returns the thread which currently controls this stage. It is safe to call this method on any

thread -- this allows callers to check that they are running on the correct thread. However, if

not called from `thread()`, the returned value may change concurrently.

Returns the clock used by the stage's destination stream.

The source streams may use different clocks.

Returns a function that translates from presentation time to frame time, where frame time is

represented by a `Fixed::raw_value()` while presentation time is represented by a `zx::time`.