docs/random/states

OUTDATED
--------


GST State Bits and Transition Rules (graph to follow)
-----------------------------------

These are the 'new' state bits and what they mean.

What the state bits are:
GST_STATE_COMPLETE: if the element has enough data, but is not in any kind
	of running or explicitely stopped state.  ready to be used.
GST_STATE_RUNNING: this is the normal state of the pipeline, where data
	goes all the way through the pipeline normally.
GST_STATE_DISCOVERY: anything the element does in this state must be reset
	after discovery.  any data read from sync source must be cached.
GST_STATE_PREROLL: not a lot different from PLAYING, except sinks don't
	render what they're getting.  useful for elements that require
	data to get in sync, such as an MPEG video decoder that needs
	IBBPBB before starting at the next P.



Basic transition rules:

Completeness is based on the element having enough information to actually
do something.  GST_STATE_COMPLETE is required for any other state to be
valid, though the only invariant is that you can't be RUNNING unless
you're COMPLETE.  In fact, AFAICT, that's the *only* invariant.

The element is entirely in control of this bit at all times.  There is no
way to externally change this bit except by changing the state of the
element in such a way as to effect a change.

|= GST_STATE_COMPLETE
	setting whatever the last bit of info the element was looking for
	(gst_object_set)

&= ~GST_STATE_COMPLETE
	changing anything that invalidates the complete state of the element


Whether the element is running or not, on the other hand, is almost
entirely out of the hands of the individual element.  This is generally
turned on by way of gst_element_run() as called by the parent (ultimately
by the Pipeline), which happens to optionally call a function private to
the element to prepare it.  As per docs/random/gboolean, very likely this
function should return a TRUE/FALSE.

Generally, I think if there is no such function, the generic element code
should go ahead and set the state, and trigger the state_changed signal,
returning TRUE.  If there is a function, call it.  If it returns TRUE,
fire off the signal (since the signal is actually an Element signal
anyway, why eat another function call?).  Return the result regardless.

|= GST_STATE_RUNNING
	starting up the pipeline with gst_pipeline_start

~= ~GST_STATE_RUNNING
	stopping the pipeline with gst_pipeline_stop, or some error state

gst_pipeline_start() simply calls the gst_element_start() function on each
of the elements in it.  This sets the RUNNING bit of each element, and for
GstBin's it loops through that list.  gst_pipeline_start() is just a
special case version of gst_bin_start().  All start() functions are
GstElementClass functions, meaning you can start any element the same way.

The pipeline can be stopped the same way, but more likely the pipeline
will be stopped due to some stoppage condition, such as EOF on the source
file, or the parser being told to stop the stream.  In the EOF case, it
would turn its RUNNING bit off, then call the stop() class function on its
parent.  This would trigger an up-hill, breath-first traversal of the
whole graph.  Alternately, if each element lists its uber-parent (the
Pipeline) it can simply inform the pipeline directly, causing a
depth-first traversal just like the start() case.