API: add gst_object_{s,g}et_control_rate(), add private data section, fix docs

Original commit message from CVS:
* docs/libs/gstreamer-libs-sections.txt:
* libs/gst/controller/gstcontroller.c:
(_gst_controller_get_property), (_gst_controller_set_property),
(_gst_controller_init), (_gst_controller_class_init):
* libs/gst/controller/gstcontroller.h:
* libs/gst/controller/gsthelper.c: (gst_object_get_control_rate),
(gst_object_set_control_rate):
API: add gst_object_{s,g}et_control_rate(), add private data section,
fix docs
* libs/gst/dataprotocol/dataprotocol.c: (gst_dp_packetizer_new):
* libs/gst/dataprotocol/dataprotocol.h:
add deprecation guards to make gtk-doc happy and allow disabling cruft

ChangeLog

@@ -1,3 +1,19 @@
+2006-08-10  Stefan Kost  <ensonic@users.sf.net>
+
+	* docs/libs/gstreamer-libs-sections.txt:
+	* libs/gst/controller/gstcontroller.c:
+	(_gst_controller_get_property), (_gst_controller_set_property),
+	(_gst_controller_init), (_gst_controller_class_init):
+	* libs/gst/controller/gstcontroller.h:
+	* libs/gst/controller/gsthelper.c: (gst_object_get_control_rate),
+	(gst_object_set_control_rate):
+          API: add gst_object_{s,g}et_control_rate(), add private data section,
+          fix docs
+
+	* libs/gst/dataprotocol/dataprotocol.c: (gst_dp_packetizer_new):
+	* libs/gst/dataprotocol/dataprotocol.h:
+          add deprecation guards to make gtk-doc happy and allow disabling cruft
+
 2006-08-09  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* tests/check/Makefile.am:

docs/libs/gstreamer-libs-sections.txt

@@ -80,6 +80,7 @@ gst_controller_set_interpolation_mode
 GST_PARAM_CONTROLLABLE
 <SUBSECTION Standard>
 GstControllerClass
+GstControllerPrivate
 GST_CONTROLLER
 GST_IS_CONTROLLER
 GST_CONTROLLER_CLASS
@@ -104,6 +105,8 @@ gst_object_set_controller
 gst_object_sync_values
 gst_object_get_value_arrays
 gst_object_get_value_array
+gst_object_get_control_rate
+gst_object_set_control_rate
 <SUBSECTION Standard>
 <SUBSECTION Private>
 </SECTION>

libs/gst/controller/gstcontroller.c

@@ -78,6 +78,16 @@ GST_DEBUG_CATEGORY_EXTERN (GST_CAT_DEFAULT);
 static GObjectClass *parent_class = NULL;
 GQuark __gst_controller_key;
 
+/* property ids */
+enum
+{
+  PROP_CONTROL_RATE = 1
+};
+
+struct _GstControllerPrivate
+{
+  guint control_rate;
+};
 
 /* imports from gst-interpolation.c */
 
@@ -1103,6 +1113,62 @@ gst_controller_set_live_value(GstController * self, gchar *property_name,
 
 /* gobject handling */
 
+static void
+_gst_controller_get_property (GObject * object, guint property_id,
+    GValue * value, GParamSpec * pspec)
+{
+  GstController *self = GST_CONTROLLER (object);
+
+  switch (property_id) {
+    case PROP_CONTROL_RATE:{
+      /* FIXME: don't change if element is playing, controller works for GObject
+         so this wont work
+
+         GstState c_state, p_state;
+         GstStateChangeReturn ret;
+
+         ret = gst_element_get_state (self->object, &c_state, &p_state, 0);
+         if ((ret == GST_STATE_CHANGE_SUCCESS &&
+         (c_state == GST_STATE_NULL || c_state == GST_STATE_READY)) ||
+         (ret == GST_STATE_CHANGE_ASYNC &&
+         (p_state == GST_STATE_NULL || p_state == GST_STATE_READY))) {
+       */
+      g_value_set_uint (value, self->priv->control_rate);
+      /*
+         }
+         else {
+         GST_WARNING ("Changing the control rate is only allowed if the elemnt"
+         " is in NULL or READY");
+         }
+       */
+    }
+      break;
+    default:{
+      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
+    }
+      break;
+  }
+}
+
+/* sets the given properties for this object */
+static void
+_gst_controller_set_property (GObject * object, guint property_id,
+    const GValue * value, GParamSpec * pspec)
+{
+  GstController *self = GST_CONTROLLER (object);
+
+  switch (property_id) {
+    case PROP_CONTROL_RATE:{
+      self->priv->control_rate = g_value_get_uint (value);
+    }
+      break;
+    default:{
+      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
+    }
+      break;
+  }
+}
+
 static void
 _gst_controller_finalize (GObject * object)
 {
@@ -1134,7 +1200,9 @@ _gst_controller_init (GTypeInstance * instance, gpointer g_class)
   GstController *self = GST_CONTROLLER (instance);
 
   self->lock = g_mutex_new ();
-
+  self->priv =
+      G_TYPE_INSTANCE_GET_PRIVATE (self, GST_TYPE_CONTROLLER,
+      GstControllerPrivate);
 }
 
 static void
@@ -1143,17 +1211,23 @@ _gst_controller_class_init (GstControllerClass * klass)
   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 
   parent_class = g_type_class_peek_parent (klass);
+  g_type_class_add_private (klass, sizeof (GstControllerPrivate));
 
+  gobject_class->set_property = _gst_controller_set_property;
+  gobject_class->get_property = _gst_controller_get_property;
   gobject_class->finalize = _gst_controller_finalize;
 
   __gst_controller_key = g_quark_from_string ("gst::controller");
 
   /* register properties */
+  g_object_class_install_property (gobject_class, PROP_CONTROL_RATE,
+      g_param_spec_uint ("control-rate",
+          "control rate",
+          "Controlled properties will be updated this many times per second",
+          1, G_MAXUINT, 10, G_PARAM_READWRITE));
+
   /* register signals */
   /* set defaults for overridable methods */
-  /* TODO which of theses do we need ?
-     BilboEd : none :)
-   */
 }
 
 GType

