Add a simple example application for the spectrum element, include it in the docs, and fix some documentation ambigui...

Original commit message from CVS:
* docs/plugins/Makefile.am:
* gst/spectrum/gstspectrum.c:
* tests/examples/spectrum/.cvsignore:
* tests/examples/spectrum/Makefile.am:
* tests/examples/spectrum/spectrum-example.c:
Add a simple example application for the spectrum element, include it
in the docs, and fix some documentation ambiguities.
Fixes: #348085

6 files changed, 157 insertions, 10 deletions

diff --git a/ChangeLog b/ChangeLog
index 8e8969a5..df0572e8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2008-02-09  Jan Schmidt  <jan.schmidt@sun.com>
+
+	* docs/plugins/Makefile.am:
+	* gst/spectrum/gstspectrum.c:
+	* tests/examples/spectrum/.cvsignore:
+	* tests/examples/spectrum/Makefile.am:
+	* tests/examples/spectrum/spectrum-example.c:
+
+	Add a simple example application for the spectrum element, include it
+	in the docs, and fix some documentation ambiguities.
+
+	Fixes: #348085
+
 2008-02-08  Jan Schmidt  <jan.schmidt@sun.com>
 
 	* gst/equalizer/Makefile.am:
diff --git a/docs/plugins/Makefile.am b/docs/plugins/Makefile.am
index e5c0a894..35b85a9f 100644
--- a/docs/plugins/Makefile.am
+++ b/docs/plugins/Makefile.am
@@ -154,7 +154,8 @@ EXTRA_HFILES = \
 
 # example code that needs to be converted to xml and placed in xml/
 EXAMPLE_CFILES = \
-	$(top_srcdir)/tests/examples/level/level-example.c
+	$(top_srcdir)/tests/examples/level/level-example.c \
+	$(top_srcdir)/tests/examples/spectrum/spectrum-example.c
 
 # Images to copy into HTML directory.
 HTML_IMAGES =
diff --git a/gst/spectrum/gstspectrum.c b/gst/spectrum/gstspectrum.c
index e3f7b2d4..8e34fffa 100644
--- a/gst/spectrum/gstspectrum.c
+++ b/gst/spectrum/gstspectrum.c
@@ -25,19 +25,19 @@
  * <refsect2>
  * <para>
  * The Spectrum element analyzes the frequency spectrum of an audio signal.
- * If #GstSpectrum:message property is #TRUE it sends analysis results as
- * application message named
+ * If the #GstSpectrum:message property is #TRUE, it sends analysis results as
+ * application messages named
  * <classname>&quot;spectrum&quot;</classname> after each interval of time given
  * by the #GstSpectrum:interval property.
  * </para>
  * <para>
- * The message's structure contains three fields:
+ * The message's structure contains some combination of these fields:
  * <itemizedlist>
  * <listitem>
  *   <para>
  *   #GstClockTime
  *   <classname>&quot;endtime&quot;</classname>:
- *   the end time of the buffer that triggered the message
+ *   the end time of the buffer that triggered the message. Always present.
  *   </para>
  * </listitem>
  * <listitem>
@@ -45,24 +45,30 @@
  *   #GstValueList of #gfloat
  *   <classname>&quot;magnitude&quot;</classname>:
  *   the level for each frequency band in dB. All values below the value of the
- *   #GstSpectrum:threshold property will be set to the threshold.
+ *   #GstSpectrum:threshold property will be set to the threshold. Only present
+ *   if the message-magnitude property is true.
  *   </para>
  * </listitem>
  * <listitem>
  *   <para>
  *   #GstValueList of #gfloat
  *   <classname>&quot;phase&quot;</classname>:
- *   the phase for each frequency band. The value is between -pi and pi.
+ *   The phase for each frequency band. The value is between -pi and pi. Only
+ *   present if the message-phase property is true.
  *   </para>
  * </listitem>
  * </itemizedlist>
  * </para>
  * <para>
  * This element cannot be used with the gst-launch command in a sensible way.
- * The included demo shows how to use it in an application.
+ * This sample code demonstrates how to use it in an application.
  * </para>
+ * <title>Example application</title>
  * <para>
- * Last reviewed on 2008-02-07 (0.10.6)
+ * <include xmlns="http://www.w3.org/2003/XInclude" href="element-spectrum-example.xml" />
+ * </para>
+ * <para>
+ * Last reviewed on 2008-02-09 (0.10.6)
  * </para>
  * </refsect2>
  */
diff --git a/tests/examples/spectrum/.gitignore b/tests/examples/spectrum/.gitignore
index d1d65d58..8e5a3cf9 100644
--- a/tests/examples/spectrum/.gitignore
+++ b/tests/examples/spectrum/.gitignore
@@ -1,2 +1,3 @@
 demo-audiotest
 demo-osssrc
+spectrum-example
diff --git a/tests/examples/spectrum/Makefile.am b/tests/examples/spectrum/Makefile.am
index 0fd2ef17..a0a71629 100644
--- a/tests/examples/spectrum/Makefile.am
+++ b/tests/examples/spectrum/Makefile.am
@@ -1,5 +1,5 @@
 if HAVE_GTK
