From 4f77b464948c84e0509f400f34467f48066fc6e8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebastian=20Dr=C3=B6ge?= <slomo@circular-chaos.org>
Date: Sun, 11 Nov 2007 13:55:27 +0000
Subject: [PATCH] gst/equalizer/: And continue to update docs. Also include
 some sample code for the n-band equalizer in the docs.

Original commit message from CVS:
* gst/equalizer/gstiirequalizer10bands.c:
* gst/equalizer/gstiirequalizer3bands.c:
* gst/equalizer/gstiirequalizernbands.c:
And continue to update docs. Also include some sample code
for the n-band equalizer in the docs.
---
 gst/equalizer/gstiirequalizer10bands.c |  6 ++-
 gst/equalizer/gstiirequalizer3bands.c  |  8 ++--
 gst/equalizer/gstiirequalizernbands.c  | 53 +++++++++++++++++++++++++-
 3 files changed, 60 insertions(+), 7 deletions(-)

diff --git a/gst/equalizer/gstiirequalizer10bands.c b/gst/equalizer/gstiirequalizer10bands.c
index a2e2018f8a..e951077d60 100644
--- a/gst/equalizer/gstiirequalizer10bands.c
+++ b/gst/equalizer/gstiirequalizer10bands.c
@@ -19,12 +19,14 @@
 
 /**
  * SECTION:element-equalizer-10bands
+ * @short_description: 10-band equalizer
  *
  * <refsect2>
- * <title>Example launch line</title>
  * <para>
- * The 10 band equalizer element changes the frequency spectrum of the audio data.
+ * The 10 band equalizer element allows to change the gain of 10 equally distributed
+ * frequency bands between 30 Hz and 15 kHz.
  * </para>
+ * <title>Example launch line</title>
  * <para>
  * <programlisting>
  * gst-launch filesrc location=song.ogg ! oggdemux ! vorbisdec ! audioconvert ! equalizer-10bands band2=3.0 ! alsasink
diff --git a/gst/equalizer/gstiirequalizer3bands.c b/gst/equalizer/gstiirequalizer3bands.c
index e2229dd7ae..f1e11d508e 100644
--- a/gst/equalizer/gstiirequalizer3bands.c
+++ b/gst/equalizer/gstiirequalizer3bands.c
@@ -19,17 +19,19 @@
 
 /**
  * SECTION:element-equalizer-3bands
+ * @short_description: 3-band equalizer
  *
  * <refsect2>
- * <title>Example launch line</title>
  * <para>
- * The 3 band equalizer element changes the frequency spectrum of the audio data.
+ * The 3-band equalizer element allows to change the gain of a low frequency,
+ * medium frequency and high frequency band.
  * </para>
+ * <title>Example launch line</title>
  * <para>
  * <programlisting>
  * gst-launch filesrc location=song.ogg ! oggdemux ! vorbisdec ! audioconvert ! equalizer-3bands band1=6.0 ! alsasink
  * </programlisting>
- * This raises the volume of the 2nd band which is at 1110 Hz by 6 db.
+ * This raises the volume of the 2nd band, which is at 1110 Hz, by 6 db.
  * </para>
  * </refsect2>
  */
diff --git a/gst/equalizer/gstiirequalizernbands.c b/gst/equalizer/gstiirequalizernbands.c
index 164dca5cd6..316cd02977 100644
--- a/gst/equalizer/gstiirequalizernbands.c
+++ b/gst/equalizer/gstiirequalizernbands.c
@@ -20,18 +20,67 @@
 
 /**
  * SECTION:element-equalizer-nbands
+ * @short_description: Fully parametric N-band equalizer
  *
  * <refsect2>
- * <title>Example launch line</title>
  * <para>
- * The n-band equalizer element changes the frequency spectrum of the audio data.
+ * The n-band equalizer element is a fully parametric equalizer. It allows to
+ * select between 1 and 64 bands and has properties on each band to change
+ * the center frequency, band width and gain.
  * </para>
+ * <title>Example launch line</title>
  * <para>
  * <programlisting>
  * gst-launch filesrc location=song.ogg ! oggdemux ! vorbisdec ! audioconvert ! equalizer-nbands num-bands=15 band5::gain=6.0 ! alsasink
  * </programlisting>
  * This make the equalizer use 15 bands and raises the volume of the 5th band by 6 db.
  * </para>
+ * <title>Example code</title>
+ * <para>
+ * <programlisting>
+
+#include &lt;gst/gst.h&gt;
+
+...
+typedef struct {
+  gfloat freq;
+  gfloat width;
+  gfloat gain;
+} GstEqualizerBandState;
+
+...
+
+  GstElement *equalizer;
+  GstObject *band;
+  gint i;
+  GstEqualizerBandState state[] = {
+    { 120.0,   50.0, - 3.0},
+    { 500.0,   20.0,  12.0},
+    {1503.0,    2.0, -20.0},
+    {6000.0, 1000.0,   6.0},
+    {3000.0,  120.0,   2.0}
+  };
+
+...
+
+
+  equalizer = gst_element_factory_make ("equalizer-nbands", "equalizer");
+  g_object_set (G_OBJECT (equalizer), "num-bands", 5, NULL);
+
+...
+
+  for (i = 0; i &lt; 5; i++) {
+    band = gst_child_proxy_get_child_by_index (GST_CHILD_PROXY (equalizer), i);
+    g_object_set (G_OBJECT (band), "freq", state[i].freq,
+        "bandwidth", state[i].width,
+	"gain", state[i].gain);
+    g_object_unref (G_OBJECT (band));
+  }
+
+...
+
+ * </programlisting>
+ * </para>
  * </refsect2>
  */