docs/random/states

   1 GST State Bits and Transition Rules (graph to follow)
   2 -----------------------------------
   3
   4 These are the 'new' state bits and what they mean.
   5
   6 What the state bits are:
   7 GST_STATE_COMPLETE: if the element has enough data, but is not in any kind
   8         of running or explicitely stopped state.  ready to be used.
   9 GST_STATE_RUNNING: this is the normal state of the pipeline, where data
  10         goes all the way through the pipeline normally.
  11 GST_STATE_DISCOVERY: anything the element does in this state must be reset
  12         after discovery.  any data read from sync source must be cached.
  13 GST_STATE_PREROLL: not a lot different from PLAYING, except sinks don't
  14         render what they're getting.  useful for elements that require
  15         data to get in sync, such as an MPEG video decoder that needs
  16         IBBPBB before starting at the next P.
  17
  18
  19
  20 Basic transition rules:
  21
  22 Completeness is based on the element having enough information to actually
  23 do something.  GST_STATE_COMPLETE is required for any other state to be
  24 valid, though the only invariant is that you can't be RUNNING unless
  25 you're COMPLETE.  In fact, AFAICT, that's the *only* invariant.
  26
  27 The element is entirely in control of this bit at all times.  There is no
  28 way to externally change this bit except by changing the state of the
  29 element in such a way as to effect a change.
  30
  31 |= GST_STATE_COMPLETE
  32         setting whatever the last bit of info the element was looking for
  33         (gst_object_set)
  34
  35 &= ~GST_STATE_COMPLETE
  36         changing anything that invalidates the complete state of the element
  37
  38
  39 Whether the element is running or not, on the other hand, is almost
  40 entirely out of the hands of the individual element.  This is generally
  41 turned on by way of gst_element_run() as called by the parent (ultimately
  42 by the Pipeline), which happens to optionally call a function private to
  43 the element to prepare it.  As per docs/random/gboolean, very likely this
  44 function should return a TRUE/FALSE.
  45
  46 Generally, I think if there is no such function, the generic element code
  47 should go ahead and set the state, and trigger the state_changed signal,
  48 returning TRUE.  If there is a function, call it.  If it returns TRUE,
  49 fire off the signal (since the signal is actually an Element signal
  50 anyway, why eat another function call?).  Return the result regardless.
  51
  52 |= GST_STATE_RUNNING
  53         starting up the pipeline with gst_pipeline_start
  54
  55 ~= ~GST_STATE_RUNNING
  56         stopping the pipeline with gst_pipeline_stop, or some error state
  57
  58 gst_pipeline_start() simply calls the gst_element_start() function on each
  59 of the elements in it.  This sets the RUNNING bit of each element, and for
  60 GstBin's it loops through that list.  gst_pipeline_start() is just a
  61 special case version of gst_bin_start().  All start() functions are
  62 GstElementClass functions, meaning you can start any element the same way.
  63
  64 The pipeline can be stopped the same way, but more likely the pipeline
  65 will be stopped due to some stoppage condition, such as EOF on the source
  66 file, or the parser being told to stop the stream.  In the EOF case, it
  67 would turn its RUNNING bit off, then call the stop() class function on its
  68 parent.  This would trigger an up-hill, breath-first traversal of the
  69 whole graph.  Alternately, if each element lists its uber-parent (the
  70 Pipeline) it can simply inform the pipeline directly, causing a
  71 depth-first traversal just like the start() case.