From afa31cfea03063a848ba4db5aa03001301839aa2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebastian=20Dr=C3=B6ge?= <slomo@circular-chaos.org>
Date: Wed, 23 Jan 2008 10:34:40 +0000
Subject: Add documentation for the xingheader plugin.

Original commit message from CVS:
* docs/plugins/Makefile.am:
* docs/plugins/gst-plugins-bad-plugins-docs.sgml:
* docs/plugins/gst-plugins-bad-plugins-sections.txt:
* gst/xingheader/gstxingmux.c:
* gst/xingheader/gstxingmux.h:
Add documentation for the xingheader plugin.
* tests/check/elements/xingmux.c: (GST_START_TEST):
Set element state to PLAYING before doing something else.
---
 gst/xingheader/gstxingmux.c | 31 ++++++++++++++++++++++
 gst/xingheader/gstxingmux.h | 64 +++++++++++++++++++++++++++++----------------
 2 files changed, 73 insertions(+), 22 deletions(-)

(limited to 'gst/xingheader')

diff --git a/gst/xingheader/gstxingmux.c b/gst/xingheader/gstxingmux.c
index d10006cc..49a4628b 100644
--- a/gst/xingheader/gstxingmux.c
+++ b/gst/xingheader/gstxingmux.c
@@ -20,6 +20,31 @@
 
 /* Xing SDK: http://www.mp3-tech.org/programmer/sources/vbrheadersdk.zip */
 
+
+/**
+ * SECTION:element-xingmux
+ * @short_description: Adds a Xing header to MP3 files
+ *
+ * <refsect2>
+ * <para>
+ * xingmux adds a Xing header to MP3 files. This contains information about the duration and size
+ * of the file and a seek table and is very useful for getting an almost correct duration and better
+ * seeking on VBR MP3 files.
+ * </para>
+ * <para>
+ * This element will remove any existing Xing, LAME or VBRI headers from the beginning of the file.
+ * </para>
+ * <title>Example launch line</title>
+ * <para>
+ * <programlisting>
+ * gst-launch audiotestsrc num-buffers=1000 ! audioconvert ! lame ! xingmux ! filesink location=test.mp3
+ * gst-launch filesrc location=test.mp3 ! xingmux ! filesink location=test2.mp3
+ * gst-launch filesrc location=test.mp3 ! mp3parse ! xingmux ! filesink location=test2.mp3
+ * </programlisting>
+ * </para>
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif
@@ -38,6 +63,12 @@ GST_BOILERPLATE (GstXingMux, gst_xing_mux, GstElement, GST_TYPE_ELEMENT);
 #define GST_XING_TOC_FIELD     (1 << 2)
 #define GST_XING_QUALITY_FIELD (1 << 3)
 
+typedef struct _GstXingSeekEntry
+{
+  gint64 timestamp;
+  gint byte;
+} GstXingSeekEntry;
+
 static void gst_xing_mux_finalize (GObject * obj);
 static GstStateChangeReturn
 gst_xing_mux_change_state (GstElement * element, GstStateChange transition);
diff --git a/gst/xingheader/gstxingmux.h b/gst/xingheader/gstxingmux.h
index 06b25a35..197fc6f2 100644
--- a/gst/xingheader/gstxingmux.h
+++ b/gst/xingheader/gstxingmux.h
@@ -21,18 +21,40 @@
 #include <gst/gst.h>
 #include <gst/base/gstadapter.h>
 
-typedef struct _GstXingSeekEntry
-{
-  gint64 timestamp;
-  gint byte;
-} GstXingSeekEntry;
+#ifndef __GST_XINGMUX_H__
+#define __GST_XINGMUX_H__
+
+G_BEGIN_DECLS
+
+/* Standard macros for defining types for this element.  */
+#define GST_TYPE_XING_MUX \
+  (gst_xing_mux_get_type())
+#define GST_XING_MUX(obj) \
+  (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_XING_MUX,GstXingMux))
+#define GST_XING_MUX_CLASS(klass) \
+  (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_XING_MUX,GstXingMuxClass))
+#define GST_IS_XING_MUX(obj) \
+  (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_XING_MUX))
+#define GST_IS_XING_MUX_CLASS(klass) \
+  (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_XING_MUX))
+
+typedef struct _GstXingMux GstXingMux;
+typedef struct _GstXingMuxClass GstXingMuxClass;
 
 /* Definition of structure storing data for this element. */
-typedef struct _GstXingMux {
+
+/**
+ * GstXingMux:
+ *
+ * Opaque data structure.
+ */
+struct _GstXingMux {
   GstElement element;
 
   GstPad *sinkpad, *srcpad;
 
+  /* < private > */
+
   GstAdapter *adapter;
   GstClockTime duration;
   guint64 byte_count;
@@ -42,24 +64,22 @@ typedef struct _GstXingMux {
 
   /* Copy of the first frame header */
   guint32 first_header;
-} GstXingMux;
+};
 
 /* Standard definition defining a class for this element. */
-typedef struct _GstXingMuxClass {
-  GstElementClass parent_class;
-} GstXingMuxClass;
 
-/* Standard macros for defining types for this element.  */
-#define GST_TYPE_XING_MUX \
-  (gst_xing_mux_get_type())
-#define GST_XING_MUX(obj) \
-  (G_TYPE_CHECK_INSTANCE_CAST((obj),GST_TYPE_XING_MUX,GstXingMux))
-#define GST_XING_MUX_CLASS(klass) \
-  (G_TYPE_CHECK_CLASS_CAST((klass),GST_TYPE_XING_MUX,GstXingMuxClass))
-#define GST_IS_XING_MUX(obj) \
-  (G_TYPE_CHECK_INSTANCE_TYPE((obj),GST_TYPE_XING_MUX))
-#define GST_IS_XING_MUX_CLASS(klass) \
-  (G_TYPE_CHECK_CLASS_TYPE((klass),GST_TYPE_XING_MUX))
+/**
+ * GstXingMuxClass:
+ *
+ * Opaque data structure.
+ */
+struct _GstXingMuxClass {
+  GstElementClass parent_class;
+};
 
 /* Standard function returning type information. */
-GType gst_my_filter_get_type (void);
+GType gst_xing_mux_get_type (void);
+
+G_END_DECLS
+
+#endif /* __GST_XINGMUX_H__ */
-- 
cgit v1.2.1