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

diff --git a/ChangeLog b/ChangeLog
index 4eaf5aa..b191d7d 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
 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/manual/appendix-checklist.xml:
        * docs/manual/appendix-programs.xml:

diff --git a/docs/pwg/building-chainfn.xml b/docs/pwg/building-chainfn.xml
index 1cda939..9e27354 100644 (file)
--- 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 ae01054..ddd2df2 100644 (file)
--- a/docs/pwg/building-pads.xml
+++ b/docs/pwg/building-pads.xml
@@ -27,8 +27,8 @@
 #include "filter.h"
 #include <string.h>
 
-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 1c27018..b5011f5 100644 (file)
--- 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)->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 ebc6741..f1141a2 100644 (file)
--- 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)->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>