Modernizing our documentation and preparing a possible move to hotdoc.
This commits also adds missing @title metadatas to all SECTIONs
/**
* SECTION:gst
+ * @title: GStreamer
* @short_description: Media library supporting arbitrary formats and filter
* graphs.
*
* 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[])
* {
* gst_init (&argc, &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
* 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"
* <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
* 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)
/**
* SECTION:gstallocator
+ * @title: GstAllocator
* @short_description: allocate memory blocks
* @see_also: #GstMemory
*
/**
* 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
* 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
* 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"
* 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.
*
/**
* SECTION:gstbuffer
+ * @title: GstBuffer
* @short_description: Data-passing buffer type
* @see_also: #GstPad, #GstMiniObject, #GstMemory, #GstMeta, #GstBufferPool
*
/**
* SECTION:gstbufferlist
+ * @title: GstBufferList
* @short_description: Lists of buffers for data-passing
* @see_also: #GstPad, #GstMiniObject
*
/**
* SECTION:gstbufferpool
+ * @title: GstBufferPool
* @short_description: Pool for buffers
* @see_also: #GstBuffer
*
*
* 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,
}
} 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
* @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)
/**
* SECTION:gstbus
+ * @title: GstBus
* @short_description: Asynchronous message bus subsystem
* @see_also: #GstMessage, #GstElement
*
/**
* SECTION:gstcaps
+ * @title: GstCaps
* @short_description: Structure describing sets of media formats
* @see_also: #GstStructure, #GstMiniObject
*
* @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
*/
/**
* 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
/**
* SECTION:gstchildproxy
+ * @title: GstChildProxy
* @short_description: Interface for multi child elements.
* @see_also: #GstBin
*
/**
* SECTION:gstclock
+ * @title: GstClock
* @short_description: Abstract class for global clocks
* @see_also: #GstSystemClock, #GstPipeline
*
* 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
* 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.
* @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.
* @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
* 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.
/**
* 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
/**
* 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.
/**
* 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.
/**
* 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
* 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.
*
* 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.
*
*
* 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 { \
#define __GSTCOMPAT_H__
/**
* SECTION:gstcompat
+ * @title: GstCompat
* @short_description: Deprecated API entries
*
* Please do not use these in new code.
/**
* SECTION:gstcontext
+ * @title: GstContext
* @short_description: Lightweight objects to represent element contexts
* @see_also: #GstMiniObject, #GstElement
*
*/
/**
* SECTION:gstcontrolbinding
+ * @title: GstControlBinding
* @short_description: attachment for control source sources
*
* A base class for value mapping objects that attaches control sources to gobject
* 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.
*
/**
* SECTION:gstcontrolsource
+ * @title: GstControlSource
* @short_description: base class for control source sources
*
* The #GstControlSource is a base class for control value sources that could
* 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.
*
/**
* SECTION:gstdevice
+ * @title: GstDevice
* @short_description: Object representing a device
* @see_also: #GstDeviceProvider
*
/**
* SECTION:gstdevicemonitor
+ * @title: GstDeviceMonitor
* @short_description: A device monitor and prober
* @see_also: #GstDevice, #GstDeviceProvider
*
* 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
/**
* SECTION:gstdeviceprovider
+ * @title: GstDeviceProvider
* @short_description: A device provider
* @see_also: #GstDevice, #GstDeviceMonitor
*
* multiple author metadata. E.g: "Joe Bloggs <joe.blogs at foo.com>"
*
* 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
*/
* foo.com>"
*
* 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
/**
* SECTION:gstdeviceproviderfactory
+ * @title: GstDeviceProviderFactory
* @short_description: Create GstDeviceProviders from a factory
* @see_also: #GstDeviceProvider, #GstPlugin, #GstPluginFeature, #GstPadTemplate.
*
/**
* SECTION:gstdynamictypefactory
+ * @title: GstDynamicTypeFactory
* @short_description: Represents a registered dynamically loadable GType
* @see_also: #GstPlugin, #GstPluginFeature.
*
* 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
/**
* SECTION:gstelement
+ * @title: GstElement
* @short_description: Abstract base class for all pipeline elements
* @see_also: #GstElementFactory, #GstPad
*
* @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.
* multiple author metadata. E.g: "Joe Bloggs <joe.blogs at foo.com>"
*
* 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,
* multiple author metadata. E.g: "Joe Bloggs <joe.blogs at foo.com>"
*
* 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
*
* 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.
* @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
/**
* 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 ⇒ %GST_STATE_PLAYING is called an upwards state change
/**
* SECTION:gstelementfactory
+ * @title: GstElementFactory
* @short_description: Create GstElements from a factory
* @see_also: #GstElement, #GstPlugin, #GstPluginFeature, #GstPadTemplate.
*
*
* 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 <gst/gst.h>
*
* GstElement *src;
* src = gst_element_factory_create (srcfactory, "src");
* g_return_if_fail (src != NULL);
* ...
- * </programlisting>
- * </example>
+ * ]|
*/
#include "gst_private.h"
/**
* SECTION:gsterror
+ * @title: GstError
* @short_description: Categorized error messages
* @see_also: #GstMessage
*
*
* 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
/**
* SECTION:gstevent
+ * @title: GstEvent
* @short_description: Structure describing events that are passed up and down
* a pipeline
* @see_also: #GstPad, #GstElement
* ...
* // 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);
*
* 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.
* @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.
*
*
* 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
* @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
*/
/**
* SECTION:gstformat
+ * @title: GstFormat
* @short_description: Dynamically register new data formats
* @see_also: #GstPad, #GstElement
*
/**
* SECTION:gstghostpad
+ * @title: GstGhostPad
* @short_description: Pseudo link pads
* @see_also: #GstPad
*
/**
* 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.
* 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)
* 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,
* 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) \
/**
* SECTION:gstiterator
+ * @title: GstIterator
* @short_description: Object to retrieve multiple elements in a threadsafe
* way.
* @see_also: #GstElement, #GstBin
* 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.
* @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
*
* 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.
*
/**
* SECTION:gstmemory
+ * @title: GstMemory
* @short_description: refcounted wrapper for memory blocks
* @see_also: #GstBuffer
*
/**
* SECTION:gstmessage
+ * @title: GstMessage
* @short_description: Lightweight objects to signal the application of
* pipeline events
* @see_also: #GstBus, #GstMiniObject, #GstElement
* switch (GST_MESSAGE_TYPE (msg)) {
* case GST_MESSAGE_TAG: {
* GstTagList *tags = NULL;
- *
+ *
* gst_message_parse_tag (msg, &tags);
* g_print ("Got tags from element %s\n", GST_OBJECT_NAME (msg->src));
* handle_tags (tags);
/**
* 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
* switch (GST_MESSAGE_TYPE (msg)) {
* case GST_MESSAGE_STATE_CHANGED: {
* GstState old_state, new_state;
- *
+ *
* gst_message_parse_state_changed (msg, &old_state, &new_state, NULL);
* g_print ("Element %s changed state from %s to %s.\n",
* GST_OBJECT_NAME (msg->src),
* case GST_MESSAGE_ERROR: {
* GError *err = NULL;
* gchar *dbg_info = NULL;
- *
+ *
* gst_message_parse_error (msg, &err, &dbg_info);
* g_printerr ("ERROR from element %s: %s\n",
* GST_OBJECT_NAME (msg->src), err->message);
*
* 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.
* @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.
* 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.
*/
* @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.
* @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
*/
* @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
*/
/**
* SECTION:gstmeta
+ * @title: GstMeta
* @short_description: Buffer metadata
*
* The #GstMeta structure should be included as the first member of a #GstBuffer
*/
/**
* 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
/**
* 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
* 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
*
* 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"
*/
/**
* SECTION:gstpad
+ * @title: GstPad
* @short_description: Object contained by elements that allows links to
* other elements
* @see_also: #GstPadTemplate, #GstElement, #GstEvent, #GstQuery, #GstBuffer
* 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 {
/**
* SECTION:gstpadtemplate
+ * @title: GstPadTemplate
* @short_description: Describe the media type of a pad.
* @see_also: #GstPad, #GstElementFactory
*
*/
/**
* SECTION:gstparamspec
+ * @title: GstParamSpec
* @short_description: GParamSpec implementations specific
* to GStreamer
*
/**
* 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
/**
* SECTION:gstpipeline
+ * @title: GstPipeline
* @short_description: Top-level bin with clocking and bus management
functionality.
* @see_also: #GstElement, #GstBin, #GstClock, #GstBus
/**
* SECTION:gstplugin
+ * @title: GstPlugin
* @short_description: Container for features loaded from a shared object module
* @see_also: #GstPluginFeature, #GstElementFactory
*
*
* 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 *
* 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.
*/
/**
* SECTION:gstpluginfeature
+ * @title: GstPluginfeature
* @short_description: Base class for contents of a GstPlugin
* @see_also: #GstPlugin
*
*/
/**
* SECTION:gstpoll
+ * @title: GstPoll
* @short_description: Keep track of file descriptors and make it possible
* to wait on them in a cancellable way
*
* 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
*
*
* 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
*/
/**
* SECTION:gstpreset
+ * @title: GstPreset
* @short_description: helper interface for element presets
*
* This interface offers methods to query and manipulate parameter preset sets.
/**
* SECTION:gstprotection
+ * @title: GstProtection
* @short_description: Functions and classes to support encrypted streams.
*
* The GstProtectionMeta class enables the information needed to decrypt a
/**
* SECTION:gstquery
+ * @title: GstQuery
* @short_description: Provide functions to create queries, and to set and parse
* values in them.
* @see_also: #GstPad, #GstElement
*
* 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.
*/
/**
* SECTION:gstregistry
+ * @title: GstRegistry
* @short_description: Abstract base class for management of #GstPlugin objects
* @see_also: #GstPlugin, #GstPluginFeature
*
*
* 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
* 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
/**
* SECTION:gstsample
+ * @title: GstSample
* @short_description: A media sample
* @see_also: #GstBuffer, #GstCaps, #GstSegment
*
/**
* SECTION:gstsegment
+ * @title: GstSegment
* @short_description: Structure describing the configured region of interest
* in a media file.
* @see_also: #GstEvent
* 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.
/**
* SECTION:gststreamcollection
+ * @title: GstStreamCollection
* @short_description: Base class for collection of streams
*
* Since: 1.10
/**
* 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
/**
* SECTION:gststructure
+ * @title: GstStructure
* @short_description: Generic structure containing fields of names and values
* @see_also: #GstCaps, #GstMessage, #GstEvent, #GstQuery
*
/**
* SECTION:gstsystemclock
+ * @title: GstSystemClock
* @short_description: Default clock that uses the current system time
* @see_also: #GstClock
*
/**
* 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.
/**
* SECTION:gsttagsetter
+ * @title: GstTagsetter
* @short_description: Element interface that allows setting and retrieval
* of media metadata
*
* 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
* 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:
* 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);
* ]|
*/
/**
* SECTION:gsttask
+ * @title: GstTask
* @short_description: Abstraction of GStreamer streaming threads.
* @see_also: #GstElement, #GstPad
*
/**
* SECTION:gsttaskpool
+ * @title: GstTaskPool
* @short_description: Pool of GStreamer streaming threads
* @see_also: #GstTask, #GstPad
*
* @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
/**
* SECTION:gsttoc
+ * @title: GstToc
* @short_description: Generic table of contents support
* @see_also: #GstStructure, #GstEvent, #GstMessage, #GstQuery
*
/**
* SECTION:gsttocsetter
+ * @title: GstTocSetter
* @short_description: Element interface that allows setting and retrieval
* of the TOC
*
*
* 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.
* 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
*/
/**
* SECTION:gsttracer
+ * @title: GstTracer
* @short_description: Tracing base class
*
* Tracing modules will subclass #GstTracer and register through
/**
* 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
/**
* SECTION:gsttracerrecord
+ * @title: GstTracerRecord
* @short_description: Trace log entry class
*
* Tracing modules will create instances of this class to announce the data they
* 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
*/
*
* 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, ...)
/**
* SECTION:gsttypefind
+ * @title: GstTypefind
* @short_description: Stream type detection
*
* The following functions allow you to detect the media type of an unknown
/**
* SECTION:gsttypefindfactory
+ * @title: GstTypeFindFactory
* @short_description: Information about registered typefind functions
*
* These functions allow querying informations about registered typefind
/**
* 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
/**
* 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
/**
* SECTION:gstutils
+ * @title: GstUtils
* @short_description: Various utility functions
*
*/
* %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
*
/**
* SECTION:gstvalue
+ * @title: GstValue
* @short_description: GValue implementations specific
* to GStreamer
*
*
* 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))
* 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)))
*
* 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"
/**
* 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.
* 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);
* // -> 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,
/**
* SECTION:gstbaseparse
+ * @title: GstBaseParse
* @short_description: Base class for stream parsers
* @see_also: #GstBaseTransform
*
* 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
* 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.
*
*/
/**
* SECTION:gstbasesink
+ * @title: GstBaseSink
* @short_description: Base class for sink elements
* @see_also: #GstBaseTransform, #GstBaseSrc
*
* "Sink name",
* "Sink",
* "My Sink element",
- * "The author <my.sink@my.email>");
+ * "The author <my.sink@my.email>");
* }
* ]|
*
* 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.
*
* 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)
* 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.
}
} 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
/**
* 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
*
* #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.
* "Source name",
* "Source",
* "My Source element",
- * "The author <my.sink@my.email>");
+ * "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
* 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
/**
* SECTION:gstbasetransform
+ * @title: GstBaseTransform
* @short_description: Base class for simple transform filters
* @see_also: #GstBaseSrc, #GstBaseSink
*
* 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
/* 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
*
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);
*
* 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.
*/
* 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
/**
* 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
/**
* SECTION:gstbytereader
+ * @title: GstByteReader
* @short_description: Reads different integer, string and floating point
* types from a memory buffer
*
* position if at least @size bytes are left and
* updates the current position.
*
- *
* Returns: %TRUE if successful, %FALSE otherwise.
*/
gboolean
* position if at least @size bytes are left and
* keeps the current position.
*
- *
* Returns: %TRUE if successful, %FALSE otherwise.
*/
gboolean
* 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);
* // -> 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,
/**
* SECTION:gstbytewriter
+ * @title: GstByteWriter
* @short_description: Writes different integer, string and floating point
* types to a memory buffer and allows reading
*
*/
/**
* 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
* 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)
/**
* SECTION:gstdataqueue
+ * @title: GstDataQueue
* @short_description: Threadsafe queueing object
*
* #GstDataQueue is an object that handles threadsafe queueing of objects. It
* 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.
* @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.
*
/**
* SECTION:gstflowcombiner
+ * @title: GstFlowCombiner
* @short_description: Utility to combine multiple flow returns into one
*
* Utility struct to help handling #GstFlowReturn combination. Useful for
* Boston, MA 02110-1301, USA.
*/
-/*
+/**
* SECTION:gstindex
+ * @title: GstIndexEntry
* @short_description: Generate indexes on objects
* @see_also: #GstIndexFactory
*
* 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.
*/
/**
* SECTION:gstpushsrc
+ * @title: GstPushSrc
* @short_description: Base class for push based source elements
* @see_also: #GstBaseSrc
*
/**
* SECTION:gstqueuearray
+ * @title: GstQueueArray
* @short_description: Array based queue object
*
* #GstQueueArray is an object that provides standard queue functionality
/**
* 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
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)) {
/**
* 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
*/
/**
* 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
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;
typedef struct
{
- const gchar * domain;
- const gchar * message;
+ const gchar *domain;
+ const gchar *message;
GLogLevelFlags level;
gboolean discard;
} LogFilterApplyData;
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;
/**
* 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
/**
* SECTION:gstharness
+ * @title: GstHarness
* @short_description: A test-harness for writing GStreamer unit tests
* @see_also: #GstTestClock,\
*
* The basic structure of #GstHarness is two "floating" #GstPads that connect
* to the harnessed #GstElement src and sink #GstPads like so:
*
- * <programlisting>
+ * |[
* __________________________
* _____ | _____ _____ | _____
* | | | | | | | | | |
* |_____| | |_____| |_____| | |_____|
* |__________________________|
*
- * </programlisting>
+ * ]|
*
* With this, you can now simulate any environment the #GstElement might find
* itself in. By specifying the #GstCaps of the harness #GstPads, using
* 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 <gst/gst.h>
- * #include <gst/check/gstharness.h>
+ * ## 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;
* 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
* 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
/**
* SECTION:gsttestclock
+ * @title: GstTestClock
* @short_description: Controllable, deterministic clock for GStreamer unit tests
* @see_also: #GstSystemClock, #GstClock
*
* 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 <gst/gst.h>
- * #include <gst/check/gsttestclock.h>
+ * ## Advancing the time of a #GstTestClock
+ *
+ * |[<!-- language="C" -->
+ * #include <gst/gst.h>
+ * #include <gst/check/gsttestclock.h>
*
* GstClock *clock;
* GstTestClock *test_clock;
* 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
* 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 <gst/gst.h>
- * #include <gst/check/gstcheck.h>
- * #include <gst/check/gsttestclock.h>
+ * ## 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;
* 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
*/
/**
* 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
*/
/**
* SECTION:gstdirectcontrolbinding
+ * @title: GstDirectControlBinding
* @short_description: direct attachment for control sources
*
* A value mapping object that attaches control sources to gobject properties. It
/**
* SECTION:gstinterpolationcontrolsource
+ * @title: GstInterpolationControlSource
* @short_description: interpolation control source
*
* #GstInterpolationControlSource is a #GstControlSource, that interpolates values between user-given
/**
* SECTION:gstlfocontrolsource
+ * @title: GstLFOControlSource
* @short_description: LFO control source
*
* #GstLFOControlSource is a #GstControlSource, that provides several periodic
*/
/**
* SECTION:gstproxycontrolbinding
+ * @title: GstProxyControlBinding
* @short_description: attachment for forwarding control sources
* @see_also: #GstControlBinding
*
/**
* SECTION:gsttimedvaluecontrolsource
+ * @title: GstTimedValueControlSource
* @short_description: timed value control source base class
*
* Base class for #GstControlSource that use time-stamped values.
/**
* SECTION:gsttriggercontrolsource
+ * @title: GstTriggerControlSource
* @short_description: trigger control source
*
* #GstTriggerControlSource is a #GstControlSource, that returns values from user-given
/**
* SECTION:gstnetaddressmeta
+ * @title: GstNetAddressMeta
* @short_description: Network address metadata
*
* #GstNetAddressMeta can be used to store a network address (a #GSocketAddress)
*/
/**
* SECTION:gstnetclientclock
+ * @title: GstNetClientClock
* @short_description: Special clock that synchronizes to a remote time
* provider.
* @see_also: #GstClock, #GstNetTimeProvider, #GstPipeline
* @base_time: initial time of the clock
*
* Create a new #GstNetClientInternalClock that will report the time
- * provided by the #GstNetTimeProvider on @remote_address and
+ * provided by the #GstNetTimeProvider on @remote_address and
* @remote_port.
*
* Returns: a new #GstClock that receives a time from the remote
/**
* SECTION:gstnetcontrolmessagemeta
+ * @title: GstNetControlMessageMeta
* @short_description: Network Control Message Meta
*
* #GstNetControlMessageMeta can be used to store control messages (ancillary
*/
/**
* SECTION:gstnettimepacket
+ * @title: GstNetTimePacket
* @short_description: Helper structure to construct clock packets used
* by network clocks.
* @see_also: #GstClock, #GstNetClientClock, #GstNetTimeProvider
*/
/**
* SECTION:gstnettimeprovider
+ * @title: GstNetTimeProvider
* @short_description: Special object that exposed the time of a clock
* on the network.
* @see_also: #GstClock, #GstNetClientClock, #GstPipeline
*/
/**
* SECTION:gstptpclock
+ * @title: GstPtpClock
* @short_description: Special clock that synchronizes to a remote time
* provider via PTP (IEEE1588:2008).
* @see_also: #GstClock, #GstNetClientClock, #GstPipeline
* check this, you can use gst_clock_wait_for_sync(), the GstClock::synced
* signal and gst_clock_is_synced().
*
- *
* To gather statistics about the PTP clock synchronization,
* gst_ptp_statistics_callback_add() can be used. This gives the application
* the possibility to collect all kinds of statistics from the clock
* If @clock_id is %GST_PTP_CLOCK_ID_NONE, a clock id is automatically
* generated from the MAC address of the first network interface.
*
- *
* This function is automatically called by gst_ptp_clock_new() with default
* parameters if it wasn't called before.
*
* If gst_ptp_init() was not called before, this will call gst_ptp_init() with
* default parameters.
*
- *
* This clock only returns valid timestamps after it received the first
* times from the PTP master clock on the network. Once this happens the
* GstPtpClock::internal-clock property will become non-NULL. You can
*/
/**
* SECTION:element-capsfilter
+ * @title: capsfilter
*
* The element does not modify data as such, but can enforce limitations on the
* data format.
*
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
* |[
* gst-launch-1.0 videotestsrc ! capsfilter caps=video/x-raw,format=GRAY8 ! videoconvert ! autovideosink
* ]| Limits acceptable video from videotestsrc to be grayscale. Equivalent to
* |[
* gst-launch-1.0 videotestsrc ! video/x-raw,format=GRAY8 ! videoconvert ! autovideosink
* ]| which is a short notation for the capsfilter element.
- * </refsect2>
+ *
*/
#ifdef HAVE_CONFIG_H
*/
/**
* SECTION:element-concat
+ * @title: concat
* @see_also: #GstFunnel
*
* Concatenates streams together to one continous stream.
* another downstream element like a streamsynchronizer adjusts the base
* values on its own). The adjust-base property can be used for this purpose.
*
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
* |[
* gst-launch-1.0 concat name=c ! xvimagesink videotestsrc num-buffers=100 ! c. videotestsrc num-buffers=100 pattern=ball ! c.
* ]| Plays two video streams one after another.
- * </refsect2>
+ *
*/
#ifdef HAVE_CONFIG_H
/**
* SECTION:element-dataurisrc
+ * @title: dataurisrc
*
- * dataurisrc handles data: URIs, see <ulink url="http://tools.ietf.org/html/rfc2397">RFC 2397</ulink> for more information.
+ * dataurisrc handles data: URIs, see [RFC 2397](http://tools.ietf.org/html/rfc2397) for more information.
+ *
+ * ## Example launch line
*
- * <refsect2>
- * <title>Example launch line</title>
* |[
* gst-launch-1.0 -v dataurisrc uri="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAfElEQVQ4je2MwQnAIAxFgziA4EnczIsO4MEROo/gzZWc4xdTbe1R6LGRR74heYS7iKElzfcMiRnt4hf8gk8EayB6luefue/HzlJfCA50XsNjYRxprZmenXNIKSGEsC+QUqK1hhgj521BzhnWWiilUGvdF5RS4L2HMQZCCJy8sHMm2TYdJAAAAABJRU5ErkJggg==" ! pngdec ! videoconvert ! imagefreeze ! videoconvert ! autovideosink
- * ]| This pipeline displays a small 16x16 PNG image from the data URI.
- * </refsect2>
+ * ]|
+ *
+ * This pipeline displays a small 16x16 PNG image from the data URI.
*/
#ifdef HAVE_CONFIG_H
/**
* SECTION:element-downloadbuffer
+ * @title: downloadbuffer
*
* The downloadbuffer element provides on-disk buffering and caching of, typically,
* a network file. temp-template should be set to a value such as
* When the downloadbuffer has completely downloaded the media, it will
* post an application message named <classname>"GstCacheDownloadComplete"</classname>
* with the following information:
- * <itemizedlist>
- * <listitem>
- * <para>
+ *
+ * *
* G_TYPE_STRING
* <classname>"location"</classname>:
* the location of the completely downloaded file.
- * </para>
- * </listitem>
- * </itemizedlist>
+ *
*/
#ifdef HAVE_CONFIG_H
*/
/**
* SECTION:element-fakesink
+ * @title: fakesink
* @see_also: #GstFakeSrc
*
* Dummy sink that swallows everything.
- *
- * <refsect2>
- * <title>Example launch line</title>
+ *
+ * ## Example launch line
* |[
* gst-launch-1.0 audiotestsrc num-buffers=1000 ! fakesink sync=false
* ]| Render 1000 audio buffers (of default size) as fast as possible.
- * </refsect2>
+ *
*/
#ifdef HAVE_CONFIG_H
*/
/**
* SECTION:element-fakesrc
+ * @title: fakesrc
* @see_also: #GstFakeSink
*
* The fakesrc element is a multipurpose element that can generate
* It is mostly used as a testing element, one trivial example for testing
* basic <application>GStreamer</application> core functionality is:
*
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
* |[
* gst-launch-1.0 -v fakesrc num-buffers=5 ! fakesink
* ]| This pipeline will push 5 empty buffers to the fakesink element and then
* sends an EOS.
- * </refsect2>
+ *
*/
/* FIXME: this ignores basesrc::blocksize property, which could be used as an
/**
* GstFakeSrcFillType:
- * @FAKE_SRC_FILLTYPE_NOTHING: do not fill buffers
+ * @FAKE_SRC_FILLTYPE_NOTHING: do not fill buffers
* @FAKE_SRC_FILLTYPE_ZERO: fill buffers with 0
* @FAKE_SRC_FILLTYPE_RANDOM: fill buffers with random bytes
* @FAKE_SRC_FILLTYPE_PATTERN: fill buffers with a pattern
/**
* SECTION:element-fdsink
+ * @title: fdsink
* @see_also: #GstFdSrc
*
* Write data to a unix file descriptor.
*/
/**
* SECTION:element-fdsrc
+ * @title: fdsrc
* @see_also: #GstFdSink
*
* Read data from a unix file descriptor.
* if no data was received in the given timeout.
*
* The message's structure contains one field:
- * <itemizedlist>
- * <listitem>
- * <para>
- * #guint64
- * <classname>"timeout"</classname>: the timeout in microseconds that
+ *
+ * * #guint64 `timeout`: the timeout in microseconds that
* expired when waiting for data.
- * </para>
- * </listitem>
- * </itemizedlist>
*
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
* |[
* echo "Hello GStreamer" | gst-launch-1.0 -v fdsrc ! fakesink dump=true
* ]| A simple pipeline to read from the standard input and dump the data
* with a fakesink as hex ascii block.
- * </refsect2>
+ *
*/
#ifdef HAVE_CONFIG_H
*/
/**
* SECTION:element-filesink
+ * @title: filesink
* @see_also: #GstFileSrc
*
* Write incoming data to a file in the local file system.
*
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
* |[
* gst-launch-1.0 v4l2src num-buffers=1 ! jpegenc ! filesink location=capture1.jpeg
* ]| Capture one frame from a v4l2 camera and save as jpeg image.
- * </refsect2>
+ *
*/
#ifdef HAVE_CONFIG_H
*/
/**
* SECTION:element-filesrc
+ * @title: filesrc
* @see_also: #GstFileSrc
*
* Read data from a file in the local file system.
*
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
* |[
* gst-launch-1.0 filesrc location=song.ogg ! decodebin ! audioconvert ! audioresample ! autoaudiosink
* ]| Play song.ogg audio file which must be in the current working directory.
- * </refsect2>
+ *
*/
#ifdef HAVE_CONFIG_H
#ifdef G_OS_WIN32
/* Unfortunately, g_filename_from_uri() doesn't handle some UNC paths
* correctly on windows, it leaves them with an extra backslash
- * at the start if they're of the mozilla-style file://///host/path/file
+ * at the start if they're of the mozilla-style file://///host/path/file
* form. Correct this.
*/
if (location[0] == '\\' && location[1] == '\\' && location[2] == '\\')
/**
* SECTION:element-funnel
+ * @title: funnel
*
* Takes packets from various input sinks into one output source.
*
*/
/**
* SECTION:element-identity
+ * @title: identity
*
* Dummy element that passes incoming data through unmodified. It has some
* useful diagnostic functions, such as offset and timestamp checking.
/**
* SECTION:element-input-selector
+ * @title: input-selector
* @see_also: #GstOutputSelector
*
* Direct one out of N input streams to the output pad.
* The input pads are from a GstPad subclass and have additional
* properties, which users may find useful, namely:
*
- * <itemizedlist>
- * <listitem>
- * "running-time": Running time of stream on pad (#gint64)
- * </listitem>
- * <listitem>
- * "tags": The currently active tags on the pad (#GstTagList, boxed type)
- * </listitem>
- * <listitem>
- * "active": If the pad is currently active (#gboolean)
- * </listitem>
- * <listitem>
- * "always-ok" : Make an inactive pads return #GST_FLOW_OK instead of
+ * * "running-time": Running time of stream on pad (#gint64)
+ * * "tags": The currently active tags on the pad (#GstTagList, boxed type)
+ * * "active": If the pad is currently active (#gboolean)
+ * * "always-ok" : Make an inactive pads return #GST_FLOW_OK instead of
* #GST_FLOW_NOT_LINKED
- * </listitem>
- * </itemizedlist>
+ *
*/
#ifdef HAVE_CONFIG_H
/**
* SECTION:element-multiqueue
+ * @title: multiqueue
* @see_also: #GstQueue
*
- * <refsect2>
- * <para>
* Multiqueue is similar to a normal #GstQueue with the following additional
* features:
- * <orderedlist>
- * <listitem>
- * <itemizedlist><title>Multiple streamhandling</title>
- * <listitem><para>
- * The element handles queueing data on more than one stream at once. To
- * achieve such a feature it has request sink pads (sink%u) and
- * 'sometimes' src pads (src%u).
- * </para><para>
- * When requesting a given sinkpad with gst_element_request_pad(),
- * the associated srcpad for that stream will be created.
- * Example: requesting sink1 will generate src1.
- * </para></listitem>
- * </itemizedlist>
- * </listitem>
- * <listitem>
- * <itemizedlist><title>Non-starvation on multiple streams</title>
- * <listitem><para>
- * If more than one stream is used with the element, the streams' queues
- * will be dynamically grown (up to a limit), in order to ensure that no
- * stream is risking data starvation. This guarantees that at any given
- * time there are at least N bytes queued and available for each individual
- * stream.
- * </para><para>
- * If an EOS event comes through a srcpad, the associated queue will be
- * considered as 'not-empty' in the queue-size-growing algorithm.
- * </para></listitem>
- * </itemizedlist>
- * </listitem>
- * <listitem>
- * <itemizedlist><title>Non-linked srcpads graceful handling</title>
- * <listitem><para>
- * In order to better support dynamic switching between streams, the multiqueue
- * (unlike the current GStreamer queue) continues to push buffers on non-linked
- * pads rather than shutting down.
- * </para><para>
- * In addition, to prevent a non-linked stream from very quickly consuming all
- * available buffers and thus 'racing ahead' of the other streams, the element
- * must ensure that buffers and inlined events for a non-linked stream are pushed
- * in the same order as they were received, relative to the other streams
- * controlled by the element. This means that a buffer cannot be pushed to a
- * non-linked pad any sooner than buffers in any other stream which were received
- * before it.
- * </para></listitem>
- * </itemizedlist>
- * </listitem>
- * </orderedlist>
- * </para>
- * <para>
- * Data is queued until one of the limits specified by the
- * #GstMultiQueue:max-size-buffers, #GstMultiQueue:max-size-bytes and/or
- * #GstMultiQueue:max-size-time properties has been reached. Any attempt to push
- * more buffers into the queue will block the pushing thread until more space
- * becomes available. #GstMultiQueue:extra-size-buffers,
- * </para>
- * <para>
- * #GstMultiQueue:extra-size-bytes and #GstMultiQueue:extra-size-time are
- * currently unused.
- * </para>
- * <para>
- * The default queue size limits are 5 buffers, 10MB of data, or
- * two second worth of data, whichever is reached first. Note that the number
- * of buffers will dynamically grow depending on the fill level of
- * other queues.
- * </para>
- * <para>
- * The #GstMultiQueue::underrun signal is emitted when all of the queues
- * are empty. The #GstMultiQueue::overrun signal is emitted when one of the
- * queues is filled.
- * Both signals are emitted from the context of the streaming thread.
- * </para>
- * <para>
- * When using #GstMultiQueue:sync-by-running-time the unlinked streams will
- * be throttled by the highest running-time of linked streams. This allows
- * further relinking of those unlinked streams without them being in the
- * future (i.e. to achieve gapless playback).
- * When dealing with streams which have got different consumption requirements
- * downstream (ex: video decoders which will consume more buffer (in time) than
- * audio decoders), it is recommended to group streams of the same type
- * by using the pad "group-id" property. This will further throttle streams
- * in time within that group.
- * </para>
- * </refsect2>
+ *
+ * 1) Multiple streamhandling
+ *
+ * * The element handles queueing data on more than one stream at once. To
+ * achieve such a feature it has request sink pads (sink%u) and
+ * 'sometimes' src pads (src%u). When requesting a given sinkpad with gst_element_request_pad(),
+ * the associated srcpad for that stream will be created.
+ * Example: requesting sink1 will generate src1.
+ *
+ * 2) Non-starvation on multiple stream
+ *
+ * * If more than one stream is used with the element, the streams' queues
+ * will be dynamically grown (up to a limit), in order to ensure that no
+ * stream is risking data starvation. This guarantees that at any given
+ * time there are at least N bytes queued and available for each individual
+ * stream. If an EOS event comes through a srcpad, the associated queue will be
+ * considered as 'not-empty' in the queue-size-growing algorithm.
+ *
+ * 3) Non-linked srcpads graceful handling
+ *
+ * * In order to better support dynamic switching between streams, the multiqueue
+ * (unlike the current GStreamer queue) continues to push buffers on non-linked
+ * pads rather than shutting down. In addition, to prevent a non-linked stream from very quickly consuming all
+ * available buffers and thus 'racing ahead' of the other streams, the element
+ * must ensure that buffers and inlined events for a non-linked stream are pushed
+ * in the same order as they were received, relative to the other streams
+ * controlled by the element. This means that a buffer cannot be pushed to a
+ * non-linked pad any sooner than buffers in any other stream which were received
+ * before it.
+ *
+ * Data is queued until one of the limits specified by the
+ * #GstMultiQueue:max-size-buffers, #GstMultiQueue:max-size-bytes and/or
+ * #GstMultiQueue:max-size-time properties has been reached. Any attempt to push
+ * more buffers into the queue will block the pushing thread until more space
+ * becomes available. #GstMultiQueue:extra-size-buffers,
+ *
+ *
+ * #GstMultiQueue:extra-size-bytes and #GstMultiQueue:extra-size-time are
+ * currently unused.
+ *
+ * The default queue size limits are 5 buffers, 10MB of data, or
+ * two second worth of data, whichever is reached first. Note that the number
+ * of buffers will dynamically grow depending on the fill level of
+ * other queues.
+ *
+ * The #GstMultiQueue::underrun signal is emitted when all of the queues
+ * are empty. The #GstMultiQueue::overrun signal is emitted when one of the
+ * queues is filled.
+ * Both signals are emitted from the context of the streaming thread.
+ *
+ * When using #GstMultiQueue:sync-by-running-time the unlinked streams will
+ * be throttled by the highest running-time of linked streams. This allows
+ * further relinking of those unlinked streams without them being in the
+ * future (i.e. to achieve gapless playback).
+ * When dealing with streams which have got different consumption requirements
+ * downstream (ex: video decoders which will consume more buffer (in time) than
+ * audio decoders), it is recommended to group streams of the same type
+ * by using the pad "group-id" property. This will further throttle streams
+ * in time within that group.
*/
#ifdef HAVE_CONFIG_H
* size) is higher than the boundary values which can be set through the
* GObject properties.
*
- * This can be used as an indicator of pre-roll.
+ * This can be used as an indicator of pre-roll.
*/
gst_multi_queue_signals[SIGNAL_OVERRUN] =
g_signal_new ("overrun", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_FIRST,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
/**
- * GstMultiQueue:use-buffering
- *
+ * GstMultiQueue:use-buffering:
+ *
* Enable the buffering option in multiqueue so that BUFFERING messages are
* emitted based on low-/high-percent thresholds.
*/
DEFAULT_USE_BUFFERING, G_PARAM_READWRITE | GST_PARAM_MUTABLE_PLAYING |
G_PARAM_STATIC_STRINGS));
/**
- * GstMultiQueue:low-percent
- *
+ * GstMultiQueue:low-percent:
+ *
* Low threshold percent for buffering to start.
*/
g_object_class_install_property (gobject_class, PROP_LOW_PERCENT,
0, 100, DEFAULT_LOW_WATERMARK * 100,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
/**
- * GstMultiQueue:high-percent
- *
+ * GstMultiQueue:high-percent:
+ *
* High threshold percent for buffering to finish.
*/
g_object_class_install_property (gobject_class, PROP_HIGH_PERCENT,
0, 100, DEFAULT_HIGH_WATERMARK * 100,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
/**
- * GstMultiQueue:low-watermark
+ * GstMultiQueue:low-watermark:
*
* Low threshold watermark for buffering to start.
*
0.0, 1.0, DEFAULT_LOW_WATERMARK,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
/**
- * GstMultiQueue:high-watermark
+ * GstMultiQueue:high-watermark:
*
* High threshold watermark for buffering to finish.
*
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
/**
- * GstMultiQueue:sync-by-running-time
- *
+ * GstMultiQueue:sync-by-running-time:
+ *
* If enabled multiqueue will synchronize deactivated or not-linked streams
* to the activated and linked streams by taking the running time.
* Otherwise multiqueue will synchronize the deactivated or not-linked
/* calculate the diff between running time on the sink and src of the queue.
- * This is the total amount of time in the queue.
+ * This is the total amount of time in the queue.
* WITH LOCK TAKEN */
static void
update_time_level (GstMultiQueue * mq, GstSingleQueue * sq)
{
GST_MULTI_QUEUE_MUTEX_LOCK (mq);
- /* if no timestamp is set, assume it's continuous with the previous
+ /* if no timestamp is set, assume it's continuous with the previous
* time */
if (timestamp == GST_CLOCK_TIME_NONE)
timestamp = segment->position;
lowest = sq->nextid;
} else if (!GST_PAD_IS_EOS (sq->srcpad) && sq->srcresult != GST_FLOW_EOS) {
/* If we don't have a global highid, or the global highid is lower than
- * this single queue's last outputted id, store the queue's one,
+ * this single queue's last outputted id, store the queue's one,
* unless the singlequeue output is at EOS */
if ((highid == G_MAXUINT32) || (sq->oldid > highid))
highid = sq->oldid;
/**
* SECTION:element-output-selector
+ * @title: output-selector
* @see_also: #GstOutputSelector, #GstInputSelector
*
* Direct input stream to one out of N output pads.
/**
* SECTION:element-queue
+ * @title: queue
*
* Data is queued until one of the limits specified by the
* #GstQueue:max-size-buffers, #GstQueue:max-size-bytes and/or
/**
* SECTION:element-queue2
+ * @title: queue2
*
* Data is queued until one of the limits specified by the
* #GstQueue2:max-size-buffers, #GstQueue2:max-size-bytes and/or
/**
* SECTION:element-streamiddemux
+ * @title: streamiddemux
*
* The basic concept was started from de-funneling element which restores one
* serialized stream via #GstFunnel to its original state. #GstStreamidDemux
/**
* SECTION:element-tee
+ * @title: tee
* @see_also: #GstIdentity
*
* Split data to multiple pads. Branching the data flow is useful when e.g.
* provide separate threads for each branch. Otherwise a blocked dataflow in one
* branch would stall the other branches.
*
- * <refsect2>
- * <title>Example launch line</title>
+ * ## Example launch line
* |[
* gst-launch-1.0 filesrc location=song.ogg ! decodebin ! tee name=t ! queue ! audioconvert ! audioresample ! autoaudiosink t. ! queue ! audioconvert ! goom ! videoconvert ! autovideosink
- * ]| Play song.ogg audio file which must be in the current working directory
+ * ]|
+ *
+ * Play song.ogg audio file which must be in the current working directory
* and render visualisations using the goom element (this can be easier done
* using the playbin element, this is just an example pipeline).
- * </refsect2>
*/
#ifdef HAVE_CONFIG_H
*/
/**
* SECTION:element-typefind
+ * @title: typefind
*
* Determines the media-type of a stream. It applies typefind functions in the
* order of their rank. Once the type has been detected it sets its src pad caps
/**
* SECTION:element-valve
+ * @title: valve
*
* The valve is a simple element that drops buffers when the #GstValve:drop
* property is set to %TRUE and lets then through otherwise.
projects / platform / upstream / gstreamer.git / commitdiff