-noinst_PROGRAMS = demo-osssrc demo-audiotest
+noinst_PROGRAMS = demo-osssrc demo-audiotest spectrum-example
 endif
 
 demo_osssrc_SOURCES = demo-osssrc.c
@@ -10,3 +10,7 @@ demo_audiotest_SOURCES = demo-audiotest.c
 demo_audiotest_CFLAGS  = $(GST_BASE_CFLAGS) $(GST_CFLAGS) $(GTK_CFLAGS)
 demo_audiotest_LDFLAGS = $(GST_BASE_LIBS) $(GST_LIBS) $(GTK_LIBS)
 
+spectrum_example_SOURCES = spectrum-example.c
+spectrum_example_CFLAGS  = $(GST_BASE_CFLAGS) $(GST_CFLAGS) $(GTK_CFLAGS)
+spectrum_example_LDFLAGS = $(GST_BASE_LIBS) $(GST_LIBS) $(GTK_LIBS)
+
diff --git a/tests/examples/spectrum/spectrum-example.c b/tests/examples/spectrum/spectrum-example.c
new file mode 100644
index 00000000..7c20e279
--- /dev/null
+++ b/tests/examples/spectrum/spectrum-example.c
@@ -0,0 +1,122 @@
+/* GStreamer
+ * Copyright (C) 2006 Stefan Kost <ensonic@users.sf.net>
+ * Copyright (C) 2008 Jan Schmidt <jan.schmidt@sun.com>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#include <string.h>
+#include <gst/gst.h>
+
+static guint spect_bands = 20;
+
+#define AUDIOFREQ 32000
+
+/* receive spectral data from element message */
+gboolean
+message_handler (GstBus * bus, GstMessage * message, gpointer data)
+{
+  if (message->type == GST_MESSAGE_ELEMENT) {
+    const GstStructure *s = gst_message_get_structure (message);
+    const gchar *name = gst_structure_get_name (s);
+    GstClockTime endtime;
+
+    if (strcmp (name, "spectrum") == 0) {
+      const GValue *magnitudes;
+      const GValue *phases;
+      const GValue *mag, *phase;
+      gdouble freq;
+      guint i;
+
+      if (!gst_structure_get_clock_time (s, "endtime", &endtime))
+        endtime = GST_CLOCK_TIME_NONE;
+
+      g_print ("New spectrum message, endtime %" GST_TIME_FORMAT "\n",
+          GST_TIME_ARGS (endtime));
+
+      magnitudes = gst_structure_get_value (s, "magnitude");
+      phases = gst_structure_get_value (s, "phase");
+
+      for (i = 0; i < spect_bands; ++i) {
+        freq = (gdouble) ((AUDIOFREQ / 2) * i + AUDIOFREQ / 4) / spect_bands;
+        mag = gst_value_list_get_value (magnitudes, i);
+        phase = gst_value_list_get_value (phases, i);
+
+        if (mag != NULL && phase != NULL) {
+          g_print ("band %d (freq %g): magnitude %f dB phase %f\n", i, freq,
+              g_value_get_float (mag), g_value_get_float (phase));
+        }
+      }
+      g_print ("\n");
+    }
+  }
+  return TRUE;
+}
+
+int
+main (int argc, char *argv[])
+{
+  GstElement *bin;
+  GstElement *src, *audioconvert, *spectrum, *sink;
+  GstBus *bus;
+  GstCaps *caps;
+  GMainLoop *loop;
+
+  gst_init (&argc, &argv);
+
+  bin = gst_pipeline_new ("bin");
+
+  src = gst_element_factory_make ("audiotestsrc", "src");
+  g_object_set (G_OBJECT (src), "wave", 0, "freq", 6000.0, NULL);
+  audioconvert = gst_element_factory_make ("audioconvert", NULL);
+  g_assert (audioconvert);
+
+  spectrum = gst_element_factory_make ("spectrum", "spectrum");
+  g_object_set (G_OBJECT (spectrum), "bands", spect_bands, "threshold", -80,
+      "message", TRUE, "message-phase", TRUE, NULL);
+
+  sink = gst_element_factory_make ("fakesink", "sink");
+  g_object_set (G_OBJECT (sink), "sync", TRUE, NULL);
+
+  gst_bin_add_many (GST_BIN (bin), src, audioconvert, spectrum, sink, NULL);
+
+  caps = gst_caps_new_simple ("audio/x-raw-int",
+      "rate", G_TYPE_INT, AUDIOFREQ, NULL);
+
+  if (!gst_element_link (src, audioconvert) ||
+      !gst_element_link_filtered (audioconvert, spectrum, caps) ||
+      !gst_element_link (spectrum, sink)) {
+    fprintf (stderr, "can't link elements\n");
+    exit (1);
+  }
+  gst_caps_unref (caps);
+
+  bus = gst_element_get_bus (bin);
+  gst_bus_add_watch (bus, message_handler, NULL);
+  gst_object_unref (bus);
+
+  gst_element_set_state (bin, 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);
+
+  gst_element_set_state (bin, GST_STATE_NULL);
+
+  gst_object_unref (bin);
+
+  return 0;
+}