mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-26 18:20:44 +00:00
Code Issues 1 Projects Releases Wiki Activity

Port gtk-doc comments to their equivalent markdown syntax

Browse source 
Modernizing our documentation and preparing a possible move to hotdoc.
This commits also adds missing @title metadatas to all SECTIONs
This commit is contained in:
Thibault Saunier 2017-01-16 11:26:16 -03:00
parent 76f049bc49
commit a87b4551a6
129 changed files with 822 additions and 1041 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
gst/gst.c
View file

@ -22,6 +22,7 @@
/**
* SECTION:gst
* @title: GStreamer
* @short_description: Media library supporting arbitrary formats and filter
* graphs.
*
@ -40,9 +41,9 @@
* and argv variables so that GStreamer can process its own command line
* options, as shown in the following example.
*
* <example>
* <title>Initializing the gstreamer library</title>
* <programlisting language="c">
* ## Initializing the gstreamer library
*
* |[ <!-- language="C" -->
* int
* main (int argc, char *argv[])
* {
@ -50,17 +51,16 @@
* gst_init (&amp;argc, &amp;argv);
* ...
* }
* </programlisting>
* </example>
* ]|
*
* It's allowed to pass two %NULL pointers to gst_init() in case you don't want
* to pass the command line args to GStreamer.
*
* You can also use GOption to initialize your own parameters as shown in
* the next code fragment:
* <example>
* <title>Initializing own parameters when initializing gstreamer</title>
* <programlisting>
*
* ## Initializing own parameters when initializing gstreamer
* |[ <!-- language="C" -->
* static gboolean stats = FALSE;
* ...
* int
@ -81,16 +81,14 @@
* g_option_context_free (ctx);
* ...
* }
* </programlisting>
* </example>
* ]|
*
* Use gst_version() to query the library version at runtime or use the
* GST_VERSION_* macros to find the version at compile time. Optionally
* gst_version_string() returns a printable string.
*
* The gst_deinit() call is used to clean up all internal resources used
* by <application>GStreamer</application>. It is mostly used in unit tests
* to check for leaks.
* by GStreamer. It is mostly used in unit tests to check for leaks.
*/
#include "gst_private.h"
@ -381,11 +379,9 @@ gst_init_check (int *argc, char **argv[], GError ** err)
* <link linkend="gst-running">Running GStreamer Applications</link>
* for how to disable automatic registry updates.
*
* <note><para>
* This function will terminate your program if it was unable to initialize
* GStreamer for some reason. If you want your program to fall back,
* use gst_init_check() instead.
* </para></note>
* > This function will terminate your program if it was unable to initialize
* > GStreamer for some reason. If you want your program to fall back,
* > use gst_init_check() instead.
*
* WARNING: This function does not work in the same way as corresponding
* functions in other glib-style libraries, such as gtk_init\(\). In
@ -991,7 +987,7 @@ parse_goption_arg (const gchar * opt,
* This function is therefore mostly used by testsuites and other memory
* profiling tools.
*
* After this call GStreamer (including this method) should not be used anymore.
* After this call GStreamer (including this method) should not be used anymore.
*/
void
gst_deinit (void)

1
gst/gstallocator.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gstallocator
* @title: GstAllocator
* @short_description: allocate memory blocks
* @see_also: #GstMemory
*

155
gst/gstbin.c
View file

@ -25,6 +25,7 @@
/**
* SECTION:gstbin
* @title: GstBin
* @short_description: Base class and element that can contain other elements
*
* #GstBin is an element that can contain other #GstElement, allowing them to be
@ -55,97 +56,67 @@
* the bin. Likewise the #GstBin::element-removed signal is fired whenever an
* element is removed from the bin.
*
* <refsect2><title>Notes</title>
* <para>
* ## Notes
*
* A #GstBin internally intercepts every #GstMessage posted by its children and
* implements the following default behaviour for each of them:
* <variablelist>
* <varlistentry>
* <term>GST_MESSAGE_EOS</term>
* <listitem><para>This message is only posted by sinks in the PLAYING
* state. If all sinks posted the EOS message, this bin will post and EOS
* message upwards.</para></listitem>
* </varlistentry>
* <varlistentry>
* <term>GST_MESSAGE_SEGMENT_START</term>
* <listitem><para>just collected and never forwarded upwards.
* The messages are used to decide when all elements have completed playback
* of their segment.</para></listitem>
* </varlistentry>
* <varlistentry>
* <term>GST_MESSAGE_SEGMENT_DONE</term>
* <listitem><para> Is posted by #GstBin when all elements that posted
* a SEGMENT_START have posted a SEGMENT_DONE.</para></listitem>
* </varlistentry>
* <varlistentry>
* <term>GST_MESSAGE_DURATION_CHANGED</term>
* <listitem><para> Is posted by an element that detected a change
* in the stream duration. The default bin behaviour is to clear any
* cached duration values so that the next duration query will perform
* a full duration recalculation. The duration change is posted to the
* application so that it can refetch the new duration with a duration
* query. Note that these messages can be posted before the bin is
* prerolled, in which case the duration query might fail.
* </para></listitem>
* </varlistentry>
* <varlistentry>
* <term>GST_MESSAGE_CLOCK_LOST</term>
* <listitem><para> This message is posted by an element when it
* can no longer provide a clock. The default bin behaviour is to
* check if the lost clock was the one provided by the bin. If so and
* the bin is currently in the PLAYING state, the message is forwarded to
* the bin parent.
* This message is also generated when a clock provider is removed from
* the bin. If this message is received by the application, it should
* PAUSE the pipeline and set it back to PLAYING to force a new clock
* distribution.
* </para></listitem>
* </varlistentry>
* <varlistentry>
* <term>GST_MESSAGE_CLOCK_PROVIDE</term>
* <listitem><para> This message is generated when an element
* can provide a clock. This mostly happens when a new clock
* provider is added to the bin. The default behaviour of the bin is to
* mark the currently selected clock as dirty, which will perform a clock
* recalculation the next time the bin is asked to provide a clock.
* This message is never sent tot the application but is forwarded to
* the parent of the bin.
* </para></listitem>
* </varlistentry>
* <varlistentry>
* <term>OTHERS</term>
* <listitem><para> posted upwards.</para></listitem>
* </varlistentry>
* </variablelist>
*
* * GST_MESSAGE_EOS: This message is only posted by sinks in the PLAYING
* state. If all sinks posted the EOS message, this bin will post and EOS
* message upwards.
*
* * GST_MESSAGE_SEGMENT_START: Just collected and never forwarded upwards.
* The messages are used to decide when all elements have completed playback
* of their segment.
*
* * GST_MESSAGE_SEGMENT_DONE: Is posted by #GstBin when all elements that posted
* a SEGMENT_START have posted a SEGMENT_DONE.
*
* * GST_MESSAGE_DURATION_CHANGED: Is posted by an element that detected a change
* in the stream duration. The default bin behaviour is to clear any
* cached duration values so that the next duration query will perform
* a full duration recalculation. The duration change is posted to the
* application so that it can refetch the new duration with a duration
* query. Note that these messages can be posted before the bin is
* prerolled, in which case the duration query might fail.
*
* * GST_MESSAGE_CLOCK_LOST: This message is posted by an element when it
* can no longer provide a clock. The default bin behaviour is to
* check if the lost clock was the one provided by the bin. If so and
* the bin is currently in the PLAYING state, the message is forwarded to
* the bin parent.
* This message is also generated when a clock provider is removed from
* the bin. If this message is received by the application, it should
* PAUSE the pipeline and set it back to PLAYING to force a new clock
* distribution.
*
* * GST_MESSAGE_CLOCK_PROVIDE: This message is generated when an element
* can provide a clock. This mostly happens when a new clock
* provider is added to the bin. The default behaviour of the bin is to
* mark the currently selected clock as dirty, which will perform a clock
* recalculation the next time the bin is asked to provide a clock.
* This message is never sent tot the application but is forwarded to
* the parent of the bin.
*
* * OTHERS: posted upwards.
*
* A #GstBin implements the following default behaviour for answering to a
* #GstQuery:
* <variablelist>
* <varlistentry>
* <term>GST_QUERY_DURATION</term>
* <listitem><para>If the query has been asked before with the same format
* and the bin is a toplevel bin (ie. has no parent),
* use the cached previous value. If no previous value was cached, the
* query is sent to all sink elements in the bin and the MAXIMUM of all
* values is returned. If the bin is a toplevel bin the value is cached.
* If no sinks are available in the bin, the query fails.
* </para></listitem>
* </varlistentry>
* <varlistentry>
* <term>GST_QUERY_POSITION</term>
* <listitem><para>The query is sent to all sink elements in the bin and the
* MAXIMUM of all values is returned. If no sinks are available in the bin,
* the query fails.
* </para></listitem>
* </varlistentry>
* <varlistentry>
* <term>OTHERS</term>
* <listitem><para>the query is forwarded to all sink elements, the result
* of the first sink that answers the query successfully is returned. If no
* sink is in the bin, the query fails.</para></listitem>
* </varlistentry>
* </variablelist>
*
* * GST_QUERY_DURATION:If the query has been asked before with the same format
* and the bin is a toplevel bin (ie. has no parent),
* use the cached previous value. If no previous value was cached, the
* query is sent to all sink elements in the bin and the MAXIMUM of all
* values is returned. If the bin is a toplevel bin the value is cached.
* If no sinks are available in the bin, the query fails.
*
* * GST_QUERY_POSITION:The query is sent to all sink elements in the bin and the
* MAXIMUM of all values is returned. If no sinks are available in the bin,
* the query fails.
*
* * OTHERS:the query is forwarded to all sink elements, the result
* of the first sink that answers the query successfully is returned. If no
* sink is in the bin, the query fails.
*
* A #GstBin will by default forward any event sent to it to all sink
* (#GST_EVENT_TYPE_DOWNSTREAM) or source (#GST_EVENT_TYPE_UPSTREAM) elements
@ -154,8 +125,6 @@
* is returned. If no elements of the required type are in the bin, the event
* handler will return %TRUE.
*
* </para>
* </refsect2>
*/
#include "gst_private.h"
@ -1527,13 +1496,11 @@ gst_bin_deep_element_removed_func (GstBin * bin, GstBin * sub_bin,
* If the element's pads are linked to other pads, the pads will be unlinked
* before the element is added to the bin.
*
* <note>
* When you add an element to an already-running pipeline, you will have to
* take care to set the state of the newly-added element to the desired
* state (usually PLAYING or PAUSED, same you set the pipeline to originally)
* with gst_element_set_state(), or use gst_element_sync_state_with_parent().
* The bin or pipeline will not take care of this for you.
* </note>
* > When you add an element to an already-running pipeline, you will have to
* > take care to set the state of the newly-added element to the desired
* > state (usually PLAYING or PAUSED, same you set the pipeline to originally)
* > with gst_element_set_state(), or use gst_element_sync_state_with_parent().
* > The bin or pipeline will not take care of this for you.
*
* MT safe.
*

1
gst/gstbuffer.c
View file

@ -22,6 +22,7 @@
/**
* SECTION:gstbuffer
* @title: GstBuffer
* @short_description: Data-passing buffer type
* @see_also: #GstPad, #GstMiniObject, #GstMemory, #GstMeta, #GstBufferPool
*

1
gst/gstbufferlist.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstbufferlist
* @title: GstBufferList
* @short_description: Lists of buffers for data-passing
* @see_also: #GstPad, #GstMiniObject
*

5
gst/gstbufferpool.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gstbufferpool
* @title: GstBufferPool
* @short_description: Pool for buffers
* @see_also: #GstBuffer
*
@ -1030,7 +1031,7 @@ gst_buffer_pool_config_get_params (GstStructure * config, GstCaps ** caps,
*
* Get the @allocator and @params from @config.
*
* Returns: %TRUE, if the values are set.
* Returns: %TRUE, if the values are set.
*/
gboolean
gst_buffer_pool_config_get_allocator (GstStructure * config,
@ -1160,7 +1161,7 @@ default_acquire_buffer (GstBufferPool * pool, GstBuffer ** buffer,
}
} else {
/* We're the first thread waiting, we got the wait token and have to
* write it again later
* write it again later
* OR
* We're a second thread and just consumed the flush token and block all
* other threads, in which case we must not wait and give it back

2
gst/gstbufferpool.h
View file

@ -143,7 +143,7 @@ struct _GstBufferPool {
* @release_buffer: release a buffer back in the pool. The default
* implementation will put the buffer back in the queue and notify any
* blocking acquire_buffer calls when the #GST_BUFFER_FLAG_TAG_MEMORY
* is not set on the buffer. If #GST_BUFFER_FLAG_TAG_MEMORY is set, the
* is not set on the buffer. If #GST_BUFFER_FLAG_TAG_MEMORY is set, the
* buffer will be freed with @free_buffer.
* @free_buffer: free a buffer. The default implementation unrefs the buffer.
* @flush_start: enter the flushing state. (Since 1.4)

1
gst/gstbus.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gstbus
* @title: GstBus
* @short_description: Asynchronous message bus subsystem
* @see_also: #GstMessage, #GstElement
*

5
gst/gstcaps.c
View file

@ -19,6 +19,7 @@
/**
* SECTION:gstcaps
* @title: GstCaps
* @short_description: Structure describing sets of media formats
* @see_also: #GstStructure, #GstMiniObject
*
@ -1768,8 +1769,8 @@ gst_caps_structure_subtract (GSList ** into, const GstStructure * minuend,
* @subtrahend: #GstCaps to subtract
*
* Subtracts the @subtrahend from the @minuend.
* <note>This function does not work reliably if optional properties for caps
* are included on one caps and omitted on the other.</note>
* > This function does not work reliably if optional properties for caps
* > are included on one caps and omitted on the other.
*
* Returns: (transfer full): the resulting caps
*/

3
gst/gstcapsfeatures.c
View file

@ -20,7 +20,8 @@
/**
* SECTION:gstcapsfeatures
* @short_description: A set of features in caps
* @title: GstCapsFeatures
* @short_description: A set of features in caps
* @see_also: #GstCaps
*
* #GstCapsFeatures can optionally be set on a #GstCaps to add requirements

1
gst/gstchildproxy.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gstchildproxy
* @title: GstChildProxy
* @short_description: Interface for multi child elements.
* @see_also: #GstBin
*

50
gst/gstclock.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstclock
* @title: GstClock
* @short_description: Abstract class for global clocks
* @see_also: #GstSystemClock, #GstPipeline
*
@ -74,7 +75,7 @@
* for unreffing the ids itself. This holds for both periodic and single shot
* notifications. The reason being that the owner of the #GstClockID has to
* keep a handle to the #GstClockID to unblock the wait on FLUSHING events or
* state changes and if the entry would be unreffed automatically, the handle
* state changes and if the entry would be unreffed automatically, the handle
* might become invalid without any notification.
*
* These clock operations do not operate on the running time, so the callbacks
@ -90,7 +91,7 @@
* plugins that have an internal clock but must operate with another clock
* selected by the #GstPipeline. They can track the offset and rate difference
* of their internal clock relative to the master clock by using the
* gst_clock_get_calibration() function.
* gst_clock_get_calibration() function.
*
* The master/slave synchronisation can be tuned with the #GstClock:timeout,
* #GstClock:window-size and #GstClock:window-threshold properties.
@ -490,23 +491,23 @@ gst_clock_id_get_time (GstClockID id)
* @jitter: (out) (allow-none): a pointer that will contain the jitter,
* can be %NULL.
*
* Perform a blocking wait on @id.
* Perform a blocking wait on @id.
* @id should have been created with gst_clock_new_single_shot_id()
* or gst_clock_new_periodic_id() and should not have been unscheduled
* with a call to gst_clock_id_unschedule().
* with a call to gst_clock_id_unschedule().
*
* If the @jitter argument is not %NULL and this function returns #GST_CLOCK_OK
* or #GST_CLOCK_EARLY, it will contain the difference
* against the clock and the time of @id when this method was
* called.
* called.
* Positive values indicate how late @id was relative to the clock
* (in which case this function will return #GST_CLOCK_EARLY).
* Negative values indicate how much time was spent waiting on the clock
* (in which case this function will return #GST_CLOCK_EARLY).
* Negative values indicate how much time was spent waiting on the clock
* before this function returned.
*
* Returns: the result of the blocking wait. #GST_CLOCK_EARLY will be returned
* if the current clock time is past the time of @id, #GST_CLOCK_OK if
* @id was scheduled in time. #GST_CLOCK_UNSCHEDULED if @id was
* if the current clock time is past the time of @id, #GST_CLOCK_OK if
* @id was scheduled in time. #GST_CLOCK_UNSCHEDULED if @id was
* unscheduled with gst_clock_id_unschedule().
*
* MT safe.
@ -1101,7 +1102,7 @@ gst_clock_get_time (GstClock * clock)
* @internal: a reference internal time
* @external: a reference external time
* @rate_num: the numerator of the rate of the clock relative to its
* internal time
* internal time
* @rate_denom: the denominator of the rate of the clock
*
* Adjusts the rate and time of @clock. A rate of 1/1 is the normal speed of
@ -1115,9 +1116,9 @@ gst_clock_get_time (GstClock * clock)
* Subsequent calls to gst_clock_get_time() will return clock times computed as
* follows:
*
* <programlisting>
* |[
* time = (internal_time - internal) * rate_num / rate_denom + external
* </programlisting>
* ]|
*
* This formula is implemented in gst_clock_adjust_unlocked(). Of course, it
* tries to do the integer arithmetic as precisely as possible.
@ -1156,7 +1157,7 @@ gst_clock_set_calibration (GstClock * clock, GstClockTime internal, GstClockTime
/**
* gst_clock_get_calibration:
* @clock: a #GstClock
* @clock: a #GstClock
* @internal: (out) (allow-none): a location to store the internal time
* @external: (out) (allow-none): a location to store the external time
* @rate_num: (out) (allow-none): a location to store the rate numerator
@ -1226,22 +1227,22 @@ gst_clock_slave_callback (GstClock * master, GstClockTime time,
/**
* gst_clock_set_master:
* @clock: a #GstClock
* @master: (allow-none): a master #GstClock
* @clock: a #GstClock
* @master: (allow-none): a master #GstClock
*
* Set @master as the master clock for @clock. @clock will be automatically
* calibrated so that gst_clock_get_time() reports the same time as the
* master clock.
*
* master clock.
*
* A clock provider that slaves its clock to a master can get the current
* calibration values with gst_clock_get_calibration().
*
* @master can be %NULL in which case @clock will not be slaved anymore. It will
* however keep reporting its time adjusted with the last configured rate
* however keep reporting its time adjusted with the last configured rate
* and time offsets.
*
* Returns: %TRUE if the clock is capable of being slaved to a master clock.
* Trying to set a master on a clock without the
* Returns: %TRUE if the clock is capable of being slaved to a master clock.
* Trying to set a master on a clock without the
* #GST_CLOCK_FLAG_CAN_SET_MASTER flag will make this function return %FALSE.
*
* MT safe.
@ -1314,7 +1315,7 @@ master_not_synced:
/**
* gst_clock_get_master:
* @clock: a #GstClock
* @clock: a #GstClock
*
* Get the master clock that @clock is slaved to or %NULL when the clock is
* not slaved to any master clock.
@ -1345,7 +1346,7 @@ gst_clock_get_master (GstClock * clock)
/**
* gst_clock_add_observation:
* @clock: a #GstClock
* @clock: a #GstClock
* @slave: a time on the slave
* @master: a time on the master
* @r_squared: (out): a pointer to hold the result
@ -1355,13 +1356,13 @@ gst_clock_get_master (GstClock * clock)
* are available, a linear regression algorithm is run on the
* observations and @clock is recalibrated.
*
* If this functions returns %TRUE, @r_squared will contain the
* If this functions returns %TRUE, @r_squared will contain the
* correlation coefficient of the interpolation. A value of 1.0
* means a perfect regression was performed. This value can
* be used to control the sampling frequency of the master and slave
* clocks.
*
* Returns: %TRUE if enough observations were added to run the
* Returns: %TRUE if enough observations were added to run the
* regression algorithm.
*
* MT safe.
@ -1588,7 +1589,6 @@ gst_clock_get_property (GObject * object, guint prop_id,
*
* For asynchronous waiting, the GstClock::synced signal can be used.
*
*
* This returns immediately with TRUE if GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC
* is not set on the clock, or if the clock is already synced.
*

6
gst/gstclock.h
View file

@ -176,9 +176,9 @@ typedef gpointer GstClockID;
*
* Convert a #GstClockTime to a #GTimeVal
*
* <note>on 32-bit systems, a timeval has a range of only 2^32 - 1 seconds,
* which is about 68 years. Expect trouble if you want to schedule stuff
* in your pipeline for 2038.</note>
* > on 32-bit systems, a timeval has a range of only 2^32 - 1 seconds,
* > which is about 68 years. Expect trouble if you want to schedule stuff
* > in your pipeline for 2038.
*/
#define GST_TIME_TO_TIMEVAL(t,tv) \
G_STMT_START { \

1
gst/gstcompat.h
View file

@ -25,6 +25,7 @@
#define __GSTCOMPAT_H__
/**
* SECTION:gstcompat
* @title: GstCompat
* @short_description: Deprecated API entries
*
* Please do not use these in new code.

1
gst/gstcontext.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstcontext
* @title: GstContext
* @short_description: Lightweight objects to represent element contexts
* @see_also: #GstMiniObject, #GstElement
*

3
gst/gstcontrolbinding.c
View file

@ -21,6 +21,7 @@
*/
/**
* SECTION:gstcontrolbinding
* @title: GstControlBinding
* @short_description: attachment for control source sources
*
* A base class for value mapping objects that attaches control sources to gobject
@ -321,7 +322,7 @@ gst_control_binding_get_value (GstControlBinding * binding,
* This function is useful if one wants to e.g. draw a graph of the control
* curve or apply a control curve sample by sample.
*
* The values are unboxed and ready to be used. The similar function
* The values are unboxed and ready to be used. The similar function
* gst_control_binding_get_g_value_array() returns the array as #GValues and is
* more suitable for bindings.
*

1
gst/gstcontrolsource.c
View file

@ -22,6 +22,7 @@
/**
* SECTION:gstcontrolsource
* @title: GstControlSource
* @short_description: base class for control source sources
*
* The #GstControlSource is a base class for control value sources that could

4
gst/gstdebugutils.h
View file

@ -74,9 +74,9 @@ void gst_debug_bin_to_dot_file_with_ts (GstBin *bin, GstDebugGraphDetails detail
* To aid debugging applications one can use this method to write out the whole
* network of gstreamer elements that form the pipeline into an dot file.
* This file can be processed with graphviz to get an image, like this:
* <informalexample><programlisting>
* |[
* dot -Tpng -oimage.png graph_lowlevel.dot
* </programlisting></informalexample>
* ]|
* There is also a utility called xdot which allows you to view the dot file
* directly without converting it first.
*

1
gst/gstdevice.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gstdevice
* @title: GstDevice
* @short_description: Object representing a device
* @see_also: #GstDeviceProvider
*

2
gst/gstdevicemonitor.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gstdevicemonitor
* @title: GstDeviceMonitor
* @short_description: A device monitor and prober
* @see_also: #GstDevice, #GstDeviceProvider
*
@ -34,7 +35,6 @@
* The device monitor will monitor all devices matching the filters that
* the application has set.
*
*
* The basic use pattern of a device monitor is as follows:
* |[
* static gboolean

7
gst/gstdeviceprovider.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gstdeviceprovider
* @title: GstDeviceProvider
* @short_description: A device provider
* @see_also: #GstDevice, #GstDeviceMonitor
*
@ -252,7 +253,8 @@ gst_device_provider_class_add_static_metadata (GstDeviceProviderClass * klass,
* multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;"
*
* Sets the detailed information for a #GstDeviceProviderClass.
* <note>This function is for use in _class_init functions only.</note>
*
* > This function is for use in _class_init functions only.
*
* Since: 1.4
*/
@ -288,7 +290,8 @@ gst_device_provider_class_set_metadata (GstDeviceProviderClass * klass,
* foo.com&gt;"
*
* Sets the detailed information for a #GstDeviceProviderClass.
* <note>This function is for use in _class_init functions only.</note>
*
* > This function is for use in _class_init functions only.
*
* Same as gst_device_provider_class_set_metadata(), but @longname, @classification,
* @description, and @author must be static strings or inlined strings, as

1
gst/gstdeviceproviderfactory.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstdeviceproviderfactory
* @title: GstDeviceProviderFactory
* @short_description: Create GstDeviceProviders from a factory
* @see_also: #GstDeviceProvider, #GstPlugin, #GstPluginFeature, #GstPadTemplate.
*

10
gst/gstdynamictypefactory.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gstdynamictypefactory
* @title: GstDynamicTypeFactory
* @short_description: Represents a registered dynamically loadable GType
* @see_also: #GstPlugin, #GstPluginFeature.
*
@ -33,17 +34,16 @@
* done, the type is stored in the registry, and ready as soon as the
* registry is loaded.
*
* <example>
* <title>Registering a type for dynamic loading</title>
* <programlisting language="c">
* ## Registering a type for dynamic loading
*
* |[<!-- language="C" -->
*
* static gboolean
* plugin_init (GstPlugin * plugin)
* {
* return gst_dynamic_type_register (plugin, GST_TYPE_CUSTOM_CAPS_FIELD);
* }
* </programlisting>
* </example>
* ]|
*/
#ifdef HAVE_CONFIG_H

22
gst/gstelement.c
View file

@ -22,6 +22,7 @@
/**
* SECTION:gstelement
* @title: GstElement
* @short_description: Abstract base class for all pipeline elements
* @see_also: #GstElementFactory, #GstPad
*
@ -362,8 +363,8 @@ gst_element_release_request_pad (GstElement * element, GstPad * pad)
* @element: a #GstElement to query
*
* Get the clock provided by the given element.
* <note>An element is only required to provide a clock in the PAUSED
* state. Some elements can provide a clock in other states.</note>
* > An element is only required to provide a clock in the PAUSED
* > state. Some elements can provide a clock in other states.
*
* Returns: (transfer full) (nullable): the GstClock provided by the
* element or %NULL if no clock could be provided. Unref after usage.
@ -1365,7 +1366,7 @@ gst_element_class_add_static_metadata (GstElementClass * klass,
* multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;"
*
* Sets the detailed information for a #GstElementClass.
* <note>This function is for use in _class_init functions only.</note>
* > This function is for use in _class_init functions only.
*/
void
gst_element_class_set_metadata (GstElementClass * klass,
@ -1398,7 +1399,8 @@ gst_element_class_set_metadata (GstElementClass * klass,
* multiple author metadata. E.g: "Joe Bloggs &lt;joe.blogs at foo.com&gt;"
*
* Sets the detailed information for a #GstElementClass.
* <note>This function is for use in _class_init functions only.</note>
*
* > This function is for use in _class_init functions only.
*
* Same as gst_element_class_set_metadata(), but @longname, @classification,
* @description, and @author must be static strings or inlined strings, as
@ -1459,9 +1461,9 @@ gst_element_class_get_metadata (GstElementClass * klass, const gchar * key)
*
* Retrieves a list of the pad templates associated with @element_class. The
* list must not be modified by the calling code.
* <note>If you use this function in the #GInstanceInitFunc of an object class
* that has subclasses, make sure to pass the g_class parameter of the
* #GInstanceInitFunc here.</note>
* > If you use this function in the #GInstanceInitFunc of an object class
* > that has subclasses, make sure to pass the g_class parameter of the
* > #GInstanceInitFunc here.
*
* Returns: (transfer none) (element-type Gst.PadTemplate): the #GList of
* pad templates.
@ -1480,9 +1482,9 @@ gst_element_class_get_pad_template_list (GstElementClass * element_class)
* @name: the name of the #GstPadTemplate to get.
*
* Retrieves a padtemplate from @element_class with the given name.
* <note>If you use this function in the #GInstanceInitFunc of an object class
* that has subclasses, make sure to pass the g_class parameter of the
* #GInstanceInitFunc here.</note>
* > If you use this function in the #GInstanceInitFunc of an object class
* > that has subclasses, make sure to pass the g_class parameter of the
* > #GInstanceInitFunc here.
*
* Returns: (transfer none) (nullable): the #GstPadTemplate with the
* given name, or %NULL if none was found. No unreferencing is

148
gst/gstelement.h
View file

@ -176,126 +176,74 @@ typedef enum {
/**
* GstStateChange:
* @GST_STATE_CHANGE_NULL_TO_READY : state change from NULL to READY.
* <itemizedlist>
* <listitem><para>
* The element must check if the resources it needs are available. Device
* #GST_STATE_CHANGE_NULL_TO_READY : state change from NULL to READY.
*
* * The element must check if the resources it needs are available. Device
* sinks and -sources typically try to probe the device to constrain their
* caps.
* </para></listitem>
* <listitem><para>
* The element opens the device (in case feature need to be probed).
* </para></listitem>
* </itemizedlist>
* @GST_STATE_CHANGE_READY_TO_PAUSED : state change from READY to PAUSED.
* <itemizedlist>
* <listitem><para>
* The element pads are activated in order to receive data in PAUSED.
* * The element opens the device (in case feature need to be probed).
*
* #GST_STATE_CHANGE_READY_TO_PAUSED : state change from READY to PAUSED.
*
* * The element pads are activated in order to receive data in PAUSED.
* Streaming threads are started.
* </para></listitem>
* <listitem><para>
* Some elements might need to return %GST_STATE_CHANGE_ASYNC and complete
* * Some elements might need to return %GST_STATE_CHANGE_ASYNC and complete
* the state change when they have enough information. It is a requirement
* for sinks to return %GST_STATE_CHANGE_ASYNC and complete the state change
* when they receive the first buffer or %GST_EVENT_EOS (preroll).
* Sinks also block the dataflow when in PAUSED.
* </para></listitem>
* <listitem><para>
* A pipeline resets the running_time to 0.
* </para></listitem>
* <listitem><para>
* Live sources return %GST_STATE_CHANGE_NO_PREROLL and don't generate data.
* </para></listitem>
* </itemizedlist>
* @GST_STATE_CHANGE_PAUSED_TO_PLAYING: state change from PAUSED to PLAYING.
* <itemizedlist>
* <listitem><para>
* Most elements ignore this state change.
* </para></listitem>
* <listitem><para>
* The pipeline selects a #GstClock and distributes this to all the children
* * A pipeline resets the running_time to 0.
*
* * Live sources return %GST_STATE_CHANGE_NO_PREROLL and don't generate data.
*
* #GST_STATE_CHANGE_PAUSED_TO_PLAYING: state change from PAUSED to PLAYING.
*
* * Most elements ignore this state change.
* * The pipeline selects a #GstClock and distributes this to all the children
* before setting them to PLAYING. This means that it is only allowed to
* synchronize on the #GstClock in the PLAYING state.
* </para></listitem>
* <listitem><para>
* The pipeline uses the #GstClock and the running_time to calculate the
* * The pipeline uses the #GstClock and the running_time to calculate the
* base_time. The base_time is distributed to all children when performing
* the state change.
* </para></listitem>
* <listitem><para>
* Sink elements stop blocking on the preroll buffer or event and start
* * Sink elements stop blocking on the preroll buffer or event and start
* rendering the data.
* </para></listitem>
* <listitem><para>
* Sinks can post %GST_MESSAGE_EOS in the PLAYING state. It is not allowed
* * Sinks can post %GST_MESSAGE_EOS in the PLAYING state. It is not allowed
* to post %GST_MESSAGE_EOS when not in the PLAYING state.
* </para></listitem>
* <listitem><para>
* While streaming in PAUSED or PLAYING elements can create and remove
* * While streaming in PAUSED or PLAYING elements can create and remove
* sometimes pads.
* </para></listitem>
* <listitem><para>
* Live sources start generating data and return %GST_STATE_CHANGE_SUCCESS.
* </para></listitem>
* </itemizedlist>
* @GST_STATE_CHANGE_PLAYING_TO_PAUSED: state change from PLAYING to PAUSED.
* <itemizedlist>
* <listitem><para>
* Most elements ignore this state change.
* </para></listitem>
* <listitem><para>
* The pipeline calculates the running_time based on the last selected
* * Live sources start generating data and return %GST_STATE_CHANGE_SUCCESS.
*
* #GST_STATE_CHANGE_PLAYING_TO_PAUSED: state change from PLAYING to PAUSED.
*
* * Most elements ignore this state change.
* * The pipeline calculates the running_time based on the last selected
* #GstClock and the base_time. It stores this information to continue
* playback when going back to the PLAYING state.
* </para></listitem>
* <listitem><para>
* Sinks unblock any #GstClock wait calls.
* </para></listitem>
* <listitem><para>
* When a sink does not have a pending buffer to play, it returns
* %GST_STATE_CHANGE_ASYNC from this state change and completes the state
*
* * Sinks unblock any #GstClock wait calls.
* * When a sink does not have a pending buffer to play, it returns
* #GST_STATE_CHANGE_ASYNC from this state change and completes the state
* change when it receives a new buffer or an %GST_EVENT_EOS.
* </para></listitem>
* <listitem><para>
* Any queued %GST_MESSAGE_EOS items are removed since they will be reposted
* * Any queued %GST_MESSAGE_EOS items are removed since they will be reposted
* when going back to the PLAYING state. The EOS messages are queued in
* #GstBin containers.
* </para></listitem>
* <listitem><para>
* Live sources stop generating data and return %GST_STATE_CHANGE_NO_PREROLL.
* </para></listitem>
* </itemizedlist>
* @GST_STATE_CHANGE_PAUSED_TO_READY : state change from PAUSED to READY.
* <itemizedlist>
* <listitem><para>
* Sinks unblock any waits in the preroll.
* </para></listitem>
* <listitem><para>
* Elements unblock any waits on devices
* </para></listitem>
* <listitem><para>
* Chain or get_range functions return %GST_FLOW_FLUSHING.
* </para></listitem>
* <listitem><para>
* The element pads are deactivated so that streaming becomes impossible and
*
* * Live sources stop generating data and return %GST_STATE_CHANGE_NO_PREROLL.
*
* #GST_STATE_CHANGE_PAUSED_TO_READY : state change from PAUSED to READY.
*
* * Sinks unblock any waits in the preroll.
* * Elements unblock any waits on devices
* * Chain or get_range functions return %GST_FLOW_FLUSHING.
* * The element pads are deactivated so that streaming becomes impossible and
* all streaming threads are stopped.
* </para></listitem>
* <listitem><para>
* The sink forgets all negotiated formats
* </para></listitem>
* <listitem><para>
* Elements remove all sometimes pads
* </para></listitem>
* </itemizedlist>
* @GST_STATE_CHANGE_READY_TO_NULL : state change from READY to NULL.
* <itemizedlist>
* <listitem><para>
* Elements close devices
* </para></listitem>
* <listitem><para>
* Elements reset any internal state.
* </para></listitem>
* </itemizedlist>
* * The sink forgets all negotiated formats
* * Elements remove all sometimes pads
*
* #GST_STATE_CHANGE_READY_TO_NULL : state change from READY to NULL.
*
* * Elements close devices
* * Elements reset any internal state.
*
* These are the different state changes an element goes through.
* %GST_STATE_NULL &rArr; %GST_STATE_PLAYING is called an upwards state change

9
gst/gstelementfactory.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstelementfactory
* @title: GstElementFactory
* @short_description: Create GstElements from a factory
* @see_also: #GstElement, #GstPlugin, #GstPluginFeature, #GstPadTemplate.
*
@ -36,9 +37,8 @@
*
* The following code example shows you how to create a GstFileSrc element.
*
* <example>
* <title>Using an element factory</title>
* <programlisting language="c">
* ## Using an element factory
* |[<!-- language="C" -->
* #include &lt;gst/gst.h&gt;
*
* GstElement *src;
@ -51,8 +51,7 @@
* src = gst_element_factory_create (srcfactory, "src");
* g_return_if_fail (src != NULL);
* ...
* </programlisting>
* </example>
* ]|
*/
#include "gst_private.h"

30
gst/gsterror.c
View file

@ -19,6 +19,7 @@
/**
* SECTION:gsterror
* @title: GstError
* @short_description: Categorized error messages
* @see_also: #GstMessage
*
@ -66,34 +67,33 @@
*
* Elements throw errors using the #GST_ELEMENT_ERROR convenience macro:
*
* <example>
* <title>Throwing an error</title>
* <programlisting>
* ## Throwing an error
*
* |[
* GST_ELEMENT_ERROR (src, RESOURCE, NOT_FOUND,
* (_("No file name specified for reading.")), (NULL));
* </programlisting>
* </example>
* ]|
*
* Things to keep in mind:
* <itemizedlist>
* <listitem><para>Don't go off inventing new error codes. The ones
*
* * Don't go off inventing new error codes. The ones
* currently provided should be enough. If you find your type of error
* does not fit the current codes, you should use FAILED.</para></listitem>
* <listitem><para>Don't provide a message if the default one suffices.
* does not fit the current codes, you should use FAILED.
* * Don't provide a message if the default one suffices.
* this keeps messages more uniform. Use (%NULL) - not forgetting the
* parentheses.</para></listitem>
* <listitem><para>If you do supply a custom message, it should be
* parentheses.
* * If you do supply a custom message, it should be
* marked for translation. The message should start with a capital
* and end with a period. The message should describe the error in short,
* in a human-readable form, and without any complex technical terms.
* A user interface will present this message as the first thing a user
* sees. Details, technical info, ... should go in the debug string.
* </para></listitem>
* <listitem><para>The debug string can be as you like. Again, use (%NULL)
*
* * The debug string can be as you like. Again, use (%NULL)
* if there's nothing to add - file and line number will still be
* passed. #GST_ERROR_SYSTEM can be used as a shortcut to give
* debug information on a system call error.</para></listitem>
* </itemizedlist>
* debug information on a system call error.
*
*/
/* FIXME 2.0: the entire error system needs an overhaul - it's not very

17
gst/gstevent.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstevent
* @title: GstEvent
* @short_description: Structure describing events that are passed up and down
* a pipeline
* @see_also: #GstPad, #GstElement
@ -57,8 +58,8 @@
* ...
* // construct a seek event to play the media from second 2 to 5, flush
* // the pipeline to decrease latency.
* event = gst_event_new_seek (1.0,
* GST_FORMAT_TIME,
* event = gst_event_new_seek (1.0,
* GST_FORMAT_TIME,
* GST_SEEK_FLAG_FLUSH,
* GST_SEEK_TYPE_SET, 2 * GST_SECOND,
* GST_SEEK_TYPE_SET, 5 * GST_SECOND);
@ -589,7 +590,7 @@ gst_event_parse_flush_stop (GstEvent * event, gboolean * reset_time)
*
* The list of @streams corresponds to the "Stream ID" of each stream to be
* activated. Those ID can be obtained via the #GstStream objects present
* in #GST_EVENT_STREAM_START, #GST_EVENT_STREAM_COLLECTION or
* in #GST_EVENT_STREAM_START, #GST_EVENT_STREAM_COLLECTION or
* #GST_MESSSAGE_STREAM_COLLECTION.
*
* Returns: (transfer full): a new select-streams event.
@ -1089,7 +1090,7 @@ gst_event_parse_buffer_size (GstEvent * event, GstFormat * format,
* @type indicates the reason for the QoS event. #GST_QOS_TYPE_OVERFLOW is
* used when a buffer arrived in time or when the sink cannot keep up with
* the upstream datarate. #GST_QOS_TYPE_UNDERFLOW is when the sink is not
* receiving buffers fast enough and thus has to drop late buffers.
* receiving buffers fast enough and thus has to drop late buffers.
* #GST_QOS_TYPE_THROTTLE is used when the datarate is artificially limited
* by the application, for example to reduce power consumption.
*
@ -1229,15 +1230,15 @@ gst_event_parse_qos (GstEvent * event, GstQOSType * type,
*
* A pipeline has a default playback segment configured with a start
* position of 0, a stop position of -1 and a rate of 1.0. The currently
* configured playback segment can be queried with #GST_QUERY_SEGMENT.
* configured playback segment can be queried with #GST_QUERY_SEGMENT.
*
* @start_type and @stop_type specify how to adjust the currently configured
* @start_type and @stop_type specify how to adjust the currently configured
* start and stop fields in playback segment. Adjustments can be made relative
* or absolute to the last configured values. A type of #GST_SEEK_TYPE_NONE
* means that the position should not be updated.
*
* When the rate is positive and @start has been updated, playback will start
* from the newly configured start position.
* from the newly configured start position.
*
* For negative rates, playback will start from the newly configured stop
* position (if any). If the stop position is updated, it must be different from
@ -1641,7 +1642,7 @@ gst_event_parse_stream_start (GstEvent * event, const gchar ** stream_id)
* @event: a stream-start event
* @stream: (transfer none): the stream object to set
*
* Set the @stream on the stream-start @event
* Set the @stream on the stream-start @event
*
* Since: 1.10
*/

1
gst/gstformat.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstformat
* @title: GstFormat
* @short_description: Dynamically register new data formats
* @see_also: #GstPad, #GstElement
*

1
gst/gstghostpad.c
View file

@ -24,6 +24,7 @@
/**
* SECTION:gstghostpad
* @title: GstGhostPad
* @short_description: Pseudo link pads
* @see_also: #GstPad
*

13
gst/gstinfo.c
View file

@ -24,6 +24,7 @@
/**
* SECTION:gstinfo
* @title: GstInfo
* @short_description: Debugging and logging facilities
* @see_also: #gst-running for command line parameters
* and environment variables that affect the debugging output.
@ -1524,8 +1525,8 @@ gst_debug_get_color_mode (void)
* If activated, debugging messages are sent to the debugging
* handlers.
* It makes sense to deactivate it for speed issues.
* <note><para>This function is not threadsafe. It makes sense to only call it
* during initialization.</para></note>
* > This function is not threadsafe. It makes sense to only call it
* during initialization.
*/
void
gst_debug_set_active (gboolean active)
@ -1761,11 +1762,9 @@ gst_debug_category_free (GstDebugCategory * category)
* Sets the threshold of the category to the given level. Debug information will
* only be output if the threshold is lower or equal to the level of the
* debugging message.
* <note><para>
* Do not use this function in production code, because other functions may
* change the threshold of categories as side effect. It is however a nice
* function to use when debugging (even from gdb).
* </para></note>
* > Do not use this function in production code, because other functions may
* > change the threshold of categories as side effect. It is however a nice
* > function to use when debugging (even from gdb).
*/
void
gst_debug_category_set_threshold (GstDebugCategory * category,

42
gst/gstinfo.h
View file

@ -482,30 +482,24 @@ G_STMT_START{ \
* Initializes a new #GstDebugCategory with the given properties and set to
* the default threshold.
*
* <note>
* <para>
* This macro expands to nothing if debugging is disabled.
* </para>
* <para>
* When naming your category, please follow the following conventions to ensure
* that the pattern matching for categories works as expected. It is not
* earth-shattering if you don't follow these conventions, but it would be nice
* for everyone.
* </para>
* <para>
* If you define a category for a plugin or a feature of it, name the category
* like the feature. So if you wanted to write a "filesrc" element, you would
* name the category "filesrc". Use lowercase letters only.
* If you define more than one category for the same element, append an
* underscore and an identifier to your categories, like this: "filesrc_cache"
* </para>
* <para>
* If you create a library or an application using debugging categories, use a
* common prefix followed by an underscore for all your categories. GStreamer
* uses the GST prefix so GStreamer categories look like "GST_STATES". Be sure
* to include uppercase letters.
* </para>
* </note>
* > This macro expands to nothing if debugging is disabled.
* >
* > When naming your category, please follow the following conventions to ensure
* > that the pattern matching for categories works as expected. It is not
* > earth-shattering if you don't follow these conventions, but it would be nice
* > for everyone.
* >
* > If you define a category for a plugin or a feature of it, name the category
* > like the feature. So if you wanted to write a "filesrc" element, you would
* > name the category "filesrc". Use lowercase letters only.
* > If you define more than one category for the same element, append an
* > underscore and an identifier to your categories, like this: "filesrc_cache"
* >
* > If you create a library or an application using debugging categories, use a
* > common prefix followed by an underscore for all your categories. GStreamer
* > uses the GST prefix so GStreamer categories look like "GST_STATES". Be sure
* > to include uppercase letters.
*
*/
#define GST_DEBUG_CATEGORY_INIT(cat,name,color,description) G_STMT_START{\
if (cat == NULL) \

7
gst/gstiterator.c
View file

@ -22,6 +22,7 @@
/**
* SECTION:gstiterator
* @title: GstIterator
* @short_description: Object to retrieve multiple elements in a threadsafe
* way.
* @see_also: #GstElement, #GstBin
@ -227,7 +228,7 @@ gst_list_iterator_free (GstListIterator * it)
* Create a new iterator designed for iterating @list.
*
* The list you iterate is usually part of a data structure @owner and is
* protected with @lock.
* protected with @lock.
*
* The iterator will use @lock to retrieve the next item of the list and it
* will then call the @item function before releasing @lock again.
@ -296,7 +297,7 @@ gst_iterator_pop (GstIterator * it)
* @it: The #GstIterator to iterate
* @elem: (out caller-allocates): pointer to hold next element
*
* Get the next item from the iterator in @elem.
* Get the next item from the iterator in @elem.
*
* Only when this function returns %GST_ITERATOR_OK, @elem will contain a valid
* value. @elem must have been initialized to the type of the iterator or
@ -309,7 +310,7 @@ gst_iterator_pop (GstIterator * it)
*
* A return value of %GST_ITERATOR_RESYNC indicates that the element list was
* concurrently updated. The user of @it should call gst_iterator_resync() to
* get the newly updated list.
* get the newly updated list.
*
* A return value of %GST_ITERATOR_ERROR indicates an unrecoverable fatal error.
*

1
gst/gstmemory.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gstmemory
* @title: GstMemory
* @short_description: refcounted wrapper for memory blocks
* @see_also: #GstBuffer
*

21
gst/gstmessage.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gstmessage
* @title: GstMessage
* @short_description: Lightweight objects to signal the application of
* pipeline events
* @see_also: #GstBus, #GstMiniObject, #GstElement
@ -1195,7 +1196,7 @@ gst_message_has_name (GstMessage * message, const gchar * name)
* switch (GST_MESSAGE_TYPE (msg)) {
* case GST_MESSAGE_TAG: {
* GstTagList *tags = NULL;
*
*
* gst_message_parse_tag (msg, &amp;tags);
* g_print ("Got tags from element %s\n", GST_OBJECT_NAME (msg->src));
* handle_tags (tags);
@ -1245,7 +1246,7 @@ gst_message_parse_buffering (GstMessage * message, gint * percent)
/**
* gst_message_set_buffering_stats:
* @message: A valid #GstMessage of type GST_MESSAGE_BUFFERING.
* @mode: a buffering mode
* @mode: a buffering mode
* @avg_in: the average input rate
* @avg_out: the average output rate
* @buffering_left: amount of buffering time left in milliseconds
@ -1318,7 +1319,7 @@ gst_message_parse_buffering_stats (GstMessage * message,
* switch (GST_MESSAGE_TYPE (msg)) {
* case GST_MESSAGE_STATE_CHANGED: {
* GstState old_state, new_state;
*
*
* gst_message_parse_state_changed (msg, &amp;old_state, &amp;new_state, NULL);
* g_print ("Element %s changed state from %s to %s.\n",
* GST_OBJECT_NAME (msg->src),
@ -1506,7 +1507,7 @@ gst_message_parse_structure_change (GstMessage * message,
* case GST_MESSAGE_ERROR: {
* GError *err = NULL;
* gchar *dbg_info = NULL;
*
*
* gst_message_parse_error (msg, &amp;err, &amp;dbg_info);
* g_printerr ("ERROR from element %s: %s\n",
* GST_OBJECT_NAME (msg->src), err->message);
@ -1696,7 +1697,7 @@ gst_message_parse_request_state (GstMessage * message, GstState * state)
*
* Create a new stream status message. This message is posted when a streaming
* thread is created/destroyed or when the state changed.
*
*
* Returns: (transfer full): the new stream status message.
*
* MT safe.
@ -1886,7 +1887,7 @@ gst_message_parse_step_done (GstMessage * message, GstFormat * format,
* @intermediate: is this an intermediate step
*
* This message is posted by elements when they accept or activate a new step
* event for @amount in @format.
* event for @amount in @format.
*
* @active is set to %FALSE when the element accepted the new step event and has
* queued it for execution in the streaming threads.
@ -1896,7 +1897,7 @@ gst_message_parse_step_done (GstMessage * message, GstFormat * format,
* message is emitted, the application can queue a new step operation in the
* element.
*
* Returns: (transfer full): The new step_start message.
* Returns: (transfer full): The new step_start message.
*
* MT safe.
*/
@ -2577,7 +2578,7 @@ gst_message_new_device_added (GstObject * src, GstDevice * device)
* @message: a #GstMessage of type %GST_MESSAGE_DEVICE_ADDED
* @device: (out) (allow-none) (transfer full): A location where to store a
* pointer to the new #GstDevice, or %NULL
*
*
* Parses a device-added message. The device-added message is produced by
* #GstDeviceProvider or a #GstDeviceMonitor. It announces the appearance
* of monitored devices.
@ -2755,7 +2756,7 @@ gst_message_new_stream_collection (GstObject * src,
* @collection: (out) (allow-none) (transfer full): A location where to store a
* pointer to the #GstStreamCollection, or %NULL
*
* Parses a stream-collection message.
* Parses a stream-collection message.
*
* Since: 1.10
*/
@ -2903,7 +2904,7 @@ gst_message_streams_selected_get_stream (GstMessage * msg, guint idx)
* @collection: (out) (allow-none) (transfer full): A location where to store a
* pointer to the #GstStreamCollection, or %NULL
*
* Parses a streams-selected message.
* Parses a streams-selected message.
*
* Since: 1.10
*/

1
gst/gstmeta.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gstmeta
* @title: GstMeta
* @short_description: Buffer metadata
*
* The #GstMeta structure should be included as the first member of a #GstBuffer

1
gst/gstminiobject.c
View file

@ -20,6 +20,7 @@
*/
/**
* SECTION:gstminiobject
* @title: GstMiniObject
* @short_description: Lightweight base class for the GStreamer object hierarchy
*
* #GstMiniObject is a simple structure that can be used to implement refcounted

45
gst/gstobject.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstobject
* @title: GstObject
* @short_description: Base class for the GStreamer object hierarchy
*
* #GstObject provides a root for the object hierarchy tree filed in by the
@ -42,9 +43,8 @@
* gst_object_set_name() and gst_object_get_name() are used to set/get the name
* of the object.
*
* <refsect2>
* <title>controlled properties</title>
* <para>
* ## controlled properties
*
* Controlled properties offers a lightweight way to adjust gobject properties
* over stream-time. It works by using time-stamped value pairs that are queued
* for element-properties. At run-time the elements continuously pull value
@ -52,42 +52,29 @@
*
* What needs to be changed in a #GstElement?
* Very little - it is just two steps to make a plugin controllable!
* <orderedlist>
* <listitem><para>
* mark gobject-properties paramspecs that make sense to be controlled,
*
* * mark gobject-properties paramspecs that make sense to be controlled,
* by GST_PARAM_CONTROLLABLE.
* </para></listitem>
* <listitem><para>
* when processing data (get, chain, loop function) at the beginning call
*
* * when processing data (get, chain, loop function) at the beginning call
* gst_object_sync_values(element,timestamp).
* This will make the controller update all GObject properties that are
* under its control with the current values based on the timestamp.
* </para></listitem>
* </orderedlist>
*
* What needs to be done in applications?
* Again it's not a lot to change.
* <orderedlist>
* <listitem><para>
* create a #GstControlSource.
* What needs to be done in applications? Again it's not a lot to change.
*
* * create a #GstControlSource.
* csource = gst_interpolation_control_source_new ();
* g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL);
* </para></listitem>
* <listitem><para>
* Attach the #GstControlSource on the controller to a property.
*
* * Attach the #GstControlSource on the controller to a property.
* gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource));
* </para></listitem>
* <listitem><para>
* Set the control values
*
* * Set the control values
* gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,0 * GST_SECOND, value1);
* gst_timed_value_control_source_set ((GstTimedValueControlSource *)csource,1 * GST_SECOND, value2);
* </para></listitem>
* <listitem><para>
* start your pipeline
* </para></listitem>
* </orderedlist>
* </para>
* </refsect2>
*
* * start your pipeline
*/
#include "gst_private.h"

1
gst/gstpad.c
View file

@ -21,6 +21,7 @@
*/
/**
* SECTION:gstpad
* @title: GstPad
* @short_description: Object contained by elements that allows links to
* other elements
* @see_also: #GstPadTemplate, #GstElement, #GstEvent, #GstQuery, #GstBuffer

10
gst/gstpad.h
View file

@ -205,12 +205,10 @@ const gchar* gst_pad_link_get_name (GstPadLinkReturn ret);
* and @GST_PAD_LINK_CHECK_TEMPLATE_CAPS are mutually exclusive. If both are
* specified, expensive but safe @GST_PAD_LINK_CHECK_CAPS are performed.
*
* <warning><para>
* Only disable some of the checks if you are 100% certain you know the link
* will not fail because of hierarchy/caps compatibility failures. If uncertain,
* use the default checks (%GST_PAD_LINK_CHECK_DEFAULT) or the regular methods
* for linking the pads.
* </para></warning>
* > Only disable some of the checks if you are 100% certain you know the link
* > will not fail because of hierarchy/caps compatibility failures. If uncertain,
* > use the default checks (%GST_PAD_LINK_CHECK_DEFAULT) or the regular methods
* > for linking the pads.
*/
typedef enum {

1
gst/gstpadtemplate.c
View file

@ -22,6 +22,7 @@
/**
* SECTION:gstpadtemplate
* @title: GstPadTemplate
* @short_description: Describe the media type of a pad.
* @see_also: #GstPad, #GstElementFactory
*

1
gst/gstparamspecs.c
View file

@ -18,6 +18,7 @@
*/
/**
* SECTION:gstparamspec
* @title: GstParamSpec
* @short_description: GParamSpec implementations specific
* to GStreamer
*

1
gst/gstparse.c
View file

@ -24,6 +24,7 @@
/**
* SECTION:gstparse
* @title: GstParse
* @short_description: Get a pipeline from a text pipeline description
*
* These function allow to create a pipeline based on the syntax used in the

1
gst/gstpipeline.c
View file

@ -22,6 +22,7 @@
/**
* SECTION:gstpipeline
* @title: GstPipeline
* @short_description: Top-level bin with clocking and bus management
functionality.
* @see_also: #GstElement, #GstBin, #GstClock, #GstBus

7
gst/gstplugin.c
View file

@ -22,6 +22,7 @@
/**
* SECTION:gstplugin
* @title: GstPlugin
* @short_description: Container for features loaded from a shared object module
* @see_also: #GstPluginFeature, #GstElementFactory
*
@ -671,7 +672,7 @@ static GMutex gst_plugin_loading_mutex;
*
* Loads the given plugin and refs it. Caller needs to unref after use.
*
* Returns: (transfer full): a reference to the existing loaded GstPlugin, a
* Returns: (transfer full): a reference to the existing loaded GstPlugin, a
* reference to the newly-loaded GstPlugin, or %NULL if an error occurred.
*/
GstPlugin *
@ -1285,13 +1286,13 @@ gst_plugin_load_by_name (const gchar * name)
* Loads @plugin. Note that the *return value* is the loaded plugin; @plugin is
* untouched. The normal use pattern of this function goes like this:
*
* <programlisting>
* |[
* GstPlugin *loaded_plugin;
* loaded_plugin = gst_plugin_load (plugin);
* // presumably, we're no longer interested in the potentially-unloaded plugin
* gst_object_unref (plugin);
* plugin = loaded_plugin;
* </programlisting>
* ]|
*
* Returns: (transfer full): a reference to a loaded plugin, or %NULL on error.
*/

1
gst/gstpluginfeature.c
View file

@ -22,6 +22,7 @@
/**
* SECTION:gstpluginfeature
* @title: GstPluginfeature
* @short_description: Base class for contents of a GstPlugin
* @see_also: #GstPlugin
*

5
gst/gstpoll.c
View file

@ -23,6 +23,7 @@
*/
/**
* SECTION:gstpoll
* @title: GstPoll
* @short_description: Keep track of file descriptors and make it possible
* to wait on them in a cancellable way
*
@ -734,7 +735,7 @@ no_socket_pair:
* timeouts.
*
* A timeout is performed with gst_poll_wait(). Multiple timeouts can be
* performed from different threads.
* performed from different threads.
*
* Free-function: gst_poll_free
*
@ -1636,7 +1637,7 @@ gst_poll_set_flushing (GstPoll * set, gboolean flushing)
*
* Write a byte to the control socket of the controllable @set.
* This function is mostly useful for timer #GstPoll objects created with
* gst_poll_new_timer().
* gst_poll_new_timer().
*
* It will make any current and future gst_poll_wait() function return with
* 1, meaning the control socket is set. After an equal amount of calls to

1
gst/gstpreset.c
View file

@ -20,6 +20,7 @@
*/
/**
* SECTION:gstpreset
* @title: GstPreset
* @short_description: helper interface for element presets
*
* This interface offers methods to query and manipulate parameter preset sets.

1
gst/gstprotection.c
View file

@ -19,6 +19,7 @@
/**
* SECTION:gstprotection
* @title: GstProtection
* @short_description: Functions and classes to support encrypted streams.
*
* The GstProtectionMeta class enables the information needed to decrypt a

15
gst/gstquery.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstquery
* @title: GstQuery
* @short_description: Provide functions to create queries, and to set and parse
* values in them.
* @see_also: #GstPad, #GstElement
@ -2252,15 +2253,11 @@ gst_query_parse_nth_scheduling_mode (GstQuery * query, guint index)
*
* Check if @query has scheduling mode set.
*
* <note>
* <para>
* When checking if upstream supports pull mode, it is usually not
* enough to just check for GST_PAD_MODE_PULL with this function, you
* also want to check whether the scheduling flags returned by
* gst_query_parse_scheduling() have the seeking flag set (meaning
* random access is supported, not only sequential pulls).
* </para>
* </note>
* > When checking if upstream supports pull mode, it is usually not
* > enough to just check for GST_PAD_MODE_PULL with this function, you
* > also want to check whether the scheduling flags returned by
* > gst_query_parse_scheduling() have the seeking flag set (meaning
* > random access is supported, not only sequential pulls).
*
* Returns: %TRUE when @mode is in the list of scheduling modes.
*/

57
gst/gstregistry.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstregistry
* @title: GstRegistry
* @short_description: Abstract base class for management of #GstPlugin objects
* @see_also: #GstPlugin, #GstPluginFeature
*
@ -44,48 +45,28 @@
*
* On startup, plugins are searched for in the plugin search path. The following
* locations are checked in this order:
* <itemizedlist>
* <listitem>
* <para>location from --gst-plugin-path commandline option.</para>
* </listitem>
* <listitem>
* <para>the GST_PLUGIN_PATH environment variable.</para>
* </listitem>
* <listitem>
* <para>the GST_PLUGIN_SYSTEM_PATH environment variable.</para>
* </listitem>
* <listitem>
* <para>default locations (if GST_PLUGIN_SYSTEM_PATH is not set). Those
* default locations are:
* <filename>$XDG_DATA_HOME/gstreamer-$GST_API_VERSION/plugins/</filename>
* and <filename>$prefix/libs/gstreamer-$GST_API_VERSION/</filename>.
* <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">
* <filename>$XDG_DATA_HOME</filename></ulink> defaults to
* <filename>$HOME/.local/share</filename>.
* </para>
* </listitem>
* </itemizedlist>
*
* * location from --gst-plugin-path commandline option.
* * the GST_PLUGIN_PATH environment variable.
* * the GST_PLUGIN_SYSTEM_PATH environment variable.
* * default locations (if GST_PLUGIN_SYSTEM_PATH is not set).
* Those default locations are:
* `$XDG_DATA_HOME/gstreamer-$GST_API_VERSION/plugins/`
* and `$prefix/libs/gstreamer-$GST_API_VERSION/`.
* [$XDG_DATA_HOME](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html) defaults to
* `$HOME/.local/share`.
*
* The registry cache file is loaded from
* <filename>$XDG_CACHE_HOME/gstreamer-$GST_API_VERSION/registry-$ARCH.bin</filename>
* (where
* <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">
* <filename>$XDG_CACHE_HOME</filename></ulink> defaults to
* <filename>$HOME/.cache</filename>) or the file listed in the GST_REGISTRY
* `$XDG_CACHE_HOME/gstreamer-$GST_API_VERSION/registry-$ARCH.bin`
* (where $XDG_CACHE_HOME defaults to `$HOME/.cache`) or the file listed in the `GST_REGISTRY`
* env var. One reason to change the registry location is for testing.
*
* For each plugin that is found in the plugin search path, there could be 3
* possibilities for cached information:
* <itemizedlist>
* <listitem>
* <para>the cache may not contain information about a given file.</para>
* </listitem>
* <listitem>
* <para>the cache may have stale information.</para>
* </listitem>
* <listitem>
* <para>the cache may have current information.</para>
* </listitem>
* </itemizedlist>
*
* * the cache may not contain information about a given file.
* * the cache may have stale information.
* * the cache may have current information.
*
* In the first two cases, the plugin is loaded and the cache updated. In
* addition to these cases, the cache may have entries for plugins that are not
@ -97,7 +78,7 @@
* checked to make sure the information is minimally valid. If not, the entry is
* simply dropped.
*
* <emphasis role="bold">Implementation notes:</emphasis>
* ## Implementation notes:
*
* The "cache" and "registry" are different concepts and can represent
* different sets of plugins. For various reasons, at init time, the cache is

1
gst/gstsample.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gstsample
* @title: GstSample
* @short_description: A media sample
* @see_also: #GstBuffer, #GstCaps, #GstSegment
*

8
gst/gstsegment.c
View file

@ -28,6 +28,7 @@
/**
* SECTION:gstsegment
* @title: GstSegment
* @short_description: Structure describing the configured region of interest
* in a media file.
* @see_also: #GstEvent
@ -36,10 +37,9 @@
* interest in a media file, called a segment.
*
* The structure can be used for two purposes:
* <itemizedlist>
* <listitem><para>performing seeks (handling seek events)</para></listitem>
* <listitem><para>tracking playback regions (handling newsegment events)</para></listitem>
* </itemizedlist>
*
* * performing seeks (handling seek events)
* * tracking playback regions (handling newsegment events)
*
* The segment is usually configured by the application with a seek event which
* is propagated upstream and eventually handled by an element that performs the seek.

1
gst/gststreamcollection.c
View file

@ -26,6 +26,7 @@
/**
* SECTION:gststreamcollection
* @title: GstStreamCollection
* @short_description: Base class for collection of streams
*
* Since: 1.10

1
gst/gststreams.c
View file

@ -26,6 +26,7 @@
/**
* SECTION:gststreams
* @title: GstStreams
* @short_description: Base class for stream objects
*
* A #GstStream is a high-level object defining a stream of data which is, or

1
gst/gststructure.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gststructure
* @title: GstStructure
* @short_description: Generic structure containing fields of names and values
* @see_also: #GstCaps, #GstMessage, #GstEvent, #GstQuery
*

1
gst/gstsystemclock.c
View file

@ -22,6 +22,7 @@
/**
* SECTION:gstsystemclock
* @title: GstSystemClock
* @short_description: Default clock that uses the current system time
* @see_also: #GstClock
*

1
gst/gsttaglist.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gsttaglist
* @title: GstTagList
* @short_description: List of tags and values used to describe media metadata
*
* List of tags and values used to describe media metadata.

15
gst/gsttagsetter.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gsttagsetter
* @title: GstTagsetter
* @short_description: Element interface that allows setting and retrieval
* of media metadata
*
@ -29,7 +30,7 @@
* Elements that support changing a stream's metadata will implement this
* interface. Examples of such elements are 'vorbisenc', 'theoraenc' and
* 'id3v2mux'.
*
*
* If you just want to retrieve metadata in your application then all you
* need to do is watch for tag messages on your pipeline's bus. This
* interface is only for setting metadata, not for extracting it. To set tags
@ -38,7 +39,7 @@
* setting the #GstTagMergeMode that is used for tag events that arrive at the
* tagsetter element (default mode is to keep existing tags).
* The application should do that before the element goes to %GST_STATE_PAUSED.
*
*
* Elements implementing the #GstTagSetter interface often have to merge
* any tags received from upstream and the tags set by the application via
* the interface. This can be done like this:
@ -49,19 +50,19 @@
* const GstTagList *event_tags;
* GstTagSetter *tagsetter;
* GstTagList *result;
*
*
* tagsetter = GST_TAG_SETTER (element);
*
*
* merge_mode = gst_tag_setter_get_tag_merge_mode (tagsetter);
* application_tags = gst_tag_setter_get_tag_list (tagsetter);
* event_tags = (const GstTagList *) element->event_tags;
*
*
* GST_LOG_OBJECT (tagsetter, "merging tags, merge mode = %d", merge_mode);
* GST_LOG_OBJECT (tagsetter, "event tags: %" GST_PTR_FORMAT, event_tags);
* GST_LOG_OBJECT (tagsetter, "set tags: %" GST_PTR_FORMAT, application_tags);
*
*
* result = gst_tag_list_merge (application_tags, event_tags, merge_mode);
*
*
* GST_LOG_OBJECT (tagsetter, "final tags: %" GST_PTR_FORMAT, result);
* ]|
*/

1
gst/gsttask.c
View file

@ -22,6 +22,7 @@
/**
* SECTION:gsttask
* @title: GstTask
* @short_description: Abstraction of GStreamer streaming threads.
* @see_also: #GstElement, #GstPad
*

3
gst/gsttaskpool.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gsttaskpool
* @title: GstTaskPool
* @short_description: Pool of GStreamer streaming threads
* @see_also: #GstTask, #GstPad
*
@ -255,7 +256,7 @@ not_supported:
* @pool: a #GstTaskPool
* @id: the id
*
* Join a task and/or return it to the pool. @id is the id obtained from
* Join a task and/or return it to the pool. @id is the id obtained from
* gst_task_pool_push().
*/
void

1
gst/gsttoc.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gsttoc
* @title: GstToc
* @short_description: Generic table of contents support
* @see_also: #GstStructure, #GstEvent, #GstMessage, #GstQuery
*

6
gst/gsttocsetter.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gsttocsetter
* @title: GstTocSetter
* @short_description: Element interface that allows setting and retrieval
* of the TOC
*
@ -28,13 +29,13 @@
*
* Elements that support some kind of chapters or editions (or tracks like in
* the FLAC cue sheet) will implement this interface.
*
*
* If you just want to retrieve the TOC in your application then all you
* need to do is watch for TOC messages on your pipeline's bus (or you can
* perform TOC query). This interface is only for setting TOC data, not for
* extracting it. To set TOC from the application, find proper tocsetter element
* and set TOC using gst_toc_setter_set_toc().
*
*
* Elements implementing the #GstTocSetter interface can extend existing TOC
* by getting extend UID for that (you can use gst_toc_find_entry() to retrieve it)
* with any TOC entries received from downstream.
@ -127,7 +128,6 @@ gst_toc_setter_reset (GstTocSetter * setter)
* Return current TOC the setter uses. The TOC should not be
* modified without making it writable first.
*
*
* Returns: (transfer full) (nullable): TOC set, or %NULL. Unref with
* gst_toc_unref() when no longer needed
*/

1
gst/gsttracer.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gsttracer
* @title: GstTracer
* @short_description: Tracing base class
*
* Tracing modules will subclass #GstTracer and register through

1
gst/gsttracerfactory.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gsttracerfactory
* @title: GstTracerFactory
* @short_description: Information about registered tracer functions
*
* Use gst_tracer_factory_get_list() to get a list of tracer factories known to

10
gst/gsttracerrecord.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gsttracerrecord
* @title: GstTracerRecord
* @short_description: Trace log entry class
*
* Tracing modules will create instances of this class to announce the data they
@ -175,9 +176,7 @@ gst_tracer_record_init (GstTracerRecord * self)
* pointer type values must not be NULL - the underlying serialisation can not
* handle that right now.
*
* <note><para>
* Please note that this is still under discussion and subject to change.
* </para></note>
* > Please note that this is still under discussion and subject to change.
*
* Returns: a new #GstTracerRecord
*/
@ -236,9 +235,8 @@ gst_tracer_record_new (const gchar * name, const gchar * firstfield, ...)
*
* Right now this is using the gstreamer debug log with the level TRACE (7) and
* the category "GST_TRACER".
* <note><para>
* Please note that this is still under discussion and subject to change.
* </para></note>
*
* > Please note that this is still under discussion and subject to change.
*/
void
gst_tracer_record_log (GstTracerRecord * self, ...)

1
gst/gsttypefind.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gsttypefind
* @title: GstTypefind
* @short_description: Stream type detection
*
* The following functions allow you to detect the media type of an unknown

1
gst/gsttypefindfactory.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gsttypefindfactory
* @title: GstTypeFindFactory
* @short_description: Information about registered typefind functions
*
* These functions allow querying informations about registered typefind

2
gst/gsturi.c
View file

@ -25,6 +25,7 @@
/**
* SECTION:gsturihandler
* @title: GstUriHandler
* @short_description: Interface to ease URI handling in plugins.
*
* The #GstURIHandler is an interface that is implemented by Source and Sink
@ -960,6 +961,7 @@ beach:
/**
* SECTION:gsturi
* @title: GstUri
* @short_description: URI parsing and manipulation.
*
* A #GstUri object can be used to parse and split a URI string into its

9
gst/gstutils.c
View file

@ -25,6 +25,7 @@
/**
* SECTION:gstutils
* @title: GstUtils
* @short_description: Various utility functions
*
*/
@ -4092,10 +4093,10 @@ gst_log2 (GstClockTime in)
* %NULL, an allocation will take place. @temp should have at least the same
* amount of memory allocated as @xy, i.e. 2*n*sizeof(GstClockTime).
*
* <note>This function assumes (x,y) values with reasonable large differences
* between them. It will not calculate the exact results if the differences
* between neighbouring values are too small due to not being able to
* represent sub-integer values during the calculations.</note>
* > This function assumes (x,y) values with reasonable large differences
* > between them. It will not calculate the exact results if the differences
* > between neighbouring values are too small due to not being able to
* > represent sub-integer values during the calculations.
*
* Returns: %TRUE if the linear regression was successfully calculated
*

1
gst/gstvalue.c
View file

@ -19,6 +19,7 @@
/**
* SECTION:gstvalue
* @title: GstValue
* @short_description: GValue implementations specific
* to GStreamer
*

24
gst/gstvalue.h
View file

@ -36,11 +36,11 @@ G_BEGIN_DECLS
*
* Transform four characters into a #guint32 fourcc value with host
* endianness.
* <informalexample>
* <programlisting>
*
* |[
* guint32 fourcc = GST_MAKE_FOURCC ('M', 'J', 'P', 'G');
* </programlisting>
* </informalexample>
* ]|
*
*/
#define GST_MAKE_FOURCC(a,b,c,d) ((guint32)((a)|(b)<<8|(c)<<16|(d)<<24))
@ -52,11 +52,11 @@ G_BEGIN_DECLS
* endianness.
* Caller is responsible for ensuring the input string consists of at least
* four characters.
* <informalexample>
* <programlisting>
*
* |[
* guint32 fourcc = GST_STR_FOURCC ("MJPG");
* </programlisting>
* </informalexample>
* ]|
*
*/
#define GST_STR_FOURCC(f) ((guint32)(((f)[0])|((f)[1]<<8)|((f)[2]<<16)|((f)[3]<<24)))
@ -65,11 +65,11 @@ G_BEGIN_DECLS
*
* Can be used together with #GST_FOURCC_ARGS to properly output a
* #guint32 fourcc value in a printf()-style text message.
* <informalexample>
* <programlisting>
*
* |[
* printf ("fourcc: %" GST_FOURCC_FORMAT "\n", GST_FOURCC_ARGS (fcc));
* </programlisting>
* </informalexample>
* ]|
*
*/
#define GST_FOURCC_FORMAT "c%c%c%c"

5
libs/gst/base/gstadapter.c
View file

@ -20,6 +20,7 @@
/**
* SECTION:gstadapter
* @title: GstAdapter
* @short_description: adapts incoming data on a sink pad into chunks of N bytes
*
* This class is for elements that receive buffers in an undesired size.
@ -1766,7 +1767,7 @@ gst_adapter_masked_scan_uint32_peek (GstAdapter * adapter, guint32 mask,
* Returns: offset of the first match, or -1 if no match was found.
*
* Example:
* <programlisting>
* |[
* // Assume the adapter contains 0x00 0x01 0x02 ... 0xfe 0xff
*
* gst_adapter_masked_scan_uint32 (adapter, 0xffffffff, 0x00010203, 0, 256);
@ -1783,7 +1784,7 @@ gst_adapter_masked_scan_uint32_peek (GstAdapter * adapter, guint32 mask,
* // -> returns 2
* gst_adapter_masked_scan_uint32 (adapter, 0xffff0000, 0x02030000, 0, 4);
* // -> returns -1
* </programlisting>
* ]|
*/
gssize
gst_adapter_masked_scan_uint32 (GstAdapter * adapter, guint32 mask,

240
libs/gst/base/gstbaseparse.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstbaseparse
* @title: GstBaseParse
* @short_description: Base class for stream parsers
* @see_also: #GstBaseTransform
*
@ -30,109 +31,88 @@
* into separate audio/video/whatever frames.
*
* It provides for:
* <itemizedlist>
* <listitem><para>provides one sink pad and one source pad</para></listitem>
* <listitem><para>handles state changes</para></listitem>
* <listitem><para>can operate in pull mode or push mode</para></listitem>
* <listitem><para>handles seeking in both modes</para></listitem>
* <listitem><para>handles events (SEGMENT/EOS/FLUSH)</para></listitem>
* <listitem><para>
* handles queries (POSITION/DURATION/SEEKING/FORMAT/CONVERT)
* </para></listitem>
* <listitem><para>handles flushing</para></listitem>
* </itemizedlist>
*
* * provides one sink pad and one source pad
* * handles state changes
* * can operate in pull mode or push mode
* * handles seeking in both modes
* * handles events (SEGMENT/EOS/FLUSH)
* * handles queries (POSITION/DURATION/SEEKING/FORMAT/CONVERT)
* * handles flushing
*
* The purpose of this base class is to provide the basic functionality of
* a parser and share a lot of rather complex code.
*
* Description of the parsing mechanism:
* <orderedlist>
* <listitem>
* <itemizedlist><title>Set-up phase</title>
* <listitem><para>
* #GstBaseParse calls @start to inform subclass that data processing is
* about to start now.
* </para></listitem>
* <listitem><para>
* #GstBaseParse class calls @set_sink_caps to inform the subclass about
* incoming sinkpad caps. Subclass could already set the srcpad caps
* accordingly, but this might be delayed until calling
* gst_base_parse_finish_frame() with a non-queued frame.
* </para></listitem>
* <listitem><para>
* At least at this point subclass needs to tell the #GstBaseParse class
* how big data chunks it wants to receive (min_frame_size). It can do
* this with gst_base_parse_set_min_frame_size().
* </para></listitem>
* <listitem><para>
* #GstBaseParse class sets up appropriate data passing mode (pull/push)
* and starts to process the data.
* </para></listitem>
* </itemizedlist>
* </listitem>
* <listitem>
* <itemizedlist>
* <title>Parsing phase</title>
* <listitem><para>
* #GstBaseParse gathers at least min_frame_size bytes of data either
* by pulling it from upstream or collecting buffers in an internal
* #GstAdapter.
* </para></listitem>
* <listitem><para>
* A buffer of (at least) min_frame_size bytes is passed to subclass with
* @handle_frame. Subclass checks the contents and can optionally
* return GST_FLOW_OK along with an amount of data to be skipped to find
* a valid frame (which will result in a subsequent DISCONT).
* If, otherwise, the buffer does not hold a complete frame,
* @handle_frame can merely return and will be called again when additional
* data is available. In push mode this amounts to an
* additional input buffer (thus minimal additional latency), in pull mode
* this amounts to some arbitrary reasonable buffer size increase.
* Of course, gst_base_parse_set_min_frame_size() could also be used if a
* very specific known amount of additional data is required.
* If, however, the buffer holds a complete valid frame, it can pass
* the size of this frame to gst_base_parse_finish_frame().
* If acting as a converter, it can also merely indicate consumed input data
* while simultaneously providing custom output data.
* Note that baseclass performs some processing (such as tracking
* overall consumed data rate versus duration) for each finished frame,
* but other state is only updated upon each call to @handle_frame
* (such as tracking upstream input timestamp).
* </para><para>
* Subclass is also responsible for setting the buffer metadata
* (e.g. buffer timestamp and duration, or keyframe if applicable).
* (although the latter can also be done by #GstBaseParse if it is
* appropriately configured, see below). Frame is provided with
* timestamp derived from upstream (as much as generally possible),
* duration obtained from configuration (see below), and offset
* if meaningful (in pull mode).
* </para><para>
* Note that @check_valid_frame might receive any small
* amount of input data when leftover data is being drained (e.g. at EOS).
* </para></listitem>
* <listitem><para>
* As part of finish frame processing,
* just prior to actually pushing the buffer in question,
* it is passed to @pre_push_frame which gives subclass yet one
* last chance to examine buffer metadata, or to send some custom (tag)
* events, or to perform custom (segment) filtering.
* </para></listitem>
* <listitem><para>
* During the parsing process #GstBaseParseClass will handle both srcpad
* and sinkpad events. They will be passed to subclass if @event or
* @src_event callbacks have been provided.
* </para></listitem>
* </itemizedlist>
* </listitem>
* <listitem>
* <itemizedlist><title>Shutdown phase</title>
* <listitem><para>
* #GstBaseParse class calls @stop to inform the subclass that data
* parsing will be stopped.
* </para></listitem>
* </itemizedlist>
* </listitem>
* </orderedlist>
* # Description of the parsing mechanism:
*
* ## Set-up phase
*
* * #GstBaseParse calls @start to inform subclass that data processing is
* about to start now.
*
* * #GstBaseParse class calls @set_sink_caps to inform the subclass about
* incoming sinkpad caps. Subclass could already set the srcpad caps
* accordingly, but this might be delayed until calling
* gst_base_parse_finish_frame() with a non-queued frame.
*
* * At least at this point subclass needs to tell the #GstBaseParse class
* how big data chunks it wants to receive (min_frame_size). It can do
* this with gst_base_parse_set_min_frame_size().
*
* * #GstBaseParse class sets up appropriate data passing mode (pull/push)
* and starts to process the data.
*
* ## Parsing phase
*
* * #GstBaseParse gathers at least min_frame_size bytes of data either
* by pulling it from upstream or collecting buffers in an internal
* #GstAdapter.
*
* * A buffer of (at least) min_frame_size bytes is passed to subclass with
* @handle_frame. Subclass checks the contents and can optionally
* return GST_FLOW_OK along with an amount of data to be skipped to find
* a valid frame (which will result in a subsequent DISCONT).
* If, otherwise, the buffer does not hold a complete frame,
* @handle_frame can merely return and will be called again when additional
* data is available. In push mode this amounts to an
* additional input buffer (thus minimal additional latency), in pull mode
* this amounts to some arbitrary reasonable buffer size increase.
* Of course, gst_base_parse_set_min_frame_size() could also be used if a
* very specific known amount of additional data is required.
* If, however, the buffer holds a complete valid frame, it can pass
* the size of this frame to gst_base_parse_finish_frame().
* If acting as a converter, it can also merely indicate consumed input data
* while simultaneously providing custom output data.
* Note that baseclass performs some processing (such as tracking
* overall consumed data rate versus duration) for each finished frame,
* but other state is only updated upon each call to @handle_frame
* (such as tracking upstream input timestamp).
*
* Subclass is also responsible for setting the buffer metadata
* (e.g. buffer timestamp and duration, or keyframe if applicable).
* (although the latter can also be done by #GstBaseParse if it is
* appropriately configured, see below). Frame is provided with
* timestamp derived from upstream (as much as generally possible),
* duration obtained from configuration (see below), and offset
* if meaningful (in pull mode).
*
* Note that @check_valid_frame might receive any small
* amount of input data when leftover data is being drained (e.g. at EOS).
*
* * As part of finish frame processing,
* just prior to actually pushing the buffer in question,
* it is passed to @pre_push_frame which gives subclass yet one
* last chance to examine buffer metadata, or to send some custom (tag)
* events, or to perform custom (segment) filtering.
*
* * During the parsing process #GstBaseParseClass will handle both srcpad
* and sinkpad events. They will be passed to subclass if @event or
* @src_event callbacks have been provided.
*
* ## Shutdown phase
*
* * #GstBaseParse class calls @stop to inform the subclass that data
* parsing will be stopped.
*
* Subclass is responsible for providing pad template caps for
* source and sink pads. The pads need to be named "sink" and "src". It also
@ -151,44 +131,30 @@
* and end of data processing.
*
* Things that subclass need to take care of:
* <itemizedlist>
* <listitem><para>Provide pad templates</para></listitem>
* <listitem><para>
* Fixate the source pad caps when appropriate
* </para></listitem>
* <listitem><para>
* Inform base class how big data chunks should be retrieved. This is
* done with gst_base_parse_set_min_frame_size() function.
* </para></listitem>
* <listitem><para>
* Examine data chunks passed to subclass with @handle_frame and pass
* proper frame(s) to gst_base_parse_finish_frame(), and setting src pad
* caps and timestamps on frame.
* </para></listitem>
* <listitem><para>Provide conversion functions</para></listitem>
* <listitem><para>
* Update the duration information with gst_base_parse_set_duration()
* </para></listitem>
* <listitem><para>
* Optionally passthrough using gst_base_parse_set_passthrough()
* </para></listitem>
* <listitem><para>
* Configure various baseparse parameters using
* gst_base_parse_set_average_bitrate(), gst_base_parse_set_syncable()
* and gst_base_parse_set_frame_rate().
* </para></listitem>
* <listitem><para>
* In particular, if subclass is unable to determine a duration, but
* parsing (or specs) yields a frames per seconds rate, then this can be
* provided to #GstBaseParse to enable it to cater for
* buffer time metadata (which will be taken from upstream as much as
* possible). Internally keeping track of frame durations and respective
* sizes that have been pushed provides #GstBaseParse with an estimated
* bitrate. A default @convert (used if not overridden) will then use these
* rates to perform obvious conversions. These rates are also used to
* update (estimated) duration at regular frame intervals.
* </para></listitem>
* </itemizedlist>
*
* * Provide pad templates
* * Fixate the source pad caps when appropriate
* * Inform base class how big data chunks should be retrieved. This is
* done with gst_base_parse_set_min_frame_size() function.
* * Examine data chunks passed to subclass with @handle_frame and pass
* proper frame(s) to gst_base_parse_finish_frame(), and setting src pad
* caps and timestamps on frame.
* * Provide conversion functions
* * Update the duration information with gst_base_parse_set_duration()
* * Optionally passthrough using gst_base_parse_set_passthrough()
* * Configure various baseparse parameters using
* gst_base_parse_set_average_bitrate(), gst_base_parse_set_syncable()
* and gst_base_parse_set_frame_rate().
*
* * In particular, if subclass is unable to determine a duration, but
* parsing (or specs) yields a frames per seconds rate, then this can be
* provided to #GstBaseParse to enable it to cater for
* buffer time metadata (which will be taken from upstream as much as
* possible). Internally keeping track of frame durations and respective
* sizes that have been pushed provides #GstBaseParse with an estimated
* bitrate. A default @convert (used if not overridden) will then use these
* rates to perform obvious conversions. These rates are also used to
* update (estimated) duration at regular frame intervals.
*
*/

11
libs/gst/base/gstbasesink.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gstbasesink
* @title: GstBaseSink
* @short_description: Base class for sink elements
* @see_also: #GstBaseTransform, #GstBaseSrc
*
@ -51,7 +52,7 @@
* "Sink name",
* "Sink",
* "My Sink element",
* "The author &lt;my.sink@my.email&gt;");
* "The author <my.sink@my.email>");
* }
* ]|
*
@ -98,7 +99,7 @@
* should configure itself to process a specific media type.
*
* The #GstBaseSinkClass.start() and #GstBaseSinkClass.stop() virtual methods
* will be called when resources should be allocated. Any
* will be called when resources should be allocated. Any
* #GstBaseSinkClass.preroll(), #GstBaseSinkClass.render() and
* #GstBaseSinkClass.set_caps() function will be called between the
* #GstBaseSinkClass.start() and #GstBaseSinkClass.stop() calls.
@ -1330,7 +1331,7 @@ gst_base_sink_get_blocksize (GstBaseSink * sink)
*
* Set the time that will be inserted between rendered buffers. This
* can be used to control the maximum buffers per second that the sink
* will render.
* will render.
*/
void
gst_base_sink_set_throttle_time (GstBaseSink * sink, guint64 throttle)
@ -1347,7 +1348,7 @@ gst_base_sink_set_throttle_time (GstBaseSink * sink, guint64 throttle)
* gst_base_sink_get_throttle_time:
* @sink: a #GstBaseSink
*
* Get the time that will be inserted between frames to control the
* Get the time that will be inserted between frames to control the
* maximum buffers per second.
*
* Returns: the number of nanoseconds @sink will put between frames.
@ -4104,7 +4105,7 @@ paused:
}
} else if (result == GST_FLOW_NOT_LINKED || result <= GST_FLOW_EOS) {
/* for fatal errors we post an error message, post the error
* first so the app knows about the error first.
* first so the app knows about the error first.
* wrong-state is not a fatal error because it happens due to
* flushing and posting an error message in that case is the
* wrong thing to do, e.g. when basesrc is doing a flushing

48
libs/gst/base/gstbasesrc.c
View file

@ -22,16 +22,16 @@
/**
* SECTION:gstbasesrc
* @title: GstBaseSrc
* @short_description: Base class for getrange based source elements
* @see_also: #GstPushSrc, #GstBaseTransform, #GstBaseSink
*
* This is a generic base class for source elements. The following
* types of sources are supported:
* <itemizedlist>
* <listitem><para>random access sources like files</para></listitem>
* <listitem><para>seekable sources</para></listitem>
* <listitem><para>live sources</para></listitem>
* </itemizedlist>
*
* * random access sources like files
* * seekable sources
* * live sources
*
* The source can be configured to operate in any #GstFormat with the
* gst_base_src_set_format() method. The currently set format determines
@ -40,30 +40,20 @@
*
* #GstBaseSrc always supports push mode scheduling. If the following
* conditions are met, it also supports pull mode scheduling:
* <itemizedlist>
* <listitem><para>The format is set to %GST_FORMAT_BYTES (default).</para>
* </listitem>
* <listitem><para>#GstBaseSrcClass.is_seekable() returns %TRUE.</para>
* </listitem>
* </itemizedlist>
*
* * The format is set to %GST_FORMAT_BYTES (default).
* * #GstBaseSrcClass.is_seekable() returns %TRUE.
*
* If all the conditions are met for operating in pull mode, #GstBaseSrc is
* automatically seekable in push mode as well. The following conditions must
* be met to make the element seekable in push mode when the format is not
* %GST_FORMAT_BYTES:
* <itemizedlist>
* <listitem><para>
* #GstBaseSrcClass.is_seekable() returns %TRUE.
* </para></listitem>
* <listitem><para>
* #GstBaseSrcClass.query() can convert all supported seek formats to the
* internal format as set with gst_base_src_set_format().
* </para></listitem>
* <listitem><para>
* #GstBaseSrcClass.do_seek() is implemented, performs the seek and returns
* %TRUE.
* </para></listitem>
* </itemizedlist>
*
* * #GstBaseSrcClass.is_seekable() returns %TRUE.
* * #GstBaseSrcClass.query() can convert all supported seek formats to the
* internal format as set with gst_base_src_set_format().
* * #GstBaseSrcClass.do_seek() is implemented, performs the seek and returns
* %TRUE.
*
* When the element does not meet the requirements to operate in pull mode, the
* offset and length in the #GstBaseSrcClass.create() method should be ignored.
@ -125,13 +115,12 @@
* "Source name",
* "Source",
* "My Source element",
* "The author &lt;my.sink@my.email&gt;");
* "The author <my.sink@my.email>");
* }
* ]|
*
* <refsect2>
* <title>Controlled shutdown of live sources in applications</title>
* <para>
* ## Controlled shutdown of live sources in applications
*
* Applications that record from a live source may want to stop recording
* in a controlled way, so that the recording is stopped, but the data
* already in the pipeline is processed to the end (remember that many live
@ -149,8 +138,7 @@
* After the EOS has been sent to the element, the application should wait for
* an EOS message to be posted on the pipeline's bus. Once this EOS message is
* received, it may safely shut down the entire pipeline.
* </para>
* </refsect2>
*
*/
#ifdef HAVE_CONFIG_H

252
libs/gst/base/gstbasetransform.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstbasetransform
* @title: GstBaseTransform
* @short_description: Base class for simple transform filters
* @see_also: #GstBaseSrc, #GstBaseSink
*
@ -36,172 +37,100 @@
* for more concrete use cases.
*
* It provides for:
* <itemizedlist>
* <listitem><para>one sinkpad and one srcpad</para></listitem>
* <listitem><para>
* Possible formats on sink and source pad implemented
* with custom transform_caps function. By default uses
* same format on sink and source.
* </para></listitem>
* <listitem><para>Handles state changes</para></listitem>
* <listitem><para>Does flushing</para></listitem>
* <listitem><para>Push mode</para></listitem>
* <listitem><para>
* Pull mode if the sub-class transform can operate on arbitrary data
* </para></listitem>
* </itemizedlist>
*
* <refsect2>
* <title>Use Cases</title>
* <para>
* <orderedlist>
* <listitem>
* <itemizedlist><title>Passthrough mode</title>
* <listitem><para>
* Element has no interest in modifying the buffer. It may want to inspect it,
* * one sinkpad and one srcpad
* * Possible formats on sink and source pad implemented
* with custom transform_caps function. By default uses
* same format on sink and source.
*
* * Handles state changes
* * Does flushing
* * Push mode
* * Pull mode if the sub-class transform can operate on arbitrary data
*
* # Use Cases
*
* ## Passthrough mode
*
* * Element has no interest in modifying the buffer. It may want to inspect it,
* in which case the element should have a transform_ip function. If there
* is no transform_ip function in passthrough mode, the buffer is pushed
* intact.
* </para></listitem>
* <listitem><para>
* The #GstBaseTransformClass.passthrough_on_same_caps variable
*
* * The #GstBaseTransformClass.passthrough_on_same_caps variable
* will automatically set/unset passthrough based on whether the
* element negotiates the same caps on both pads.
* </para></listitem>
* <listitem><para>
* #GstBaseTransformClass.passthrough_on_same_caps on an element that
*
* * #GstBaseTransformClass.passthrough_on_same_caps on an element that
* doesn't implement a transform_caps function is useful for elements that
* only inspect data (such as level)
* </para></listitem>
* </itemizedlist>
* <itemizedlist>
* <title>Example elements</title>
* <listitem>Level</listitem>
* <listitem>Videoscale, audioconvert, videoconvert, audioresample in
* certain modes.</listitem>
* </itemizedlist>
* </listitem>
* <listitem>
* <itemizedlist>
* <title>Modifications in-place - input buffer and output buffer are the
* same thing.</title>
* <listitem><para>
* The element must implement a transform_ip function.
* </para></listitem>
* <listitem><para>
* Output buffer size must <= input buffer size
* </para></listitem>
* <listitem><para>
* If the always_in_place flag is set, non-writable buffers will be copied
* and passed to the transform_ip function, otherwise a new buffer will be
* created and the transform function called.
* </para></listitem>
* <listitem><para>
* Incoming writable buffers will be passed to the transform_ip function
* immediately. </para></listitem>
* <listitem><para>
* only implementing transform_ip and not transform implies always_in_place
* = %TRUE
* </para></listitem>
* </itemizedlist>
* <itemizedlist>
* <title>Example elements</title>
* <listitem>Volume</listitem>
* <listitem>Audioconvert in certain modes (signed/unsigned
* conversion)</listitem>
* <listitem>videoconvert in certain modes (endianness
* swapping)</listitem>
* </itemizedlist>
* </listitem>
* <listitem>
* <itemizedlist>
* <title>Modifications only to the caps/metadata of a buffer</title>
* <listitem><para>
* The element does not require writable data, but non-writable buffers
* should be subbuffered so that the meta-information can be replaced.
* </para></listitem>
* <listitem><para>
* Elements wishing to operate in this mode should replace the
* prepare_output_buffer method to create subbuffers of the input buffer
* and set always_in_place to %TRUE
* </para></listitem>
* </itemizedlist>
* <itemizedlist>
* <title>Example elements</title>
* <listitem>Capsfilter when setting caps on outgoing buffers that have
* none.</listitem>
* <listitem>identity when it is going to re-timestamp buffers by
* datarate.</listitem>
* </itemizedlist>
* </listitem>
* <listitem>
* <itemizedlist><title>Normal mode</title>
* <listitem><para>
* always_in_place flag is not set, or there is no transform_ip function
* </para></listitem>
* <listitem><para>
* Element will receive an input buffer and output buffer to operate on.
* </para></listitem>
* <listitem><para>
* Output buffer is allocated by calling the prepare_output_buffer function.
* </para></listitem>
* </itemizedlist>
* <itemizedlist>
* <title>Example elements</title>
* <listitem>Videoscale, videoconvert, audioconvert when doing
* scaling/conversions</listitem>
* </itemizedlist>
* </listitem>
* <listitem>
* <itemizedlist><title>Special output buffer allocations</title>
* <listitem><para>
* Elements which need to do special allocation of their output buffers
*
* * Example elements
*
* * Level
* * Videoscale, audioconvert, videoconvert, audioresample in certain modes.
*
* ## Modifications in-place - input buffer and output buffer are the same thing.
*
* * The element must implement a transform_ip function.
* * Output buffer size must <= input buffer size
* * If the always_in_place flag is set, non-writable buffers will be copied
* and passed to the transform_ip function, otherwise a new buffer will be
* created and the transform function called.
*
* * Incoming writable buffers will be passed to the transform_ip function
* immediately.
* * only implementing transform_ip and not transform implies always_in_place = %TRUE
*
* * Example elements:
* * Volume
* * Audioconvert in certain modes (signed/unsigned conversion)
* * videoconvert in certain modes (endianness swapping)
*
* ## Modifications only to the caps/metadata of a buffer
*
* * The element does not require writable data, but non-writable buffers
* should be subbuffered so that the meta-information can be replaced.
*
* * Elements wishing to operate in this mode should replace the
* prepare_output_buffer method to create subbuffers of the input buffer
* and set always_in_place to %TRUE
*
* * Example elements
* * Capsfilter when setting caps on outgoing buffers that have
* none.
* * identity when it is going to re-timestamp buffers by
* datarate.
*
* ## Normal mode
* * always_in_place flag is not set, or there is no transform_ip function
* * Element will receive an input buffer and output buffer to operate on.
* * Output buffer is allocated by calling the prepare_output_buffer function.
* * Example elements:
* * Videoscale, videoconvert, audioconvert when doing
* scaling/conversions
*
* ## Special output buffer allocations
* * Elements which need to do special allocation of their output buffers
* beyond allocating output buffers via the negotiated allocator or
* buffer pool should implement the prepare_output_buffer method.
* </para></listitem>
* </itemizedlist>
* <itemizedlist>
* <title>Example elements</title>
* <listitem>efence</listitem>
* </itemizedlist>
* </listitem>
* </orderedlist>
* </para>
* </refsect2>
* <refsect2>
* <title>Sub-class settable flags on GstBaseTransform</title>
* <para>
* <itemizedlist>
* <listitem><para>
* <itemizedlist><title>passthrough</title>
* <listitem><para>
* Implies that in the current configuration, the sub-class is not
* interested in modifying the buffers.
* </para></listitem>
* <listitem><para>
* Elements which are always in passthrough mode whenever the same caps
* has been negotiated on both pads can set the class variable
* passthrough_on_same_caps to have this behaviour automatically.
* </para></listitem>
* </itemizedlist>
* </para></listitem>
* <listitem><para>
* <itemizedlist><title>always_in_place</title>
* <listitem><para>
* Determines whether a non-writable buffer will be copied before passing
* to the transform_ip function.
* </para></listitem>
* <listitem><para>
* Implied %TRUE if no transform function is implemented.
* </para></listitem>
* <listitem><para>
* Implied %FALSE if ONLY transform function is implemented.
* </para></listitem>
* </itemizedlist>
* </para></listitem>
* </itemizedlist>
* </para>
* </refsect2>
*
* * Example elements:
* * efence
*
* # Sub-class settable flags on GstBaseTransform
*
* * passthrough
*
* * Implies that in the current configuration, the sub-class is not interested in modifying the buffers.
* * Elements which are always in passthrough mode whenever the same caps has been negotiated on both pads can set the class variable passthrough_on_same_caps to have this behaviour automatically.
*
* * always_in_place
* * Determines whether a non-writable buffer will be copied before passing
* to the transform_ip function.
*
* * Implied %TRUE if no transform function is implemented.
* * Implied %FALSE if ONLY transform function is implemented.
*/
#ifdef HAVE_CONFIG_H
@ -679,7 +608,7 @@ gst_base_transform_transform_size (GstBaseTransform * trans,
/* get the caps that can be handled by @pad. We perform:
*
* - take the caps of peer of otherpad,
* - filter against the padtemplate of otherpad,
* - filter against the padtemplate of otherpad,
* - calculate all transforms of remaining caps
* - filter against template of @pad
*
@ -2478,7 +2407,7 @@ gst_base_transform_activate (GstBaseTransform * trans, gboolean active)
GST_PAD_STREAM_UNLOCK (trans->sinkpad);
priv->have_same_caps = FALSE;
/* We can only reset the passthrough mode if the instance told us to
/* We can only reset the passthrough mode if the instance told us to
handle it in configure_caps */
if (bclass->passthrough_on_same_caps) {
gst_base_transform_set_passthrough (trans, FALSE);
@ -2621,10 +2550,9 @@ gst_base_transform_is_passthrough (GstBaseTransform * trans)
*
* Determines whether a non-writable buffer will be copied before passing
* to the transform_ip function.
* <itemizedlist>
* <listitem>Always %TRUE if no transform function is implemented.</listitem>
* <listitem>Always %FALSE if ONLY transform function is implemented.</listitem>
* </itemizedlist>
*
* * Always %TRUE if no transform function is implemented.
* * Always %FALSE if ONLY transform function is implemented.
*
* MT safe.
*/

2
libs/gst/base/gstbasetransform.h
View file

@ -208,7 +208,7 @@ struct _GstBaseTransform {
* do 1-to-1 transformations on input to output buffers can either
* return GST_BASE_TRANSFORM_FLOW_DROPPED or simply not generate
* an output buffer until they are ready to do so. (Since 1.6)
*
*
* Subclasses can override any of the available virtual methods or not, as
* needed. At minimum either @transform or @transform_ip need to be overridden.
* If the element can overwrite the input data with the results (data is of the

1
libs/gst/base/gstbitreader.c
View file

@ -29,6 +29,7 @@
/**
* SECTION:gstbitreader
* @title: GstBitReader
* @short_description: Reads any number of bits from a memory buffer
*
* #GstBitReader provides a bit reader that can read any number of bits

7
libs/gst/base/gstbytereader.c
View file

@ -30,6 +30,7 @@
/**
* SECTION:gstbytereader
* @title: GstByteReader
* @short_description: Reads different integer, string and floating point
* types from a memory buffer
*
@ -769,7 +770,6 @@ GST_BYTE_READER_PEEK_GET(64,gdouble,float64_be)
* position if at least @size bytes are left and
* updates the current position.
*
*
* Returns: %TRUE if successful, %FALSE otherwise.
*/
gboolean
@ -790,7 +790,6 @@ gst_byte_reader_get_data (GstByteReader * reader, guint size,
* position if at least @size bytes are left and
* keeps the current position.
*
*
* Returns: %TRUE if successful, %FALSE otherwise.
*/
gboolean
@ -916,7 +915,7 @@ _masked_scan_uint32_peek (const GstByteReader * reader,
* Returns: offset of the first match, or -1 if no match was found.
*
* Example:
* <programlisting>
* |[
* // Assume the reader contains 0x00 0x01 0x02 ... 0xfe 0xff
*
* gst_byte_reader_masked_scan_uint32 (reader, 0xffffffff, 0x00010203, 0, 256);
@ -933,7 +932,7 @@ _masked_scan_uint32_peek (const GstByteReader * reader,
* // -> returns 2
* gst_byte_reader_masked_scan_uint32 (reader, 0xffff0000, 0x02030000, 0, 4);
* // -> returns -1
* </programlisting>
* ]|
*/
guint
gst_byte_reader_masked_scan_uint32 (const GstByteReader * reader, guint32 mask,

1
libs/gst/base/gstbytewriter.c
View file

@ -27,6 +27,7 @@
/**
* SECTION:gstbytewriter
* @title: GstByteWriter
* @short_description: Writes different integer, string and floating point
* types to a memory buffer and allows reading
*

46
libs/gst/base/gstcollectpads.c
View file

@ -22,55 +22,47 @@
*/
/**
* SECTION:gstcollectpads
* @title: GstCollectPads
* @short_description: manages a set of pads that operate in collect mode
* @see_also:
*
* Manages a set of pads that operate in collect mode. This means that control
* is given to the manager of this object when all pads have data.
* <itemizedlist>
* <listitem><para>
* Collectpads are created with gst_collect_pads_new(). A callback should then
*
* * Collectpads are created with gst_collect_pads_new(). A callback should then
* be installed with gst_collect_pads_set_function ().
* </para></listitem>
* <listitem><para>
* Pads are added to the collection with gst_collect_pads_add_pad()/
*
* * Pads are added to the collection with gst_collect_pads_add_pad()/
* gst_collect_pads_remove_pad(). The pad
* has to be a sinkpad. The chain and event functions of the pad are
* overridden. The element_private of the pad is used to store
* private information for the collectpads.
* </para></listitem>
* <listitem><para>
* For each pad, data is queued in the _chain function or by
*
* * For each pad, data is queued in the _chain function or by
* performing a pull_range.
* </para></listitem>
* <listitem><para>
* When data is queued on all pads in waiting mode, the callback function is called.
* </para></listitem>
* <listitem><para>
* Data can be dequeued from the pad with the gst_collect_pads_pop() method.
*
* * When data is queued on all pads in waiting mode, the callback function is called.
*
* * Data can be dequeued from the pad with the gst_collect_pads_pop() method.
* One can peek at the data with the gst_collect_pads_peek() function.
* These functions will return %NULL if the pad received an EOS event. When all
* pads return %NULL from a gst_collect_pads_peek(), the element can emit an EOS
* event itself.
* </para></listitem>
* <listitem><para>
* Data can also be dequeued in byte units using the gst_collect_pads_available(),
*
* * Data can also be dequeued in byte units using the gst_collect_pads_available(),
* gst_collect_pads_read_buffer() and gst_collect_pads_flush() calls.
* </para></listitem>
* <listitem><para>
* Elements should call gst_collect_pads_start() and gst_collect_pads_stop() in
*
* * Elements should call gst_collect_pads_start() and gst_collect_pads_stop() in
* their state change functions to start and stop the processing of the collectpads.
* The gst_collect_pads_stop() call should be called before calling the parent
* element state change function in the PAUSED_TO_READY state change to ensure
* no pad is blocked and the element can finish streaming.
* </para></listitem>
* <listitem><para>
* gst_collect_pads_set_waiting() sets a pad to waiting or non-waiting mode.
*
* * gst_collect_pads_set_waiting() sets a pad to waiting or non-waiting mode.
* CollectPads element is not waiting for data to be collected on non-waiting pads.
* Thus these pads may but need not have data when the callback is called.
* All pads are in waiting mode by default.
* </para></listitem>
* </itemizedlist>
*
*/
#ifdef HAVE_CONFIG_H
@ -2137,7 +2129,7 @@ pad_removed:
* and if so we call the collected function. When this is done we check if
* data has been unqueued. If data is still queued we wait holding the stream
* lock to make sure no EOS event can happen while we are ready to be
* collected
* collected
*/
static GstFlowReturn
gst_collect_pads_chain (GstPad * pad, GstObject * parent, GstBuffer * buffer)

3
libs/gst/base/gstdataqueue.c
View file

@ -21,6 +21,7 @@
/**
* SECTION:gstdataqueue
* @title: GstDataQueue
* @short_description: Threadsafe queueing object
*
* #GstDataQueue is an object that handles threadsafe queueing of objects. It
@ -386,7 +387,7 @@ gst_data_queue_is_full (GstDataQueue * queue)
* Sets the queue to flushing state if @flushing is %TRUE. If set to flushing
* state, any incoming data on the @queue will be discarded. Any call currently
* blocking on #gst_data_queue_push or #gst_data_queue_pop will return straight
* away with a return value of %FALSE. While the @queue is in flushing state,
* away with a return value of %FALSE. While the @queue is in flushing state,
* all calls to those two functions will return %FALSE.
*
* MT Safe.

2
libs/gst/base/gstdataqueue.h
View file

@ -93,7 +93,7 @@ struct _GstDataQueueSize
* @bytes: The amount of bytes currently in the queue.
* @time: The accumulated duration of the items currently in the queue.
* @checkdata: The #gpointer registered when the #GstDataQueue was created.
*
*
* The prototype of the function used to inform the queue that it should be
* considered as full.
*

1
libs/gst/base/gstflowcombiner.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstflowcombiner
* @title: GstFlowCombiner
* @short_description: Utility to combine multiple flow returns into one
*
* Utility struct to help handling #GstFlowReturn combination. Useful for

11
libs/gst/base/gstindex.c
View file

@ -20,8 +20,9 @@
* Boston, MA 02110-1301, USA.
*/
/*
/**
* SECTION:gstindex
* @title: GstIndexEntry
* @short_description: Generate indexes on objects
* @see_also: #GstIndexFactory
*
@ -687,11 +688,9 @@ gst_index_gtype_resolver (GstIndex * index, GstObject * writer,
* to a string. That string will be used to register or look up an id
* in the index.
*
* <note>
* The caller must not hold @writer's GST_OBJECT_LOCK(), as the default
* resolver may call functions that take the object lock as well, and
* the lock is not recursive.
* </note>
* > The caller must not hold @writer's GST_OBJECT_LOCK(), as the default
* > resolver may call functions that take the object lock as well, and
* > the lock is not recursive.
*
* Returns: %TRUE if the writer would be mapped to an id.
*/

1
libs/gst/base/gstpushsrc.c
View file

@ -22,6 +22,7 @@
/**
* SECTION:gstpushsrc
* @title: GstPushSrc
* @short_description: Base class for push based source elements
* @see_also: #GstBaseSrc
*

1
libs/gst/base/gstqueuearray.c
View file

@ -22,6 +22,7 @@
/**
* SECTION:gstqueuearray
* @title: GstQueueArray
* @short_description: Array based queue object
*
* #GstQueueArray is an object that provides standard queue functionality

5
libs/gst/base/gsttypefindhelper.c
View file

@ -23,7 +23,8 @@
/**
* SECTION:gsttypefindhelper
* @short_description: Utility functions for typefinding
* @title: GstTypeFindHelper
* @short_description: Utility functions for typefinding
*
* Utility functions for elements doing typefinding:
* gst_type_find_helper() does typefinding in pull mode, while
@ -118,7 +119,7 @@ helper_find_peek (gpointer data, gint64 offset, guint size)
buf_size = bmp->map.size;
/* buffers are kept sorted by end offset (highest first) in the list, so
* at this point we save the current position and stop searching if
* at this point we save the current position and stop searching if
* we're after the searched end offset */
if (buf_offset <= offset) {
if ((offset + size) < (buf_offset + buf_size)) {

1
libs/gst/check/gstbufferstraw.c
View file

@ -22,6 +22,7 @@
/**
* SECTION:gstcheckbufferstraw
* @title: GstBufferStraw
* @short_description: Buffer interception code for GStreamer unit tests
*
* These macros and functions are for internal use of the unit tests found

10
libs/gst/check/gstcheck.c
View file

@ -22,6 +22,7 @@
*/
/**
* SECTION:gstcheck
* @title: GstCheck
* @short_description: Common code for GStreamer unit tests
*
* These macros and functions are for internal use of the unit tests found
@ -64,7 +65,8 @@ gboolean _gst_check_list_tests = FALSE;
static GQueue _gst_check_log_filters = G_QUEUE_INIT;
static GMutex _gst_check_log_filters_mutex;
struct _GstCheckLogFilter {
struct _GstCheckLogFilter
{
gchar *log_domain;
GLogLevelFlags log_level;
GRegex *regex;
@ -199,8 +201,8 @@ gst_check_clear_log_filter (void)
typedef struct
{
const gchar * domain;
const gchar * message;
const gchar *domain;
const gchar *message;
GLogLevelFlags level;
gboolean discard;
} LogFilterApplyData;
@ -243,7 +245,7 @@ gst_check_filter_log_filter (const gchar * log_domain,
static gboolean
gst_check_log_fatal_func (const gchar * log_domain, GLogLevelFlags log_level,
const gchar *message, gpointer user_data)
const gchar * message, gpointer user_data)
{
if (gst_check_filter_log_filter (log_domain, log_level, message))
return FALSE;

1
libs/gst/check/gstconsistencychecker.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstcheckconsistencychecker
* @title: GstStreamConsistencyChecker
* @short_description: Data flow consistency checker for GStreamer unit tests.
*
* These macros and functions are for internal use of the unit tests found

30
libs/gst/check/gstharness.c
View file

@ -20,6 +20,7 @@
/**
* SECTION:gstharness
* @title: GstHarness
* @short_description: A test-harness for writing GStreamer unit tests
* @see_also: #GstTestClock,\
*
@ -30,7 +31,7 @@
* The basic structure of #GstHarness is two "floating" #GstPads that connect
* to the harnessed #GstElement src and sink #GstPads like so:
*
* <programlisting>
* |[
* __________________________
* _____ | _____ _____ | _____
* | | | | | | | | | |
@ -38,7 +39,7 @@
* |_____| | |_____| |_____| | |_____|
* |__________________________|
*
* </programlisting>
* ]|
*
* With this, you can now simulate any environment the #GstElement might find
* itself in. By specifying the #GstCaps of the harness #GstPads, using
@ -54,11 +55,11 @@
* then pull them out to examine them with gst_harness_pull() and
* gst_harness_pull_event().
*
* <example>
* <title>A simple buffer-in buffer-out example</title>
* <programlisting language="c">
* #include &lt;gst/gst.h&gt;
* #include &lt;gst/check/gstharness.h&gt;
* ## A simple buffer-in buffer-out example
*
* |[<!-- language="C" -->
* #include <gst/gst.h>
* #include <gst/check/gstharness.h>
* GstHarness *h;
* GstBuffer *in_buf;
* GstBuffer *out_buf;
@ -85,8 +86,7 @@
* gst_buffer_unref (out_buf);
* gst_harness_teardown (h);
*
* </programlisting>
* </example>
* ]|
*
* Another main feature of the #GstHarness is its integration with the
* #GstTestClock. Operating the #GstTestClock can be very challenging, but
@ -104,20 +104,16 @@
* src-element (videotestsrc) and an encoder (vp8enc) to feed the decoder data
* with different configurations, by simply doing:
*
* <example>
* <programlisting language="c">
* |[<!-- language="C" -->
* GstHarness * h = gst_harness_new (h, "vp8dec");
* gst_harness_add_src_parse (h, "videotestsrc is-live=1 ! vp8enc", TRUE);
* </programlisting>
* </example>
* ]|
*
* and then feeding it data with:
*
* <example>
* <programlisting language="c">
* |[<!-- language="C" -->
* gst_harness_push_from_src (h);
* </programlisting>
* </example>
* ]|
*
*/
#ifdef HAVE_CONFIG_H

29
libs/gst/check/gsttestclock.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gsttestclock
* @title: GstTestClock
* @short_description: Controllable, deterministic clock for GStreamer unit tests
* @see_also: #GstSystemClock, #GstClock
*
@ -34,11 +35,11 @@
* precisely advance the time in a deterministic manner, independent of the
* system time or any other external factors.
*
* <example>
* <title>Advancing the time of a #GstTestClock</title>
* <programlisting language="c">
* #include &lt;gst/gst.h&gt;
* #include &lt;gst/check/gsttestclock.h&gt;
* ## Advancing the time of a #GstTestClock
*
* |[<!-- language="C" -->
* #include <gst/gst.h>
* #include <gst/check/gsttestclock.h>
*
* GstClock *clock;
* GstTestClock *test_clock;
@ -53,8 +54,7 @@
* gst_test_clock_set_time (test_clock, 42 * GST_SECOND);
* GST_INFO ("Time: %" GST_TIME_FORMAT, GST_TIME_ARGS (gst_clock_get_time (clock)));
* ...
* </programlisting>
* </example>
* ]|
*
* #GstClock allows for setting up single shot or periodic clock notifications
* as well as waiting for these notifications synchronously (using
@ -93,12 +93,12 @@
* second buffer will arrive a little late (7ms) due to simulated jitter in the
* clock notification.
*
* <example>
* <title>Demonstration of how to work with clock notifications and #GstTestClock</title>
* <programlisting language="c">
* #include &lt;gst/gst.h&gt;
* #include &lt;gst/check/gstcheck.h&gt;
* #include &lt;gst/check/gsttestclock.h&gt;
* ## Demonstration of how to work with clock notifications and #GstTestClock
*
* |[<!-- language="C" -->
* #include <gst/gst.h>
* #include <gst/check/gstcheck.h>
* #include <gst/check/gsttestclock.h>
*
* GstClockTime latency;
* GstElement *element;
@ -166,8 +166,7 @@
* GST_INFO ("Check that element does not wait for any clock notification\n");
* g_assert (!gst_test_clock_peek_next_pending_id (test_clock, NULL));
* ...
* </programlisting>
* </example>
* ]|
*
* Since #GstTestClock is only supposed to be used in unit tests it calls
* g_assert(), g_assert_cmpint() or g_assert_cmpuint() to validate all function

1
libs/gst/controller/gstargbcontrolbinding.c
View file

@ -22,6 +22,7 @@
*/
/**
* SECTION:gstargbcontrolbinding
* @title: GstARGBControlBinding
* @short_description: attachment for control sources to argb properties
*
* A value mapping object that attaches multiple control sources to a guint

1
libs/gst/controller/gstdirectcontrolbinding.c
View file

@ -21,6 +21,7 @@
*/
/**
* SECTION:gstdirectcontrolbinding
* @title: GstDirectControlBinding
* @short_description: direct attachment for control sources
*
* A value mapping object that attaches control sources to gobject properties. It

1
libs/gst/controller/gstinterpolationcontrolsource.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstinterpolationcontrolsource
* @title: GstInterpolationControlSource
* @short_description: interpolation control source
*
* #GstInterpolationControlSource is a #GstControlSource, that interpolates values between user-given

1
libs/gst/controller/gstlfocontrolsource.c
View file

@ -23,6 +23,7 @@
/**
* SECTION:gstlfocontrolsource
* @title: GstLFOControlSource
* @short_description: LFO control source
*
* #GstLFOControlSource is a #GstControlSource, that provides several periodic

1
libs/gst/controller/gstproxycontrolbinding.c
View file

@ -19,6 +19,7 @@
*/
/**
* SECTION:gstproxycontrolbinding
* @title: GstProxyControlBinding
* @short_description: attachment for forwarding control sources
* @see_also: #GstControlBinding
*

1
libs/gst/controller/gsttimedvaluecontrolsource.c
View file

@ -24,6 +24,7 @@
/**
* SECTION:gsttimedvaluecontrolsource
* @title: GstTimedValueControlSource
* @short_description: timed value control source base class
*
* Base class for #GstControlSource that use time-stamped values.

Some files were not shown because too many files have changed in this diff Show more