diff options
| -rw-r--r-- | ChangeLog | 9 | ||||
| m--------- | common | 0 | ||||
| -rw-r--r-- | docs/plugins/Makefile.am | 2 | ||||
| -rw-r--r-- | docs/plugins/gst-plugins-bad-plugins-docs.sgml | 2 | ||||
| -rw-r--r-- | docs/plugins/gst-plugins-bad-plugins-sections.txt | 50 | ||||
| -rw-r--r-- | gst-libs/gst/app/gstappsink.c | 35 | ||||
| -rw-r--r-- | gst-libs/gst/app/gstappsrc.c | 60 |
7 files changed, 155 insertions, 3 deletions
@@ -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): diff --git a/common b/common -Subproject 2c4d28a75c26e572b94a967901254caff83d85c +Subproject 5dc8ae302733ce1aae5b1aaa613ce77a8ae4b3d diff --git a/docs/plugins/Makefile.am b/docs/plugins/Makefile.am index f132618d..0d20ecda 100644 --- a/docs/plugins/Makefile.am +++ b/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 \ diff --git a/docs/plugins/gst-plugins-bad-plugins-docs.sgml b/docs/plugins/gst-plugins-bad-plugins-docs.sgml index 01f6d456..1ab6ad3e 100644 --- a/docs/plugins/gst-plugins-bad-plugins-docs.sgml +++ b/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" /> diff --git a/docs/plugins/gst-plugins-bad-plugins-sections.txt b/docs/plugins/gst-plugins-bad-plugins-sections.txt index 4c52bf49..0ed5d62e 100644 --- a/docs/plugins/gst-plugins-bad-plugins-sections.txt +++ b/docs/plugins/gst-plugins-bad-plugins-sections.txt @@ -1,4 +1,54 @@ <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> GstAacParse diff --git a/gst-libs/gst/app/gstappsink.c b/gst-libs/gst/app/gstappsink.c index 0079c2e9..79b1b843 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 27848080..9cf1afc3 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)); /** |