Added docs for the audio libs.

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/gstaudioclock.c:
* gst-libs/gst/audio/gstaudioclock.h:
* gst-libs/gst/audio/gstaudiosink.c:
* gst-libs/gst/audio/gstaudiosink.h:
* gst-libs/gst/audio/gstaudiosrc.c:
* gst-libs/gst/audio/gstbaseaudiosink.c:
(gst_base_audio_sink_render):
* gst-libs/gst/audio/gstbaseaudiosink.h:
* gst-libs/gst/audio/gstbaseaudiosrc.c: (gst_base_audio_src_init):
* gst-libs/gst/audio/gstbaseaudiosrc.h:
* gst-libs/gst/audio/gstringbuffer.h:
Added docs for the audio libs.

ChangeLog

@@ -1,3 +1,20 @@
+2006-09-27  Wim Taymans  <wim@fluendo.com>
+
+	* docs/libs/gst-plugins-base-libs-docs.sgml:
+	* docs/libs/gst-plugins-base-libs-sections.txt:
+	* gst-libs/gst/audio/gstaudioclock.c:
+	* gst-libs/gst/audio/gstaudioclock.h:
+	* gst-libs/gst/audio/gstaudiosink.c:
+	* gst-libs/gst/audio/gstaudiosink.h:
+	* gst-libs/gst/audio/gstaudiosrc.c:
+	* gst-libs/gst/audio/gstbaseaudiosink.c:
+	(gst_base_audio_sink_render):
+	* gst-libs/gst/audio/gstbaseaudiosink.h:
+	* gst-libs/gst/audio/gstbaseaudiosrc.c: (gst_base_audio_src_init):
+	* gst-libs/gst/audio/gstbaseaudiosrc.h:
+	* gst-libs/gst/audio/gstringbuffer.h:
+	Added docs for the audio libs.
+
 2006-09-27  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* tests/check/Makefile.am:

docs/libs/gst-plugins-base-libs-docs.sgml

@@ -124,7 +124,7 @@
       &GstTuner;
       &GstTunerChannel;
       &GstTunerNorm;
-      &GstVideoorientation;
+      &GstVideoOrientation;
       &GstXOverlay;
     </chapter>
 

docs/libs/gst-plugins-base-libs-sections.txt

@@ -23,17 +23,16 @@ gst_audio_structure_set_int
 <FILE>gstaudioclock</FILE>
 <INCLUDE>gst/audio/gstaudioclock.h</INCLUDE>
 GstAudioClock
-GstAudioClockClass
 GstAudioClockGetTimeFunc
 gst_audio_clock_new
 <SUBSECTION Standard>
+GstAudioClockClass
 GST_AUDIO_CLOCK
 GST_IS_AUDIO_CLOCK
 GST_TYPE_AUDIO_CLOCK
 gst_audio_clock_get_type
 GST_AUDIO_CLOCK_CLASS
 GST_IS_AUDIO_CLOCK_CLASS
-GST_AUDIO_CLOCK_GET_CLASS
 </SECTION>
 
 <SECTION>
@@ -458,6 +457,20 @@ GST_IS_TUNER_NORM_CLASS
 gst_tuner_norm_get_type
 </SECTION>
 
+<SECTION>
+<FILE>gstvideoorientation</FILE>
+<INCLUDE>gst/interfaces/videoorientation.h</INCLUDE>
+GstVideoOrientation
+GstVideoOrientationInterface
+<SUBSECTION Standard>
+GST_TYPE_VIDEO_ORIENTATION
+GST_VIDEO_ORIENTATION
+GST_VIDEO_ORIENTATION_CLASS
+GST_IS_VIDEO_ORIENTATION
+GST_IS_VIDEO_ORIENTATION_CLASS
+gst_video_orientation_get_type
+</SECTION>
+
 <SECTION>
 <FILE>gstxoverlay</FILE>
 <INCLUDE>gst/interfaces/xoverlay.h</INCLUDE>
@@ -800,7 +813,6 @@ gst_rtp_buffer_get_seq
 gst_rtp_buffer_get_ssrc
 gst_rtp_buffer_get_timestamp
 gst_rtp_buffer_get_version