libs/gst/controller/gstcontroller.h

@@ -111,6 +111,8 @@ typedef enum
 
 typedef struct _GstController GstController;
 typedef struct _GstControllerClass GstControllerClass;
+typedef struct _GstControllerPrivate GstControllerPrivate;
+
 
 /**
  * GstController:
@@ -127,7 +129,8 @@ struct _GstController
   GObject *object;    /* the object we control */
 
   /*< private >*/
-  gpointer       _gst_reserved[GST_PADDING];
+  GstControllerPrivate *priv;
+  gpointer       _gst_reserved[GST_PADDING - sizeof (GstControllerPrivate *)];
 };
 
 struct _GstControllerClass
@@ -194,6 +197,9 @@ gboolean gst_object_get_value_arrays (GObject * object,
 gboolean gst_object_get_value_array (GObject * object,
     GstClockTime timestamp, GstValueArray * value_array);
 
+guint gst_object_get_control_rate (GObject * object);
+void gst_object_set_control_rate (GObject * object, guint control_rate);
+
 /* lib init/done */
 
 gboolean gst_controller_init (int * argc, char ***argv);

libs/gst/controller/gsthelper.c

@@ -107,6 +107,8 @@ gst_object_uncontrol_properties (GObject * object, ...)
  * gst_object_get_controller:
  * @object: the object that has controlled properties
  *
+ * Gets the controller for the given GObject
+ * 
  * Returns: the controller handling some of the given element's properties, %NULL if no controller
  * Since: 0.9
  */
@@ -230,3 +232,62 @@ gst_object_get_value_array (GObject * object, GstClockTime timestamp,
   }
   return (FALSE);
 }
+
+/**
+ * gst_object_get_control_rate:
+ * @object: the object that has controlled properties
+ *
+ * Obtain the control-rate for this @object. Audio processing #GstElement
+ * objects will use this rate to sub-divide their processing loop and call
+ * gst_object_sync_values() inbetween. The length of the processing segment
+ * should be sampling-rate/control-rate.
+ *
+ * If the @object is not under property control, this will return 0. This allows
+ * the element to avoid the sub-dividing.
+ *
+ * The control-rate is not expected to change if the elemnt is in
+ * %GST_STATE_PAUSED or %GST_STATE_PLAYING.
+ *
+ * Returns: the control rate
+ * Since: 0.10.10
+ */
+guint
+gst_object_get_control_rate (GObject * object)
+{
+  GstController *ctrl;
+  guint control_rate = 0;
+
+  g_return_val_if_fail (G_IS_OBJECT (object), FALSE);
+
+  if ((ctrl = g_object_get_qdata (object, __gst_controller_key))) {
+    g_object_get (ctrl, "control-rate", &control_rate, NULL);
+  }
+  return (control_rate);
+}
+
+/**
+ * gst_object_set_control_rate:
+ * @object: the object that has controlled properties
+ * @control_rate: the new control-rate (1 .. sampling_rate)
+ *
+ * Change the control-rate for this @object. Audio processing #GstElement
+ * objects will use this rate to sub-divide their processing loop and call
+ * gst_object_sync_values() inbetween. The length of the processing segment
+ * should be sampling-rate/control-rate.
+ *
+ * The control-rate should not change if the elemnt is in %GST_STATE_PAUSED or
+ * %GST_STATE_PLAYING.
+ *
+ * Since: 0.10.10
+ */
+void
+gst_object_set_control_rate (GObject * object, guint control_rate)
+{
+  GstController *ctrl;
+
+  g_return_if_fail (G_IS_OBJECT (object));
+
+  if ((ctrl = g_object_get_qdata (object, __gst_controller_key))) {
+    g_object_set (ctrl, "control-rate", control_rate, NULL);
+  }
+}

