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.

common

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

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