mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-11-30 05:31:15 +00:00
Code Issues 1 Projects Releases Wiki Activity

Documentation updates.

Browse source 
Original commit message from CVS:
Documentation updates.
This commit is contained in:
Thomas Vander Stichele 2005-10-28 17:35:43 +00:00
parent 55bf3d095b
commit 4a8451a360
4 changed files with 99 additions and 85 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
ChangeLog
View file

@ -1,3 +1,10 @@
2005-10-28 Thomas Vander Stichele <thomas at apestaart dot org>
* gst/gstbin.c: (gst_bin_class_init):
* gst/gstbin.h:
* gst/gstutils.c:
Documentation updates.
2005-10-28 Wim Taymans <wim@fluendo.com> 2005-10-28 Wim Taymans <wim@fluendo.com>
* docs/gst/gstreamer-sections.txt: * docs/gst/gstreamer-sections.txt:

149
gst/gstbin.c
View file

@ -52,7 +52,7 @@
* bin. Likewise the "element_removed" signal is fired whenever an element is * bin. Likewise the "element_removed" signal is fired whenever an element is
* removed from the bin. * removed from the bin.
* *
* A GstBin internally interceps all #GstMessage posted by its children and * A GstBin internally intercepts all #GstMessage posted by its children and
* implements the following default behaviour for each of them. * implements the following default behaviour for each of them.
* *
* GST_MESSAGE_EOS: This message is only posted by sinks * GST_MESSAGE_EOS: This message is only posted by sinks
@ -82,6 +82,8 @@
* no sink is in the bin, the query fails. * no sink is in the bin, the query fails.
* *
* gst_object_unref() is used to destroy the bin. * gst_object_unref() is used to destroy the bin.
*
* Last reviewed on 2005-10-28 (0.9.4)
*/ */
#include "gst_private.h" #include "gst_private.h"
@ -264,8 +266,8 @@ gst_bin_class_init (GstBinClass * klass)
/** /**
* GstBin::element-added: * GstBin::element-added:
* @bin: the object which emitted the signal. * @bin: the #GstBin
* @element: the element that was added to the bin * @element: the #GstElement that was added to the bin
* *
* Will be emitted if a new element was removed/added to this bin. * Will be emitted if a new element was removed/added to this bin.
*/ */
@ -275,8 +277,8 @@ gst_bin_class_init (GstBinClass * klass)
NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_ELEMENT); NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_ELEMENT);
/** /**
* GstBin::element-removed: * GstBin::element-removed:
* @bin: the object which emitted the signal. * @bin: #GstBin
* @element: the element that was removed from the bin * @element: the #GstElement that was removed from the bin
* *
* Will be emitted if an element was removed from this bin. * Will be emitted if an element was removed from this bin.
*/ */
@ -340,11 +342,11 @@ gst_bin_init (GstBin * bin)
/** /**
* gst_bin_new: * gst_bin_new:
* @name: name of new bin * @name: the name of the new bin
* *
* Create a new bin with given name. * Creates a new bin with the given name.
* *
* Returns: new bin * Returns: a new #GstBin
*/ */
GstElement * GstElement *
gst_bin_new (const gchar * name) gst_bin_new (const gchar * name)
@ -695,8 +697,8 @@ had_parent:
/** /**
* gst_bin_add: * gst_bin_add:
* @bin: #GstBin to add element to * @bin: a #GstBin
* @element: #GstElement to add to bin * @element: the #GstElement to add to the bin
* *
* Adds the given element to the bin. Sets the element's parent, and thus * Adds the given element to the bin. Sets the element's parent, and thus
* takes ownership of the element. An element can only be added to one bin. * takes ownership of the element. An element can only be added to one bin.
@ -706,7 +708,7 @@ had_parent:
* *
* MT safe. * MT safe.
* *
* Returns: TRUE if the element could be added, FALSE on wrong parameters or * Returns: TRUE if the element could be added, FALSE if
* the bin does not want to accept the element. * the bin does not want to accept the element.
*/ */
gboolean gboolean
@ -845,10 +847,10 @@ already_removing:
/** /**
* gst_bin_remove: * gst_bin_remove:
* @bin: #GstBin to remove element from * @bin: a #GstBin
* @element: #GstElement to remove * @element: the #GstElement to remove
* *
* Remove the element from its associated bin, unparenting it as well. * Removes the element from the bin, unparenting it as well.
* Unparenting the element means that the element will be dereferenced, * Unparenting the element means that the element will be dereferenced,
* so if the bin holds the only reference to the element, the element * so if the bin holds the only reference to the element, the element
* will be freed in the process of removing it from the bin. If you * will be freed in the process of removing it from the bin. If you
@ -860,7 +862,7 @@ already_removing:
* *
* MT safe. * MT safe.
* *
* Returns: TRUE if the element could be removed, FALSE on wrong parameters or * Returns: TRUE if the element could be removed, FALSE if
* the bin does not want to remove the element. * the bin does not want to remove the element.
*/ */
gboolean gboolean
@ -902,16 +904,16 @@ iterate_child (GstIterator * it, GstElement * child)
/** /**
* gst_bin_iterate_elements: * gst_bin_iterate_elements:
* @bin: #Gstbin to iterate the elements of * @bin: a #GstBin
* *
* Get an iterator for the elements in this bin. * Gets an iterator for the elements in this bin.
* Each element will have its refcount increased, so unref
* after use.
* *
* MT safe. * Each element yielded by the iterator will have its refcount increased, so
* unref after use.
* *
* Returns: a #GstIterator of #GstElements. gst_iterator_free after * MT safe. Caller owns returned value.
* use. returns NULL when passing bad parameters. *
* Returns: a #GstIterator of #GstElement, or NULL
*/ */
GstIterator * GstIterator *
gst_bin_iterate_elements (GstBin * bin) gst_bin_iterate_elements (GstBin * bin)
@ -951,16 +953,17 @@ iterate_child_recurse (GstIterator * it, GstElement * child)
/** /**
* gst_bin_iterate_recurse: * gst_bin_iterate_recurse:
* @bin: #Gstbin to iterate the elements of * @bin: a #GstBin
* *
* Get an iterator for the elements in this bin. * Gets an iterator for the elements in this bin.
* Each element will have its refcount increased, so unref * This iterator recurses into GstBin children.
* after use. This iterator recurses into GstBin children.
* *
* MT safe. * Each element yielded by the iterator will have its refcount increased, so
* unref after use.
* *
* Returns: a #GstIterator of #GstElements. gst_iterator_free after * MT safe. Caller owns returned value.
* use. returns NULL when passing bad parameters. *
* Returns: a #GstIterator of #GstElement, or NULL
*/ */
GstIterator * GstIterator *
gst_bin_iterate_recurse (GstBin * bin) gst_bin_iterate_recurse (GstBin * bin)
@ -1021,17 +1024,17 @@ sink_iterator_filter (GstElement * child, GstBin * bin)
/** /**
* gst_bin_iterate_sinks: * gst_bin_iterate_sinks:
* @bin: #Gstbin to iterate on * @bin: a #GstBin
* *
* Get an iterator for the sink elements in this bin. * Gets an iterator for all elements in the bin that have the
* Each element will have its refcount increased, so unref * #GST_ELEMENT_IS_SINK flag set.
* after use.
* *
* The sink elements are those with the GST_ELEMENT_IS_SINK flag set. * Each element yielded by the iterator will have its refcount increased, so
* unref after use.
* *
* MT safe. * MT safe. Caller owns returned value.
* *
* Returns: a #GstIterator of #GstElements. gst_iterator_free after use. * Returns: a #GstIterator of #GstElement, or NULL
*/ */
GstIterator * GstIterator *
gst_bin_iterate_sinks (GstBin * bin) gst_bin_iterate_sinks (GstBin * bin)
@ -1460,21 +1463,21 @@ gst_bin_sort_iterator_free (GstBinSortIterator * bit)
/** /**
* gst_bin_iterate_sorted: * gst_bin_iterate_sorted:
* @bin: #Gstbin to iterate on * @bin: a #GstBin
* *
* Get an iterator for the elements in this bin in topologically * Gets an iterator for the elements in this bin in topologically
* sorted order. This means that the elements are returned from * sorted order. This means that the elements are returned from
* the most downstream elements (sinks) to the sources. * the most downstream elements (sinks) to the sources.
* *
* This function is used internally to perform the state changes * This function is used internally to perform the state changes
* of the bin elements. * of the bin elements.
* *
* Each element will have its refcount increased, so unref * Each element yielded by the iterator will have its refcount increased, so
* after use. * unref after use.
* *
* MT safe. * MT safe. Caller owns returned value.
* *
* Returns: a #GstIterator of #GstElements. gst_iterator_free after use. * Returns: a #GstIterator of #GstElement, or NULL
*/ */
GstIterator * GstIterator *
gst_bin_iterate_sorted (GstBin * bin) gst_bin_iterate_sorted (GstBin * bin)
@ -2072,17 +2075,17 @@ compare_name (GstElement * element, const gchar * name)
/** /**
* gst_bin_get_by_name: * gst_bin_get_by_name:
* @bin: #Gstbin to search * @bin: a #GstBin
* @name: the element name to search for * @name: the element name to search for
* *
* Get the element with the given name from this bin. This * Gets the element with the given name from a bin. This
* function recurses into subbins. * function recurses into child bins.
* *
* MT safe. * Returns NULL if no element with the given name is found in the bin.
* *
* Returns: the element with the given name. Returns NULL if the * MT safe. Caller owns returned reference.
* element is not found or when bad parameters were given. Unref after *
* use. * Returns: the #GstElement with the given name, or NULL
*/ */
GstElement * GstElement *
gst_bin_get_by_name (GstBin * bin, const gchar * name) gst_bin_get_by_name (GstBin * bin, const gchar * name)
@ -2105,16 +2108,18 @@ gst_bin_get_by_name (GstBin * bin, const gchar * name)
/** /**
* gst_bin_get_by_name_recurse_up: * gst_bin_get_by_name_recurse_up:
* @bin: #Gstbin to search * @bin: a #GstBin
* @name: the element name to search for * @name: the element name to search for
* *
* MT safe. * Gets the element with the given name from this bin. If the
*
* Get the element with the given name from this bin. If the
* element is not found, a recursion is performed on the parent bin. * element is not found, a recursion is performed on the parent bin.
* *
* Returns: the element with the given name or NULL when the element * Returns NULL if:
* was not found or bad parameters were given. Unref after use. * - no element with the given name is found in the bin
*
* MT safe. Caller owns returned reference.
*
* Returns: the #GstElement with the given name, or NULL
*/ */
GstElement * GstElement *
gst_bin_get_by_name_recurse_up (GstBin * bin, const gchar * name) gst_bin_get_by_name_recurse_up (GstBin * bin, const gchar * name)
@ -2159,19 +2164,18 @@ compare_interface (GstElement * element, gpointer interface)
/** /**
* gst_bin_get_by_interface: * gst_bin_get_by_interface:
* @bin: bin to find element in * @bin: a #GstBin
* @interface: interface to be implemented by interface * @interface: the #GType of an interface
* *
* Looks for the first element inside the bin that implements the given * Looks for an element inside the bin that implements the given
* interface. If such an element is found, it returns the element. You can * interface. If such an element is found, it returns the element.
* cast this element to the given interface afterwards. * You can cast this element to the given interface afterwards. If you want
* If you want all elements that implement the interface, use * all elements that implement the interface, use
* gst_bin_iterate_all_by_interface(). The function recurses inside bins. * gst_bin_iterate_all_by_interface(). This function recurses into child bins.
* *
* MT safe. * MT safe. Caller owns returned reference.
* *
* Returns: An #GstElement inside the bin implementing the interface. * Returns: A #GstElement inside the bin implementing the interface
* Unref after use.
*/ */
GstElement * GstElement *
gst_bin_get_by_interface (GstBin * bin, GType interface) gst_bin_get_by_interface (GstBin * bin, GType interface)
@ -2191,18 +2195,21 @@ gst_bin_get_by_interface (GstBin * bin, GType interface)
/** /**
* gst_bin_iterate_all_by_interface: * gst_bin_iterate_all_by_interface:
* @bin: bin to find elements in * @bin: a #GstBin
* @interface: interface to be implemented by interface * @interface: the #GType of an interface
* *
* Looks for all elements inside the bin that implements the given * Looks for all elements inside the bin that implements the given
* interface. You can safely cast all returned elements to the given interface. * interface. You can safely cast all returned elements to the given interface.
* The function recurses bins inside bins. The iterator will return a series * The function recurses inside child bins. The iterator will yield a series
* of #GstElement that should be unreffed after use. * of #GstElement that should be unreffed after use.
* *
* MT safe. * Each element yielded by the iterator will have its refcount increased, so
* unref after use.
* *
* Returns: A #GstIterator for the elements inside the bin implementing the * MT safe. Caller owns returned value.
* given interface. *
* Returns: a #GstIterator of #GstElement for all elements in the bin
* implementing the given interface, or NULL
*/ */
GstIterator * GstIterator *
gst_bin_iterate_all_by_interface (GstBin * bin, GType interface) gst_bin_iterate_all_by_interface (GstBin * bin, GType interface)