libs/gst/dataprotocol/dataprotocol.c

@@ -380,6 +380,7 @@ gst_dp_header_payload_type (const guint8 * header)
  *
  * Returns: %TRUE if the header was successfully created.
  */
+#ifndef GST_DISABLE_DEPRECATED
 gboolean
 gst_dp_header_from_buffer (const GstBuffer * buffer, GstDPHeaderFlag flags,
     guint * length, guint8 ** header)
@@ -387,6 +388,7 @@ gst_dp_header_from_buffer (const GstBuffer * buffer, GstDPHeaderFlag flags,
   return gst_dp_header_from_buffer_any (buffer, flags, length, header,
       GST_DP_VERSION_0_2);
 }
+#endif
 
 static gboolean
 gst_dp_header_from_buffer_1_0 (const GstBuffer * buffer, GstDPHeaderFlag flags,
@@ -396,7 +398,7 @@ gst_dp_header_from_buffer_1_0 (const GstBuffer * buffer, GstDPHeaderFlag flags,
       GST_DP_VERSION_1_0);
 }
 
- /**
+/**
  * gst_dp_packet_from_caps:
  * @caps: a #GstCaps to create a packet for
  * @flags: the #GDPHeaderFlags to create the header with
@@ -410,6 +412,7 @@ gst_dp_header_from_buffer_1_0 (const GstBuffer * buffer, GstDPHeaderFlag flags,
  *
  * Returns: %TRUE if the packet was successfully created.
  */
+#ifndef GST_DISABLE_DEPRECATED
 gboolean
 gst_dp_packet_from_caps (const GstCaps * caps, GstDPHeaderFlag flags,
     guint * length, guint8 ** header, guint8 ** payload)
@@ -417,6 +420,7 @@ gst_dp_packet_from_caps (const GstCaps * caps, GstDPHeaderFlag flags,
   return gst_dp_packet_from_caps_any (caps, flags, length, header, payload,
       GST_DP_VERSION_0_2);
 }
+#endif
 
 static gboolean
 gst_dp_packet_from_caps_1_0 (const GstCaps * caps, GstDPHeaderFlag flags,
@@ -440,6 +444,7 @@ gst_dp_packet_from_caps_1_0 (const GstCaps * caps, GstDPHeaderFlag flags,
  *
  * Returns: %TRUE if the packet was successfully created.
  */
+#ifndef GST_DISABLE_DEPRECATED
 gboolean
 gst_dp_packet_from_event (const GstEvent * event, GstDPHeaderFlag flags,
     guint * length, guint8 ** header, guint8 ** payload)
@@ -517,6 +522,7 @@ gst_dp_packet_from_event (const GstEvent * event, GstDPHeaderFlag flags,
   *header = h;
   return TRUE;
 }
+#endif
 
 static gboolean
 gst_dp_packet_from_event_1_0 (const GstEvent * event, GstDPHeaderFlag flags,
@@ -869,11 +875,13 @@ gst_dp_packetizer_new (GstDPVersion version)
   ret->version = version;
 
   switch (version) {
+#ifndef GST_DISABLE_DEPRECATED
     case GST_DP_VERSION_0_2:
       ret->header_from_buffer = gst_dp_header_from_buffer;
       ret->packet_from_caps = gst_dp_packet_from_caps;
       ret->packet_from_event = gst_dp_packet_from_event;
       break;
+#endif
     case GST_DP_VERSION_1_0:
       ret->header_from_buffer = gst_dp_header_from_buffer_1_0;
       ret->packet_from_caps = gst_dp_packet_from_caps_1_0;

libs/gst/dataprotocol/dataprotocol.h

@@ -140,21 +140,26 @@ GstDPPayloadType
 		gst_dp_header_payload_type	(const guint8 * header);
 
 /* converting from GstBuffer/GstEvent/GstCaps */
+#ifndef GST_DISABLE_DEPRECATED
 gboolean	gst_dp_header_from_buffer	(const GstBuffer * buffer,
 						GstDPHeaderFlag flags,
 						guint * length,
 						guint8 ** header);
+#endif
+#ifndef GST_DISABLE_DEPRECATED
 gboolean	gst_dp_packet_from_caps		(const GstCaps * caps,
 						GstDPHeaderFlag flags,
 						guint * length,
 						guint8 ** header,
 						guint8 ** payload);
+#endif
+#ifndef GST_DISABLE_DEPRECATED
 gboolean	gst_dp_packet_from_event	(const GstEvent * event,
 						GstDPHeaderFlag flags,
 						guint * length,
 						guint8 ** header,
 						guint8 ** payload);
-
+#endif
 /* converting to GstBuffer/GstEvent/GstCaps */
 GstBuffer *	gst_dp_buffer_from_header	(guint header_length,
 						const guint8 * header);