From f220f8295b16eeee1432bddfc7cf2f8196d1760e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tim-Philipp=20M=C3=BCller?= <tim@centricular.net>
Date: Sat, 14 Jan 2006 12:52:22 +0000
Subject: [PATCH] Add docs for mixerutils stuff.

Original commit message from CVS:
* docs/libs/gst-plugins-base-libs-docs.sgml:
* docs/libs/gst-plugins-base-libs-sections.txt:
* gst-libs/gst/audio/mixerutils.c:
* gst-libs/gst/audio/mixerutils.h:
Add docs for mixerutils stuff.
---
 ChangeLog                                    |  8 +++++
 docs/libs/gst-plugins-base-libs-docs.sgml    |  2 ++
 docs/libs/gst-plugins-base-libs-sections.txt |  7 +++++
 gst-libs/gst/audio/mixerutils.c              | 32 ++++++++++++++++++++
 gst-libs/gst/audio/mixerutils.h              | 14 +++++++++
 5 files changed, 63 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index 5451391f17..d7d4131630 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2006-01-14  Tim-Philipp Müller  <tim at centricular dot net>
+
+	* docs/libs/gst-plugins-base-libs-docs.sgml:
+	* docs/libs/gst-plugins-base-libs-sections.txt:
+	* gst-libs/gst/audio/mixerutils.c:
+	* gst-libs/gst/audio/mixerutils.h:
+	  Add docs for mixerutils stuff.
+
 2006-01-13  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* gst/playback/gstplaybasebin.c: (setup_source):
diff --git a/docs/libs/gst-plugins-base-libs-docs.sgml b/docs/libs/gst-plugins-base-libs-docs.sgml
index 2ba2f8cf0b..4d7ef54a33 100644
--- a/docs/libs/gst-plugins-base-libs-docs.sgml
+++ b/docs/libs/gst-plugins-base-libs-docs.sgml
@@ -6,6 +6,7 @@
 
 <!ENTITY GstCompiling SYSTEM "compiling.sgml">
 <!ENTITY GstAudio SYSTEM "xml/gstaudio.xml">
+<!ENTITY GstAudioMixerUtils SYSTEM "xml/gstaudiomixerutils.xml">
 <!ENTITY GstCddaBaseSrc SYSTEM "xml/gstcddabasesrc.xml">
 <!ENTITY GstVideoSink SYSTEM "xml/gstvideosink.xml">
 <!ENTITY GstVideoFilter SYSTEM "xml/gstvideofilter.xml">
@@ -39,6 +40,7 @@ This library should be linked to by getting cflags and libs from
 <filename>-lgstaudio-&GST_MAJORMINOR;</filename> to the library flags.
     </para>
     &GstAudio;
+    &GstAudioMixerUtils;
     &GstRingBuffer;
   </chapter>
 
diff --git a/docs/libs/gst-plugins-base-libs-sections.txt b/docs/libs/gst-plugins-base-libs-sections.txt
index 888e85cb88..42485e58b7 100644
--- a/docs/libs/gst-plugins-base-libs-sections.txt
+++ b/docs/libs/gst-plugins-base-libs-sections.txt
@@ -9,6 +9,13 @@ gst_audio_is_buffer_framed
 gst_audio_structure_set_int
 </SECTION>
 
+<SECTION>
+<FILE>gstaudiomixerutils</FILE>
+<INCLUDE>gst/audio/mixerutils.h</INCLUDE>
+GstAudioMixerFilterFunc
+gst_audio_default_registry_mixer_filter
+</SECTION>
+
 <SECTION>
 <FILE>gstcddabasesrc</FILE>
 <INCLUDE>gst/cdda/gstcddabasesrc.h</INCLUDE>
diff --git a/gst-libs/gst/audio/mixerutils.c b/gst-libs/gst/audio/mixerutils.c
index 5524ce63bd..3ac14dcd03 100644
--- a/gst-libs/gst/audio/mixerutils.c
+++ b/gst-libs/gst/audio/mixerutils.c
@@ -18,6 +18,19 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstaudiomixerutils
+ * @short_description:  utility functions to find available audio mixers
+ *                      from the plugin registry
+ *
+ * <refsect2>
+ * <para>
+ * Provides some utility functions to detect available audio mixers
+ * on the system.
+ * </para>
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -166,6 +179,25 @@ element_factory_rank_compare_func (gconstpointer a, gconstpointer b)
   return rank_b - rank_a;
 }
 
+/**
+ * gst_audio_default_registry_mixer_filter:
+ * @filter_func: filter function, or #NULL
+ * @first: set to #TRUE if you only want the first suitable mixer element
+ * @user_data: user data to pass to the filter function
+ *
+ * Utility function to find audio mixer elements.
+ *
+ * Will traverse the default plugin registry in order of plugin rank and
+ * find usable audio mixer elements. The caller may optionally fine-tune
+ * the selection by specifying a filter function.
+ *
+ * Returns: a #GList of audio mixer #GstElement<!-- -->s. You must free each
+ *          element in the list by setting it to NULL state and calling
+ *          gst_object_unref(). After that the list itself should be freed
+ *          using g_list_free().
+ *
+ * Since: 0.10.2
+ */
 GList *
 gst_audio_default_registry_mixer_filter (GstAudioMixerFilterFunc filter_func,
     gboolean first, gpointer data)
diff --git a/gst-libs/gst/audio/mixerutils.h b/gst-libs/gst/audio/mixerutils.h
index a0590963ec..204a5a9017 100644
--- a/gst-libs/gst/audio/mixerutils.h
+++ b/gst-libs/gst/audio/mixerutils.h
@@ -23,8 +23,22 @@
 #include <gst/gst.h>
 #include <gst/interfaces/mixer.h>
 
+/**
+ * GstAudioMixerFilterFunc:
+ * @mixer: a #GstElement implementing the #GstMixer interface
+ * @user_data: user data
+ *
+ * Function that will be called by gst_audio_default_registry_mixer_filter()
+ * so the caller can decide which mixer elements should be kept and returned.
+ * When the mixer element is passed to the callback function, it is opened
+ * and in READY state. If you decide to keep the element, you need to set it
+ * back to NULL state yourself (unless you want to keep it opened of course).
+ *
+ * Returns: TRUE if the element should be kept, FALSE otherwise.
+ */
 typedef gboolean (*GstAudioMixerFilterFunc) (GstMixer * mixer, gpointer user_data);
 
+
 GList * gst_audio_default_registry_mixer_filter (GstAudioMixerFilterFunc  filter_func,
                                                  gboolean                 first,
                                                  gpointer                 user_data);