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).

4 files changed, 37 insertions, 24 deletions

diff --git a/docs/pwg/building-chainfn.xml b/docs/pwg/building-chainfn.xml
index 1cda9393f..9e2735419 100644
--- a/docs/pwg/building-chainfn.xml
+++ b/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
-gst_my_filter_change_state (GstElement * element)
+static GstStateChangeReturn
+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
-gst_my_filter_change_state (GstElement * element)
+static GstStateChangeReturn
+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>
diff --git a/docs/pwg/building-pads.xml b/docs/pwg/building-pads.xml
index ae01054e2..ddd2df2d8 100644
--- a/docs/pwg/building-pads.xml
+++ b/docs/pwg/building-pads.xml
@@ -27,8 +27,8 @@
 #include "filter.h"
 #include &lt;string.h&gt;
 
-static GstElementStateReturn
-			gst_my_filter_change_state (GstElement * element);
+static GstStateChangeReturn
+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
-gst_my_filter_change_state (GstElement * element)
+static GstStateChangeReturn
+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"
diff --git a/docs/pwg/building-state.xml b/docs/pwg/building-state.xml
index 1c27018ed..b5011f5db 100644
--- a/docs/pwg/building-state.xml
+++ b/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)-&gt;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 
-    downwards (PLAYING=>PAUSED, PAUSED=>READY, READY=>NULL) state changes
-    are handled in two separate blocks with the downwards state change
+    Note that upwards (NULL=&gt;READY, READY=&gt;PAUSED, PAUSED=&gt;PLAYING)
+    and downwards (PLAYING=&gt;PAUSED, PAUSED=&gt;READY, READY=&gt;NULL) state
+    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.
diff --git a/docs/pwg/other-source.xml b/docs/pwg/other-source.xml
index ebc674167..f1141a28a 100644
--- a/docs/pwg/other-source.xml
+++ b/docs/pwg/other-source.xml
@@ -299,24 +299,35 @@ gst_my_source_get (GstPad *pad)
   return GST_DATA (buf);
 }
 
-static GstStateReturn
-gst_my_source_change_state (GstElement *element)
+static GstStateChangeReturn
+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)) {
-    case GT_STATE_PAUSED_TO_READY:
-      src->total_bytes = 0;
+  /* First, handle upwards state changes */
+  switch (transition) {
+    case GST_STATE_READY_TO_PAUSED:
+      /* do something */
       break;
-
     default:
       break;
   }
 
-  if (GST_ELEMENT_CLASS (parent_class)->change_state)
-    return GST_ELEMENT_CLASS (parent_class)->change_state (element);
+  ret = GST_ELEMENT_CLASS (parent_class)-&gt;change_state (element, transition);
+  if (ret == GST_STATE_CHANGE_FAILURE)
+    return ret;
+
+  /* Now handle downwards state changes after chaining up */
+  switch (transition) {
+    case GST_STATE_PAUSED_TO_READY:
+      src->total_bytes = 0;
+      break;
+    default:
+      break;
+  }
 
-  return GST_STATE_SUCCESS;
+  return ret;
 }
     </programlisting>
     <para>