common/: a simple py script to generate valid xml from a C example probably also need to strip an MIT license when we...

Original commit message from CVS:

* common/c-to-xml.py:
* common/gtk-doc-plugins.mak:
a simple py script to generate valid xml from a C example
probably also need to strip an MIT license when we decide
* docs/plugins/Makefile.am:
* gst/level/Makefile.am:
* gst/level/gstlevel.c: (gst_level_init):
* gst/level/level-example.c: (message_handler), (main):
add an example to level that will show up in the docs
* gst/rtp/TODO:
add a note for the future

3 files changed, 131 insertions, 1 deletions

diff --git a/gst/level/Makefile.am b/gst/level/Makefile.am
index 5bed77d8..6a48efab 100644
--- a/gst/level/Makefile.am
+++ b/gst/level/Makefile.am
@@ -6,3 +6,7 @@ libgstlevel_la_LIBADD = $(GST_BASE_LIBS)
 libgstlevel_la_LDFLAGS = $(GST_PLUGIN_LDFLAGS)
 
 noinst_HEADERS = gstlevel.h
+
+noinst_PROGRAMS = level-example
+level_example_CFLAGS = $(GST_CFLAGS)
+level_example_LDADD = $(GST_LIBS)
diff --git a/gst/level/gstlevel.c b/gst/level/gstlevel.c
index e3dabd8a..6feb8b64 100644
--- a/gst/level/gstlevel.c
+++ b/gst/level/gstlevel.c
@@ -19,6 +19,38 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-level
+ *
+ * <refsect2>
+ * <para>
+ * Level analyses incoming audio buffers and generates an application
+ * message per given interval of time.
+ * The message's structure contains four fields:
+ * <itemizedlist>
+ * <listitem>
+ *   <para>
+ *   <link linkend="gdouble">gdouble</link>
+ *   <classname>&quot;endtime&quot;</classname>:
+ *   the end time of the buffer that
+ *   triggered the message</para>
+ * </listitem>
+ * <listitem>
+ *   <para>
+ *   <link linkend="gdouble">gdouble</link>
+ *   <classname>&quot;endtime&quot;</classname>:
+ *   the end time of the buffer that
+ *   triggered the message</para>
+ * </listitem>
+  * </itemizedlist>
+ * </para>
+ * <title>Example application</title>
+ * <para>
+ * <include xmlns="http://www.w3.org/2003/XInclude" href="element-level-example.xml" />
+ * </para>
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -146,6 +178,8 @@ gst_level_init (GstLevel * filter, GstLevelClass * g_class)
   filter->interval = 0.1;
   filter->decay_peak_ttl = 0.4;
   filter->decay_peak_falloff = 10.0;    /* dB falloff (/sec) */
+
+  filter->message = TRUE;
 }
 
 static void
@@ -257,6 +291,9 @@ gst_level_set_caps (GstBaseTransform * trans, GstCaps * in, GstCaps * out)
  * samples for multiple channels are interleaved
  * input sample data enters in *in_data as 8 or 16 bit data
  * this filter only accepts signed audio data, so mid level is always 0
+ *
+ * for 16 bit, this code considers the non-existant 32768 value to be
+ * full-scale; so 32767 will not map to 1.0
  */
 
 #define DEFINE_LEVEL_CALCULATOR(TYPE)                                         \
@@ -268,7 +305,7 @@ gst_level_calculate_##TYPE (TYPE * in, guint num, gint channels,              \
   double squaresum = 0.0;        /* square sum of the integer samples */      \
   register double square = 0.0;	 /* Square */                                 \
   register double PSS = 0.0;     /* Peak Square Sample */                     \
-  gdouble normalizer;            /* divisor to get a [-1, - 1] range */       \
+  gdouble normalizer;            /* divisor to get a [-1.0, 1.0] range */     \
                                                                               \
   *CS = 0.0;                     /* Cumulative Square for this block */       \
                                                                               \
diff --git a/gst/level/level-example.c b/gst/level/level-example.c
new file mode 100644
index 00000000..dcfdec0c
--- /dev/null
+++ b/gst/level/level-example.c
@@ -0,0 +1,89 @@
+#include <string.h>
+#include <math.h>
+
+#include <gst/gst.h>
+
+gboolean
+message_handler (GstBus * bus, GstMessage * message, gpointer data)
+{
+
+  if (message->type == GST_MESSAGE_APPLICATION) {
+    const GstStructure *s = gst_message_get_structure (message);
+    const gchar *name = gst_structure_get_name (s);
+
+    if (strcmp (name, "level") == 0) {
+      gint channels;
+      gdouble endtime, rms_dB, peak_dB, decay_dB;
+      gdouble rms;
+      const GValue *list;
+      const GValue *value;
+
+      if (!gst_structure_get_double (s, "endtime", &endtime))
+        g_warning ("Could not parse endtime");
+      list = gst_structure_get_value (s, "rms");
+      /* we can get the number of channels as the length of any of the value
+       * lists */
+      channels = gst_value_list_get_size (list);
+
+      /* we will only get values for the first channel, since we know sinesrc
+       * is mono */
+      value = gst_value_list_get_value (list, 0);
+      rms_dB = g_value_get_double (value);
+      list = gst_structure_get_value (s, "peak");
+      value = gst_value_list_get_value (list, 0);
+      peak_dB = g_value_get_double (value);
+      list = gst_structure_get_value (s, "decay");
+      value = gst_value_list_get_value (list, 0);
+      decay_dB = g_value_get_double (value);
+      g_print ("endtime: %f, channels: %d\n", endtime, channels);
+      g_print ("RMS: %f dB, peak: %f dB, decay: %f dB\n",
+          rms_dB, peak_dB, decay_dB);
+
+      /* converting from dB to normal gives us a value between 0.0 and 1.0 */
+      rms = pow (10, rms_dB / 20);
+      g_print ("normalized rms value: %f\n", rms);
+    }
+  }
+  /* we handled the message we want, and ignored the ones we didn't want.
+   * so the core can unref the message for us */
+  return TRUE;
+}
+
+int
+main (int argc, char *argv[])
+{
+  GstElement *sinesrc, *level, *fakesink;
+  GstElement *pipeline;
+  GstBus *bus;
+  gint watch_id;
+  GMainLoop *loop;
+
+  gst_init (&argc, &argv);
+
+  pipeline = gst_pipeline_new (NULL);
+  g_assert (pipeline);
+  sinesrc = gst_element_factory_make ("sinesrc", NULL);
+  g_assert (sinesrc);
+  level = gst_element_factory_make ("level", NULL);
+  g_assert (level);
+  fakesink = gst_element_factory_make ("fakesink", NULL);
+  g_assert (fakesink);
+
+  gst_bin_add_many (GST_BIN (pipeline), sinesrc, level, fakesink, NULL);
+  gst_element_link (sinesrc, level);
+  gst_element_link (level, fakesink);
+
+  /* make sure we'll get messages */
+  g_object_set (G_OBJECT (level), "message", TRUE, NULL);
+
+  bus = gst_element_get_bus (pipeline);
+  watch_id = gst_bus_add_watch (bus, message_handler, NULL);
+
+  gst_element_set_state (pipeline, GST_STATE_PLAYING);
+
+  /* we need to run a GLib main loop to get the messages */
+  loop = g_main_loop_new (NULL, FALSE);
+  g_main_loop_run (loop);
+
+  return 0;
+}