From 8567ee21492d6bc89d5d9ad2e001f76722fe4ed0 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Wed, 17 Dec 2008 13:51:46 +0000 Subject: [PATCH] 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 | 2 +- gst-libs/gst/app/gstappsink.c | 35 ++++++++++++++++++-- gst-libs/gst/app/gstappsrc.c | 60 ++++++++++++++++++++++++++++++++++- 3 files changed, 93 insertions(+), 4 deletions(-) diff --git a/common b/common index 2c4d28a75c..5dc8ae3027 160000 --- a/common +++ b/common @@ -1 +1 @@ -Subproject commit 2c4d28a75c26e572b94a967901254caff83d85c4 +Subproject commit 5dc8ae302733ce1aae5b1aaa613ce77a8ae4b3d9 diff --git a/gst-libs/gst/app/gstappsink.c b/gst-libs/gst/app/gstappsink.c index 0079c2e970..79b1b843b4 100644 --- a/gst-libs/gst/app/gstappsink.c +++ b/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 diff --git a/gst-libs/gst/app/gstappsrc.c b/gst-libs/gst/app/gstappsrc.c index 27848080b2..9cf1afc33a 100644 --- a/gst-libs/gst/app/gstappsrc.c +++ b/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)); /**