1 <chapter id="chapter-statemanage-states">
2 <title>What are states?</title>
4 A state describes whether the element instance is initialized, whether it
5 is ready to transfer data and whether it is currently handling data. There
6 are four states defined in &GStreamer;:
11 <symbol>GST_STATE_NULL</symbol>
16 <symbol>GST_STATE_READY</symbol>
21 <symbol>GST_STATE_PAUSED</symbol>
26 <symbol>GST_STATE_PLAYING</symbol>
31 which will from now on be referred to simply as <quote>NULL</quote>,
32 <quote>READY</quote>, <quote>PAUSED</quote> and <quote>PLAYING</quote>.
35 <symbol>GST_STATE_NULL</symbol> is the default state of an element. In this state, it
36 has not allocated any runtime resources, it has not loaded any runtime
37 libraries and it can obviously not handle data.
40 <symbol>GST_STATE_READY</symbol> is the next state that an element can be in. In the
41 READY state, an element has all default resources (runtime-libraries,
42 runtime-memory) allocated. However, it has not yet allocated or defined
43 anything that is stream-specific. When going from NULL to READY state
44 (<symbol>GST_STATE_CHANGE_NULL_TO_READY</symbol>), an element should
45 allocate any non-stream-specific resources and should load runtime-loadable
46 libraries (if any). When going the other way around (from READY to NULL,
47 <symbol>GST_STATE_CHANGE_READY_TO_NULL</symbol>), an element should unload
48 these libraries and free all allocated resources. Examples of such
49 resources are hardware devices. Note that files are generally streams,
50 and these should thus be considered as stream-specific resources; therefore,
51 they should <emphasis>not</emphasis> be allocated in this state.
54 <symbol>GST_STATE_PAUSED</symbol> is the state in which an element is
55 ready to accept and handle data. For most elements this state is the same
56 as PLAYING. The only exception to this rule are sink elements. Sink
57 elements only accept one single buffer of data and then block. At this
58 point the pipeline is 'prerolled' and ready to render data immediately.
61 <symbol>GST_STATE_PLAYING</symbol> is the highest state that an element
62 can be in. For most elements this state is exactly the same as PAUSED,
63 they accept and process events and buffers with data. Only sink elements
64 need to differentiate between PAUSED and PLAYING state. In PLAYING state,
65 sink elements actually render incoming data, e.g. output audio to a sound
66 card or render video pictures to an image sink.
69 <sect1 id="section-statemanage-filters">
70 <title>Managing filter state</title>
72 If at all possible, your element should derive from one of the new base
73 classes (<xref linkend="chapter-other-base"/>). There are ready-made
74 general purpose base classes for different types of sources, sinks and
75 filter/transformation elements. In addition to those, specialised base
76 classes exist for audio and video elements and others.
79 If you use a base class, you will rarely have to handle state changes
80 yourself. All you have to do is override the base class's start() and
81 stop() virtual functions (might be called differently depending on the
82 base class) and the base class will take care of everything for you.
85 If, however, you do not derive from a ready-made base class, but from
86 GstElement or some other class not built on top of a base class, you
87 will most likely have to implement your own state change function to
88 be notified of state changes. This is definitively necessary if your
89 plugin is a demuxer or a muxer, as there are no base classes for
90 muxers or demuxers yet.
93 An element can be notified of state changes through a virtual function
94 pointer. Inside this function, the element can initialize any sort of
95 specific data needed by the element, and it can optionally fail to
96 go from one state to another.
99 Do not g_assert for unhandled state changes; this is taken care of by
100 the GstElement base class.
103 static GstStateChangeReturn
104 gst_my_filter_change_state (GstElement *element, GstStateChange transition);
107 gst_my_filter_class_init (GstMyFilterClass *klass)
109 GstElementClass *element_class = GST_ELEMENT_CLASS (klass);
111 element_class->change_state = gst_my_filter_change_state;
113 <!-- example-begin state.c a --><!--
116 #include "chain.func"
117 #include "state.func"
118 --><!-- example-end state.c a -->
119 <!-- example-begin state.func a --><!--
121 gst_my_filter_allocate_memory (GstMyFilter * filter)
126 gst_my_filter_free_memory (GstMyFilter * filter)
129 --><!-- example-end state.func a -->
130 <!-- example-begin state.func b -->
131 static GstStateChangeReturn
132 gst_my_filter_change_state (GstElement *element, GstStateChange transition)
134 GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
135 GstMyFilter *filter = GST_MY_FILTER (element);
137 switch (transition) {
138 case GST_STATE_CHANGE_NULL_TO_READY:
139 if (!gst_my_filter_allocate_memory (filter))
140 return GST_STATE_CHANGE_FAILURE;
146 ret = GST_ELEMENT_CLASS (parent_class)->change_state (element, transition);
147 if (ret == GST_STATE_CHANGE_FAILURE)
150 switch (transition) {
151 case GST_STATE_CHANGE_READY_TO_NULL:
152 gst_my_filter_free_memory (filter);
160 <!-- example-end state.func b -->
161 <!-- example-begin state.c b --><!--
162 #include "register.func"
163 --><!-- example-end state.c b --></programlisting>
165 Note that upwards (NULL=>READY, READY=>PAUSED, PAUSED=>PLAYING)
166 and downwards (PLAYING=>PAUSED, PAUSED=>READY, READY=>NULL) state
167 changes are handled in two separate blocks with the downwards state change
168 handled only after we have chained up to the parent class's state
169 change function. This is necessary in order to safely handle concurrent
170 access by multiple threads.
173 The reason for this is that in the case of downwards state changes
174 you don't want to destroy allocated resources while your plugin's
175 chain function (for example) is still accessing those resources in
176 another thread. Whether your chain function might be running or not
177 depends on the state of your plugin's pads, and the state of those
178 pads is closely linked to the state of the element. Pad states are
179 handled in the GstElement class's state change function, including
180 proper locking, that's why it is essential to chain up before
181 destroying allocated resources.