-gst_rtp_buffer_new
 gst_rtp_buffer_new_allocate
 gst_rtp_buffer_new_allocate_len
 gst_rtp_buffer_new_copy_data

gst-libs/gst/audio/gstaudioclock.c

@@ -20,6 +20,19 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstaudioclock
+ * @short_description: Helper object for implementing audio clocks
+ * @see_also: #GstBaseAudioSink, #GstSystemClock
+ *
+ * #GstAudioClock makes it easy for elements to implement a #GstClock, they
+ * simply need to provide a function that returns the current clock time.
+ *
+ * This object is internally used to implement the clock in #GstBaseAudioSink.
+ *
+ * Last reviewed on 2006-09-27 (0.10.12)
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -86,6 +99,18 @@ gst_audio_clock_init (GstAudioClock * clock)
   GST_OBJECT_FLAG_SET (clock, GST_CLOCK_FLAG_CAN_SET_MASTER);
 }
 
+/**
+ * gst_audio_clock_new:
+ * @name: the name of the clock
+ * @func: a function
+ * @user_data: user data
+ *
+ * Create a new #GstAudioClock instance. Whenever the clock time should be
+ * calculated it will call @func with @user_data. When @func returns
+ * #GST_CLOCK_TIME_NONE, the clock will return the last reported time.
+ *
+ * Returns: a new #GstAudioClock casted to a #GstClock.
+ */
 GstClock *
 gst_audio_clock_new (gchar * name, GstAudioClockGetTimeFunc func,
     gpointer user_data)

gst-libs/gst/audio/gstaudioclock.h

@@ -20,7 +20,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-
 #ifndef __GST_AUDIO_CLOCK_H__
 #define __GST_AUDIO_CLOCK_H__
 
@@ -42,8 +41,26 @@ G_BEGIN_DECLS
 typedef struct _GstAudioClock GstAudioClock;
 typedef struct _GstAudioClockClass GstAudioClockClass;
 
+/**
+ * GstAudioClockGetTimeFunc:
+ * @clock: the #GstAudioClock
+ * @user_data: user data
+ *
+ * This function will be called whenever the current clock time needs to be
+ * calculated. If this function returns #GST_CLOCK_TIME_NONE, the last reported
+ * time will be returned by the clock.
+ *
+ * Returns: the current time or #GST_CLOCK_TIME_NONE if the previous time should
+ * be used.
+ */
 typedef GstClockTime (*GstAudioClockGetTimeFunc) (GstClock *clock, gpointer user_data);
 
