docs/manual/states.xml

   1 <chapter id="cha-states">
   2   <title>Element states</title>
   3   <para>
   4     Once you have created a pipeline packed with elements, nothing will happen
   5     right away. This is where the different states come into play.
   6   </para>
   7
   8   <sect1 id="sec-states">
   9     <title>The different element states</title>
  10     <para>
  11       All elements can be in one of the following four states:
  12       <itemizedlist>
  13         <listitem>
  14           <para>
  15             NULL: this is the default state all elements are in when they are created
  16             and are doing nothing.
  17           </para>
  18         </listitem>
  19         <listitem>
  20           <para>
  21             READY: An element is ready to start doing something.
  22           </para>
  23         </listitem>
  24         <listitem>
  25           <para>
  26             PAUSED: The element is paused for a period of time.
  27           </para>
  28         </listitem>
  29         <listitem>
  30           <para>
  31             PLAYING: The element is doing something.
  32           </para>
  33         </listitem>
  34       </itemizedlist>
  35     </para>
  36
  37     <para>
  38       All elements start with the NULL state. The elements will go throught
  39       the following state changes: NULL -&gt; READY -&gt; PAUSED -&gt;
  40       PLAYING. Remember when going from PLAYING to READY, GStreamer will
  41       internally go throught the intermediate states.
  42     </para>
  43     <para>
  44       The state of an element can be changed with the following code:
  45     </para>
  46     <programlisting>
  47   GstElement *bin;
  48
  49   // create a bin, put elements in it and link them
  50   ...
  51   gst_element_set_state (bin, GST_STATE_PLAYING);
  52   ...
  53     </programlisting>
  54
  55     <para>
  56       You can set the following states to an element:
  57     </para>
  58     <informaltable pgwide="1" frame="none" role="enum">
  59     <tgroup cols="2">
  60     <tbody>
  61       <row>
  62         <entry><literal>GST_STATE_NULL</literal></entry>
  63         <entry>Reset the state of an element.
  64         </entry>
  65       </row>
  66       <row>
  67         <entry><literal>GST_STATE_READY</literal></entry>
  68         <entry>will make the element ready to start processing data.
  69         </entry>
  70       </row>
  71       <row>
  72         <entry><literal>GST_STATE_PAUSED</literal></entry>
  73         <entry>temporary stops the data flow.
  74         </entry>
  75       </row>
  76       <row>
  77         <entry><literal>GST_STATE_PLAYING</literal></entry>
  78         <entry>means there really is data flowing through the graph.
  79         </entry>
  80       </row>
  81     </tbody>
  82     </tgroup>
  83     </informaltable>
  84
  85   </sect1>
  86
  87   <sect1 id="sec-states-null">
  88     <title>The NULL state</title>
  89     <para>
  90       When you created the pipeline all of the elements will be in the NULL state. There is
  91       nothing spectacular about the NULL state.
  92     </para>
  93     <note>
  94       <para>
  95         Don't forget to reset the pipeline to the NULL state when you are not going to use it
  96         anymore. This will allow the elements to free the resources they might use.
  97       </para>
  98     </note>
  99   </sect1>
 100
 101   <sect1 id="sec-states-ready">
 102     <title>The READY state</title>
 103     <para>
 104       You will start the pipeline by first setting it to the READY state. This will allow the
 105       pipeline and all the elements contained in it to prepare themselves for the actions
 106       they are about to perform.
 107     </para>
 108     <para>
 109       The typical actions that an element will perform in the READY state might be to open a file or
 110       an audio device. Some more complex elements might have a non trivial action to perform in
 111       the READY state such as connecting to a media server using a CORBA connection.
 112     </para>
 113     <note>
 114       <para>
 115         You can also go from the NULL to PLAYING state directly without
 116         going through the READY state. This is a shortcut; the framework
 117         will internally go through the READY and the PAUSED state for you.
 118       </para>
 119     </note>
 120   </sect1>
 121
 122   <sect1 id="sec-states-playing">
 123     <title>The PLAYING state</title>
 124     <para>
 125       A Pipeline that is in the READY state can be started by setting it to the PLAYING state. At
 126       that time data will start to flow all the way through the pipeline.
 127     </para>
 128   </sect1>
 129
 130   <sect1 id="sec-states-paused">
 131     <title>The PAUSED state</title>
 132     <para>
 133       A pipeline that is playing can be set to the PAUSED state. This will temporarily stop all
 134       data flowing through the pipeline.
 135     </para>
 136     <para>
 137       You can resume the data flow by setting the pipeline back to the PLAYING state.
 138     </para>
 139     <note>
 140       <para>
 141         The PAUSED state is available for temporarily freezing the pipeline.
 142         Elements will typically not free their resources in the PAUSED state.
 143         Use the NULL state if you want to stop the data flow permanently.
 144       </para>
 145     </note>
 146     <para>
 147       The pipeline has to be in the PAUSED or NULL state if you want to insert or modify an element
 148       in the pipeline. We will cover dynamic pipeline behaviour in <xref linkend="cha-dynamic"/>.
 149     </para>
 150   </sect1>
 151
 152 </chapter>