2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2004 Wim Taymans <wim@fluendo.com>
5 * gstelement.c: The base element, all elements derive from this
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
24 * @short_description: Abstract base class for all pipeline elements
25 * @see_also: #GstElementFactory, #GstPad
27 * GstElement is the base class needed to construct an element that can be
28 * used in a GStreamer pipeline. As such, it is not a functional entity, and
29 * cannot do anything when placed in a pipeline.
31 * The name of a GstElement can be get with gst_element_get_name() and set with
32 * gst_element_set_name(). For speed, GST_ELEMENT_NAME() can be used in the
33 * core when using the appropriate locking. Do not use this in plug-ins or
34 * applications in order to retain ABI compatibility.
36 * All elements have pads (of the type #GstPad). These pads link to pads on
37 * other elements. Buffers flow between these linked pads.
38 * A GstElement has a GList of #GstPad structures for all their input (or sink)
39 * and output (or source) pads.
40 * Core and plug-in writers can add and remove pads with gst_element_add_pad()
41 * and gst_element_remove_pad().
43 * A pad of an element can be retrieved by name with gst_element_get_pad().
44 * An iterator of all pads can be retrieved with gst_element_iterate_pads().
46 * Elements can be linked through their pads.
47 * If the link is straightforward, use the gst_element_link()
48 * convenience function to link two elements, or gst_element_link_many()
49 * for more elements in a row.
50 * Use gst_element_link_filtered() to link two elements constrained by
51 * a specified set of #GstCaps.
52 * For finer control, use gst_element_link_pads() and
53 * gst_element_link_pads_filtered() to specify the pads to link on
54 * each element by name.
56 * Each element has a state (see #GstState). You can get and set the state
57 * of an element with gst_element_get_state() and gst_element_set_state().
58 * You can wait for an element to change it's state with gst_element_wait_state_change().
59 * To get a string representation of a #GstState, use
60 * gst_element_state_get_name().
62 * You can get and set a #GstClock on an element using gst_element_get_clock()
63 * and gst_element_set_clock().
64 * Some elements can provide a clock for the pipeline if
65 * gst_element_provides_clock() returns TRUE. With the gst_element_provide_clock()
66 * method one can retrieve the clock provided by such an element.
67 * Not all elements require a clock to operate correctly. If
68 * gst_element_requires_clock() returns TRUE, a clock should be set on the element
69 * with gst_element_set_clock().
71 * Note that clock slection and distribution is normally handled by the toplevel
72 * #GstPipeline so the clock functions are only to be used in very specific situations.
74 #include "gst_private.h"
77 #include <gobject/gvaluecollector.h>
79 #include "gstelement.h"
81 #include "gstmarshal.h"
86 #include "gst-i18n-lib.h"
88 /* Element signals and args */
105 extern void __gst_element_details_clear (GstElementDetails * dp);
106 extern void __gst_element_details_copy (GstElementDetails * dest,
107 const GstElementDetails * src);
109 static void gst_element_class_init (GstElementClass * klass);
110 static void gst_element_init (GstElement * element);
111 static void gst_element_base_class_init (gpointer g_class);
112 static void gst_element_base_class_finalize (gpointer g_class);
114 static void gst_element_dispose (GObject * object);
115 static void gst_element_finalize (GObject * object);
117 static GstStateChangeReturn gst_element_change_state (GstElement * element,
118 GstStateChange transition);
119 static GstStateChangeReturn gst_element_change_state_func (GstElement * element,
120 GstStateChange transition);
121 static GstStateChangeReturn gst_element_get_state_func (GstElement * element,
122 GstState * state, GstState * pending, GTimeVal * timeout);
123 static void gst_element_set_bus_func (GstElement * element, GstBus * bus);
125 #ifndef GST_DISABLE_LOADSAVE
126 static xmlNodePtr gst_element_save_thyself (GstObject * object,
128 static void gst_element_restore_thyself (GstObject * parent, xmlNodePtr self);
131 GType _gst_element_type = 0;
133 static GstObjectClass *parent_class = NULL;
134 static guint gst_element_signals[LAST_SIGNAL] = { 0 };
137 gst_element_get_type (void)
139 if (!_gst_element_type) {
140 static const GTypeInfo element_info = {
141 sizeof (GstElementClass),
142 gst_element_base_class_init,
143 gst_element_base_class_finalize,
144 (GClassInitFunc) gst_element_class_init,
149 (GInstanceInitFunc) gst_element_init,
153 _gst_element_type = g_type_register_static (GST_TYPE_OBJECT, "GstElement",
154 &element_info, G_TYPE_FLAG_ABSTRACT);
156 return _gst_element_type;
160 gst_element_class_init (GstElementClass * klass)
162 GObjectClass *gobject_class;
163 GstObjectClass *gstobject_class;
165 gobject_class = (GObjectClass *) klass;
166 gstobject_class = (GstObjectClass *) klass;
168 parent_class = g_type_class_ref (GST_TYPE_OBJECT);
171 * GstElement::pad-added:
172 * @gstelement: the object which received the signal
173 * @new_pad: the pad that has been added
175 * a new #GstPad has been added to the element.
177 gst_element_signals[NEW_PAD] =
178 g_signal_new ("pad-added", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
179 G_STRUCT_OFFSET (GstElementClass, pad_added), NULL, NULL,
180 gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_OBJECT);
182 * GstElement::pad-removed:
183 * @gstelement: the object which received the signal
184 * @old_pad: the pad that has been removed
186 * a #GstPad has been removed from the element
188 gst_element_signals[PAD_REMOVED] =
189 g_signal_new ("pad-removed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
190 G_STRUCT_OFFSET (GstElementClass, pad_removed), NULL, NULL,
191 gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_OBJECT);
193 * GstElement::no-more-pads:
194 * @gstelement: the object which received the signal
196 * This signals that the element will not generate more dynamic pads.
198 gst_element_signals[NO_MORE_PADS] =
199 g_signal_new ("no-more-pads", G_TYPE_FROM_CLASS (klass),
200 G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstElementClass, no_more_pads), NULL,
201 NULL, gst_marshal_VOID__VOID, G_TYPE_NONE, 0);
203 gobject_class->dispose = GST_DEBUG_FUNCPTR (gst_element_dispose);
204 gobject_class->finalize = GST_DEBUG_FUNCPTR (gst_element_finalize);
206 #ifndef GST_DISABLE_LOADSAVE
207 gstobject_class->save_thyself = GST_DEBUG_FUNCPTR (gst_element_save_thyself);
208 gstobject_class->restore_thyself =
209 GST_DEBUG_FUNCPTR (gst_element_restore_thyself);
212 klass->change_state = GST_DEBUG_FUNCPTR (gst_element_change_state_func);
213 klass->get_state = GST_DEBUG_FUNCPTR (gst_element_get_state_func);
214 klass->set_bus = GST_DEBUG_FUNCPTR (gst_element_set_bus_func);
215 klass->numpadtemplates = 0;
217 klass->elementfactory = NULL;
221 gst_element_base_class_init (gpointer g_class)
223 GstElementClass *element_class = GST_ELEMENT_CLASS (g_class);
225 memset (&element_class->details, 0, sizeof (GstElementDetails));
226 element_class->padtemplates = NULL;
230 gst_element_base_class_finalize (gpointer g_class)
232 GstElementClass *klass = GST_ELEMENT_CLASS (g_class);
234 g_list_foreach (klass->padtemplates, (GFunc) gst_object_unref, NULL);
235 g_list_free (klass->padtemplates);
236 __gst_element_details_clear (&klass->details);
240 gst_element_init (GstElement * element)
242 element->current_state = GST_STATE_NULL;
243 element->pending_state = GST_STATE_VOID_PENDING;
244 element->state_lock = g_new0 (GStaticRecMutex, 1);
245 g_static_rec_mutex_init (element->state_lock);
246 element->state_cond = g_cond_new ();
250 * gst_element_default_error:
251 * @object: a #GObject that signalled the error.
252 * @orig: the #GstObject that initiated the error.
253 * @error: the GError.
254 * @debug: an additional debug information string, or NULL.
256 * A default error signal callback to attach to an element.
257 * The user data passed to the g_signal_connect is ignored.
259 * The default handler will simply print the error string using g_print.
264 gst_element_default_error (GObject * object, GstObject * source, GError * error,
267 gchar *name = gst_object_get_path_string (source);
269 g_print (_("ERROR: from element %s: %s\n"), name, error->message);
271 g_print (_("Additional debug info:\n%s\n"), debug);
277 * gst_element_release_request_pad:
278 * @element: a #GstElement to release the request pad of.
279 * @pad: the #GstPad to release.
281 * Makes the element free the previously requested pad as obtained
282 * with gst_element_get_request_pad().
287 gst_element_release_request_pad (GstElement * element, GstPad * pad)
289 GstElementClass *oclass;
291 g_return_if_fail (GST_IS_ELEMENT (element));
292 g_return_if_fail (GST_IS_PAD (pad));
294 oclass = GST_ELEMENT_GET_CLASS (element);
296 if (oclass->release_pad)
297 (oclass->release_pad) (element, pad);
299 gst_element_remove_pad (element, pad);
303 * gst_element_requires_clock:
304 * @element: a #GstElement to query
306 * Query if the element requires a clock.
308 * Returns: TRUE if the element requires a clock
313 gst_element_requires_clock (GstElement * element)
317 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
319 result = (GST_ELEMENT_GET_CLASS (element)->set_clock != NULL);
325 * gst_element_provides_clock:
326 * @element: a #GstElement to query
328 * Query if the element provides a clock.
330 * Returns: TRUE if the element provides a clock
335 gst_element_provides_clock (GstElement * element)
339 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
341 result = (GST_ELEMENT_GET_CLASS (element)->provide_clock != NULL);
347 * gst_element_provide_clock:
348 * @element: a #GstElement to query
350 * Get the clock provided by the given element.
352 * Returns: the GstClock provided by the element or NULL
353 * if no clock could be provided. Unref after usage.
358 gst_element_provide_clock (GstElement * element)
360 GstClock *result = NULL;
361 GstElementClass *oclass;
363 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
365 oclass = GST_ELEMENT_GET_CLASS (element);
367 if (oclass->provide_clock)
368 result = oclass->provide_clock (element);
374 * gst_element_set_clock:
375 * @element: a #GstElement to set the clock for.
376 * @clock: the #GstClock to set for the element.
378 * Sets the clock for the element. This function increases the
379 * refcount on the clock. Any previously set clock on the object
385 gst_element_set_clock (GstElement * element, GstClock * clock)
387 GstElementClass *oclass;
389 g_return_if_fail (GST_IS_ELEMENT (element));
391 oclass = GST_ELEMENT_GET_CLASS (element);
393 if (oclass->set_clock)
394 oclass->set_clock (element, clock);
397 gst_object_replace ((GstObject **) & element->clock, (GstObject *) clock);
398 GST_UNLOCK (element);
402 * gst_element_get_clock:
403 * @element: a #GstElement to get the clock of.
405 * Gets the currently configured clock of the element.
407 * Returns: the #GstClock of the element. unref after usage.
412 gst_element_get_clock (GstElement * element)
416 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
419 if ((result = element->clock))
420 gst_object_ref (result);
421 GST_UNLOCK (element);
427 * gst_element_set_base_time:
428 * @element: a #GstElement.
429 * @time: the base time to set.
431 * Set the base time of an element. See @gst_element_get_base_time().
436 gst_element_set_base_time (GstElement * element, GstClockTime time)
438 g_return_if_fail (GST_IS_ELEMENT (element));
441 element->base_time = time;
442 GST_UNLOCK (element);
446 * gst_element_get_base_time:
447 * @element: a #GstElement.
449 * Returns the base time of the element. The base time is the
450 * absolute time of the clock when this element was last put to
451 * PLAYING. Substracting the base time from the clock time gives
452 * the stream time of the element.
454 * Returns: the base time of the element.
459 gst_element_get_base_time (GstElement * element)
463 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_CLOCK_TIME_NONE);
466 result = element->base_time;
467 GST_UNLOCK (element);
472 #ifndef GST_DISABLE_INDEX
474 * gst_element_is_indexable:
475 * @element: a #GstElement.
477 * Queries if the element can be indexed.
479 * Returns: TRUE if the element can be indexed.
484 gst_element_is_indexable (GstElement * element)
488 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
490 result = (GST_ELEMENT_GET_CLASS (element)->set_index != NULL);
496 * gst_element_set_index:
497 * @element: a #GstElement.
498 * @index: a #GstIndex.
500 * Set the specified GstIndex on the element. The refcount of the index
501 * will be increased, any previously set index is unreffed.
506 gst_element_set_index (GstElement * element, GstIndex * index)
508 GstElementClass *oclass;
510 g_return_if_fail (GST_IS_ELEMENT (element));
511 g_return_if_fail (GST_IS_INDEX (index));
513 oclass = GST_ELEMENT_GET_CLASS (element);
515 if (oclass->set_index)
516 oclass->set_index (element, index);
520 * gst_element_get_index:
521 * @element: a #GstElement.
523 * Gets the index from the element.
525 * Returns: a #GstIndex or NULL when no index was set on the
526 * element. unref after usage.
531 gst_element_get_index (GstElement * element)
533 GstElementClass *oclass;
535 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
537 oclass = GST_ELEMENT_GET_CLASS (element);
539 if (oclass->get_index)
540 return oclass->get_index (element);
547 * gst_element_add_pad:
548 * @element: a #GstElement to add the pad to.
549 * @pad: the #GstPad to add to the element.
551 * Adds a pad (link point) to @element. @pad's parent will be set to @element;
552 * see gst_object_set_parent() for refcounting information.
554 * Pads are not automatically activated so elements should perform the needed
555 * steps to activate the pad in case this pad is added in the PAUSED or PLAYING
558 * The pad and the element should be unlocked when calling this function.
560 * Returns: TRUE if the pad could be added. This function can fail when
561 * passing bad arguments or when a pad with the same name already existed.
566 gst_element_add_pad (GstElement * element, GstPad * pad)
570 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
571 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
573 /* locking pad to look at the name */
575 pad_name = g_strdup (GST_PAD_NAME (pad));
576 GST_CAT_INFO_OBJECT (GST_CAT_ELEMENT_PADS, element, "adding pad '%s'",
577 GST_STR_NULL (pad_name));
580 /* then check to see if there's already a pad by that name here */
582 if (G_UNLIKELY (!gst_object_check_uniqueness (element->pads, pad_name)))
585 /* try to set the pad's parent */
586 if (G_UNLIKELY (!gst_object_set_parent (GST_OBJECT_CAST (pad),
587 GST_OBJECT_CAST (element))))
592 /* add it to the list */
593 switch (gst_pad_get_direction (pad)) {
595 element->srcpads = g_list_prepend (element->srcpads, pad);
596 element->numsrcpads++;
599 element->sinkpads = g_list_prepend (element->sinkpads, pad);
600 element->numsinkpads++;
605 element->pads = g_list_prepend (element->pads, pad);
607 element->pads_cookie++;
608 GST_UNLOCK (element);
610 /* emit the NEW_PAD signal */
611 g_signal_emit (G_OBJECT (element), gst_element_signals[NEW_PAD], 0, pad);
618 g_critical ("Padname %s is not unique in element %s, not adding",
619 pad_name, GST_ELEMENT_NAME (element));
620 GST_UNLOCK (element);
627 ("Pad %s already has parent when trying to add to element %s",
628 pad_name, GST_ELEMENT_NAME (element));
629 GST_UNLOCK (element);
637 ("Trying to add pad %s to element %s, but it has no direction",
638 GST_OBJECT_NAME (pad), GST_ELEMENT_NAME (element));
640 GST_UNLOCK (element);
646 * gst_element_remove_pad:
647 * @element: a #GstElement to remove pad from.
648 * @pad: the #GstPad to remove from the element.
650 * Removes @pad from @element. @pad will be destroyed if it has not been
651 * referenced elsewhere.
653 * Returns: TRUE if the pad could be removed. Can return FALSE if the
654 * pad is not belonging to the provided element or when wrong parameters
655 * are passed to this function.
660 gst_element_remove_pad (GstElement * element, GstPad * pad)
664 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
665 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
667 /* locking pad to look at the name and parent */
669 GST_CAT_INFO_OBJECT (GST_CAT_ELEMENT_PADS, element, "removing pad '%s'",
670 GST_STR_NULL (GST_PAD_NAME (pad)));
672 if (G_UNLIKELY (GST_PAD_PARENT (pad) != element))
677 if ((peer = gst_pad_get_peer (pad))) {
678 /* window for MT unsafeness, someone else could unlink here
679 * and then we call unlink with wrong pads. The unlink
680 * function would catch this and safely return failed. */
681 if (GST_PAD_IS_SRC (pad))
682 gst_pad_unlink (pad, peer);
684 gst_pad_unlink (peer, pad);
686 gst_object_unref (peer);
690 /* remove it from the list */
691 switch (gst_pad_get_direction (pad)) {
693 element->srcpads = g_list_remove (element->srcpads, pad);
694 element->numsrcpads--;
697 element->sinkpads = g_list_remove (element->sinkpads, pad);
698 element->numsinkpads--;
701 g_critical ("Removing pad without direction???");
704 element->pads = g_list_remove (element->pads, pad);
706 element->pads_cookie++;
707 GST_UNLOCK (element);
709 g_signal_emit (G_OBJECT (element), gst_element_signals[PAD_REMOVED], 0, pad);
711 gst_object_unparent (GST_OBJECT (pad));
717 /* FIXME, locking order? */
719 g_critical ("Padname %s:%s does not belong to element %s when removing",
720 GST_ELEMENT_NAME (GST_PAD_PARENT (pad)), GST_PAD_NAME (pad),
721 GST_ELEMENT_NAME (element));
722 GST_UNLOCK (element);
729 * gst_element_no_more_pads:
730 * @element: a #GstElement
732 * Use this function to signal that the element does not expect any more pads
733 * to show up in the current pipeline. This function should be called whenever
734 * pads have been added by the element itself. Elements with GST_PAD_SOMETIMES
735 * pad templates use this in combination with autopluggers to figure out that
736 * the element is done initializing its pads.
741 gst_element_no_more_pads (GstElement * element)
743 g_return_if_fail (GST_IS_ELEMENT (element));
745 g_signal_emit (element, gst_element_signals[NO_MORE_PADS], 0);
749 pad_compare_name (GstPad * pad1, const gchar * name)
754 result = strcmp (GST_PAD_NAME (pad1), name);
761 * gst_element_get_static_pad:
762 * @element: a #GstElement to find a static pad of.
763 * @name: the name of the static #GstPad to retrieve.
765 * Retrieves a pad from @element by name. This version only retrieves
766 * already-existing (i.e. 'static') pads.
768 * Returns: the requested #GstPad if found, otherwise NULL. unref after
774 gst_element_get_static_pad (GstElement * element, const gchar * name)
777 GstPad *result = NULL;
779 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
780 g_return_val_if_fail (name != NULL, NULL);
784 g_list_find_custom (element->pads, name, (GCompareFunc) pad_compare_name);
786 result = GST_PAD_CAST (find->data);
787 gst_object_ref (result);
790 if (result == NULL) {
791 GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "no such pad '%s' in element \"%s\"",
792 name, GST_ELEMENT_NAME (element));
794 GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "found pad %s:%s",
795 GST_ELEMENT_NAME (element), name);
797 GST_UNLOCK (element);
803 gst_element_request_pad (GstElement * element, GstPadTemplate * templ,
806 GstPad *newpad = NULL;
807 GstElementClass *oclass;
809 oclass = GST_ELEMENT_GET_CLASS (element);
811 if (oclass->request_new_pad)
812 newpad = (oclass->request_new_pad) (element, templ, name);
815 gst_object_ref (newpad);
821 * gst_element_get_request_pad:
822 * @element: a #GstElement to find a request pad of.
823 * @name: the name of the request #GstPad to retrieve.
825 * Retrieves a pad from the element by name. This version only retrieves
828 * Returns: requested #GstPad if found, otherwise NULL. Unref after usage.
831 gst_element_get_request_pad (GstElement * element, const gchar * name)
833 GstPadTemplate *templ = NULL;
835 const gchar *req_name = NULL;
836 gboolean templ_found = FALSE;
840 gchar *str, *endptr = NULL;
841 GstElementClass *class;
843 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
844 g_return_val_if_fail (name != NULL, NULL);
846 class = GST_ELEMENT_GET_CLASS (element);
848 if (strstr (name, "%")) {
849 templ = gst_element_class_get_pad_template (class, name);
854 list = gst_element_class_get_pad_template_list (class);
855 while (!templ_found && list) {
856 templ = (GstPadTemplate *) list->data;
857 if (templ->presence == GST_PAD_REQUEST) {
858 /* Because of sanity checks in gst_pad_template_new(), we know that %s
859 and %d, occurring at the end of the name_template, are the only
861 GST_CAT_DEBUG (GST_CAT_PADS, "comparing %s to %s", name,
862 templ->name_template);
863 if ((str = strchr (templ->name_template, '%'))
864 && strncmp (templ->name_template, name,
865 str - templ->name_template) == 0
866 && strlen (name) > str - templ->name_template) {
867 data = name + (str - templ->name_template);
868 if (*(str + 1) == 'd') {
870 n = (gint) strtol (data, &endptr, 10);
871 if (endptr && *endptr == '\0') {
891 pad = gst_element_request_pad (element, templ, req_name);
897 * gst_element_get_pad:
898 * @element: a #GstElement.
899 * @name: the name of the pad to retrieve.
901 * Retrieves a pad from @element by name. Tries gst_element_get_static_pad()
902 * first, then gst_element_get_request_pad().
904 * Returns: the #GstPad if found, otherwise %NULL. Unref after usage.
907 gst_element_get_pad (GstElement * element, const gchar * name)
911 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
912 g_return_val_if_fail (name != NULL, NULL);
914 pad = gst_element_get_static_pad (element, name);
916 pad = gst_element_get_request_pad (element, name);
921 static GstIteratorItem
922 iterate_pad (GstIterator * it, GstPad * pad)
924 gst_object_ref (pad);
925 return GST_ITERATOR_ITEM_PASS;
929 * gst_element_iterate_pads:
930 * @element: a #GstElement to iterate pads of.
932 * Retrieves an iterattor of @element's pads. The iterator should
933 * be freed after usage.
935 * Returns: the #GstIterator of #GstPad. Unref each pad after use.
940 gst_element_iterate_pads (GstElement * element)
944 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
947 gst_object_ref (element);
948 result = gst_iterator_new_list (GST_TYPE_PAD,
949 GST_GET_LOCK (element),
950 &element->pads_cookie,
953 (GstIteratorItemFunction) iterate_pad,
954 (GstIteratorDisposeFunction) gst_object_unref);
955 GST_UNLOCK (element);
961 direction_filter (gconstpointer pad, gconstpointer direction)
963 if (GST_PAD_DIRECTION (pad) == GPOINTER_TO_INT (direction)) {
964 /* pass the ref through */
968 /* FIXME: this is very stupid */
969 gst_object_unref (GST_OBJECT_CAST (pad));
975 * gst_element_iterate_src_pads:
976 * @element: a #GstElement.
978 * Retrieves an iterator of @element's source pads.
980 * Returns: the #GstIterator of #GstPad. Unref each pad after use.
985 gst_element_iterate_src_pads (GstElement * element)
987 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
989 return gst_iterator_filter (gst_element_iterate_pads (element),
990 direction_filter, GINT_TO_POINTER (GST_PAD_SRC));
994 * gst_element_iterate_sink_pads:
995 * @element: a #GstElement.
997 * Retrieves an iterator of @element's sink pads.
999 * Returns: the #GstIterator of #GstPad. Unref each pad after use.
1004 gst_element_iterate_sink_pads (GstElement * element)
1006 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1008 return gst_iterator_filter (gst_element_iterate_pads (element),
1009 direction_filter, GINT_TO_POINTER (GST_PAD_SINK));
1013 * gst_element_class_add_pad_template:
1014 * @klass: the #GstElementClass to add the pad template to.
1015 * @templ: a #GstPadTemplate to add to the element class.
1017 * Adds a padtemplate to an element class. This is mainly used in the _base_init
1018 * functions of classes.
1021 gst_element_class_add_pad_template (GstElementClass * klass,
1022 GstPadTemplate * templ)
1024 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1025 g_return_if_fail (GST_IS_PAD_TEMPLATE (templ));
1027 /* avoid registering pad templates with the same name */
1028 g_return_if_fail (gst_element_class_get_pad_template (klass,
1029 templ->name_template) == NULL);
1031 klass->padtemplates = g_list_append (klass->padtemplates,
1032 gst_object_ref (templ));
1033 klass->numpadtemplates++;
1037 * gst_element_class_set_details:
1038 * @klass: class to set details for
1039 * @details: details to set
1041 * Sets the detailed information for a #GstElementClass.
1042 * <note>This function is for use in _base_init functions only.</note>
1045 gst_element_class_set_details (GstElementClass * klass,
1046 const GstElementDetails * details)
1048 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1049 g_return_if_fail (GST_IS_ELEMENT_DETAILS (details));
1051 __gst_element_details_copy (&klass->details, details);
1055 * gst_element_class_get_pad_template_list:
1056 * @element_class: a #GstElementClass to get pad templates of.
1058 * Retrieves a list of the pad templates associated with @element_class. The
1059 * list must not be modified by the calling code.
1060 * <note>If you use this function in the #GInstanceInitFunc of an object class
1061 * that has subclasses, make sure to pass the g_class parameter of the
1062 * #GInstanceInitFunc here.</note>
1064 * Returns: the #GList of padtemplates.
1067 gst_element_class_get_pad_template_list (GstElementClass * element_class)
1069 g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1071 return element_class->padtemplates;
1075 * gst_element_class_get_pad_template:
1076 * @element_class: a #GstElementClass to get the pad template of.
1077 * @name: the name of the #GstPadTemplate to get.
1079 * Retrieves a padtemplate from @element_class with the given name.
1080 * <note>If you use this function in the #GInstanceInitFunc of an object class
1081 * that has subclasses, make sure to pass the g_class parameter of the
1082 * #GInstanceInitFunc here.</note>
1084 * Returns: the #GstPadTemplate with the given name, or NULL if none was found.
1085 * No unreferencing is necessary.
1088 gst_element_class_get_pad_template (GstElementClass * element_class,
1093 g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1094 g_return_val_if_fail (name != NULL, NULL);
1096 padlist = gst_element_class_get_pad_template_list (element_class);
1099 GstPadTemplate *padtempl = (GstPadTemplate *) padlist->data;
1101 if (strcmp (padtempl->name_template, name) == 0)
1104 padlist = g_list_next (padlist);
1111 gst_element_get_random_pad (GstElement * element, GstPadDirection dir)
1113 GstPad *result = NULL;
1116 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "getting a random pad");
1121 pads = element->srcpads;
1125 pads = element->sinkpads;
1128 goto wrong_direction;
1130 for (; pads; pads = g_list_next (pads)) {
1131 GstPad *pad = GST_PAD (pads->data);
1134 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "checking pad %s:%s",
1135 GST_DEBUG_PAD_NAME (pad));
1137 if (GST_PAD_IS_LINKED (pad)) {
1142 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is not linked",
1143 GST_DEBUG_PAD_NAME (pad));
1148 gst_object_ref (result);
1150 GST_UNLOCK (element);
1154 /* ERROR handling */
1157 g_warning ("unknown pad direction %d", dir);
1163 * gst_element_send_event:
1164 * @element: a #GstElement to send the event to.
1165 * @event: the #GstEvent to send to the element.
1167 * Sends an event to an element. If the element doesn't
1168 * implement an event handler, the event will be forwarded
1169 * to a random sink pad. This function takes owership of the
1170 * provided event so you should _ref it if you want to reuse
1171 * the event after this call.
1173 * Returns: TRUE if the event was handled.
1178 gst_element_send_event (GstElement * element, GstEvent * event)
1180 GstElementClass *oclass;
1181 gboolean result = FALSE;
1183 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1184 g_return_val_if_fail (event != NULL, FALSE);
1186 oclass = GST_ELEMENT_GET_CLASS (element);
1188 if (oclass->send_event) {
1189 result = oclass->send_event (element, event);
1191 GstPad *pad = gst_element_get_random_pad (element, GST_PAD_SINK);
1194 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1195 "pushing event to random pad %s:%s", GST_DEBUG_PAD_NAME (pad));
1197 result = gst_pad_push_event (pad, event);
1198 gst_object_unref (pad);
1200 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "can't send event on element %s",
1201 GST_ELEMENT_NAME (element));
1209 * @element: a #GstElement to send the event to.
1210 * @rate: The new playback rate
1211 * @format: The format of the seek values
1212 * @flags: The optional seek flags.
1213 * @cur_type: The type and flags for the new current position
1214 * @cur: The value of the new current position
1215 * @stop_type: The type and flags for the new stop position
1216 * @stop: The value of the new stop position
1218 * Sends a seek event to an element.
1220 * Returns: %TRUE if the event was handled.
1225 gst_element_seek (GstElement * element, gdouble rate, GstFormat format,
1226 GstSeekFlags flags, GstSeekType cur_type, gint64 cur,
1227 GstSeekType stop_type, gint64 stop)
1232 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1235 gst_event_new_seek (rate, format, flags, cur_type, cur, stop_type, stop);
1236 result = gst_element_send_event (element, event);
1242 * gst_element_get_query_types:
1243 * @element: a #GstElement to query
1245 * Get an array of query types from the element.
1246 * If the element doesn't implement a query types function,
1247 * the query will be forwarded to a random sink pad.
1249 * Returns: An array of #GstQueryType elements that should not
1250 * be freed or modified.
1254 const GstQueryType *
1255 gst_element_get_query_types (GstElement * element)
1257 GstElementClass *oclass;
1258 const GstQueryType *result = NULL;
1260 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1262 oclass = GST_ELEMENT_GET_CLASS (element);
1264 if (oclass->get_query_types) {
1265 result = oclass->get_query_types (element);
1267 GstPad *pad = gst_element_get_random_pad (element, GST_PAD_SINK);
1270 GstPad *peer = gst_pad_get_peer (pad);
1273 result = gst_pad_get_query_types (peer);
1275 gst_object_unref (peer);
1277 gst_object_unref (pad);
1284 * gst_element_query:
1285 * @element: a #GstElement to perform the query on.
1286 * @query: the #GstQuery.
1288 * Performs a query on the given element. If the format is set
1289 * to GST_FORMAT_DEFAULT and this function returns TRUE, the
1290 * format pointer will hold the default format.
1291 * For element that don't implement a query handler, this function
1292 * forwards the query to a random usable sinkpad of this element.
1294 * Returns: TRUE if the query could be performed.
1299 gst_element_query (GstElement * element, GstQuery * query)
1301 GstElementClass *oclass;
1302 gboolean result = FALSE;
1304 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1305 g_return_val_if_fail (query != NULL, FALSE);
1307 oclass = GST_ELEMENT_GET_CLASS (element);
1309 if (oclass->query) {
1310 result = oclass->query (element, query);
1312 GstPad *pad = gst_element_get_random_pad (element, GST_PAD_SRC);
1315 result = gst_pad_query (pad, query);
1317 gst_object_unref (pad);
1319 pad = gst_element_get_random_pad (element, GST_PAD_SINK);
1321 GstPad *peer = gst_pad_get_peer (pad);
1324 result = gst_pad_query (peer, query);
1326 gst_object_unref (peer);
1328 gst_object_unref (pad);
1336 * gst_element_post_message:
1337 * @element: a #GstElement posting the message
1338 * @message: a #GstMessage to post
1340 * Post a message on the element's #GstBus. This function takes ownership of the
1341 * message; if you want to access the message after this call, you should add an
1342 * additional reference before calling.
1344 * Returns: TRUE if the message was successfully posted.
1349 gst_element_post_message (GstElement * element, GstMessage * message)
1352 gboolean result = FALSE;
1354 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1355 g_return_val_if_fail (message != NULL, FALSE);
1360 if (G_UNLIKELY (bus == NULL))
1363 gst_object_ref (bus);
1364 GST_UNLOCK (element);
1366 result = gst_bus_post (bus, message);
1367 gst_object_unref (bus);
1373 GST_DEBUG ("not posting message %p: no bus", message);
1374 GST_UNLOCK (element);
1375 gst_message_unref (message);
1381 * _gst_element_error_printf:
1382 * @format: the printf-like format to use, or NULL
1384 * This function is only used internally by the #gst_element_error macro.
1386 * Returns: a newly allocated string, or NULL if the format was NULL or ""
1391 _gst_element_error_printf (const gchar * format, ...)
1401 va_start (args, format);
1402 buffer = g_strdup_vprintf (format, args);
1408 * gst_element_message_full:
1409 * @element: a #GstElement to send message from
1410 * @type: the #GstMessageType
1411 * @domain: the GStreamer GError domain this message belongs to
1412 * @code: the GError code belonging to the domain
1413 * @text: an allocated text string to be used as a replacement for the
1414 * default message connected to code, or NULL
1415 * @debug: an allocated debug message to be used as a replacement for the
1416 * default debugging information, or NULL
1417 * @file: the source code file where the error was generated
1418 * @function: the source code function where the error was generated
1419 * @line: the source code line where the error was generated
1421 * Post an error or warning message on the bus from inside an element.
1425 void gst_element_message_full
1426 (GstElement * element, GstMessageType type,
1427 GQuark domain, gint code, gchar * text,
1428 gchar * debug, const gchar * file, const gchar * function, gint line)
1430 GError *gerror = NULL;
1434 GstMessage *message = NULL;
1437 GST_DEBUG ("start");
1438 g_return_if_fail (GST_IS_ELEMENT (element));
1439 g_return_if_fail ((type == GST_MESSAGE_ERROR) ||
1440 (type == GST_MESSAGE_WARNING));
1442 /* check if we send the given text or the default error text */
1443 if ((text == NULL) || (text[0] == 0)) {
1444 /* text could have come from g_strdup_printf (""); */
1446 sent_text = gst_error_get_message (domain, code);
1450 /* construct a sent_debug with extra information from source */
1451 if ((debug == NULL) || (debug[0] == 0)) {
1452 /* debug could have come from g_strdup_printf (""); */
1455 name = gst_object_get_path_string (GST_OBJECT (element));
1456 sent_debug = g_strdup_printf ("%s(%d): %s: %s:\n%s",
1457 file, line, function, name, debug ? debug : "");
1462 /* create gerror and post message */
1463 GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posting message: %s",
1465 gerror = g_error_new_literal (domain, code, sent_text);
1467 if (type == GST_MESSAGE_ERROR) {
1468 message = gst_message_new_error (GST_OBJECT (element), gerror, sent_debug);
1469 } else if (type == GST_MESSAGE_WARNING) {
1470 message = gst_message_new_warning (GST_OBJECT (element), gerror,
1473 g_assert_not_reached ();
1475 gst_element_post_message (element, message);
1477 GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posted message: %s",
1481 g_error_free (gerror);
1482 g_free (sent_debug);
1487 * gst_element_is_locked_state:
1488 * @element: a #GstElement.
1490 * Checks if the state of an element is locked.
1491 * If the state of an element is locked, state changes of the parent don't
1492 * affect the element.
1493 * This way you can leave currently unused elements inside bins. Just lock their
1494 * state before changing the state from #GST_STATE_NULL.
1496 * Returns: TRUE, if the element's state is locked.
1501 gst_element_is_locked_state (GstElement * element)
1505 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1508 result = GST_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
1509 GST_UNLOCK (element);
1515 * gst_element_set_locked_state:
1516 * @element: a #GstElement
1517 * @locked_state: TRUE to lock the element's state
1519 * Locks the state of an element, so state changes of the parent don't affect
1520 * this element anymore.
1522 * Returns: TRUE if the state was changed, FALSE if bad params were given or
1523 * the element was already in the correct state.
1528 gst_element_set_locked_state (GstElement * element, gboolean locked_state)
1532 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1535 old = GST_FLAG_IS_SET (element, GST_ELEMENT_LOCKED_STATE);
1537 if (G_UNLIKELY (old == locked_state))
1541 GST_CAT_DEBUG (GST_CAT_STATES, "locking state of element %s",
1542 GST_ELEMENT_NAME (element));
1543 GST_FLAG_SET (element, GST_ELEMENT_LOCKED_STATE);
1545 GST_CAT_DEBUG (GST_CAT_STATES, "unlocking state of element %s",
1546 GST_ELEMENT_NAME (element));
1547 GST_FLAG_UNSET (element, GST_ELEMENT_LOCKED_STATE);
1549 GST_UNLOCK (element);
1554 GST_UNLOCK (element);
1560 * gst_element_sync_state_with_parent:
1561 * @element: a #GstElement.
1563 * Tries to change the state of the element to the same as its parent.
1564 * If this function returns FALSE, the state of element is undefined.
1566 * Returns: TRUE, if the element's state could be synced to the parent's state.
1571 gst_element_sync_state_with_parent (GstElement * element)
1575 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1577 if ((parent = GST_ELEMENT_CAST (gst_element_get_parent (element)))) {
1578 GstState parent_current, parent_pending;
1579 GstStateChangeReturn ret;
1581 GST_STATE_LOCK (parent);
1582 parent_current = GST_STATE (parent);
1583 parent_pending = GST_STATE_PENDING (parent);
1584 GST_STATE_UNLOCK (parent);
1586 GST_CAT_DEBUG (GST_CAT_STATES,
1587 "syncing state of element %s (%s) to %s (%s, %s)",
1588 GST_ELEMENT_NAME (element),
1589 gst_element_state_get_name (GST_STATE (element)),
1590 GST_ELEMENT_NAME (parent), gst_element_state_get_name (parent_current),
1591 gst_element_state_get_name (parent_pending));
1593 ret = gst_element_set_state (element, parent_current);
1594 if (ret == GST_STATE_CHANGE_FAILURE)
1597 gst_object_unref (parent);
1611 static GstStateChangeReturn
1612 gst_element_get_state_func (GstElement * element,
1613 GstState * state, GstState * pending, GTimeVal * timeout)
1615 GstStateChangeReturn ret = GST_STATE_CHANGE_FAILURE;
1616 GstState old_pending;
1618 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "getting state");
1620 GST_STATE_LOCK (element);
1621 /* we got an error, report immediatly */
1622 if (GST_STATE_NO_PREROLL (element)) {
1623 ret = GST_STATE_CHANGE_NO_PREROLL;
1627 /* we got an error, report immediatly */
1628 if (GST_STATE_ERROR (element)) {
1629 ret = GST_STATE_CHANGE_FAILURE;
1633 old_pending = GST_STATE_PENDING (element);
1634 if (old_pending != GST_STATE_VOID_PENDING) {
1635 GTimeVal *timeval, abstimeout;
1638 glong add = timeout->tv_sec * G_USEC_PER_SEC + timeout->tv_usec;
1640 /* make timeout absolute */
1641 g_get_current_time (&abstimeout);
1642 g_time_val_add (&abstimeout, add);
1643 timeval = &abstimeout;
1647 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "wait for pending");
1648 /* we have a pending state change, wait for it to complete */
1649 if (!GST_STATE_TIMED_WAIT (element, timeval)) {
1650 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "timeout");
1651 /* timeout triggered */
1652 ret = GST_STATE_CHANGE_ASYNC;
1654 /* could be success or failure */
1655 if (old_pending == GST_STATE (element)) {
1656 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "got success");
1657 ret = GST_STATE_CHANGE_SUCCESS;
1659 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "got failure");
1660 ret = GST_STATE_CHANGE_FAILURE;
1664 /* if nothing is pending anymore we can return SUCCESS */
1665 if (GST_STATE_PENDING (element) == GST_STATE_VOID_PENDING) {
1666 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "nothing pending");
1667 ret = GST_STATE_CHANGE_SUCCESS;
1672 *state = GST_STATE (element);
1674 *pending = GST_STATE_PENDING (element);
1676 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
1677 "state current: %s, pending: %s, error: %d, no_preroll: %d, result: %d",
1678 gst_element_state_get_name (GST_STATE (element)),
1679 gst_element_state_get_name (GST_STATE_PENDING (element)),
1680 GST_STATE_ERROR (element), GST_STATE_NO_PREROLL (element), ret);
1682 GST_STATE_UNLOCK (element);
1688 * gst_element_get_state:
1689 * @element: a #GstElement to get the state of.
1690 * @state: a pointer to #GstState to hold the state. Can be NULL.
1691 * @pending: a pointer to #GstState to hold the pending state.
1693 * @timeout: a #GTimeVal to specify the timeout for an async
1694 * state change or NULL for infinite timeout.
1696 * Gets the state of the element.
1698 * For elements that performed an ASYNC state change, as reported by
1699 * #gst_element_set_state(), this function will block up to the
1700 * specified timeout value for the state change to complete.
1701 * If the element completes the state change or goes into
1702 * an error, this function returns immediatly with a return value of
1703 * GST_STATE_CHANGE_SUCCESS or GST_STATE_CHANGE_FAILURE respectively.
1705 * Returns: GST_STATE_CHANGE_SUCCESS if the element has no more pending state and
1706 * the last state change succeeded, GST_STATE_CHANGE_ASYNC
1707 * if the element is still performing a state change or
1708 * GST_STATE_CHANGE_FAILURE if the last state change failed.
1712 GstStateChangeReturn
1713 gst_element_get_state (GstElement * element,
1714 GstState * state, GstState * pending, GTimeVal * timeout)
1716 GstElementClass *oclass;
1717 GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
1719 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
1721 oclass = GST_ELEMENT_GET_CLASS (element);
1723 if (oclass->get_state)
1724 result = (oclass->get_state) (element, state, pending, timeout);
1730 * gst_element_abort_state:
1731 * @element: a #GstElement to abort the state of.
1733 * Abort the state change of the element. This function is used
1734 * by elements that do asynchronous state changes and find out
1735 * something is wrong.
1737 * This function should be called with the STATE_LOCK held.
1742 gst_element_abort_state (GstElement * element)
1746 g_return_if_fail (GST_IS_ELEMENT (element));
1748 pending = GST_STATE_PENDING (element);
1750 if (pending != GST_STATE_VOID_PENDING && !GST_STATE_ERROR (element)) {
1751 #ifndef GST_DISABLE_GST_DEBUG
1752 GstState old_state = GST_STATE (element);
1755 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
1756 "aborting state from %s to %s", gst_element_state_get_name (old_state),
1757 gst_element_state_get_name (pending));
1760 GST_STATE_ERROR (element) = TRUE;
1762 GST_STATE_BROADCAST (element);
1767 * gst_element_commit_state:
1768 * @element: a #GstElement to commit the state of.
1770 * Commit the state change of the element. This function is used
1771 * by elements that do asynchronous state changes.
1773 * This function can only be called with the STATE_LOCK held.
1778 gst_element_commit_state (GstElement * element)
1782 g_return_if_fail (GST_IS_ELEMENT (element));
1784 pending = GST_STATE_PENDING (element);
1786 if (pending != GST_STATE_VOID_PENDING) {
1787 GstState old_state = GST_STATE (element);
1788 GstMessage *message;
1790 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
1791 "committing state from %s to %s",
1792 gst_element_state_get_name (old_state),
1793 gst_element_state_get_name (pending));
1795 GST_STATE (element) = pending;
1796 GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
1797 GST_STATE_ERROR (element) = FALSE;
1799 message = gst_message_new_state_changed (GST_OBJECT (element),
1800 old_state, pending, pending);
1801 gst_element_post_message (element, message);
1802 GST_STATE_BROADCAST (element);
1807 * gst_element_lost_state:
1808 * @element: a #GstElement the state is lost of
1810 * Brings the element to the lost state. The current state of the
1811 * element is copied to the pending state so that any call to
1812 * #gst_element_get_state() will return ASYNC.
1814 * This is mostly used for elements that lost their preroll buffer
1815 * in the PAUSED state after a flush, they become PAUSED again
1816 * if a new preroll buffer is queued.
1817 * This function can only be called when the element is currently
1818 * not in error or an async state change.
1820 * This function can only be called with the STATE_LOCK held.
1825 gst_element_lost_state (GstElement * element)
1827 g_return_if_fail (GST_IS_ELEMENT (element));
1829 if (GST_STATE_PENDING (element) == GST_STATE_VOID_PENDING &&
1830 !GST_STATE_ERROR (element)) {
1831 GstState current_state;
1832 GstMessage *message;
1834 current_state = GST_STATE (element);
1836 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
1837 "lost state of %s", gst_element_state_get_name (current_state));
1839 GST_STATE_PENDING (element) = current_state;
1840 GST_STATE_ERROR (element) = FALSE;
1842 message = gst_message_new_state_changed (GST_OBJECT (element),
1843 current_state, current_state, current_state);
1844 gst_element_post_message (element, message);
1849 * gst_element_set_state:
1850 * @element: a #GstElement to change state of.
1851 * @state: the element's new #GstState.
1853 * Sets the state of the element. This function will try to set the
1854 * requested state by going through all the intermediary states and calling
1855 * the class's state change function for each.
1857 * Returns: Result of the state change using #GstStateChangeReturn.
1861 GstStateChangeReturn
1862 gst_element_set_state (GstElement * element, GstState state)
1864 GstState current, old_pending;
1865 GstStateChangeReturn ret;
1866 GstStateChange transition;
1869 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
1871 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "set_state to %s",
1872 gst_element_state_get_name (state));
1874 /* get current element state, need to call the method so that
1875 * we call the virtual method and subclasses can implement their
1877 GST_TIME_TO_TIMEVAL (0, tv);
1878 ret = gst_element_get_state (element, ¤t, &old_pending, &tv);
1880 GST_STATE_LOCK (element);
1882 /* this is the (new) state we should go to */
1883 GST_STATE_FINAL (element) = state;
1884 if (ret == GST_STATE_CHANGE_ASYNC) {
1885 /* force next state keeping ASYNC, this is atomic as we hold
1887 gst_element_commit_state (element);
1888 gst_element_lost_state (element);
1889 if (state == GST_STATE_PENDING (element))
1893 /* fixme, not right */
1894 transition = GST_STATE_CHANGE (element);
1896 ret = gst_element_change_state (element, transition);
1898 GST_STATE_UNLOCK (element);
1900 GST_DEBUG_OBJECT (element, "returned %d", ret);
1906 GST_STATE_UNLOCK (element);
1908 GST_DEBUG_OBJECT (element, "element was busy with async state change");
1910 return GST_STATE_CHANGE_ASYNC;
1914 /* with STATE_LOCK */
1915 static GstStateChangeReturn
1916 gst_element_change_state (GstElement * element, GstStateChange transition)
1918 GstElementClass *oclass;
1919 GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
1920 GstState current, next, final;
1922 oclass = GST_ELEMENT_GET_CLASS (element);
1924 /* start with the current state. */
1925 current = GST_STATE (element);
1926 next = GST_STATE_PENDING (element);
1927 final = GST_STATE_FINAL (element);
1929 /* We always perform at least one state change, even if the
1930 * current state is equal to the required state. This is needed
1931 * for bins that sync their children. */
1935 /* calculate the pending state */
1936 if (current < final)
1937 pending = current + 1;
1938 else if (current > final)
1939 pending = current - 1;
1943 /* set the pending state variable */
1944 GST_STATE_PENDING (element) = pending;
1946 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
1947 "%s: setting state from %s to %s",
1948 (pending != final ? "intermediate" : "final"),
1949 gst_element_state_get_name (current),
1950 gst_element_state_get_name (pending));
1952 /* call the state change function so it can set the state */
1953 if (oclass->change_state)
1954 ret = (oclass->change_state) (element, GST_STATE_CHANGE (element));
1956 ret = GST_STATE_CHANGE_FAILURE;
1958 /* clear the error and preroll flag, we need to do that after
1959 * calling the virtual change_state function so that it can use the
1960 * old previous value. */
1961 GST_STATE_ERROR (element) = FALSE;
1962 GST_STATE_NO_PREROLL (element) = FALSE;
1965 case GST_STATE_CHANGE_FAILURE:
1966 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
1967 "have failed change_state return");
1968 /* state change failure exits the loop */
1969 gst_element_abort_state (element);
1971 case GST_STATE_CHANGE_ASYNC:
1972 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
1973 "element will change state async");
1974 /* an async state change exits the loop, we can only
1975 * go to the next state change when this one completes. */
1977 case GST_STATE_CHANGE_SUCCESS:
1978 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
1979 "element changed state successfully");
1980 /* we can commit the state now and proceed to the next state */
1981 gst_element_commit_state (element);
1982 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "committed state");
1984 case GST_STATE_CHANGE_NO_PREROLL:
1985 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
1986 "element changed state successfully and can't preroll");
1987 /* we can commit the state now and proceed to the next state */
1988 gst_element_commit_state (element);
1989 GST_STATE_NO_PREROLL (element) = TRUE;
1990 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "committed state");
1993 ret = GST_STATE_CHANGE_FAILURE;
1994 goto invalid_return;
1996 /* get the current state of the element and see if we need to do more
1998 current = GST_STATE (element);
2000 while (current != final);
2003 GST_STATE_FINAL (element) = GST_STATE_VOID_PENDING;
2005 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "exit state change %d", ret);
2012 GST_STATE_FINAL (element) = GST_STATE_VOID_PENDING;
2013 /* somebody added a GST_STATE_ and forgot to do stuff here ! */
2014 g_critical ("unknown return value %d from a state change function", ret);
2019 /* gst_iterator_fold functions for pads_activate */
2022 activate_pads (GstPad * pad, GValue * ret, gboolean * active)
2024 if (!gst_pad_set_active (pad, *active))
2025 g_value_set_boolean (ret, FALSE);
2027 gst_pad_set_caps (pad, NULL);
2029 gst_object_unref (pad);
2033 /* returns false on error or early cutout of the fold, true otherwise */
2035 iterator_fold_with_resync (GstIterator * iter, GstIteratorFoldFunction func,
2036 GValue * ret, gpointer user_data)
2038 GstIteratorResult ires;
2039 gboolean res = TRUE;
2042 ires = gst_iterator_fold (iter, func, ret, user_data);
2045 case GST_ITERATOR_RESYNC:
2046 gst_iterator_resync (iter);
2048 case GST_ITERATOR_DONE:
2061 /* is called with STATE_LOCK
2064 gst_element_pads_activate (GstElement * element, gboolean active)
2066 GValue ret = { 0, };
2070 /* no need to unset this later, it's just a boolean */
2071 g_value_init (&ret, G_TYPE_BOOLEAN);
2072 g_value_set_boolean (&ret, TRUE);
2074 iter = gst_element_iterate_src_pads (element);
2075 fold_ok = iterator_fold_with_resync
2076 (iter, (GstIteratorFoldFunction) activate_pads, &ret, &active);
2077 gst_iterator_free (iter);
2078 if (!fold_ok || !g_value_get_boolean (&ret))
2081 iter = gst_element_iterate_sink_pads (element);
2082 fold_ok = iterator_fold_with_resync
2083 (iter, (GstIteratorFoldFunction) activate_pads, &ret, &active);
2084 gst_iterator_free (iter);
2085 if (!fold_ok || !g_value_get_boolean (&ret))
2091 /* is called with STATE_LOCK */
2092 static GstStateChangeReturn
2093 gst_element_change_state_func (GstElement * element, GstStateChange transition)
2095 GstState state, next;
2096 GstStateChangeReturn result = GST_STATE_CHANGE_SUCCESS;
2098 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2100 state = GST_STATE (element);
2101 next = GST_STATE_PENDING (element);
2103 /* if the element already is in the given state, we just return success */
2104 if (next == GST_STATE_VOID_PENDING || state == next)
2107 GST_CAT_LOG_OBJECT (GST_CAT_STATES, element,
2108 "default handler tries setting state from %s to %s (%04x)",
2109 gst_element_state_get_name (state),
2110 gst_element_state_get_name (next), transition);
2112 switch (transition) {
2113 case GST_STATE_CHANGE_NULL_TO_READY:
2115 case GST_STATE_CHANGE_READY_TO_PAUSED:
2116 if (!gst_element_pads_activate (element, TRUE)) {
2117 result = GST_STATE_CHANGE_FAILURE;
2120 case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
2122 case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
2124 case GST_STATE_CHANGE_PAUSED_TO_READY:
2125 case GST_STATE_CHANGE_READY_TO_NULL:
2126 /* deactivate pads in both cases, since they are activated on
2127 ready->paused but the element might not have made it to paused */
2128 if (!gst_element_pads_activate (element, FALSE)) {
2129 result = GST_STATE_CHANGE_FAILURE;
2131 gst_element_set_base_time (element, 0);
2135 /* this will catch real but unhandled state changes;
2136 * can only be caused by:
2137 * - a new state was added
2138 * - somehow the element was asked to jump across an intermediate state
2140 g_warning ("Unhandled state change from %s to %s",
2141 gst_element_state_get_name (state),
2142 gst_element_state_get_name (next));
2149 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2150 "element is already in the %s state",
2151 gst_element_state_get_name (state));
2152 if (GST_STATE_NO_PREROLL (element))
2153 return GST_STATE_CHANGE_NO_PREROLL;
2155 return GST_STATE_CHANGE_SUCCESS;
2160 * gst_element_get_factory:
2161 * @element: a #GstElement to request the element factory of.
2163 * Retrieves the factory that was used to create this element.
2165 * Returns: the #GstElementFactory used for creating this element.
2166 * no refcounting is needed.
2169 gst_element_get_factory (GstElement * element)
2171 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
2173 return GST_ELEMENT_GET_CLASS (element)->elementfactory;
2177 gst_element_dispose (GObject * object)
2179 GstElement *element = GST_ELEMENT (object);
2181 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "dispose");
2183 g_return_if_fail (GST_STATE (element) == GST_STATE_NULL);
2184 g_return_if_fail (GST_STATE_PENDING (element) == GST_STATE_VOID_PENDING);
2186 /* first we break all our links with the outside */
2187 while (element->pads) {
2188 gst_element_remove_pad (element, GST_PAD_CAST (element->pads->data));
2190 if (G_UNLIKELY (element->pads != 0)) {
2191 g_critical ("could not remove pads from element %s",
2192 GST_STR_NULL (GST_OBJECT_NAME (object)));
2196 gst_object_replace ((GstObject **) & element->clock, NULL);
2197 gst_object_replace ((GstObject **) & element->bus, NULL);
2198 GST_UNLOCK (element);
2200 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "parent class dispose");
2202 G_OBJECT_CLASS (parent_class)->dispose (object);
2206 gst_element_finalize (GObject * object)
2208 GstElement *element = GST_ELEMENT (object);
2210 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize");
2212 GST_STATE_LOCK (element);
2213 if (element->state_cond)
2214 g_cond_free (element->state_cond);
2215 element->state_cond = NULL;
2216 GST_STATE_UNLOCK (element);
2217 g_static_rec_mutex_free (element->state_lock);
2218 g_free (element->state_lock);
2219 element->state_lock = NULL;
2221 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "finalize parent");
2223 G_OBJECT_CLASS (parent_class)->finalize (object);
2226 #ifndef GST_DISABLE_LOADSAVE
2228 * gst_element_save_thyself:
2229 * @element: a #GstElement to save.
2230 * @parent: the xml parent node.
2232 * Saves the element as part of the given XML structure.
2234 * Returns: the new #xmlNodePtr.
2237 gst_element_save_thyself (GstObject * object, xmlNodePtr parent)
2240 GstElementClass *oclass;
2241 GParamSpec **specs, *spec;
2244 GValue value = { 0, };
2245 GstElement *element;
2247 g_return_val_if_fail (GST_IS_ELEMENT (object), parent);
2249 element = GST_ELEMENT (object);
2251 oclass = GST_ELEMENT_GET_CLASS (element);
2253 xmlNewChild (parent, NULL, (xmlChar *) "name",
2254 (xmlChar *) GST_ELEMENT_NAME (element));
2256 if (oclass->elementfactory != NULL) {
2257 GstElementFactory *factory = (GstElementFactory *) oclass->elementfactory;
2259 xmlNewChild (parent, NULL, (xmlChar *) "type",
2260 (xmlChar *) GST_PLUGIN_FEATURE (factory)->name);
2264 specs = g_object_class_list_properties (G_OBJECT_GET_CLASS (object), &nspecs);
2266 for (i = 0; i < nspecs; i++) {
2268 if (spec->flags & G_PARAM_READABLE) {
2272 g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (spec));
2274 g_object_get_property (G_OBJECT (element), spec->name, &value);
2275 param = xmlNewChild (parent, NULL, (xmlChar *) "param", NULL);
2276 xmlNewChild (param, NULL, (xmlChar *) "name", (xmlChar *) spec->name);
2278 if (G_IS_PARAM_SPEC_STRING (spec))
2279 contents = g_value_dup_string (&value);
2280 else if (G_IS_PARAM_SPEC_ENUM (spec))
2281 contents = g_strdup_printf ("%d", g_value_get_enum (&value));
2282 else if (G_IS_PARAM_SPEC_INT64 (spec))
2283 contents = g_strdup_printf ("%" G_GINT64_FORMAT,
2284 g_value_get_int64 (&value));
2286 contents = g_strdup_value_contents (&value);
2288 xmlNewChild (param, NULL, (xmlChar *) "value", (xmlChar *) contents);
2291 g_value_unset (&value);
2297 pads = GST_ELEMENT_PADS (element);
2300 GstPad *pad = GST_PAD (pads->data);
2302 /* figure out if it's a direct pad or a ghostpad */
2303 if (GST_ELEMENT (GST_OBJECT_PARENT (pad)) == element) {
2304 xmlNodePtr padtag = xmlNewChild (parent, NULL, (xmlChar *) "pad", NULL);
2306 gst_object_save_thyself (GST_OBJECT (pad), padtag);
2308 pads = g_list_next (pads);
2315 gst_element_restore_thyself (GstObject * object, xmlNodePtr self)
2317 xmlNodePtr children;
2318 GstElement *element;
2320 gchar *value = NULL;
2322 element = GST_ELEMENT (object);
2323 g_return_if_fail (element != NULL);
2326 children = self->xmlChildrenNode;
2328 if (!strcmp ((char *) children->name, "param")) {
2329 xmlNodePtr child = children->xmlChildrenNode;
2332 if (!strcmp ((char *) child->name, "name")) {
2333 name = (gchar *) xmlNodeGetContent (child);
2334 } else if (!strcmp ((char *) child->name, "value")) {
2335 value = (gchar *) xmlNodeGetContent (child);
2337 child = child->next;
2339 /* FIXME: can this just be g_object_set ? */
2340 gst_util_set_object_arg (G_OBJECT (element), name, value);
2341 /* g_object_set (G_OBJECT (element), name, value, NULL); */
2345 children = children->next;
2349 children = self->xmlChildrenNode;
2351 if (!strcmp ((char *) children->name, "pad")) {
2352 gst_pad_load_and_link (children, GST_OBJECT (element));
2354 children = children->next;
2357 if (GST_OBJECT_CLASS (parent_class)->restore_thyself)
2358 (GST_OBJECT_CLASS (parent_class)->restore_thyself) (object, self);
2360 #endif /* GST_DISABLE_LOADSAVE */
2363 gst_element_set_bus_func (GstElement * element, GstBus * bus)
2365 g_return_if_fail (GST_IS_ELEMENT (element));
2367 GST_CAT_DEBUG_OBJECT (GST_CAT_PARENTAGE, element, "setting bus to %p", bus);
2370 gst_object_replace ((GstObject **) & GST_ELEMENT_BUS (element),
2371 GST_OBJECT_CAST (bus));
2372 GST_UNLOCK (element);
2376 * gst_element_set_bus:
2377 * @element: a #GstElement to set the bus of.
2378 * @bus: the #GstBus to set.
2380 * Sets the bus of the element. For internal use only, unless you're
2386 gst_element_set_bus (GstElement * element, GstBus * bus)
2388 GstElementClass *oclass;
2390 g_return_if_fail (GST_IS_ELEMENT (element));
2392 oclass = GST_ELEMENT_GET_CLASS (element);
2394 if (oclass->set_bus)
2395 oclass->set_bus (element, bus);
2399 * gst_element_get_bus:
2400 * @element: a #GstElement to get the bus of.
2402 * Returns the bus of the element.
2404 * Returns: the element's #GstBus. unref after usage.
2409 gst_element_get_bus (GstElement * element)
2411 GstBus *result = NULL;
2413 g_return_val_if_fail (GST_IS_ELEMENT (element), result);
2416 result = GST_ELEMENT_BUS (element);
2417 gst_object_ref (result);
2418 GST_UNLOCK (element);
2420 GST_DEBUG_OBJECT (element, "got bus %" GST_PTR_FORMAT, result);