+2004-02-10 Andy Wingo <wingo@pobox.com>
+
+ * 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 <wingo@pobox.com>
+
+ * 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 <wingo@pobox.com>
+
+ * 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 <wingo@pobox.com>
+
+ * gst/gstbin.[ch]: (gst_bin_get_by_interface): GTypes are scalars,
+ of course they're const
+
2004-02-11 Thomas Vander Stichele <thomas at apestaart dot org>
* tools/Makefile.am:
revert patch that breaks applications, reapply after release
to get this fixed properly
+>>>>>>> 1.222
2004-02-05 Benjamin Otte <in7y118@public.uni-hamburg.de>
* gst/gsttag.c: (_gst_tag_initialize):
* gst/gstelement.c: (gst_element_default_error):
suffix error messages with period
+>>>>>>> 1.206
2004-01-31 Thomas Vander Stichele <thomas at apestaart dot org>
* gst/elements/gstfilesrc.c: (gst_filesrc_open_file):
* gst/gstvalue.h:
sync .h with .c declarations
+>>>>>>> 1.182
2004-01-30 Julien Moutte <julien@moutte.net>
* libs/gst/bytestream/bytestream.c: Reverting my event handling patch.
Time to get into the advanced topics. ;).
+>>>>>>> 1.174
2004-01-27 Ronald Bultje <rbultje@ronald.bitfreak.net>
* docs/pwg/advanced_types.xml:
* gst/gsttag.h:
add GstTagFlag
+>>>>>>> 1.143
2004-01-20 Thomas Vander Stichele <thomas at apestaart dot org>
* docs/gst/gstreamer-sections.txt:
* @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
* @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.
*/
* @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)
* @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
/**
* 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)
* @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.
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 &&
* 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.
*/
/**
* 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.
*/
/**
* 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.
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);
}
/**
* @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,
* 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");
+ if (padtempl->direction != compattempl->direction) {
+ GST_CAT_DEBUG (GST_CAT_CAPS, "compatible direction: found %s pad template",
+ padtempl->direction == GST_PAD_SRC ? "src" : "sink");
+
comp = gst_caps_is_always_compatible (GST_PAD_TEMPLATE_CAPS (compattempl),
- GST_PAD_TEMPLATE_CAPS (padtempl));
+ GST_PAD_TEMPLATE_CAPS (padtempl));
+
GST_CAT_DEBUG (GST_CAT_CAPS, "caps are %scompatible", (comp ? "" : "not "));
- }
- if (comp) {
- newtempl = padtempl;
- break;
+ if (comp) {
+ newtempl = padtempl;
+ break;
+ }
}
padlist = g_list_next (padlist);
}
/**
+ * 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)
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,
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",
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;
}
* 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)
* 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,
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,
* @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.
*/
* @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)
* 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,
* @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, ...)
*
* 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
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)
{
* @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)
* 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
*/
* 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)
* @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)
* @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
*/
}
}
-
+/* 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.
*
* 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)
*
* 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)
* 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)
* 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)
* 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,
/**
* gst_pad_set_fixate_function:
* @pad: a #GstPad to set the fixate function for.
- * @getcaps: the #GstPadFixateFunction to set.
- *
- * Sets the given fixate function for the pad.
+ * @fixate: the #GstPadFixateFunction to set.
+ *
+ * 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)
* 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.
+ *
+ * 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.
+ *
+ * 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,
* @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,
* 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)
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)
{
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)
{
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)
{
* @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.
*/
* @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.
*/
* @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.
*/
* @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)
* 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.
*/
* @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,
* @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,
* @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.
*/
return GST_PAD_LINK_SUCCESSFUL (gst_pad_renegotiate (srcpad));
}
-void
+static void
gst_pad_link_unnegotiate (GstPadLink *link)
{
g_return_if_fail (link != NULL);
* 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 *
* 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 ()).
* @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 ()).
*
* 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)
* 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.
*/
}
}
+/**
+ * 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 */
}
/**
* 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
*/
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:
* @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)
* 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.
*/
* @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,
projects / platform / upstream / gstreamer.git / commitdiff