docs/design/part-preroll.txt - imx-gstreamer - Git at Google

 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 transition to
 PLAYING goes as fast as possible with no visual delay for the user.

 Preroll is also crucial in maintaining correct audio and video synchronsation
 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. This
 include state changes or flush events. The prerolling is implemented in
 sinks (see part-element-sink.txt)


 Committing the state
 --------------------

 When going to PAUSED and PLAYING a buffer should be queued in the pad. We also
 make this requirement for going to PLAYING since a flush event in the PAUSED
 state could unqueue the buffer again.

 The state is commited in the following conditions:

  - a buffer is received on a sinkpad
  - an EOS is received on a sinkpad.

 We require the state change to be commited in EOS as well since an EOS means
 by definition that no buffer is going to arrive anymore.

 After the state is commited, a blocking wait should be performed for the
 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_WRONG_STATE 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_WRONG_STATE shall be returned to the
 peer element.
	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 transition to
	PLAYING goes as fast as possible with no visual delay for the user.

	Preroll is also crucial in maintaining correct audio and video synchronsation
	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. This
	include state changes or flush events. The prerolling is implemented in
	sinks (see part-element-sink.txt)


	Committing the state
	--------------------

	When going to PAUSED and PLAYING a buffer should be queued in the pad. We also
	make this requirement for going to PLAYING since a flush event in the PAUSED
	state could unqueue the buffer again.

	The state is commited in the following conditions:

	- a buffer is received on a sinkpad
	- an EOS is received on a sinkpad.

	We require the state change to be commited in EOS as well since an EOS means
	by definition that no buffer is going to arrive anymore.

	After the state is commited, a blocking wait should be performed for the
	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_WRONG_STATE 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_WRONG_STATE shall be returned to the
	peer element.