docs/pwg/: Update state change stuff for 0.10 (fixes #322969).

Original commit message from CVS:
* docs/pwg/building-chainfn.xml:
* docs/pwg/building-pads.xml:
* docs/pwg/building-state.xml:
* docs/pwg/other-source.xml:
Update state change stuff for 0.10 (fixes #322969).

ChangeLog

@@ -1,3 +1,11 @@
+2005-12-11  Tim-Philipp Müller  <tim at centricular dot net>
+
+	* docs/pwg/building-chainfn.xml:
+	* docs/pwg/building-pads.xml:
+	* docs/pwg/building-state.xml:
+	* docs/pwg/other-source.xml:
+	  Update state change stuff for 0.10 (fixes #322969).
+
 2005-12-11  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* docs/manual/advanced-dataaccess.xml:

docs/pwg/building-chainfn.xml

@@ -33,11 +33,11 @@ gst_my_filter_chain (GstPad    *pad,
 }
 <!-- example-end chain.c b -->
 <!-- example-begin chain.c c --><!--
-static GstElementStateReturn
+static GstStateChangeReturn
-gst_my_filter_change_state (GstElement * element)
+gst_my_filter_change_state (GstElement * element, GstStateChange transition)
 {
   return GST_CALL_PARENT_WITH_DEFAULT (GST_ELEMENT_CLASS,
-      change_state, (element), GST_STATE_SUCCESS);
+      change_state, (element, transition), GST_STATE_CHANGE_SUCCESS);
 }
 #include "register.func"
   --><!-- example-end chain.c c --></programlisting>
@@ -113,11 +113,11 @@ gst_my_filter_chain (GstPad    *pad,
 }
 <!-- example-end chain.func b -->
 <!-- example-begin chain2.c b --><!--
-static GstElementStateReturn
+static GstStateChangeReturn
-gst_my_filter_change_state (GstElement * element)
+gst_my_filter_change_state (GstElement * element, GstStateChange transition)
 {
   return GST_CALL_PARENT_WITH_DEFAULT (GST_ELEMENT_CLASS,
-      change_state, (element), GST_STATE_SUCCESS);
+      change_state, (element, transition), GST_STATE_CHANGE_SUCCESS);
 }
 #include "register.func"
   --><!-- example-end chain2.c b --></programlisting>

docs/pwg/building-pads.xml

@@ -27,8 +27,8 @@
 #include "filter.h"
 #include <string.h>
 
-static GstElementStateReturn
+static GstStateChangeReturn
-			gst_my_filter_change_state (GstElement * element);
+gst_my_filter_change_state (GstElement * element, GstStateChange transition);
 
 GST_BOILERPLATE (GstMyFilter, gst_my_filter, GstElement, GST_TYPE_ELEMENT);
 
@@ -217,11 +217,11 @@ gst_my_filter_chain (GstPad * pad, GstBuffer * buf)
   return gst_pad_push (GST_MY_FILTER (GST_OBJECT_PARENT (pad))->srcpad, buf);
 }
 
-static GstElementStateReturn
+static GstStateChangeReturn
-gst_my_filter_change_state (GstElement * element)
+gst_my_filter_change_state (GstElement * element, GstStateChange transition)
 {
   return GST_CALL_PARENT_WITH_DEFAULT (GST_ELEMENT_CLASS,
-      change_state, (element), GST_STATE_SUCCESS);
+      change_state, (element, transition), GST_STATE_CHANGE_SUCCESS);
 }
 
 #include "register.func"

docs/pwg/building-state.xml

@@ -131,7 +131,7 @@ gst_my_filter_free_memory (GstMyFilter * filter)
 static GstStateChangeReturn
 gst_my_filter_change_state (GstElement *element, GstStateChange transition)
 {
-  GstElementStateReturn ret = GST_STATE_SUCCESS;
+  GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
   GstMyFilter *filter = GST_MY_FILTER (element);
 
   switch (transition) {
@@ -144,6 +144,8 @@ gst_my_filter_change_state (GstElement *element, GstStateChange transition)
   }
 
   ret = GST_ELEMENT_CLASS (parent_class)->change_state (element, transition);
+  if (ret == GST_STATE_CHANGE_FAILURE)
+    return ret;
 
   switch (transition) {
     case GST_STATE_CHANGE_READY_TO_NULL:
@@ -160,9 +162,9 @@ gst_my_filter_change_state (GstElement *element, GstStateChange transition)
 #include "register.func"
   --><!-- example-end state.c b --></programlisting>
   <para>
-    Note that upwards (NULL=>READY, READY=>PAUSED, PAUSED=>PLAYING) and 
+    Note that upwards (NULL=&gt;READY, READY=&gt;PAUSED, PAUSED=&gt;PLAYING)
-    downwards (PLAYING=>PAUSED, PAUSED=>READY, READY=>NULL) state changes
+    and downwards (PLAYING=&gt;PAUSED, PAUSED=&gt;READY, READY=&gt;NULL) state
-    are handled in two separate blocks with the downwards state change
+    changes are handled in two separate blocks with the downwards state change
     handled only after we have chained up to the parent class's state
     change function. This is necessary in order to safely handle concurrent
     access by multiple threads.

docs/pwg/other-source.xml

@@ -299,24 +299,35 @@ gst_my_source_get (GstPad *pad)
   return GST_DATA (buf);
 }
 
-static GstStateReturn
+static GstStateChangeReturn
-gst_my_source_change_state (GstElement *element)
+gst_my_source_change_state (GstElement *element, GstStateChange transition)
 {
+  GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
   GstMySource *src = GST_MY_SOURCE (element);
 
-  switch (GST_STATE_PENDING (element)) {
+  /* First, handle upwards state changes */
-    case GT_STATE_PAUSED_TO_READY:
+  switch (transition) {
-      src->total_bytes = 0;
+    case GST_STATE_READY_TO_PAUSED:
+      /* do something */
       break;
-
     default:
       break;
   }
 
-  if (GST_ELEMENT_CLASS (parent_class)->change_state)
+  ret = GST_ELEMENT_CLASS (parent_class)->change_state (element, transition);
-    return GST_ELEMENT_CLASS (parent_class)->change_state (element);
+  if (ret == GST_STATE_CHANGE_FAILURE)
+    return ret;
 
-  return GST_STATE_SUCCESS;
+  /* Now handle downwards state changes after chaining up */
+  switch (transition) {
+    case GST_STATE_PAUSED_TO_READY:
+      src->total_bytes = 0;
+      break;
+    default:
+      break;
+  }
+
+  return ret;
 }
     </programlisting>
     <para>