docs/pwg/building-state.xml

   1 <chapter id="chapter-statemanage-states">
   2   <title>
   3     What are states?
   4   </title>
   5   <para>
   6     A state describes whether the element instance is initialized, whether it
   7     is ready to transfer data and whether it is currently handling data. There
   8     are four states defined in &GStreamer;: <classname>GST_STATE_NULL</classname>,
   9     <classname>GST_STATE_READY</classname>, <classname>GST_STATE_PAUSED</classname>
  10     and <classname>GST_STATE_PLAYING</classname>.
  11   </para>
  12   <para>
  13     <classname>GST_STATE_NULL</classname> (from now on referred to as
  14     <quote>NULL</quote>) is the default state of an element. In this state, it
  15     has not allocated any runtime resources, it has not loaded any runtime
  16     libraries and it can obviously not handle data.
  17   </para>
  18   <para>
  19     <classname>GST_STATE_READY</classname> (from now on referred to as
  20     <quote>READY</quote>) is the next state that an element can be in. In the
  21     READY state, an element has all default resources (runtime-libraries,
  22     runtime-memory) allocated. However, it has not yet allocated or defined
  23     anything that is stream-specific. When going from NULL to READY state
  24     (<classname>GST_STATE_NULL_TO_READY</classname>), an element should
  25     allocate any non-stream-specific resources and should load runtime-loadable
  26     libraries (if any). When going the other way around (from READY to NULL,
  27     <classname>GST_STATE_READY_TO_NULL</classname>), an element should unload
  28     these libraries and free all allocated resources. Examples of such
  29     resources are hardware devices. Note that files are generally streams,
  30     and these should thus be considered as stream-specific resources; therefore,
  31     they should <emphasis>not</emphasis> be allocated in this state.
  32   </para>
  33   <para>
  34     <classname>GST_STATE_PAUSED</classname> (from now on referred to as
  35     <quote>PAUSED</quote>) is a state in which an element is by all means able
  36     to handle data; the only 'but' here is that it doesn't actually handle
  37     any data. When going from the READY state into the PAUSED state
  38     (<classname>GST_STATE_READY_TO_PAUSED</classname>), the element will
  39     usually not do anything at all: all stream-specific info is generally
  40     handled in the <function>_link ()</function>, which is called during caps
  41     negotiation. Exceptions to this rule are, for example, files: these are
  42     considered stream-specific data (since one file is one stream), and should
  43     thus be opened in this state change. When going from the PAUSED back to
  44     READY (<classname>GST_STATE_PAUSED_TO_READY</classname>), all
  45     stream-specific data should be discarded.
  46   </para>
  47   <para>
  48     <classname>GST_STATE_PLAYING</classname> (from now on referred to as
  49     <quote>PLAYING</quote>) is the highest state that an element can be in. It
  50     is similar to PAUSED, except that now, data is actually passing over the
  51     pipeline. The transition from PAUSED to PLAYING
  52     (<classname>GST_STATE_PAUSED_TO_PLAYING</classname>) should be as small
  53     as possible and would ideally cause no delay at all. The same goes for the
  54     reverse transition (<classname>GST_STATE_PLAYING_TO_PAUSED</classname>).
  55   </para>
  56
  57   <sect1 id="section-statemanage-filters">
  58   <title>
  59     Mangaging filter state
  60   </title>
  61   <para>
  62     An element can be notified of state changes through a virtual function
  63     pointer. Inside this function, the element can initialize any sort of
  64     specific data needed by the element, and it can optionally fail to
  65     go from one state to another.
  66   </para>
  67   <programlisting>
  68 static GstElementStateReturn
  69                 gst_my_filter_change_state      (GstElement *element);
  70
  71 static void
  72 gst_my_filter_class_init (GstMyFilterClass *klass)
  73 {
  74   GstElementClass *element_class = GST_ELEMENT_CLASS (klass);
  75
  76   element_class->change_state = gst_my_filter_change_state;
  77 }
  78
  79 static GstElementStateReturn
  80 gst_my_filter_change_state (GstElement *element)
  81 {
  82   GstMyFilter *filter = GST_MY_FILTER (element);
  83
  84   switch (GST_STATE_TRANSITION (element)) {
  85     case GST_STATE_NULL_TO_READY:
  86       if (!gst_my_filter_allocate_memory (filter))
  87         return GST_STATE_FAILURE;
  88       break;
  89     case GST_STATE_READY_TO_NULL:
  90       gst_my_filter_free_memory (filter);
  91       break;
  92     default:
  93       break;
  94   }
  95
  96   if (GST_ELEMENT_CLASS (parent_class)->change_state)
  97     return GST_ELEMENT_CLASS (parent_class)->change_state (element);
  98
  99   return GST_STATE_SUCCESS;
 100 }
 101   </programlisting>
 102   </sect1>
 103 </chapter>