+/**
+ * GstAudioClock:
+ * @clock: parent #GstSystemClock
+ *
+ * Opaque #GstAudioClock.
+ */
 struct _GstAudioClock {
   GstSystemClock clock;
 

gst-libs/gst/audio/gstaudiosink.c

@@ -20,6 +20,53 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstaudiosink
+ * @short_description: Simple base class for audio sinks
+ * @see_also: #GstBaseAudioSink, #GstRingBuffer, #GstAudioSink.
+ *
+ * This is the most simple base class for audio sinks that only requires
+ * subclasses to implement a set of simple functions:
+ *
+ * <variablelist>
+ *   <varlistentry>
+ *     <term>open()</term>
+ *     <listitem><para>Open the device.</para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>prepare()</term>
+ *     <listitem><para>Configure the device with the specified format.</para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>write()</term>
+ *     <listitem><para>Write samples to the device.</para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>reset()</term>
+ *     <listitem><para>Unblock writes and flush the device.</para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>delay()</term>
+ *     <listitem><para>Get the number of samples written but not yet played 
+ *     by the device.</para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>unprepare()</term>
+ *     <listitem><para>Undo operations done by prepare.</para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>close()</term>
+ *     <listitem><para>Close the device.</para></listitem>
+ *   </varlistentry>
+ * </variablelist>
+ *
+ * All scheduling of samples and timestamps is done in this base class
+ * together with #GstBaseAudioSink using a default implementation of a
+ * #GstRingBuffer that uses threads.
+ *
+ * Last reviewed on 2006-09-27 (0.10.12)
+ */
+
 #include <string.h>
 
 #include "gstaudiosink.h"

gst-libs/gst/audio/gstaudiosink.h

@@ -20,22 +20,6 @@
  * Boston, MA 02111-1307, USA.
  */
 
-/* a base class for simple audio sinks.
- *
- * This base class only requires subclasses to implement a set
- * of simple functions.
- *
- * - open: open the device with the specified caps
- * - write: write the samples to the audio device
- * - close: close the device
- * - delay: the number of samples queued in the device
- * - reset: unblock a write to the device and reset.
- *
- * All scheduling of samples and timestamps is done in this
- * base class together with the GstBaseAudioSink using a
- * default implementation of a ringbuffer that uses threads.
- */
-
 #ifndef __GST_AUDIO_SINK_H__
 #define __GST_AUDIO_SINK_H__
 
@@ -54,6 +38,11 @@ G_BEGIN_DECLS
 typedef struct _GstAudioSink GstAudioSink;
 typedef struct _GstAudioSinkClass GstAudioSinkClass;
 
+/**
+ * GstAudioSink:
+ * 
+ * Opaque #GstAudioSink.
+ */
 struct _GstAudioSink {
   GstBaseAudioSink       element;
 
@@ -64,6 +53,22 @@ struct _GstAudioSink {
   gpointer _gst_reserved[GST_PADDING];
 };
 
+/**
+ * GstAudioSinkClass:
+ * @parent_class: the parent class structure.
+ * @open: Open the device. No configuration needs to be done at this point.
+ *        This function is also used to check if the device is available.
+ * @prepare: Prepare the device to operate with the specified parameters.
+ * @unprepare: Undo operations done in prepare.
+ * @close: Close the device.
+ * @write: Write data to the device.
+ * @delay: Return how many samples are still in the device. This is used to
+ *         drive the synchronisation.
+ * @reset: Returns as quickly as possible from a write and flush any pending
+ *         samples from the device.
+ *
+ * #GstAudioSink class. Override the vmethods to implement functionality.
+ */
 struct _GstAudioSinkClass {
   GstBaseAudioSinkClass parent_class;
 

gst-libs/gst/audio/gstaudiosrc.c

@@ -20,6 +20,53 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstaudiosrc
+ * @short_description: Simple base class for audio sources
+ * @see_also: #GstBaseAudioSrc, #GstRingBuffer, #GstAudioSrc.
+ *
+ * This is the most simple base class for audio sources that only requires
+ * subclasses to implement a set of simple functions:
+ *
+ * <variablelist>
+ *   <varlistentry>
+ *     <term>open()</term>
+ *     <listitem><para>Open the device.</para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>prepare()</term>
+ *     <listitem><para>Configure the device with the specified format.</para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>read()</term>
+ *     <listitem><para>Read samples from the device.</para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>reset()</term>
+ *     <listitem><para>Unblock reads and flush the device.</para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>delay()</term>
+ *     <listitem><para>Get the number of samples in the device but not yet read.
+ *     </para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>unprepare()</term>
+ *     <listitem><para>Undo operations done by prepare.</para></listitem>
+ *   </varlistentry>
+ *   <varlistentry>
+ *     <term>close()</term>
+ *     <listitem><para>Close the device.</para></listitem>
+ *   </varlistentry>
+ * </variablelist>
+ *
+ * All scheduling of samples and timestamps is done in this base class
+ * together with #GstBaseAudioSrc using a default implementation of a
+ * #GstRingBuffer that uses threads.
+ *
+ * Last reviewed on 2006-09-27 (0.10.12)
+ */
+
 #include <string.h>
 
 #include "gstaudiosrc.h"

gst-libs/gst/audio/gstbaseaudiosink.c

@@ -20,6 +20,18 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstbaseaudiosink
+ * @short_description: Base class for audio sinks
+ * @see_also: #GstAudioSink, #GstRingBuffer.
+ *
+ * This is the base class for audio sinks. Subclasses need to implement the
+ * ::create_ringbuffer vmethod. This base class will then take care of
+ * writing samples to the ringbuffer, synchronisation, clipping and flushing.
+ *
+ * Last reviewed on 2006-09-27 (0.10.12)
+ */
+
 #include <string.h>
 
 #include "gstbaseaudiosink.h"
@@ -629,8 +641,11 @@ gst_base_audio_sink_render (GstBaseSink * bsink, GstBuffer * buf)
   } else {
     /* timestamps drifted apart from previous samples too much, we need to
      * resync. We log this as an element warning. */
-    GST_ELEMENT_WARNING (sink, CORE, CLOCK, (NULL),
+    GST_ELEMENT_WARNING (sink, CORE, CLOCK,
-        ("Unexpected discontinuity in audio timestamps of more than half a second"));
+        ("Compensating for audio synchronisation problems"),
+        ("Unexpected discontinuity in audio timestamps of more "
+            "than half a second (%" GST_TIME_FORMAT "), resyncing",
+            GST_TIME_ARGS (diff)));
   }
 
 no_align:
@@ -701,6 +716,16 @@ stopping:
   }
 }
 
