markdown/design/preroll.md

   1 # Preroll
   2
   3 A sink element can only complete the state change to `PAUSED` after a
   4 buffer has been queued on the input pad or pads. This process is called
   5 prerolling and is needed to fill the pipeline with buffers so that the
   6 transition to `PLAYING` goes as fast as possible, with no visual delay for
   7 the user.
   8
   9 Preroll is also crucial in maintaining correct audio and video
  10 synchronisation and ensuring that no buffers are dropped in the sinks.
  11
  12 After receiving a buffer (or EOS) on a pad the chain/event function
  13 should wait to render the buffers or in the EOS case, wait to post the
  14 EOS message. While waiting, the sink will wait for the preroll cond to
  15 be signalled.
  16
  17 Several things can happen that require the preroll cond to be signalled.
  18 These include state changes or flush events. The prerolling is
  19 implemented in sinks (see [Sink elements](design/element-sink.md)).
  20
  21 ## Committing the state
  22
  23 When going to `PAUSED` and `PLAYING` a buffer should be queued in the pad.
  24 We also make this a requirement for going to `PLAYING` since a flush event
  25 in the `PAUSED` state could unqueue the buffer again.
  26
  27 The state is commited in the following conditions:
  28
  29 - a buffer is received on a sinkpad;
  30 - an GAP event is received on a sinkpad;
  31 - an EOS event is received on a sinkpad.
  32
  33 We require the state change to be commited in EOS as well, since an EOS
  34 , by definition, means no buffer is going to arrive anymore.
  35
  36 After the state is commited, a blocking wait should be performed for the
  37 next event. Some sinks might render the preroll buffer before starting
  38 this blocking wait.
  39
  40 ## Unlocking the preroll
  41
  42 The following conditions unlock the preroll:
  43
  44 - a state change
  45 - a flush event
  46
  47 When the preroll is unlocked by a flush event, a return value of
  48 `GST_FLOW_FLUSHING` is to be returned to the peer pad.
  49
  50 When preroll is unlocked by a state change to `PLAYING`, playback and
  51 rendering of the buffers shall start.
  52
  53 When preroll is unlocked by a state change to READY, the buffer is to be
  54 discarded and a `GST_FLOW_FLUSHING` shall be returned to the peer
  55 element.