From 0904ecdd27e6c4509f50603779bbd47230ea091b Mon Sep 17 00:00:00 2001
From: Benjamin Otte <otte@gnome.org>
Date: Thu, 4 Aug 2005 16:26:09 +0000
Subject: [PATCH] add GstAdapter docs.

Original commit message from CVS:
* docs/libs/gstreamer-libs-docs.sgml:
* docs/libs/gstreamer-libs-sections.txt:
* libs/gst/bytestream/adapter.c:
add GstAdapter docs.
* libs/gst/bytestream/adapter.h:
mark custom fields in GstAdapter struct as private for gtk-doc
---
 ChangeLog                             |  9 ++++++
 docs/libs/gstreamer-libs-docs.sgml    |  2 ++
 docs/libs/gstreamer-libs-sections.txt | 14 +++++++++
 libs/gst/bytestream/adapter.c         | 41 +++++++++++++++++++++++++++
 libs/gst/bytestream/adapter.h         |  1 +
 5 files changed, 67 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index 5948291875..fd5f91489a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2005-08-04  Benjamin Otte  <otte@gnome.org>
+
+	* docs/libs/gstreamer-libs-docs.sgml:
+	* docs/libs/gstreamer-libs-sections.txt:
+	* libs/gst/bytestream/adapter.c:
+	  add GstAdapter docs.
+	* libs/gst/bytestream/adapter.h:
+	  mark custom fields in GstAdapter struct as private for gtk-doc
+
 2005-07-24  Benjamin Otte  <otte@gnome.org>
 
 	* tools/tools.h:
diff --git a/docs/libs/gstreamer-libs-docs.sgml b/docs/libs/gstreamer-libs-docs.sgml
index 6027b5a1ff..6ac65e0bab 100644
--- a/docs/libs/gstreamer-libs-docs.sgml
+++ b/docs/libs/gstreamer-libs-docs.sgml
@@ -3,6 +3,7 @@
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
 <!ENTITY % version-entities SYSTEM "version.entities">
 %version-entities;
+<!ENTITY GstAdapter SYSTEM "xml/gstadapter.xml">
 <!ENTITY GstBytestream SYSTEM "xml/gstbytestream.xml">
 <!ENTITY GstGetbits SYSTEM "xml/gstgetbits.xml">
 <!-- has not yet been written
@@ -36,6 +37,7 @@
     <para>
       GStreamer provides some standard libraries you can use to create plugins.
     </para>
+    &GstAdapter;
     &GstBytestream;
     &GstDataProtocol;
     &GstGetbits;
diff --git a/docs/libs/gstreamer-libs-sections.txt b/docs/libs/gstreamer-libs-sections.txt
index 88b3f54e0b..226c3468b0 100644
--- a/docs/libs/gstreamer-libs-sections.txt
+++ b/docs/libs/gstreamer-libs-sections.txt
@@ -88,6 +88,20 @@ gst_backbitsX
 swab32
 </SECTION>
 
+<SECTION>
+<FILE>gstadapter</FILE>
+<INCLUDE>gst/bytestream/adapter.h</INCLUDE>
+GstAdapter
+gst_adapter_new
+gst_adapter_clear
+gst_adapter_push
+gst_adapter_peek
+gst_adapter_flush
+gst_adapter_available
+gst_adapter_available_fast
+<SUBSECTION Standard>
+</SECTION>
+
 <SECTION>
 <FILE>gstbytestream</FILE>
 <INCLUDE>libs/bytestream/bytestream.h</INCLUDE>
diff --git a/libs/gst/bytestream/adapter.c b/libs/gst/bytestream/adapter.c
index 87fb5f80f0..a41b8aa52f 100644
--- a/libs/gst/bytestream/adapter.c
+++ b/libs/gst/bytestream/adapter.c
@@ -17,6 +17,47 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gstadapter
+ * @short_description: object to splice and merge buffers to desired size
+ * @see_also: #GstBytestream, #GstFilePad
+ *
+ * This class is for elements that receive buffers in an undesired size. 
+ * While for example raw video contains one image per buffer, the same is not 
+ * true for a lot of other formats, especially those that come directly from 
+ * a file. So if you have undefined buffer sizes and require a specific size, 
+ * this object is for you.
+ *
+ * The theory of operation is like this: All buffers received are put
+ * into the adapter using gst_adapter_push() and the data is then read back 
+ * in chunks of the desired size using gst_adapter_peek(). After the data is
+ * processed, it is freed using gst_adapter_flush(). An example function that
+ * needs to process data in 10 byte chunks could look like this:
+ * <programlisting>
+ * void
+ * process_buffer (GstAdapter *adapter, GstBuffer *buffer)
+ * {
+ *   guint8 *data;
+ *   // put buffer into adapter
+ *   #gst_adapter_push (adapter, buffer);
+ *   // while we can read out 10 bytes, process them
+ *   while ((data = #gst_adapter_peek (adapter, 10))) {
+ *     // process the 10 bytes here
+ *     // after processing the data, flush it
+ *     #gst_adapter_flush (adapter, 10);
+ *   }
+ * }
+ * </programlisting>
+ * For another example, a simple element inside GStreamer that uses GstAdapter
+ * is the libvisual element.
+ *
+ * A last thing to note is that while GstAdapter is pretty optimized, 
+ * merging buffers still might be an operation that requires a memcpy() 
+ * operation, and this operation is not the fastest. Because of this, some 
+ * functions like gst_adapter_available_fast() are provided to help speed up 
+ * such cases should you want to.
+ */
+
 #include "adapter.h"
 #include <string.h>
 
diff --git a/libs/gst/bytestream/adapter.h b/libs/gst/bytestream/adapter.h
index 4257cf54c7..1455d5eb37 100644
--- a/libs/gst/bytestream/adapter.h
+++ b/libs/gst/bytestream/adapter.h
@@ -42,6 +42,7 @@ typedef struct _GstAdapterClass GstAdapterClass;
 struct _GstAdapter {
   GObject	object;
 
+  /*< private >*/
   GSList *	buflist;
   guint		size;
   guint		skip;