10
gst/gstbin.h
View file

@ -57,21 +57,21 @@ typedef struct _GstBinClass GstBinClass;
/** /**
* GST_BIN_NUMCHILDREN: * GST_BIN_NUMCHILDREN:
* @bin: the bin to get the number of children from * @bin: a #GstBin
* *
* Gets the number of children a bin manages. * Gets the number of children in a bin.
*/ */
#define GST_BIN_NUMCHILDREN(bin) (GST_BIN_CAST(bin)->numchildren) #define GST_BIN_NUMCHILDREN(bin) (GST_BIN_CAST(bin)->numchildren)
/** /**
* GST_BIN_CHILDREN: * GST_BIN_CHILDREN:
* @bin: the bin to get the list with children from * @bin: a #GstBin
* *
* Gets the list with children a bin manages. * Gets the list with children in a bin.
*/ */
#define GST_BIN_CHILDREN(bin) (GST_BIN_CAST(bin)->children) #define GST_BIN_CHILDREN(bin) (GST_BIN_CAST(bin)->children)
/** /**
* GST_BIN_CHILDREN_COOKIE: * GST_BIN_CHILDREN_COOKIE:
* @bin: the bin to get the children cookie from * @bin: a #GstBin
* *
* Gets the children cookie that watches the children list. * Gets the children cookie that watches the children list.
*/ */

8
gst/gstutils.c
View file

@ -1971,8 +1971,8 @@ g_static_rec_cond_wait (GCond * cond, GStaticRecMutex * mutex)
/** /**
* gst_bin_add_many: * gst_bin_add_many:
* @bin: the bin to add the elements to * @bin: a #GstBin
* @element_1: the first element to add to the bin * @element_1: the #GstElement element to add to the bin
* @...: additional elements to add to the bin * @...: additional elements to add to the bin
* *
* Adds a NULL-terminated list of elements to a bin. This function is * Adds a NULL-terminated list of elements to a bin. This function is
@ -1999,8 +1999,8 @@ gst_bin_add_many (GstBin * bin, GstElement * element_1, ...)
/** /**
* gst_bin_remove_many: * gst_bin_remove_many:
* @bin: the bin to remove the elements from * @bin: a #GstBin
* @element_1: the first element to remove from the bin * @element_1: the first #GstElement to remove from the bin
* @...: NULL-terminated list of elements to remove from the bin * @...: NULL-terminated list of elements to remove from the bin
* *
* Remove a list of elements from a bin. This function is equivalent * Remove a list of elements from a bin. This function is equivalent