docs/random/states

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