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.
This commit is contained in:
Wim Taymans 2008-12-17 13:51:46 +00:00
parent b050e06170
commit 59c80c9a40
7 changed files with 156 additions and 4 deletions

View file

@ -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> 2008-12-17 Sebastian Dröge <sebastian.droege@collabora.co.uk>
* gst/mxf/mxfdemux.c: (gst_mxf_demux_chain): * gst/mxf/mxfdemux.c: (gst_mxf_demux_chain):

2
common

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

View file

@ -113,6 +113,8 @@ EXTRA_HFILES = \
$(top_srcdir)/ext/timidity/gstwildmidi.h \ $(top_srcdir)/ext/timidity/gstwildmidi.h \
$(top_srcdir)/ext/twolame/gsttwolame.h \ $(top_srcdir)/ext/twolame/gsttwolame.h \
$(top_srcdir)/ext/x264/gstx264enc.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/aacparse/gstaacparse.h \
$(top_srcdir)/gst/amrparse/gstamrparse.h \ $(top_srcdir)/gst/amrparse/gstamrparse.h \
$(top_srcdir)/gst/audioresample/gstaudioresample.h \ $(top_srcdir)/gst/audioresample/gstaudioresample.h \

View file

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

View file

@ -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> <SECTION>
<FILE>element-aacparse</FILE> <FILE>element-aacparse</FILE>
<TITLE>aacparse</TITLE> <TITLE>aacparse</TITLE>

View file

@ -20,12 +20,43 @@
/** /**
* SECTION:element-appsink * SECTION:element-appsink
* @see_also: #GstBaseSrc * @see_also: #GstBaseSink, appsrc
* *
* Appsink is a sink plugin that supports many different methods for making * Appsink is a sink plugin that supports many different methods for making
* the application get a handle on the GStreamer data in a pipeline. * 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 #ifdef HAVE_CONFIG_H

View file

@ -20,9 +20,67 @@
/** /**
* SECTION:element-appsrc * SECTION:element-appsrc
* @see_also: #GstBaseSrc, appsink
* *
* The appsrc element can be used by applications to insert data into a * The appsrc element can be used by applications to insert data into a
* GStreamer pipeline. * 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 #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_object_class_install_property (gobject_class, PROP_SIZE,
g_param_spec_int64 ("size", "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, -1, G_MAXINT64, DEFAULT_PROP_SIZE,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)); G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
/** /**