From 73677225096430031ea566eef814234279a93da3 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Wed, 27 Sep 2006 11:05:08 +0000 Subject: [PATCH] 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 | 17 +++++++ docs/libs/gst-plugins-base-libs-docs.sgml | 2 +- docs/libs/gst-plugins-base-libs-sections.txt | 18 ++++++-- gst-libs/gst/audio/gstaudioclock.c | 25 +++++++++++ gst-libs/gst/audio/gstaudioclock.h | 19 +++++++- gst-libs/gst/audio/gstaudiosink.c | 47 ++++++++++++++++++++ gst-libs/gst/audio/gstaudiosink.h | 37 ++++++++------- gst-libs/gst/audio/gstaudiosrc.c | 47 ++++++++++++++++++++ gst-libs/gst/audio/gstbaseaudiosink.c | 29 +++++++++++- gst-libs/gst/audio/gstbaseaudiosink.h | 29 +++++++++++- gst-libs/gst/audio/gstbaseaudiosrc.c | 23 ++++++++++ gst-libs/gst/audio/gstbaseaudiosrc.h | 25 +++++++++++ gst-libs/gst/audio/gstringbuffer.h | 11 ++++- 13 files changed, 303 insertions(+), 26 deletions(-) diff --git a/ChangeLog b/ChangeLog index 799deee391..8794412684 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,20 @@ +2006-09-27 Wim Taymans + + * 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 * tests/check/Makefile.am: diff --git a/docs/libs/gst-plugins-base-libs-docs.sgml b/docs/libs/gst-plugins-base-libs-docs.sgml index 90f9fd890c..4bec23a39a 100644 --- a/docs/libs/gst-plugins-base-libs-docs.sgml +++ b/docs/libs/gst-plugins-base-libs-docs.sgml @@ -124,7 +124,7 @@ &GstTuner; &GstTunerChannel; &GstTunerNorm; - &GstVideoorientation; + &GstVideoOrientation; &GstXOverlay; diff --git a/docs/libs/gst-plugins-base-libs-sections.txt b/docs/libs/gst-plugins-base-libs-sections.txt index bf525506c8..b3aa150a22 100644 --- a/docs/libs/gst-plugins-base-libs-sections.txt +++ b/docs/libs/gst-plugins-base-libs-sections.txt @@ -23,17 +23,16 @@ gst_audio_structure_set_int gstaudioclock gst/audio/gstaudioclock.h GstAudioClock -GstAudioClockClass GstAudioClockGetTimeFunc gst_audio_clock_new +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
@@ -458,6 +457,20 @@ GST_IS_TUNER_NORM_CLASS gst_tuner_norm_get_type
+
+gstvideoorientation +gst/interfaces/videoorientation.h +GstVideoOrientation +GstVideoOrientationInterface + +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 +
+
gstxoverlay gst/interfaces/xoverlay.h @@ -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 diff --git a/gst-libs/gst/audio/gstaudioclock.c b/gst-libs/gst/audio/gstaudioclock.c index 6d237e269d..5b7c79b24d 100644 --- a/gst-libs/gst/audio/gstaudioclock.c +++ b/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) diff --git a/gst-libs/gst/audio/gstaudioclock.h b/gst-libs/gst/audio/gstaudioclock.h index 383a62b915..621f81bbcb 100644 --- a/gst-libs/gst/audio/gstaudioclock.h +++ b/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; diff --git a/gst-libs/gst/audio/gstaudiosink.c b/gst-libs/gst/audio/gstaudiosink.c index 72c27b5fd7..e3c8d282ea 100644 --- a/gst-libs/gst/audio/gstaudiosink.c +++ b/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: + * + * + * + * open() + * Open the device. + * + * + * prepare() + * Configure the device with the specified format. + * + * + * write() + * Write samples to the device. + * + * + * reset() + * Unblock writes and flush the device. + * + * + * delay() + * Get the number of samples written but not yet played + * by the device. + * + * + * unprepare() + * Undo operations done by prepare. + * + * + * close() + * Close the device. + * + * + * + * 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 #include "gstaudiosink.h" diff --git a/gst-libs/gst/audio/gstaudiosink.h b/gst-libs/gst/audio/gstaudiosink.h index 804fd1e18e..ff9b8caf8e 100644 --- a/gst-libs/gst/audio/gstaudiosink.h +++ b/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; diff --git a/gst-libs/gst/audio/gstaudiosrc.c b/gst-libs/gst/audio/gstaudiosrc.c index 262f08e257..adc1704fb1 100644 --- a/gst-libs/gst/audio/gstaudiosrc.c +++ b/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: + * + * + * + * open() + * Open the device. + * + * + * prepare() + * Configure the device with the specified format. + * + * + * read() + * Read samples from the device. + * + * + * reset() + * Unblock reads and flush the device. + * + * + * delay() + * Get the number of samples in the device but not yet read. + * + * + * + * unprepare() + * Undo operations done by prepare. + * + * + * close() + * Close the device. + * + * + * + * 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 #include "gstaudiosrc.h" diff --git a/gst-libs/gst/audio/gstbaseaudiosink.c b/gst-libs/gst/audio/gstbaseaudiosink.c index d20ccb6e31..d7de64d00f 100644 --- a/gst-libs/gst/audio/gstbaseaudiosink.c +++ b/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 #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) { diff --git a/gst-libs/gst/audio/gstbaseaudiosink.h b/gst-libs/gst/audio/gstbaseaudiosink.h index 4e0c554b1b..5cd2068ac0 100644 --- a/gst-libs/gst/audio/gstbaseaudiosink.h +++ b/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 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; diff --git a/gst-libs/gst/audio/gstbaseaudiosrc.c b/gst-libs/gst/audio/gstbaseaudiosrc.c index 3e68901bdb..6f6410efb7 100644 --- a/gst-libs/gst/audio/gstbaseaudiosrc.c +++ b/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 #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) { diff --git a/gst-libs/gst/audio/gstbaseaudiosrc.h b/gst-libs/gst/audio/gstbaseaudiosrc.h index 98375c78e0..d090552b2a 100644 --- a/gst-libs/gst/audio/gstbaseaudiosrc.h +++ b/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; diff --git a/gst-libs/gst/audio/gstringbuffer.h b/gst-libs/gst/audio/gstringbuffer.h index c54857ab99..e4cbe1a488 100644 --- a/gst-libs/gst/audio/gstringbuffer.h +++ b/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); /**