Add appsrc and appsink documentation.

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-libs/gst/app/gstappsink.c:
* gst-libs/gst/app/gstappsrc.c: (gst_app_src_class_init):
Add appsrc and appsink documentation.

ChangeLog

@@ -1,3 +1,12 @@
+2008-12-17  Wim Taymans  <wim.taymans@collabora.co.uk>
+
+	* docs/plugins/Makefile.am:
+	* docs/plugins/gst-plugins-bad-plugins-docs.sgml:
+	* docs/plugins/gst-plugins-bad-plugins-sections.txt:
+	* gst-libs/gst/app/gstappsink.c:
+	* gst-libs/gst/app/gstappsrc.c: (gst_app_src_class_init):
+	Add appsrc and appsink documentation.
+
 2008-12-17  Sebastian Dröge  <sebastian.droege@collabora.co.uk>
 
 	* gst/mxf/mxfdemux.c: (gst_mxf_demux_chain):

common

@@ -1 +1 @@
-Subproject commit 2c4d28a75c26e572b94a967901254caff83d85c4
+Subproject commit 5dc8ae302733ce1aae5b1aaa613ce77a8ae4b3d9

docs/plugins/Makefile.am

@@ -113,6 +113,8 @@ EXTRA_HFILES = \
 	$(top_srcdir)/ext/timidity/gstwildmidi.h \
 	$(top_srcdir)/ext/twolame/gsttwolame.h \
 	$(top_srcdir)/ext/x264/gstx264enc.h \
+	$(top_srcdir)/gst-libs/gst/app/gstappsrc.h \
+	$(top_srcdir)/gst-libs/gst/app/gstappsink.h \
 	$(top_srcdir)/gst/aacparse/gstaacparse.h \
 	$(top_srcdir)/gst/amrparse/gstamrparse.h \
 	$(top_srcdir)/gst/audioresample/gstaudioresample.h \

docs/plugins/gst-plugins-bad-plugins-docs.sgml

@@ -12,6 +12,8 @@
 
   <chapter>
     <title>gst-plugins-bad Elements</title>
+    <xi:include href="xml/element-appsrc.xml" />
+    <xi:include href="xml/element-appsink.xml" />
     <xi:include href="xml/element-aacparse.xml" />
     <xi:include href="xml/element-amrparse.xml" />
     <xi:include href="xml/element-amrwbdec.xml" />

docs/plugins/gst-plugins-bad-plugins-sections.txt

@@ -1,3 +1,53 @@
+<SECTION>
+<FILE>element-appsrc</FILE>
+<TITLE>appsrc</TITLE>
+GstAppSrc
+GstAppStreamType
+gst_app_src_set_caps
+gst_app_src_get_caps
+gst_app_src_set_size
+gst_app_src_get_size
+gst_app_src_set_stream_type
+gst_app_src_get_stream_type
+gst_app_src_set_max_bytes
+gst_app_src_get_max_bytes
+gst_app_src_push_buffer
+gst_app_src_end_of_stream
+<SUBSECTION Standard>
+GstAppSrcClass
+GST_APP_SRC
+GST_IS_APP_SRC
+GST_TYPE_APP_SRC
+gst_app_src_get_type
+GST_APP_SRC_CLASS
+GST_IS_APP_SRC_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>element-appsink</FILE>
+<TITLE>appsink</TITLE>
+GstAppSink
+gst_app_sink_set_caps
+gst_app_sink_get_caps
+gst_app_sink_is_eos
+gst_app_sink_set_emit_signals
+gst_app_sink_get_emit_signals
+gst_app_sink_set_max_buffers
+gst_app_sink_get_max_buffers
+gst_app_sink_set_drop
+gst_app_sink_get_drop
+gst_app_sink_pull_preroll
+gst_app_sink_pull_buffer
+<SUBSECTION Standard>
+GstAppSinkClass
+GST_APP_SINK
+GST_IS_APP_SINK
+GST_TYPE_APP_SINK
+gst_app_sink_get_type
+GST_APP_SINK_CLASS
+GST_IS_APP_SINK_CLASS
+</SECTION>
+
 <SECTION>
 <FILE>element-aacparse</FILE>
 <TITLE>aacparse</TITLE>

gst-libs/gst/app/gstappsink.c

