diff --git a/ChangeLog b/ChangeLog index c15e944061..b5c6f5c9d9 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,106 @@ +2004-02-10 Andy Wingo + + * gst/gstpad.c (gst_pad_custom_new): Add a FIXME, this is a hacky + way to do inheritance. + (gst_pad_get_event_masks, gst_pad_get_event_masks_default) + (gst_pad_get_query_types, gst_pad_get_query_types_default): + Routine docs. + (gst_pad_set_link_function, gst_pad_set_fixate_function) + (gst_pad_set_getcaps_function): Doc from Dave's negotation random + doc. + (gst_pad_unlink, gst_pad_is_linked): Docs. + (gst_pad_renegotiate): A brief description of capsnego. + (gst_pad_try_set_caps): Document. + (gst_pad_try_set_caps_nonfixed): Document. + (gst_pad_can_link_filtered, gst_pad_link_filtered): Doc fixes. + (gst_pad_set_parent): Deprecated (although not out of the API). + (gst_pad_get_parent): Deprecated, although many plugins use this. + (gst_pad_add_ghost_pad, gst_pad_remove_ghost_pad): Doc that these + are private and will go away in 0.9. + (gst_pad_perform_negotiate): Doc. + (gst_pad_link_unnegotiate): I think this is meant to be static. + (gst_pad_get_negotiated_caps, gst_pad_get_pad_template_caps) + (gst_pad_template_get_caps_by_name, gst_pad_check_compatibility) + (gst_pad_get_peer): Doc updates. + (gst_pad_caps_change_notify): Doc. + (gst_pad_alloc_buffer, gst_pad_push, gst_static_pad_template_get) + (gst_ghost_pad_new): Doc fixes. + + * gst/gstobject.c (gst_object_get_parent, gst_object_unparent) + (gst_object_check_uniqueness): + + * gst/gstelement.c (gst_element_add_pad) + (gst_element_add_ghost_pad, gst_element_remove_pad) + (gst_element_remove_ghost_pad, gst_element_get_pad) + (gst_element_get_static_pad, gst_element_get_pad_list) + (gst_element_class_get_pad_template_list) + (gst_element_class_get_pad_template): Work on the docs. + (gst_element_get_pad_template_list): Uses the class method. + (gst_element_get_compatible_pad_template): Docs, and consolidate + some test conditions. + (gst_element_get_pad_from_template): New static function. + (gst_element_request_compatible_pad): Docs, and work with + non-request compatible templates. + (gst_element_get_compatible_pad_filtered): Docs and remove + redundant checks. + (gst_element_get_compatible_pad, gst_element_link_pads_filtered) + (gst_element_link_filtered, gst_element_link_many) + (gst_element_link, gst_element_link_pads) + (gst_element_unlink_many): Docs. + +2004-02-05 Andy Wingo + + * gst/gstpad.c (_gst_real_pad_fixate_accumulator): + s/pointer/boxed/. + + * gst/gstmarshal.list (VOID:BOXED, BOXED:BOXED): New marshallers. + + * gst/gstpad.c (gst_real_pad_class_init): Use a BOXED:BOXED + marshaller for ::fixate, and VOID:BOXED for ::caps-nego-failed, + with the type=GST_TYPE_CAPS. This allows language bindings to know + what kind of data they're dealing with. + + * gst/gstcaps.c (_gst_caps_value_init): GBoxed values initialize + to NULL when g_value_init is called. GstCaps, which rolls its own + type implementation, now does the same instead of allocating empty + caps. + (_gst_caps_initialize, _gst_caps_collect_value, + _gst_caps_lcopy_value): Provide collect_value and lcopy_value type + table methods. This allows G_VALUE_COLLECT to work. + +2004-02-05 Andy Wingo + + * configure.ac: + * testsuite/Makefile.am (SUBDIRS): + * testsuite/ghostpads/Makefile.am: + * testsuite/ghostpads/ghostpads.c: A new test for ghost pads. + + * gst/gstpad.c (gst_pad_add_ghost_pad, gst_pad_remove_ghost_pad): + These two routines are the only ones that set + GST_GPAD_REALPAD(gpad), the ghost pad list, and the ghost pad's + pad template. They should be made static, depending on ABI needs. + (gst_real_pad_dispose): Handle the case of ghost pads without a + parent. Assert after dealing with ghost pads that the ghost pad + list is empty. + (gst_ghost_pad_class_init): New property added, ::real-pad. Can be + set after creation. + (gst_ghost_pad_dispose): Set ::real-pad to NULL. + (gst_ghost_pad_set_property, gst_ghost_pad_get_property): New + functions. set_property will call add_ghost_pad/remove_ghost_pad + as appropriate. + (gst_ghost_pad_new): All the work is offloaded to g_object_new. + + * gst/gstelement.c (gst_element_add_pad): Handle ghost pads as well. + (gst_element_add_ghost_pad): Remove code duplicated from _add_pad. + (gst_element_remove_pad): Handle ghost pads as well. + (gst_element_remove_ghost_pad): Deprecated (could be removed, + depending on API-stability needs). + +2004-02-05 Andy Wingo + + * gst/gstbin.[ch]: (gst_bin_get_by_interface): GTypes are scalars, + of course they're const + 2004-02-11 Thomas Vander Stichele * tools/Makefile.am: @@ -117,6 +220,7 @@ revert patch that breaks applications, reapply after release to get this fixed properly +>>>>>>> 1.222 2004-02-05 Benjamin Otte * gst/gsttag.c: (_gst_tag_initialize): @@ -354,6 +458,7 @@ * gst/gstelement.c: (gst_element_default_error): suffix error messages with period +>>>>>>> 1.206 2004-01-31 Thomas Vander Stichele * gst/elements/gstfilesrc.c: (gst_filesrc_open_file): @@ -458,6 +563,7 @@ * gst/gstvalue.h: sync .h with .c declarations +>>>>>>> 1.182 2004-01-30 Julien Moutte * libs/gst/bytestream/bytestream.c: Reverting my event handling patch. @@ -832,6 +938,7 @@ Time to get into the advanced topics. ;). +>>>>>>> 1.174 2004-01-27 Ronald Bultje * docs/pwg/advanced_types.xml: @@ -922,6 +1029,7 @@ * gst/gsttag.h: add GstTagFlag +>>>>>>> 1.143 2004-01-20 Thomas Vander Stichele * docs/gst/gstreamer-sections.txt: diff --git a/gst/gstelement.c b/gst/gstelement.c index 5c9a5186fb..9c6e95dcea 100644 --- a/gst/gstelement.c +++ b/gst/gstelement.c @@ -1047,8 +1047,9 @@ gst_element_release_locks (GstElement *element) * @element: a #GstElement to add the pad to. * @pad: the #GstPad to add to the element. * - * Add a pad (link point) to the element, setting the parent of the - * pad to the element (and thus adding a reference). + * Adds a pad (link point) to @element. @pad's parent will be set to @element; + * see gst_object_set_parent() for refcounting information. + * * Pads are automatically activated when the element is in state PLAYING. */ void @@ -1100,8 +1101,8 @@ gst_element_add_pad (GstElement *element, GstPad *pad) * @name: the name of the new ghost pad, or NULL to assign a unique name * automatically. * - * Creates a ghost pad from the given pad, and adds it to the list of pads - * for this element. + * Creates a ghost pad from @pad, and adds it to @element via + * gst_element_add_pad(). * * Returns: the added ghost #GstPad, or NULL on error. */ @@ -1128,7 +1129,8 @@ gst_element_add_ghost_pad (GstElement *element, GstPad *pad, const gchar *name) * @element: a #GstElement to remove pad from. * @pad: the #GstPad to remove from the element. * - * Remove a pad (link point) from the element. + * Removes @pad from @element. @pad will be destroyed if it has not been + * referenced elsewhere. */ void gst_element_remove_pad (GstElement *element, GstPad *pad) @@ -1175,7 +1177,7 @@ gst_element_remove_pad (GstElement *element, GstPad *pad) * @element: a #GstElement to remove the ghost pad from. * @pad: ghost #GstPad to remove. * - * Removes a ghost pad from an element. Deprecated, use gst_element_remove_pad + * Removes a ghost pad from an element. Deprecated, use gst_element_remove_pad() * instead. */ void @@ -1193,12 +1195,13 @@ gst_element_remove_ghost_pad (GstElement *element, GstPad *pad) /** * gst_element_get_pad: - * @element: a #GstElement to find pad of. + * @element: a #GstElement. * @name: the name of the pad to retrieve. * - * Retrieves a pad from the element by name. + * Retrieves a pad from @element by name. Tries gst_element_get_static_pad() + * first, then gst_element_get_request_pad(). * - * Returns: requested #GstPad if found, otherwise NULL. + * Returns: the #GstPad if found, otherwise %NULL. */ GstPad* gst_element_get_pad (GstElement *element, const gchar *name) @@ -1221,7 +1224,7 @@ gst_element_get_pad (GstElement *element, const gchar *name) * @element: a #GstElement to find a static pad of. * @name: the name of the static #GstPad to retrieve. * - * Retrieves a pad from the element by name. This version only retrieves + * Retrieves a pad from @element by name. This version only retrieves * already-existing (i.e. 'static') pads. * * Returns: the requested #GstPad if found, otherwise NULL. @@ -1287,8 +1290,9 @@ gst_element_get_request_pad (GstElement *element, const gchar *name) while (!templ_found && list) { templ = (GstPadTemplate*) list->data; if (templ->presence == GST_PAD_REQUEST) { - /* we know that %s and %d are the only possibilities because of sanity - checks in gst_pad_template_new */ + /* Because of sanity checks in gst_pad_template_new(), we know that %s + and %d, occurring at the end of the name_template, are the only + possibilities. */ GST_CAT_DEBUG (GST_CAT_PADS, "comparing %s to %s", name, templ->name_template); if ((str = strchr (templ->name_template, '%')) && strncmp (templ->name_template, name, str - templ->name_template) == 0 && @@ -1326,7 +1330,8 @@ gst_element_get_request_pad (GstElement *element, const gchar *name) * gst_element_get_pad_list: * @element: a #GstElement to get pads of. * - * Retrieves a list of the pads associated with the element. + * Retrieves a list of @element's pads. The list must not be modified by the + * calling code. * * Returns: the #GList of pads. */ @@ -1386,9 +1391,10 @@ gst_element_class_set_details (GstElementClass *klass, const GstElementDetails * /** * gst_element_class_get_pad_template_list: - * @element: a #GstElementClass to get pad templates of. + * @element_class: a #GstElementClass to get pad templates of. * - * Retrieves a list of the pad templates associated with the element. + * Retrieves a list of the pad templates associated with @element_class. The + * list must not be modified by the calling code. * * Returns: the #GList of padtemplates. */ @@ -1403,11 +1409,10 @@ gst_element_class_get_pad_template_list (GstElementClass *element_class) /** * gst_element_class_get_pad_template: - * @element: a #GstElementClass to get the pad template of. + * @element_class: a #GstElementClass to get the pad template of. * @name: the name of the #GstPadTemplate to get. * - * Retrieves a padtemplate from this element with the - * given name. + * Retrieves a padtemplate from @element_class with the given name. * * Returns: the #GstPadTemplate with the given name, or NULL if none was found. * No unreferencing is necessary. @@ -1468,24 +1473,12 @@ gst_element_get_pad_template_list (GstElement *element) GstPadTemplate* gst_element_get_pad_template (GstElement *element, const gchar *name) { - GList *padlist; - g_return_val_if_fail (element != NULL, NULL); g_return_val_if_fail (GST_IS_ELEMENT (element), NULL); g_return_val_if_fail (name != NULL, NULL); - padlist = gst_element_get_pad_template_list (element); - - while (padlist) { - GstPadTemplate *padtempl = (GstPadTemplate*) padlist->data; - - if (!strcmp (padtempl->name_template, name)) - return padtempl; - - padlist = g_list_next (padlist); - } - - return NULL; + return gst_element_class_get_pad_template (GST_ELEMENT_GET_CLASS (element), + name); } /** @@ -1493,12 +1486,11 @@ gst_element_get_pad_template (GstElement *element, const gchar *name) * @element: a #GstElement to get a compatible pad template for. * @compattempl: the #GstPadTemplate to find a compatible template for. * - * Generates a pad template for this element compatible with the given - * template (meaning it is able to link with it). + * Retrieves a pad template from @element that is compatible with @compattempl. + * Pads from compatible templates can be linked together. * - * Returns: the #GstPadTemplate of the element that is compatible with - * the given GstPadTemplate, or NULL if none was found. No unreferencing - * is necessary. + * Returns: a compatible #GstPadTemplate, or NULL if none was found. No + * unreferencing is necessary. */ GstPadTemplate* gst_element_get_compatible_pad_template (GstElement *element, @@ -1525,23 +1517,19 @@ gst_element_get_compatible_pad_template (GstElement *element, * Check caps */ GST_CAT_DEBUG (GST_CAT_CAPS, "checking direction and caps"); - if (padtempl->direction == GST_PAD_SRC && - compattempl->direction == GST_PAD_SINK) { - GST_CAT_DEBUG (GST_CAT_CAPS, "compatible direction: found src pad template"); - comp = gst_caps_is_always_compatible (GST_PAD_TEMPLATE_CAPS (compattempl), - GST_PAD_TEMPLATE_CAPS (padtempl)); - GST_CAT_DEBUG (GST_CAT_CAPS, "caps are %scompatible", (comp ? "" : "not ")); - } else if (padtempl->direction == GST_PAD_SINK && - compattempl->direction == GST_PAD_SRC) { - GST_CAT_DEBUG (GST_CAT_CAPS, "compatible direction: found sink pad template"); - comp = gst_caps_is_always_compatible (GST_PAD_TEMPLATE_CAPS (compattempl), - GST_PAD_TEMPLATE_CAPS (padtempl)); - GST_CAT_DEBUG (GST_CAT_CAPS, "caps are %scompatible", (comp ? "" : "not ")); - } + if (padtempl->direction != compattempl->direction) { + GST_CAT_DEBUG (GST_CAT_CAPS, "compatible direction: found %s pad template", + padtempl->direction == GST_PAD_SRC ? "src" : "sink"); - if (comp) { - newtempl = padtempl; - break; + comp = gst_caps_is_always_compatible (GST_PAD_TEMPLATE_CAPS (compattempl), + GST_PAD_TEMPLATE_CAPS (padtempl)); + + GST_CAT_DEBUG (GST_CAT_CAPS, "caps are %scompatible", (comp ? "" : "not ")); + + if (comp) { + newtempl = padtempl; + break; + } } padlist = g_list_next (padlist); @@ -1550,17 +1538,55 @@ gst_element_get_compatible_pad_template (GstElement *element, return newtempl; } +/** + * gst_element_get_pad_from_template: + * @element: a #GstElement. + * @templ: a #GstPadTemplate belonging to @element. + * + * Gets a pad from @element described by @templ. If the presence of @templ is + * #GST_PAD_REQUEST, requests a new pad. Can return %NULL for #GST_PAD_SOMETIMES + * templates. + * + * Returns: the #GstPad, or NULL if one could not be found or created. + */ +static GstPad* +gst_element_get_pad_from_template (GstElement *element, GstPadTemplate *templ) +{ + GstPad *ret = NULL; + GstPadPresence presence; + + /* If this function is ever exported, we need check the validity of `element' + * and `templ', and to make sure the template actually belongs to the + * element. */ + + presence = GST_PAD_TEMPLATE_PRESENCE (templ); + + switch (presence) { + case GST_PAD_ALWAYS: + case GST_PAD_SOMETIMES: + ret = gst_element_get_static_pad (element, templ->name_template); + if (!ret && presence == GST_PAD_ALWAYS) + g_warning ("Element %s has an ALWAYS template %s, but no pad of the same name", + GST_OBJECT_NAME (element), templ->name_template); + break; + + case GST_PAD_REQUEST: + ret = gst_element_request_pad (element, templ, NULL); + break; + } + + return ret; +} + /** * gst_element_request_compatible_pad: - * @element: a #GstElement to request a new pad from. + * @element: a #GstElement. * @templ: the #GstPadTemplate to which the new pad should be able to link. * - * Requests a new pad from the element. The template will - * be used to decide what type of pad to create. This function - * is typically used for elements with a padtemplate with presence - * GST_PAD_REQUEST. + * Requests a pad from @element. The returned pad should be unlinked and + * compatible with @templ. Might return an existing pad, or request a new one. * - * Returns: the new #GstPad that was created, or NULL if none could be created. + * Returns: a #GstPad, or %NULL if one could not be found or created. */ GstPad* gst_element_request_compatible_pad (GstElement *element, GstPadTemplate *templ) @@ -1568,29 +1594,34 @@ gst_element_request_compatible_pad (GstElement *element, GstPadTemplate *templ) GstPadTemplate *templ_new; GstPad *pad = NULL; - g_return_val_if_fail (element != NULL, NULL); g_return_val_if_fail (GST_IS_ELEMENT (element), NULL); - g_return_val_if_fail (templ != NULL, NULL); + g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL); + /* FIXME: should really loop through the templates, testing each for + compatibility and pad availability. */ templ_new = gst_element_get_compatible_pad_template (element, templ); - if (templ_new != NULL) - pad = gst_element_request_pad (element, templ_new, NULL); + if (templ_new) + pad = gst_element_get_pad_from_template (element, templ_new); + + /* This can happen for non-request pads. No need to unref. */ + if (pad && GST_PAD_PEER (pad)) + pad = NULL; return pad; } - /** * gst_element_get_compatible_pad_filtered: * @element: a #GstElement in which the pad should be found. * @pad: the #GstPad to find a compatible one for. * @filtercaps: the #GstCaps to use as a filter. * - * Looks for an unlinked pad to which the given pad can link to. - * It is not guaranteed that linking the pads will work, though - * it should work in most cases. + * Looks for an unlinked pad to which the given pad can link. It is not + * guaranteed that linking the pads will work, though it should work in most + * cases. * - * Returns: the #GstPad to which a link can be made. + * Returns: the #GstPad to which a link can be made, or %NULL if one cannot be + * found. */ GstPad* gst_element_get_compatible_pad_filtered (GstElement *element, GstPad *pad, @@ -1601,10 +1632,7 @@ gst_element_get_compatible_pad_filtered (GstElement *element, GstPad *pad, GstCaps *templcaps; GstPad *foundpad = NULL; - /* checks */ - g_return_val_if_fail (element != NULL, NULL); g_return_val_if_fail (GST_IS_ELEMENT (element), NULL); - g_return_val_if_fail (pad != NULL, NULL); g_return_val_if_fail (GST_IS_PAD (pad), NULL); GST_DEBUG ("finding pad in %s compatible with %s:%s", @@ -1619,7 +1647,7 @@ gst_element_get_compatible_pad_filtered (GstElement *element, GstPad *pad, pads = gst_element_get_pad_list (element); while (pads) { GstPad *current = GST_PAD (pads->data); - if ((GST_PAD_PEER (GST_PAD_REALIZE (current)) == NULL) && + if (GST_PAD_PEER (current) == NULL && gst_pad_can_link_filtered (pad, current, filtercaps)) { return current; } @@ -1671,8 +1699,8 @@ gst_element_get_compatible_pad_filtered (GstElement *element, GstPad *pad, * It is not guaranteed that linking the pads will work, though * it should work in most cases. * - * Returns: the #GstPad to which a link can be made, or NULL if none - * could be found. + * Returns: the #GstPad to which a link can be made, or %NULL if one + * could not be found. */ GstPad* gst_element_get_compatible_pad (GstElement *element, GstPad *pad) @@ -1693,7 +1721,7 @@ gst_element_get_compatible_pad (GstElement *element, GstPad *pad) * child of the parent of the other element. If they have different * parents, the link fails. * - * Returns: TRUE if the pads could be linked. + * Returns: TRUE if the pads could be linked, FALSE otherwise. */ gboolean gst_element_link_pads_filtered (GstElement *src, const gchar *srcpadname, @@ -1857,20 +1885,19 @@ gst_element_link_pads_filtered (GstElement *src, const gchar *srcpadname, GST_ELEMENT_NAME (src), GST_ELEMENT_NAME (dest)); return FALSE; } + /** * gst_element_link_filtered: * @src: a #GstElement containing the source pad. * @dest: the #GstElement containing the destination pad. * @filtercaps: the #GstCaps to use as a filter. * - * Links the source to the destination element using the filtercaps. - * The link must be from source to destination, the other - * direction will not be tried. - * The functions looks for existing pads that aren't linked yet. - * It will use request pads if possible. But both pads will not be requested. + * Links @src to @dest, filtered by @filtercaps. The link must be from source to + * destination; the other direction will not be tried. The function looks for + * existing pads that aren't linked yet. It will request new pads if necessary. * If multiple links are possible, only one is established. * - * Returns: TRUE if the elements could be linked. + * Returns: TRUE if the elements could be linked, FALSE otherwise. */ gboolean gst_element_link_filtered (GstElement *src, GstElement *dest, @@ -1885,7 +1912,7 @@ gst_element_link_filtered (GstElement *src, GstElement *dest, * @element_2: the second #GstElement in the link chain. * @...: the NULL-terminated list of elements to link in order. * - * Chain together a series of elements. Uses #gst_element_link. + * Chain together a series of elements. Uses gst_element_link(). * * Returns: TRUE on success, FALSE otherwise. */ @@ -1918,14 +1945,10 @@ gst_element_link_many (GstElement *element_1, GstElement *element_2, ...) * @src: a #GstElement containing the source pad. * @dest: the #GstElement containing the destination pad. * - * Links the source to the destination element. - * The link must be from source to destination, the other - * direction will not be tried. - * The functions looks for existing pads and request pads that aren't - * linked yet. If multiple links are possible, only one is - * established. + * Links @src to @dest with no filter caps. See gst_element_link_filtered() for + * more information. * - * Returns: TRUE if the elements could be linked. + * Returns: TRUE if the elements could be linked, FALSE otherwise. */ gboolean gst_element_link (GstElement *src, GstElement *dest) @@ -1945,7 +1968,7 @@ gst_element_link (GstElement *src, GstElement *dest) * child of the parent of the other element. If they have different * parents, the link fails. * - * Returns: TRUE if the pads could be linked. + * Returns: TRUE if the pads could be linked, FALSE otherwise. */ gboolean gst_element_link_pads (GstElement *src, const gchar *srcpadname, @@ -1998,7 +2021,7 @@ gst_element_unlink_pads (GstElement *src, const gchar *srcpadname, * @element_2: the second #GstElement in the link chain. * @...: the NULL-terminated list of elements to unlink in order. * - * Unlinks a series of elements. Uses #gst_element_unlink. + * Unlinks a series of elements. Uses gst_element_unlink(). */ void gst_element_unlink_many (GstElement *element_1, GstElement *element_2, ...) diff --git a/gst/gstobject.c b/gst/gstobject.c index 60fc2b47c8..65eedf8285 100644 --- a/gst/gstobject.c +++ b/gst/gstobject.c @@ -248,7 +248,7 @@ gst_object_unref (GstObject *object) * * Removes floating reference on an object. Any newly created object has * a refcount of 1 and is FLOATING. This function should be used when - * creating a new object to symbolically 'take ownership of' the object. + * creating a new object to symbolically 'take ownership' of the object. * Use #gst_object_set_parent to have this done for you. */ void @@ -303,7 +303,7 @@ gst_object_dispose (GObject *object) parent_class->dispose (object); } -/* finilize is called when the object has to free its resources */ +/* finalize is called when the object has to free its resources */ static void gst_object_finalize (GObject *object) { @@ -496,9 +496,10 @@ gst_object_get_name (GstObject *object) * @object: GstObject to set parent of * @parent: new parent of object * - * Set the parent of the object. The object's reference count is - * incremented. - * signals the parent-set signal + * Sets the parent of @object. The object's reference count will be incremented, + * and any floating reference will be removed (see gst_object_sink()). + * + * Causes the parent-set signal to be emitted. */ void gst_object_set_parent (GstObject *object, GstObject *parent) @@ -521,7 +522,7 @@ gst_object_set_parent (GstObject *object, GstObject *parent) * gst_object_get_parent: * @object: GstObject to get parent of * - * Return the parent of the object. + * Returns the parent of @object. * * Returns: parent of the object */ @@ -538,7 +539,7 @@ gst_object_get_parent (GstObject *object) * gst_object_unparent: * @object: GstObject to unparent * - * Clear the parent of the object, removing the associated reference. + * Clear the parent of @object, removing the associated reference. */ void gst_object_unparent (GstObject *object) @@ -561,11 +562,9 @@ gst_object_unparent (GstObject *object) * @list: a list of #GstObject to check through * @name: the name to search for * - * This function checks through the list of objects to see if the name - * given appears in the list as the name of an object. It returns TRUE if - * the name does not exist in the list. + * Checks to see if there is any object named @name in @list. * - * Returns: TRUE if the name doesn't appear in the list, FALSE if it does. + * Returns: TRUE if the name does not appear in the list, FALSE if it does. */ gboolean gst_object_check_uniqueness (GList *list, const gchar *name) @@ -694,7 +693,7 @@ gst_object_get_property (GObject* object, guint prop_id, * @object: GstObject to get the path from * * Generates a string describing the path of the object in - * the object hierarchy. Only useful (or used) for debugging + * the object hierarchy. Only useful (or used) for debugging. * * Returns: a string describing the path of the object */ diff --git a/gst/gstpad.c b/gst/gstpad.c index 95588b8277..4247750bed 100644 --- a/gst/gstpad.c +++ b/gst/gstpad.c @@ -294,7 +294,8 @@ gst_real_pad_get_property (GObject *object, guint prop_id, } } - +/* FIXME-0.9: Replace these custom functions with proper inheritance via _init + functions and object properties */ /** * gst_pad_custom_new: * @type: the #Gtype of the pad. @@ -573,8 +574,8 @@ gst_pad_set_event_mask_function (GstPad *pad, * * Gets the array of eventmasks from the given pad. * - * Returns: an array with eventmasks, the list is ended - * with 0 + * Returns: a zero-terminated array of #GstEventMask, or NULL if the pad does + * not have an event mask function. */ const GstEventMask* gst_pad_get_event_masks (GstPad *pad) @@ -608,8 +609,8 @@ gst_pad_get_event_masks_dispatcher (GstPad *pad, const GstEventMask **data) * * Invokes the default event masks dispatcher on the pad. * - * Returns: an array with eventmasks, the list is ended - * with 0 + * Returns: a zero-terminated array of #GstEventMask, or NULL if none of the + * internally-linked pads have an event mask function. */ const GstEventMask* gst_pad_get_event_masks_default (GstPad *pad) @@ -687,7 +688,7 @@ gst_pad_set_query_type_function (GstPad *pad, GstPadQueryTypeFunction type_func) * Get an array of supported queries that can be performed * on this pad. * - * Returns: an array of querytypes anded with 0. + * Returns: a zero-terminated array of #GstQueryType. */ const GstQueryType* gst_pad_get_query_types (GstPad *pad) @@ -722,7 +723,8 @@ gst_pad_get_query_types_dispatcher (GstPad *pad, const GstQueryType **data) * Invoke the default dispatcher for the query types on * the pad. * - * Returns: an array of querytypes anded with 0. + * Returns: an zero-terminated array of #GstQueryType, or NULL if none of the + * internally-linked pads has a query types function. */ const GstQueryType* gst_pad_get_query_types_default (GstPad *pad) @@ -776,9 +778,28 @@ gst_pad_set_formats_function (GstPad *pad, GstPadFormatsFunction formats) * gst_pad_set_link_function: * @pad: a #GstPad to set the link function for. * @link: the #GstPadLinkFunction to set. - * - * Sets the given link function for the pad. It will be called - * when the pad is linked or relinked with caps. + * + * Sets the given link function for the pad. It will be called when the pad is + * linked or relinked with caps. The caps passed to the link function are + * guaranteed to be fixed. This means that you can assume that the caps is not + * ANY or EMPTY, and that there is exactly one structure in the caps, and that + * all the fields in the structure are fixed. + * + * The return value GST_PAD_LINK_OK should be used when the caps are acceptable, + * and you've extracted all the necessary information from the caps and set the + * element's internal state appropriately. + * + * The return value GST_PAD_LINK_REFUSED should be used when the caps are + * unacceptable for whatever reason. + * + * The return value GST_PAD_LINK_DELAYED should be used when the element is in a + * state where it can't determine whether the caps are acceptable or not. This + * is often used if the element needs to open a device or process data before + * determining acceptable caps. + * + * @link must not call gst_caps_try_set_caps() on the pad that was specified as + * a parameter, although it may (and often should) call gst_caps_try_set_caps() + * on other pads. */ void gst_pad_set_link_function (GstPad *pad, @@ -815,9 +836,17 @@ gst_pad_set_unlink_function (GstPad *pad, /** * gst_pad_set_fixate_function: * @pad: a #GstPad to set the fixate function for. - * @getcaps: the #GstPadFixateFunction to set. + * @fixate: the #GstPadFixateFunction to set. * - * Sets the given fixate function for the pad. + * Sets the given fixate function for the pad. Its job is to narrow down the + * possible caps for a connection. Fixate functions are called with a const + * caps, and should return a caps that is a strict subset of the given caps. + * That is, @fixate should create a caps that is "more fixed" than previously, + * but it does not have to return fixed caps. If @fixate can't provide more + * fixed caps, it should return %NULL. + * + * Note that @fixate will only be called after the "fixate" signal is emitted, + * and only if the caps are still non-fixed. */ void gst_pad_set_fixate_function (GstPad *pad, GstPadFixateFunction fixate) @@ -834,8 +863,26 @@ gst_pad_set_fixate_function (GstPad *pad, GstPadFixateFunction fixate) * gst_pad_set_getcaps_function: * @pad: a #GstPad to set the getcaps function for. * @getcaps: the #GstPadGetCapsFunction to set. + * + * Sets the given getcaps function for the pad. @getcaps should return the + * allowable caps for a pad in the context of the element's state, its link to + * other elements, and the devices or files it has opened. These caps must be a + * subset of the pad template caps. In the NULL state with no links, @getcaps + * should ideally return the same caps as the pad template. In rare + * circumstances, an object property can affect the caps returned by @getcaps, + * but this is discouraged. * - * Sets the given getcaps function for the pad. + * You do not need to call this function if @pad's allowed caps are always the + * same as the pad template caps. + * + * For most filters, the caps returned by @getcaps is directly affected by the + * allowed caps on other pads. For demuxers and decoders, the caps returned by + * the srcpad's getcaps function is directly related to the stream data. Again, + * @getcaps should return the most specific caps it reasonably can, since this + * helps with autoplugging. However, the returned caps should not depend on the + * stream type currently negotiated for @pad. + * + * Note that the return value from @getcaps is owned by the caller. */ void gst_pad_set_getcaps_function (GstPad *pad, @@ -875,7 +922,8 @@ gst_pad_set_bufferalloc_function (GstPad *pad, * @srcpad: the source #GstPad to unlink. * @sinkpad: the sink #GstPad to unlink. * - * Unlinks the source pad from the sink pad. + * Unlinks the source pad from the sink pad. Will emit the "unlinked" signal on + * both pads. */ void gst_pad_unlink (GstPad *srcpad, @@ -960,9 +1008,9 @@ gst_pad_unlink (GstPad *srcpad, * gst_pad_is_linked: * @pad: pad to check * - * Checks if a given pad is linked to another pad or not. + * Checks if a @pad is linked to another pad or not. * - * Returns: TRUE if the pad is linked. + * Returns: TRUE if the pad is linked, FALSE otherwise. */ gboolean gst_pad_is_linked (GstPad *pad) @@ -1282,6 +1330,29 @@ gst_pad_link_try (GstPadLink *link) return ret; } +/** + * gst_pad_renegotiate: + * @pad: a #GstPad + * + * Initiate caps negotiation on @pad. @pad must be linked. + * + * If @pad's parent is not at least in #GST_STATE_READY, returns + * #GST_PAD_LINK_DELAYED. + * + * Otherwise caps are retrieved from both @pad and its peer by calling their + * getcaps functions. They are then intersected, returning #GST_PAD_LINK_FAIL if + * there is no intersection. + * + * The intersection is fixated if necessary, and then the link functions of @pad + * and its peer are called. + * + * Returns: The return value of @pad's link function (see + * gst_pad_set_link_function()), or #GST_PAD_LINK_OK if there is no link + * function. + * + * The macros GST_PAD_LINK_SUCCESSFUL() and GST_PAD_LINK_FAILED() should be used + * when you just need success/failure information. + */ GstPadLinkReturn gst_pad_renegotiate (GstPad *pad) { @@ -1312,6 +1383,22 @@ gst_pad_renegotiate (GstPad *pad) return gst_pad_link_try (link); } +/** + * gst_pad_try_set_caps: + * @pad: a #GstPad + * @caps: #GstCaps to set on @pad + * + * Try to set the caps on @pad. @caps must be fixed. If @pad is unlinked, + * returns #GST_PAD_LINK_OK without doing anything. Otherwise, start caps + * negotiation on @pad. + * + * Returns: The return value of @pad's link function (see + * gst_pad_set_link_function()), or #GST_PAD_LINK_OK if there is no link + * function. + * + * The macros GST_PAD_LINK_SUCCESSFUL() and GST_PAD_LINK_FAILED() should be used + * when you just need success/failure information. + */ GstPadLinkReturn gst_pad_try_set_caps (GstPad *pad, const GstCaps *caps) { @@ -1379,6 +1466,15 @@ gst_pad_try_set_caps (GstPad *pad, const GstCaps *caps) return ret; } +/** + * gst_pad_try_set_caps_nonfixed: + * @pad: a #GstPad + * @caps: #GstCaps to set on @pad + * + * Like gst_pad_try_set_caps(), but allows non-fixed caps. + * + * Returns: a #GstPadLinkReturn, like gst_pad_try_set_caps(). + */ GstPadLinkReturn gst_pad_try_set_caps_nonfixed (GstPad *pad, const GstCaps *caps) { @@ -1447,7 +1543,7 @@ gst_pad_try_set_caps_nonfixed (GstPad *pad, const GstCaps *caps) * @filtercaps: the filter #GstCaps. * * Checks if the source pad and the sink pad can be linked when constrained - * by the given filter caps. + * by the given filter caps. Both @srcpad and @sinkpad must be unlinked. * * Returns: TRUE if the pads can be linked, FALSE otherwise. */ @@ -1553,7 +1649,7 @@ gst_pad_can_link_filtered (GstPad *srcpad, GstPad *sinkpad, * @srcpad: the source #GstPad to link. * @sinkpad: the sink #GstPad to link. * - * Checks if the source pad and the sink pad can be link. + * Checks if the source pad and the sink pad can be linked. * * Returns: TRUE if the pads can be linked, FALSE otherwise. */ @@ -1570,7 +1666,7 @@ gst_pad_can_link (GstPad *srcpad, GstPad *sinkpad) * @filtercaps: the filter #GstCaps. * * Links the source pad and the sink pad, constrained - * by the given filter caps. This function sinks the caps. + * by the given filter caps. * * Returns: TRUE if the pads have been linked, FALSE otherwise. */ @@ -1708,7 +1804,8 @@ gst_pad_link (GstPad *srcpad, GstPad *sinkpad) * @pad: a #GstPad to set the parent of. * @parent: the new parent #GstElement. * - * Sets the parent object of a pad. + * Sets the parent object of a pad. Deprecated, use gst_object_set_parent() + * instead. */ void gst_pad_set_parent (GstPad *pad, GstElement *parent) @@ -1727,7 +1824,8 @@ gst_pad_set_parent (GstPad *pad, GstElement *parent) * gst_pad_get_parent: * @pad: the #GstPad to get the parent of. * - * Gets the parent object of this pad. + * Gets the parent object of this pad. Deprecated, use gst_object_get_parent() + * instead. * * Returns: the parent #GstElement. */ @@ -1827,7 +1925,8 @@ gst_pad_get_real_parent (GstPad *pad) * @pad: a #GstPad to attach the ghost pad to. * @ghostpad: the ghost #GstPad to to the pad. * - * Adds a ghost pad to a pad. + * Adds a ghost pad to a pad. Private function, will be removed from the API in + * 0.9. */ void gst_pad_add_ghost_pad (GstPad *pad, @@ -1857,7 +1956,7 @@ gst_pad_add_ghost_pad (GstPad *pad, * @pad: a #GstPad to remove the ghost pad from. * @ghostpad: the ghost #GstPad to remove from the pad. * - * Removes a ghost pad from a pad. + * Removes a ghost pad from a pad. Private, will be removed from the API in 0.9. */ void gst_pad_remove_ghost_pad (GstPad *pad, @@ -1954,7 +2053,8 @@ _gst_pad_default_fixate_func (GstPad *pad, const GstCaps *caps) * @srcpad: the source #GstPad. * @sinkpad: the sink #GstPad. * - * Tries to negotiate the pads. + * Tries to negotiate the pads. See gst_pad_renegotiate() for a brief + * description of caps negotiation. * * Returns: TRUE if the pads were succesfully negotiated, FALSE otherwise. */ @@ -1964,7 +2064,7 @@ gst_pad_perform_negotiate (GstPad *srcpad, GstPad *sinkpad) return GST_PAD_LINK_SUCCESSFUL (gst_pad_renegotiate (srcpad)); } -void +static void gst_pad_link_unnegotiate (GstPadLink *link) { g_return_if_fail (link != NULL); @@ -2361,10 +2461,9 @@ gst_pad_is_negotiated (GstPad *pad) * gst_pad_get_negotiated_caps: * @pad: a #GstPad to get the negotiated capabilites of * - * Gets the currently negotiated caps of a pad or NULL if the pad isn't - * negotiated. + * Gets the currently negotiated caps of a pad. * - * Returns: the currently negotiated caps of a pad or NULL if the pad isn't + * Returns: the currently negotiated caps of a pad, or NULL if the pad isn't * negotiated. */ G_CONST_RETURN GstCaps * @@ -2449,7 +2548,7 @@ gst_pad_get_caps (GstPad *pad) * gst_pad_get_pad_template_caps: * @pad: a #GstPad to get the template capabilities from. * - * Gets the template capabilities of this pad. + * Gets the capabilities for @pad's template. * * Returns: the #GstCaps of this pad template. If you intend to keep a reference * on the caps, make a copy (see gst_caps_copy ()). @@ -2478,7 +2577,7 @@ gst_pad_get_pad_template_caps (GstPad *pad) * @templ: a #GstPadTemplate to get the capabilities of. * @name: the name of the capability to get. * - * Gets the capability with the given name from this pad template. + * Gets the capability with the given name from @templ. * * Returns: the #GstCaps of this pad template, or NULL if not found. If you * intend to keep a reference on the caps, make a copy (see gst_caps_copy ()). @@ -2506,8 +2605,8 @@ gst_pad_template_get_caps_by_name (GstPadTemplate *templ, const gchar *name) * * Checks if two pads have compatible capabilities. * - * Returns: TRUE if they are compatible or if the capabilities - * could not be checked. + * Returns: TRUE if they are compatible or if the capabilities could not be + * checked, FALSE if the capabilities are not compatible. */ gboolean gst_pad_check_compatibility (GstPad *srcpad, GstPad *sinkpad) @@ -2539,7 +2638,7 @@ gst_pad_check_compatibility (GstPad *srcpad, GstPad *sinkpad) * gst_pad_get_peer: * @pad: a #GstPad to get the peer of. * - * Gets the peer pad of this pad. + * Gets the peer pad of @pad. * * Returns: the peer #GstPad. */ @@ -2596,11 +2695,16 @@ gst_pad_get_allowed_caps (GstPad *pad) } } +/** + * gst_pad_caps_change_notify: + * @pad: a #GstPad + * + * Called to indicate that the return value of @pad's getcaps function may have + * changed, and that a renegotiation is suggested. + */ void gst_pad_caps_change_notify (GstPad *pad) { - /* call this to indicate that the return value of getcaps may have - * changed, and a renegotiation is suggested */ } /** @@ -2653,8 +2757,8 @@ gst_pad_recover_caps_error (GstPad *pad, const GstCaps *allowed) * gst_pad_alloc_buffer: * @pad: a #GstPad to get the buffer from. * - * Allocates a new, empty buffer optimized to push to pad #pad. This - * function only works if #pad is a src pad. + * Allocates a new, empty buffer optimized to push to pad @pad. This + * function only works if @pad is a src pad. * * Returns: a new, empty #GstBuffer, or NULL if there is an error */ @@ -2848,7 +2952,8 @@ gst_pad_save_thyself (GstObject *object, xmlNodePtr parent) return parent; } -/* FIXME: shouldn't pad and ghost be switched ? +/* FIXME: shouldn't it be gst_pad_ghost_* ? + * dunno -- wingo 7 feb 2004 */ /** * gst_ghost_pad_save_thyself: @@ -2881,7 +2986,7 @@ gst_ghost_pad_save_thyself (GstPad *pad, xmlNodePtr parent) * @pad: a #GstPad to push the buffer out of. * @data: the #GstData to push. * - * Pushes a buffer or an event to the peer of the pad. + * Pushes a buffer or an event to the peer of @pad. @pad must be linked. */ void gst_pad_push (GstPad *pad, GstData *data) @@ -3185,7 +3290,7 @@ name_is_valid (const gchar *name, GstPadPresence presence) * gst_static_pad_template_get: * @pad_template: the static pad template * - * Converts a GstStaticPadTemplate into a GstPadTemplate. + * Converts a #GstStaticPadTemplate into a #GstPadTemplate. * * Returns: a new #GstPadTemplate. */ @@ -3423,11 +3528,10 @@ gst_ghost_pad_get_property (GObject* object, guint prop_id, * @name: the name of the new ghost pad. * @pad: the #GstPad to create a ghost pad for. * - * Creates a new ghost pad associated with the given pad, and names it with - * the given name. If name is NULL, a guaranteed unique name (across all - * ghost pads) will be assigned. + * Creates a new ghost pad associated with @pad, and named @name. If @name is + * %NULL, a guaranteed unique name (across all ghost pads) will be assigned. * - * Returns: a new ghost #GstPad, or NULL in case of an error. + * Returns: a new ghost #GstPad, or %NULL in case of an error. */ GstPad* gst_ghost_pad_new (const gchar *name,