markdown/pwg/building/statemanage-states.md

   1 ---
   2 title: What are states?
   3 ...
   4
   5 # What are states?
   6
   7 A state describes whether the element instance is initialized, whether
   8 it is ready to transfer data and whether it is currently handling data.
   9 There are four states defined in GStreamer:
  10
  11   - `GST_STATE_NULL`
  12
  13   - `GST_STATE_READY`
  14
  15   - `GST_STATE_PAUSED`
  16
  17   - `GST_STATE_PLAYING`
  18
  19 which will from now on be referred to simply as “NULL”, “READY”,
  20 “PAUSED” and “PLAYING”.
  21
  22 `GST_STATE_NULL` is the default state of an element. In this state, it
  23 has not allocated any runtime resources, it has not loaded any runtime
  24 libraries and it can obviously not handle data.
  25
  26 `GST_STATE_READY` is the next state that an element can be in. In the
  27 READY state, an element has all default resources (runtime-libraries,
  28 runtime-memory) allocated. However, it has not yet allocated or defined
  29 anything that is stream-specific. When going from NULL to READY state
  30 (`GST_STATE_CHANGE_NULL_TO_READY`), an element should allocate any
  31 non-stream-specific resources and should load runtime-loadable libraries
  32 (if any). When going the other way around (from READY to NULL,
  33 `GST_STATE_CHANGE_READY_TO_NULL`), an element should unload these
  34 libraries and free all allocated resources. Examples of such resources
  35 are hardware devices. Note that files are generally streams, and these
  36 should thus be considered as stream-specific resources; therefore, they
  37 should *not* be allocated in this state.
  38
  39 `GST_STATE_PAUSED` is the state in which an element is ready to accept
  40 and handle data. For most elements this state is the same as PLAYING.
  41 The only exception to this rule are sink elements. Sink elements only
  42 accept one single buffer of data and then block. At this point the
  43 pipeline is 'prerolled' and ready to render data immediately.
  44
  45 `GST_STATE_PLAYING` is the highest state that an element can be in. For
  46 most elements this state is exactly the same as PAUSED, they accept and
  47 process events and buffers with data. Only sink elements need to
  48 differentiate between PAUSED and PLAYING state. In PLAYING state, sink
  49 elements actually render incoming data, e.g. output audio to a sound
  50 card or render video pictures to an image sink.
  51
  52 ## Managing filter state
  53
  54 If at all possible, your element should derive from one of the new base
  55 classes ([Pre-made base classes](pwg/other/base.md)). There are
  56 ready-made general purpose base classes for different types of sources,
  57 sinks and filter/transformation elements. In addition to those,
  58 specialised base classes exist for audio and video elements and others.
  59
  60 If you use a base class, you will rarely have to handle state changes
  61 yourself. All you have to do is override the base class's start() and
  62 stop() virtual functions (might be called differently depending on the
  63 base class) and the base class will take care of everything for you.
  64
  65 If, however, you do not derive from a ready-made base class, but from
  66 GstElement or some other class not built on top of a base class, you
  67 will most likely have to implement your own state change function to be
  68 notified of state changes. This is definitively necessary if your plugin
  69 is a demuxer or a muxer, as there are no base classes for muxers or
  70 demuxers yet.
  71
  72 An element can be notified of state changes through a virtual function
  73 pointer. Inside this function, the element can initialize any sort of
  74 specific data needed by the element, and it can optionally fail to go
  75 from one state to another.
  76
  77 Do not g\_assert for unhandled state changes; this is taken care of by
  78 the GstElement base class.
  79
  80     static GstStateChangeReturn
  81     gst_my_filter_change_state (GstElement *element, GstStateChange transition);
  82
  83     static void
  84     gst_my_filter_class_init (GstMyFilterClass *klass)
  85     {
  86       GstElementClass *element_class = GST_ELEMENT_CLASS (klass);
  87
  88       element_class->change_state = gst_my_filter_change_state;
  89     }
  90
  91
  92
  93     static GstStateChangeReturn
  94     gst_my_filter_change_state (GstElement *element, GstStateChange transition)
  95     {
  96       GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
  97       GstMyFilter *filter = GST_MY_FILTER (element);
  98
  99       switch (transition) {
 100         case GST_STATE_CHANGE_NULL_TO_READY:
 101           if (!gst_my_filter_allocate_memory (filter))
 102             return GST_STATE_CHANGE_FAILURE;
 103           break;
 104         default:
 105           break;
 106       }
 107
 108       ret = GST_ELEMENT_CLASS (parent_class)->change_state (element, transition);
 109       if (ret == GST_STATE_CHANGE_FAILURE)
 110         return ret;
 111
 112       switch (transition) {
 113         case GST_STATE_CHANGE_READY_TO_NULL:
 114           gst_my_filter_free_memory (filter);
 115           break;
 116         default:
 117           break;
 118       }
 119
 120       return ret;
 121     }
 122
 123 Note that upwards (NULL=\>READY, READY=\>PAUSED, PAUSED=\>PLAYING) and
 124 downwards (PLAYING=\>PAUSED, PAUSED=\>READY, READY=\>NULL) state changes
 125 are handled in two separate blocks with the downwards state change
 126 handled only after we have chained up to the parent class's state change
 127 function. This is necessary in order to safely handle concurrent access
 128 by multiple threads.
 129
 130 The reason for this is that in the case of downwards state changes you
 131 don't want to destroy allocated resources while your plugin's chain
 132 function (for example) is still accessing those resources in another
 133 thread. Whether your chain function might be running or not depends on
 134 the state of your plugin's pads, and the state of those pads is closely
 135 linked to the state of the element. Pad states are handled in the
 136 GstElement class's state change function, including proper locking,
 137 that's why it is essential to chain up before destroying allocated
 138 resources.