mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-20 07:16:55 +00:00
Code Issues 1 Projects Releases Wiki Activity

design: overview: fix missing markup

Browse source
This commit is contained in:
Reynaldo H. Verdejo Pinochet 2017-03-08 15:14:09 -08:00
parent 4752e9b45a
commit 586e32b25a
1 changed files with 56 additions and 54 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

110
markdown/design/overview.md
View file

@ -96,28 +96,28 @@ sink src1
+-----------+ +-----------+
``` ```
An element can be in four different states: NULL, READY, PAUSED, An element can be in four different states: `NULL`, `READY`, `PAUSED`,
PLAYING. In the NULL and READY state, the element is not processing any `PLAYING`. In the `NULL` and `READY` state, the element is not processing any
data. In the PLAYING state it is processing data. The intermediate data. In the `PLAYING` state it is processing data. The intermediate
PAUSED state is used to preroll data in the pipeline. A state change can PAUSED state is used to preroll data in the pipeline. A state change can
be performed with `gst_element_set_state()`. be performed with `gst_element_set_state()`.
An element always goes through all the intermediate state changes. This An element always goes through all the intermediate state changes. This
means that when en element is in the READY state and is put to PLAYING, means that when en element is in the `READY` state and is put to `PLAYING`,
it will first go through the intermediate PAUSED state. it will first go through the intermediate `PAUSED` state.
An element state change to PAUSED will activate the pads of the element. An element state change to `PAUSED` will activate the pads of the element.
First the source pads are activated, then the sinkpads. When the pads First the source pads are activated, then the sinkpads. When the pads
are activated, the pad activate function is called. Some pads will start are activated, the pad activate function is called. Some pads will start
a thread (`GstTask`) or some other mechanism to start producing or a thread (`GstTask`) or some other mechanism to start producing or
consuming data. consuming data.
The PAUSED state is special as it is used to preroll data in the The `PAUSED` state is special as it is used to preroll data in the
pipeline. The purpose is to fill all connected elements in the pipeline pipeline. The purpose is to fill all connected elements in the pipeline
with data so that the subsequent PLAYING state change happens very with data so that the subsequent `PLAYING` state change happens very
quickly. Some elements will therefore not complete the state change to quickly. Some elements will therefore not complete the state change to
PAUSED before they have received enough data. Sink elements are required `PAUSED` before they have received enough data. Sink elements are required
to only complete the state change to PAUSED after receiving the first to only complete the state change to `PAUSED` after receiving the first
data. data.
Normally the state changes of elements are coordinated by the pipeline Normally the state changes of elements are coordinated by the pipeline
@ -174,7 +174,7 @@ features to its children:
- Select and manage a global clock for all its children. - Select and manage a global clock for all its children.
- Manage `running_time` based on the selected clock. Running\_time is - Manage `running_time` based on the selected clock. Running\_time is
the elapsed time the pipeline spent in the PLAYING state and is used the elapsed time the pipeline spent in the `PLAYING` state and is used
for synchronisation. for synchronisation.
- Manage latency in the pipeline. - Manage latency in the pipeline.
- Provide means for elements to comunicate with the application by the - Provide means for elements to comunicate with the application by the
@ -317,7 +317,7 @@ rate of one `GST_SECOND` per second. Clock values are expressed in
nanoseconds. Elements use the clock time to synchronize the playback of nanoseconds. Elements use the clock time to synchronize the playback of
data. data.
Before the pipeline is set to PLAYING, the pipeline asks each element if Before the pipeline is set to `PLAYING`, the pipeline asks each element if
they can provide a clock. The clock is selected in the following order: they can provide a clock. The clock is selected in the following order:
- If the application selected a clock, use that one. - If the application selected a clock, use that one.
@ -340,7 +340,7 @@ produces data.
## Pipeline states ## Pipeline states
When all the pads are linked and signals have been connected, the When all the pads are linked and signals have been connected, the
pipeline can be put in the PAUSED state to start dataflow. pipeline can be put in the `PAUSED` state to start dataflow.
When a bin (and hence a pipeline) performs a state change, it will When a bin (and hence a pipeline) performs a state change, it will
change the state of all its children. The pipeline will change the state change the state of all its children. The pipeline will change the state
@ -354,18 +354,20 @@ the order alsasink, mp3dec, filesrc.
All intermediate states are traversed for each element resulting in the All intermediate states are traversed for each element resulting in the
following chain of state changes: following chain of state changes:
* alsasink to READY: the audio device is probed * alsasink to `READY`: the audio device is probed
* mp3dec to READY: nothing happens. * mp3dec to `READY`: nothing happens
* filesrc to READY: the file is probed * filesrc to `READY`: the file is probed
* alsasink to PAUSED: the audio device is opened. alsasink is a sink and returns ASYNC because it did not receive data yet. mp3dec to PAUSED: the decoding library is initialized * alsasink to `PAUSED`: the audio device is opened. alsasink is a sink and returns `ASYNC` because it did not receive data yet
* filesrc to PAUSED: the file is opened and a thread is started to push data to mp3dec * mp3dec to `PAUSED`: the decoding library is initialized
* filesrc to `PAUSED`: the file is opened and a thread is started to push data to mp3dec
At this point data flows from filesrc to mp3dec and alsasink. Since At this point data flows from filesrc to mp3dec and alsasink. Since
mp3dec is PAUSED, it accepts the data from filesrc on the sinkpad and mp3dec is `PAUSED`, it accepts the data from filesrc on the sinkpad and
starts decoding the compressed data to raw audio samples. starts decoding the compressed data to raw audio samples.
The mp3 decoder figures out the samplerate, the number of channels and The mp3 decoder figures out the samplerate, the number of channels and
@ -383,15 +385,15 @@ buffer of samples, it completes the state change to the PAUSED state. At
this point the pipeline is prerolled and all elements have samples. this point the pipeline is prerolled and all elements have samples.
Alsasink is now also capable of providing a clock to the pipeline. Alsasink is now also capable of providing a clock to the pipeline.
Since alsasink is now in the PAUSED state it blocks while receiving the Since alsasink is now in the `PAUSED` state it blocks while receiving the
first buffer. This effectively blocks both mp3dec and filesrc in their first buffer. This effectively blocks both mp3dec and filesrc in their
`gst_pad_push()`. `gst_pad_push()`.
Since all elements now return SUCCESS from the Since all elements now return `SUCCESS` from the
`gst_element_get_state()` function, the pipeline can be put in the `gst_element_get_state()` function, the pipeline can be put in the
PLAYING state. `PLAYING` state.
Before going to PLAYING, the pipeline select a clock and samples the Before going to `PLAYING`, the pipeline select a clock and samples the
current time of the clock. This is the `base_time`. It then distributes current time of the clock. This is the `base_time`. It then distributes
this time to all elements. Elements can then synchronize against the this time to all elements. Elements can then synchronize against the
clock using the buffer `running_time` clock using the buffer `running_time`
@ -399,11 +401,11 @@ clock using the buffer `running_time`
The following chain of state changes then takes place: The following chain of state changes then takes place:
* alsasink to PLAYING: the samples are played to the audio device * alsasink to `PLAYING`: the samples are played to the audio device
* mp3dec to PLAYING: nothing happens * mp3dec to `PLAYING`: nothing happens
* filesrc to PLAYING: nothing happens * filesrc to `PLAYING`: nothing happens
## Pipeline status ## Pipeline status
@ -415,11 +417,11 @@ The bus can be polled or added to the glib mainloop.
The bus is distributed to all elements added to the pipeline. The The bus is distributed to all elements added to the pipeline. The
elements use the bus to post messages on. Various message types exist elements use the bus to post messages on. Various message types exist
such as ERRORS, WARNINGS, EOS, `STATE_CHANGED`, etc.. such as `ERRORS`, `WARNINGS`, `EOS`, `STATE_CHANGED`, etc..
The pipeline handles EOS messages received from elements in a special The pipeline handles `EOS` messages received from elements in a special
way. It will only forward the message to the application when all sink way. It will only forward the message to the application when all sink
elements have posted an EOS message. elements have posted an `EOS` message.
Other methods for obtaining the pipeline status include the Query Other methods for obtaining the pipeline status include the Query
functionality that can be performed with `gst_element_query()` on the functionality that can be performed with `gst_element_query()` on the
@ -436,50 +438,50 @@ supposed to accept any more data after receiving an EOS event on a
sinkpad. sinkpad.
The element providing the streaming thread stops sending data after The element providing the streaming thread stops sending data after
sending the EOS event. sending the `EOS` event.
The EOS event will eventually arrive in the sink element. The sink will The EOS event will eventually arrive in the sink element. The sink will
then post an EOS message on the bus to inform the pipeline that a then post an `EOS` message on the bus to inform the pipeline that a
particular stream has finished. When all sinks have reported EOS, the particular stream has finished. When all sinks have reported `EOS`, the
pipeline forwards the EOS message to the application. The EOS message is pipeline forwards the EOS message to the application. The `EOS` message is
only forwarded to the application in the PLAYING state. only forwarded to the application in the `PLAYING` state.
When in EOS, the pipeline remains in the PLAYING state, it is the When in `EOS`, the pipeline remains in the `PLAYING` state, it is the
applications responsability to PAUSE or READY the pipeline. The applications responsability to `PAUSE` or `READY` the pipeline. The
application can also issue a seek, for example. application can also issue a seek, for example.
## Pipeline READY ## Pipeline READY
When a running pipeline is set from the PLAYING to READY state, the When a running pipeline is set from the `PLAYING` to `READY` state, the
following actions occur in the pipeline: following actions occur in the pipeline:
* alsasink to PAUSED: alsasink blocks and completes the state change on the * alsasink to `PAUSED`: alsasink blocks and completes the state change on the
next sample. If the element was EOS, it does not wait for a sample to complete next sample. If the element was `EOS`, it does not wait for a sample to complete
the state change. the state change.
* mp3dec to PAUSED: nothing * mp3dec to `PAUSED`: nothing
* filesrc to PAUSED: nothing * filesrc to `PAUSED`: nothing
Going to the intermediate PAUSED state will block all elements in the Going to the intermediate `PAUSED` state will block all elements in the
`_push()` functions. This happens because the sink element blocks on the `_push()` functions. This happens because the sink element blocks on the
first buffer it receives. first buffer it receives.
Some elements might be performing blocking operations in the PLAYING Some elements might be performing blocking operations in the `PLAYING`
state that must be unblocked when they go into the PAUSED state. This state that must be unblocked when they go into the PAUSED state. This
makes sure that the state change happens very fast. makes sure that the state change happens very fast.
In the next PAUSED to READY state change the pipeline has to shut down In the next `PAUSED` to `READY` state change the pipeline has to shut down
and all streaming threads must stop sending data. This happens in the and all streaming threads must stop sending data. This happens in the
following sequence: following sequence:
* alsasink to READY: alsasink unblocks from the `_chain()` function and returns * alsasink to `READY`: alsasink unblocks from the `_chain()` function and returns
a FLUSHING return value to the peer element. The sinkpad is deactivated and a `FLUSHING` return value to the peer element. The sinkpad is deactivated and
becomes unusable for sending more data. becomes unusable for sending more data.
* mp3dec to READY: the pads are deactivated and the state change completes * mp3dec to `READY`: the pads are deactivated and the state change completes
when mp3dec leaves its `_chain()` function. when mp3dec leaves its `_chain()` function.
* filesrc to READY: the pads are deactivated and the thread is paused. * filesrc to `READY`: the pads are deactivated and the thread is paused.
The upstream elements finish their `_chain()` function because the The upstream elements finish their `_chain()` function because the
downstream element returned an error code (FLUSHING) from the `_push()` downstream element returned an error code (`FLUSHING`) from the `_push()`
functions. These error codes are eventually returned to the element that functions. These error codes are eventually returned to the element that
started the streaming thread (filesrc), which pauses the thread and started the streaming thread (filesrc), which pauses the thread and
completes the state change. completes the state change.
@ -513,13 +515,13 @@ operation, that element performs the following steps.
2) make sure the streaming thread is not running. The streaming thread will 2) make sure the streaming thread is not running. The streaming thread will
always stop because of step 1). always stop because of step 1).
3) perform the seek operation 3) perform the seek operation
4) send a FLUSH done event to all downstream and upstream peer elements. 4) send a `FLUSH` done event to all downstream and upstream peer elements.
5) send SEGMENT event to inform all elements of the new position and to complete 5) send `SEGMENT` event to inform all elements of the new position and to complete
the seek. the seek.
In step 1) all downstream elements have to return from any blocking In step 1) all downstream elements have to return from any blocking
operations and have to refuse any further buffers or events different operations and have to refuse any further buffers or events different
from a FLUSH done. from a `FLUSH` done.
The first step ensures that the streaming thread eventually unblocks and The first step ensures that the streaming thread eventually unblocks and
that step 2) can be performed. At this point, dataflow is completely that step 2) can be performed. At this point, dataflow is completely
@ -536,13 +538,13 @@ Step 5) informs all elements of the new position in the stream. After
that the event function returns back to the application. and the that the event function returns back to the application. and the
streaming threads start to produce new data. streaming threads start to produce new data.
Since the pipeline is still PAUSED, this will preroll the next media Since the pipeline is still `PAUSED`, this will preroll the next media
sample in the sinks. The application can wait for this preroll to sample in the sinks. The application can wait for this preroll to
complete by performing a `_get_state()` on the pipeline. complete by performing a `_get_state()` on the pipeline.
The last step in the seek operation is then to adjust the stream The last step in the seek operation is then to adjust the stream
`running_time` of the pipeline to 0 and to set the pipeline back to `running_time` of the pipeline to 0 and to set the pipeline back to
PLAYING. `PLAYING`.
The sequence of events in our mp3 playback example. The sequence of events in our mp3 playback example.