@@ -20,12 +20,43 @@
 
 /**
  * SECTION:element-appsink
- * @see_also: #GstBaseSrc
+ * @see_also: #GstBaseSink, appsrc
  *
  * Appsink is a sink plugin that supports many different methods for making
  * the application get a handle on the GStreamer data in a pipeline.
  *
- * Last reviewed on 2008-05-03 (0.10.8)
+ * appsink can be used by linking to the gstappsink.h header file to access the
+ * methods or by using the appsink action signals and properties.
+ *
+ * The normal way of retrieving buffers from appsink is by using the
+ * gst_app_sink_pull_buffer() and gst_app_sink_pull_preroll() methods.
+ * These methods block until a buffer becomes available in the sink or when the
+ * sink is shut down or reaches EOS.
+ *
+ * Appsink will internally use a queue to collect buffers from the streaming
+ * thread. If the application is not pulling buffers fast enough, this queue
+ * will consume a lot of memory over time. The "max-buffers" property can be
+ * used to limit the queue size. The "drop" property controls whether the
+ * streaming thread blocks or if older buffers are dropped when the maximum
+ * queue size is reached. Note that blocking the streaming thread can negatively
+ * affect real-time performance and should be avoided.
+ *
+ * If a blocking behaviour is not desirable, setting the "emit-signals" property
+ * to %TRUE will make appsink emit the "new-buffer" and "new-preroll" signals
+ * when a buffer can be pulled without blocking.
+ *
+ * The "caps" property on appsink can be used to control the formats that
+ * appsink can receive. This property can contain non-fixed caps, the format of
+ * the pulled buffers can be obtained by getting the buffer caps.
+ *
+ * If one of the pull-preroll or pull-buffer methods return %NULL, the appsink
+ * is stopped or in the EOS state. You can check for the EOS state with the
+ * "eos" property or with the gst_app_sink_is_eos() method.
+ *
+ * The eos signal can also be used to be informed when the EOS state is reached
+ * to avoid polling.
+ *
+ * Last reviewed on 2008-12-17 (0.10.10)
  */
 
 #ifdef HAVE_CONFIG_H

gst-libs/gst/app/gstappsrc.c

@@ -20,9 +20,67 @@
 
 /**
  * SECTION:element-appsrc
+ * @see_also: #GstBaseSrc, appsink
  *
  * The appsrc element can be used by applications to insert data into a
  * GStreamer pipeline.
+ *
+ * appsrc can be used by linking to the gstappsrc.h header file to access the
+ * methods or by using the appsrc action signals.
+ *
+ * Before operating appsrc, the caps property must be set to a fixed caps
+ * describing the format of the data that will be pushed with appsrc.
+ *
+ * The main way of handing data to the appsrc element is by calling the
+ * gst_app_src_push_buffer() method or by emiting the push-buffer action signal.
+ * This will put the buffer onto a queue from which appsrc will read from in its
+ * streaming thread. It is important to note that data transport will not happen
+ * from the thread that performed the push-buffer call.
+ *
+ * The "max-bytes" property controls how much data can be queued in appsrc
+ * before appsrc considers the queue full. A filled internal queue will always
+ * signal the "enough-data" signal, which signals the application that it should
+ * stop pushing data into appsrc. The "block" property will cause appsrc to
+ * block the push-buffer method until free data becomes available again.
+ *
+ * When the internal queue is running out of data, the "need-data" signal is
+ * emited, which signals the application that it should start pushing more data
+ * into appsrc.
+ *
+ * In addition to the "need-data" and "enough-data" signals, appsrc can emit the
+ * "seek-data" signal when the "stream-mode" property is set to "seekable" or
+ * "random-access". The signal argument will contain the new desired position in
+ * the stream expressed in the unit set with the "format" property. After
+ * receiving the seek-data signal, the application should push-buffers from the
+ * new position.
+ *
+ * These signals allow the application to operate the appsrc in two different
+ * ways:
+ *
+ * The push model, in which the application repeadedly calls the push-buffer method
+ * with a new buffer. Optionally, the queue size in the appsrc can be controlled
+ * with the enough-data and need-data signals by respectively stopping/starting
+ * the push-buffer calls. This is a typical mode of operation for the
+ * stream-type "stream" and "seekable". Use this model when implementing various
+ * network protocols or hardware devices.
+ *
+ * The pull model where the need-data signal triggers the next push-buffer call.
+ * This mode is typically used in the "random-access" stream-type. Use this
+ * model for file access or other randomly accessable sources. In this mode, a
+ * buffer of exactly the amount of bytes given by the need-data signal should be
+ * pushed into appsrc.
+ *
+ * In all modes, the size property on appsrc should contain the total stream
+ * size in bytes. Setting this property is mandatory in the random-access mode.
+ * For the stream and seekable modes, setting this property is optional but
+ * recommended.
+ *
+ * When the application is finished pushing data into appsrc, it should call 
+ * gst_app_src_end_of_stream() or emit the end-of-stream action signal. After
+ * this call, no more buffers can be pushed into appsrc until a flushing seek
+ * happened or the state of the appsrc has gone through READY.
+ *
+ * Last reviewed on 2008-12-17 (0.10.10)
  */
 
 #ifdef HAVE_CONFIG_H
@@ -200,7 +258,7 @@ gst_app_src_class_init (GstAppSrcClass * klass)
    */
   g_object_class_install_property (gobject_class, PROP_SIZE,
       g_param_spec_int64 ("size", "Size",
-          "The size of the data stream (-1 if unknown)",
+          "The size of the data stream in bytes (-1 if unknown)",
           -1, G_MAXINT64, DEFAULT_PROP_SIZE,
           G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
   /**