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.
This commit is contained in:
Wim Taymans 2006-09-27 11:05:08 +00:00
parent bb54e8cb1f
commit 7367722509
13 changed files with 303 additions and 26 deletions

View file

@ -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:

View file

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

View file

@ -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

View file

@ -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)

View file

@ -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;

View file

@ -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"

View file

@ -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;

View file

@ -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"

View file

@ -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),
("Unexpected discontinuity in audio timestamps of more than half a second"));
GST_ELEMENT_WARNING (sink, CORE, CLOCK,
("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)
{

View file

@ -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 latency_time;
guint64 buffer_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;

View file

@ -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)
{

View file

@ -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;

View file

@ -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);
/**