States
-======
+------
Both elements and pads can be in different states. The states of the pads are
linked to the state of the element so the design of the states is mainly
State definitions
------------------
+~~~~~~~~~~~~~~~~~
- NULL: This is the initial state of an element.
- READY: The element should be prepared to go to PAUSED.
State transitions
------------------
+~~~~~~~~~~~~~~~~~
the following state changes are possible:
NULL -> READY
- The element must check if the resources it needs are available.
- Device sinks and -sources typically try to probe the device to constain
+ Device sinks and -sources typically try to probe the device to constrain
their caps.
+ - The element opens the device, this is needed if the previous step requires
+ the device to be opened.
READY -> PAUSED
- - The element opens the device and prepares itself for PLAYING.
- - the element pads are activated in order to receive data in PAUSED.
+ - The element pads are activated in order to receive data in PAUSED.
Streaming threads are started.
- - some elements might need to return ASYNC and complete the state change
+ - Some elements might need to return ASYNC and complete the state change
when they have enough information. It is a requirement for sinks to
return ASYNC and complete the state change when they receive the first
- buffer or EOS event (prerol). Sinks also block the dataflow when in PAUSED.
- - a pipeline resets the running_time to 0.
- - live sources return NO_PREROLL and don't generate data.
+ buffer or EOS event (preroll). Sinks also block the dataflow when in PAUSED.
+ - A pipeline resets the running_time to 0.
+ - Live sources return NO_PREROLL and don't generate data.
PAUSED -> PLAYING
- - most elements ignore this state change.
+ - Most elements ignore this state change.
- The pipeline selects a clock and distributes this to all the children
- before setting them to PLAYING. This means that it is only alowed to
+ before setting them to PLAYING. This means that it is only allowed to
synchronize on the clock in the PLAYING state.
- The pipeline uses the clock and the running_time to calculate the base_time.
The base_time is distributed to all children when performing the state
change.
- - sink elements stop blocking on the preroll buffer or event and start
- rendering the data.
- - sinks can post the EOS message in the PLAYING state. It is not allowed to
+ - Sink elements stop blocking on the preroll buffer or event and start
+ rendering the data.
+ - Sinks can post the EOS message in the PLAYING state. It is not allowed to
post EOS when not in the PLAYING state.
- - while streaming in PAUSED or PLAYING elements can create and remove
- dynamic pads.
- - live sources start generating data and return SUCCESS.
+ - While streaming in PAUSED or PLAYING elements can create and remove
+ sometimes pads.
+ - Live sources start generating data and return SUCCESS.
PLAYING -> PAUSED
- - most elements ignore this state change.
+ - Most elements ignore this state change.
- The pipeline calculates the running_time based on the last selected clock
and the base_time. It stores this information to continue playback when
going back to the PLAYING state.
- - sinks unblock any clock wait calls.
- - when a sink did not have a pending buffer to play, it returns ASYNC from
- this state change and complete the state change when they receive a new buffer
- or an EOS event.
- - any queued EOS messages are removed since they will be reposted when going
+ - Sinks unblock any clock wait calls.
+ - When a sink does not have a pending buffer to play, it returns ASYNC from
+ this state change and completes the state change when it receives a new
+ buffer or an EOS event.
+ - Any queued EOS messages are removed since they will be reposted when going
back to the PLAYING state. The EOS messages are queued in GstBins.
- - live sources stop generating data and return NO_PREROLL.
+ - Live sources stop generating data and return NO_PREROLL.
PAUSED -> READY
- - sinks unblock any waits in the preroll.
- - elements unblock any waits on devices
- - elements close devices
- - chain or get_range functions return WRONG_STATE.
- - the element pads are deactivated so that streaming becomes impossible and
- all streaming threads are stopped.
+ - Sinks unblock any waits in the preroll.
+ - Elements unblock any waits on devices
+ - Chain or get_range functions return WRONG_STATE.
+ - The element pads are deactivated so that streaming becomes impossible and
+ all streaming threads are stopped.
+ - The sink forgets all negotiated formats
+ - Elements remove all sometimes pads
READY -> NULL
- - element removes any dynamically created pads
+ - Elements close devices
+ - Elements reset any internal state.
State variables
----------------
+~~~~~~~~~~~~~~~
An element has 4 state variables that are protected with the object LOCK:
Setting state on elements
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
-The state of an element can be changed with _element_set_state(). When chaning
+The state of an element can be changed with _element_set_state(). When changing
the state of an element all intermediate states will also be set on the element
until the final desired state is set.
GST_STATE_SUCCESS: The state change is completed successfully.
GST_STATE_ASYNC: The state change will complete later on. This can happen
- When the element needs a long time to perform the state
+ when the element needs a long time to perform the state
change or for sinks that need to receive the first buffer
before they can complete the state change (preroll).
state. Then the state change function of the element is called and the result of
that function is used to update the STATE and STATE_RETURN fields, STATE_NEXT,
STATE_PENDING and STATE_RETURN fields. If the function returned ASYNC, this result
-is immediatly returned to the caller.
+is immediately returned to the caller.
Getting state of elements
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
The _get_state() function takes 3 arguments, two pointers that will hold the
current and pending state and one GstClockTime that holds a timeout value. The
* If the element aborts the ASYNC state change due to an error within the
specified timeout, this function returns FAILURE with the state set to last
- successfull state and pending set to the last attempt. The element should
+ successful state and pending set to the last attempt. The element should
also post an error message on the bus with more information about the problem.
States in GstBin
-----------------
+~~~~~~~~~~~~~~~~
A GstBin manages the state of its children. It does this by propagating the state
changes performed on it to all of its children. The _set_state() function on a
-bin will call the _set_state() function on all of its children.
+bin will call the _set_state() function on all of its children, that are
+not already in the target state or in a change state to the target state.
The children are iterated from the sink elements to the source elements. This makes
sure that when changing the state of an element, the downstream elements are in
If all the children return SUCCESS, the function returns SUCCESS as well.
If one of the children returns FAILURE, the function returns FAILURE as well. In
-this state it is possible that some elements successfuly changed state. The
+this state it is possible that some elements successfully changed state. The
application can check which elements have a changed state, which were in error
and which were not affected by iterating the elements and calling _get_state()
on the elements.
Implementing states in elements
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
READY
------
+^^^^^
upward state change
--------------------
+~~~~~~~~~~~~~~~~~~~
Upward state changes always return ASYNC either if the STATE_PENDING is
reached or not.
to STATE_PENDING
downward state change
-----------------------
+~~~~~~~~~~~~~~~~~~~~~
Downward state changes only return ASYNC if the final state is ASYNC.
This is to make sure that it's not needed to wait for an element to
Locking overview (element)
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
* Element commiting SUCCESS
| ...
STREAM_UNLOCK
-*********************************************
-*********************************************
+Remarks
+~~~~~~~
set_state cannot be called from multiple threads at the same time. The STATE_LOCK
prevents this.
projects / platform / upstream / gstreamer.git / blobdiff