2016-12-05 21:12:24 +00:00
|
|
|
# Preroll
|
|
|
|
|
|
|
|
|
|
A sink element can only complete the state change to `PAUSED` after a
|
|
|
|
|
buffer has been queued on the input pad or pads. This process is called
|
|
|
|
|
prerolling and is needed to fill the pipeline with buffers so that the
|
2016-12-19 23:18:24 +00:00
|
|
|
transition to `PLAYING` goes as fast as possible, with no visual delay for
|
2016-12-05 21:12:24 +00:00
|
|
|
the user.
|
|
|
|
|
|
|
|
|
|
Preroll is also crucial in maintaining correct audio and video
|
|
|
|
|
synchronisation and ensuring that no buffers are dropped in the sinks.
|
|
|
|
|
|
|
|
|
|
After receiving a buffer (or EOS) on a pad the chain/event function
|
|
|
|
|
should wait to render the buffers or in the EOS case, wait to post the
|
|
|
|
|
EOS message. While waiting, the sink will wait for the preroll cond to
|
|
|
|
|
be signalled.
|
|
|
|
|
|
|
|
|
|
Several things can happen that require the preroll cond to be signalled.
|
2016-12-19 23:18:24 +00:00
|
|
|
These include state changes or flush events. The prerolling is
|
2019-05-26 22:32:55 +00:00
|
|
|
implemented in sinks (see [Sink elements](additional/design/element-sink.md)).
|
2016-12-05 21:12:24 +00:00
|
|
|
|
|
|
|
|
## Committing the state
|
|
|
|
|
|
|
|
|
|
When going to `PAUSED` and `PLAYING` a buffer should be queued in the pad.
|
2016-12-19 23:18:24 +00:00
|
|
|
We also make this a requirement for going to `PLAYING` since a flush event
|
2016-12-05 21:12:24 +00:00
|
|
|
in the `PAUSED` state could unqueue the buffer again.
|
|
|
|
|
|
2019-08-14 05:13:08 +00:00
|
|
|
The state is committed in the following conditions:
|
2016-12-05 21:12:24 +00:00
|
|
|
|
2019-01-23 23:55:11 +00:00
|
|
|
- a buffer is received on a sinkpad;
|
2019-08-14 05:13:08 +00:00
|
|
|
- a GAP event is received on a sinkpad;
|
2016-12-05 21:12:24 +00:00
|
|
|
- an EOS event is received on a sinkpad.
|
|
|
|
|
|
2019-08-14 05:13:08 +00:00
|
|
|
We require the state change to be committed in EOS as well, since an EOS
|
2016-12-19 23:18:24 +00:00
|
|
|
, by definition, means no buffer is going to arrive anymore.
|
2016-12-05 21:12:24 +00:00
|
|
|
|
2019-08-14 05:13:08 +00:00
|
|
|
After the state is committed, a blocking wait should be performed for the
|
2016-12-05 21:12:24 +00:00
|
|
|
next event. Some sinks might render the preroll buffer before starting
|
|
|
|
|
this blocking wait.
|
|
|
|
|
|
|
|
|
|
## Unlocking the preroll
|
|
|
|
|
|
|
|
|
|
The following conditions unlock the preroll:
|
|
|
|
|
|
|
|
|
|
- a state change
|
|
|
|
|
- a flush event
|
|
|
|
|
|
|
|
|
|
When the preroll is unlocked by a flush event, a return value of
|
|
|
|
|
`GST_FLOW_FLUSHING` is to be returned to the peer pad.
|
|
|
|
|
|
|
|
|
|
When preroll is unlocked by a state change to `PLAYING`, playback and
|
|
|
|
|
rendering of the buffers shall start.
|
|
|
|
|
|
|
|
|
|
When preroll is unlocked by a state change to READY, the buffer is to be
|
|
|
|
|
discarded and a `GST_FLOW_FLUSHING` shall be returned to the peer
|
|
|
|
|
element.
|