+/**
+ * gst_base_audio_sink_create_ringbuffer:
+ * @sink: a #GstBaseAudioSink.
+ *
+ * Create and return the #GstRingBuffer for @sink. This function will call the
+ * ::create_ringbuffer vmethod and will set @sink as the parent of the returned
+ * buffer (see gst_object_set_parent()).
+ *
+ * Returns: The new ringbuffer of @sink.
+ */
 GstRingBuffer *
 gst_base_audio_sink_create_ringbuffer (GstBaseAudioSink * sink)
 {

gst-libs/gst/audio/gstbaseaudiosink.h

@@ -63,12 +63,29 @@ G_BEGIN_DECLS
 #define GST_IS_BASE_AUDIO_SINK(obj)             (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_BASE_AUDIO_SINK))
 #define GST_IS_BASE_AUDIO_SINK_CLASS(klass)     (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_BASE_AUDIO_SINK))
 
+/**
+ * GST_BASE_AUDIO_SINK_CLOCK:
+ * @obj: a #GstBaseAudioSink
+ *
+ * Get the #GstClock of @obj.
+ */
 #define GST_BASE_AUDIO_SINK_CLOCK(obj)   (GST_BASE_AUDIO_SINK (obj)->clock)
+/**
+ * GST_BASE_AUDIO_SINK_PAD:
+ * @obj: a #GstBaseAudioSink
+ *
+ * Get the sink #GstPad of @obj.
+ */
 #define GST_BASE_AUDIO_SINK_PAD(obj)     (GST_BASE_SINK (obj)->sinkpad)
 
 typedef struct _GstBaseAudioSink GstBaseAudioSink;
 typedef struct _GstBaseAudioSinkClass GstBaseAudioSinkClass;
 
+/**
+ * GstBaseAudioSink:
+ *
+ * Opaque #GstBaseAudioSink.
+ */
 struct _GstBaseAudioSink {
   GstBaseSink    element;
 
@@ -77,8 +94,8 @@ struct _GstBaseAudioSink {
   GstRingBuffer *ringbuffer;
 
   /* required buffer and latency in microseconds */
-  guint64 buffer_time;
+  guint64        buffer_time;
-  guint64 latency_time;
+  guint64        latency_time;
 
   /* the next sample to write */
   guint64        next_sample;
@@ -91,6 +108,14 @@ struct _GstBaseAudioSink {
   gpointer _gst_reserved[GST_PADDING];
 };
 
+/**
+ * GstBaseAudioSinkClass:
+ * @parent_class: the parent class.
+ * @create_ringbuffer: create and return a #GstRingBuffer to write to.
+ *
+ * #GstBaseAudioSink class. Override the vmethod to implement
+ * functionality.
+ */
 struct _GstBaseAudioSinkClass {
   GstBaseSinkClass parent_class;
 

gst-libs/gst/audio/gstbaseaudiosrc.c

@@ -20,6 +20,18 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstbaseaudiosrc
+ * @short_description: Base class for audio sources
+ * @see_also: #GstAudioSrc, #GstRingBuffer.
+ *
+ * This is the base class for audio sources. Subclasses need to implement the
+ * ::create_ringbuffer vmethod. This base class will then take care of
+ * reading samples from the ringbuffer, synchronisation and flushing.
+ *
+ * Last reviewed on 2006-09-27 (0.10.12)
+ */
+
 #include <string.h>
 
 #include "gstbaseaudiosrc.h"
@@ -144,6 +156,7 @@ gst_base_audio_src_init (GstBaseAudioSrc * baseaudiosrc,
 
   /* we are always a live source */
   gst_base_src_set_live (GST_BASE_SRC (baseaudiosrc), TRUE);
+  /* we operate in time */
   gst_base_src_set_format (GST_BASE_SRC (baseaudiosrc), GST_FORMAT_TIME);
 }
 
@@ -527,6 +540,16 @@ stopped:
   }
 }
 
+/**
+ * gst_base_audio_src_create_ringbuffer:
+ * @src: a #GstBaseAudioSrc.
+ *
+ * Create and return the #GstRingBuffer for @src. This function will call the
+ * ::create_ringbuffer vmethod and will set @src as the parent of the returned
+ * buffer (see gst_object_set_parent()).
+ *
+ * Returns: The new ringbuffer of @src.
+ */
 GstRingBuffer *
 gst_base_audio_src_create_ringbuffer (GstBaseAudioSrc * src)
 {

gst-libs/gst/audio/gstbaseaudiosrc.h

@@ -40,12 +40,29 @@ G_BEGIN_DECLS
 #define GST_IS_BASE_AUDIO_SRC(obj)              (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_BASE_AUDIO_SRC))
 #define GST_IS_BASE_AUDIO_SRC_CLASS(klass)      (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_BASE_AUDIO_SRC))
 
+/**
+ * GST_BASE_AUDIO_SRC_CLOCK:
+ * @obj: a #GstBaseAudioSrc
+ *
+ * Get the #GstClock of @obj.
+ */
 #define GST_BASE_AUDIO_SRC_CLOCK(obj)    (GST_BASE_AUDIO_SRC (obj)->clock)
+/**
+ * GST_BASE_AUDIO_SRC_PAD:
+ * @obj: a #GstBaseAudioSrc
+ *
+ * Get the source #GstPad of @obj.
+ */
 #define GST_BASE_AUDIO_SRC_PAD(obj)      (GST_BASE_SRC (obj)->srcpad)
 
 typedef struct _GstBaseAudioSrc GstBaseAudioSrc;
 typedef struct _GstBaseAudioSrcClass GstBaseAudioSrcClass;
 
+/**
+ * GstBaseAudioSrc:
+ *
+ * Opaque #GstBaseAudioSrc.
+ */
 struct _GstBaseAudioSrc {
   GstPushSrc     element;
 
@@ -67,6 +84,14 @@ struct _GstBaseAudioSrc {
   gpointer _gst_reserved[GST_PADDING];
 };
 
+/**
+ * GstBaseAudioSrcClass:
+ * @parent_class: the parent class.
+ * @create_ringbuffer: create and return a #GstRingBuffer to read from.
+ *
+ * #GstBaseAudioSrc class. Override the vmethod to implement
+ * functionality.
+ */
 struct _GstBaseAudioSrcClass {
   GstPushSrcClass parent_class;
 

gst-libs/gst/audio/gstringbuffer.h

@@ -39,7 +39,16 @@ typedef struct _GstRingBuffer GstRingBuffer;
 typedef struct _GstRingBufferClass GstRingBufferClass;
 typedef struct _GstRingBufferSpec GstRingBufferSpec;
 
-/* called to fill data with len bytes of samples */
+/**
+ * GstRingBufferCallback:
+ * @rbuf: a #GstRingBuffer
+ * @data: target to fill
+ * @len: amount to fill
+ * @user_data: user data
+ *
+ * This function is set with gst_ring_buffer_set_callback() and is
+ * called to fill the memory at @data with @len bytes of samples. 
+ */
 typedef void (*GstRingBufferCallback) (GstRingBuffer *rbuf, guint8* data, guint len, gpointer user_data);
 
 /**