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., 51 Franklin St, Fifth Floor,
20 * Boston, MA 02110-1301, USA.
25 * @short_description: Abstract base class for all pipeline elements
26 * @see_also: #GstElementFactory, #GstPad
28 * GstElement is the abstract base class needed to construct an element that
29 * can be used in a GStreamer pipeline. Please refer to the plugin writers
30 * guide for more information on creating #GstElement subclasses.
32 * The name of a #GstElement can be get with gst_element_get_name() and set with
33 * gst_element_set_name(). For speed, GST_ELEMENT_NAME() can be used in the
34 * core when using the appropriate locking. Do not use this in plug-ins or
35 * applications in order to retain ABI compatibility.
37 * Elements can have pads (of the type #GstPad). These pads link to pads on
38 * other elements. #GstBuffer flow between these linked pads.
39 * A #GstElement has a #GList of #GstPad structures for all their input (or sink)
40 * and output (or source) pads.
41 * Core and plug-in writers can add and remove pads with gst_element_add_pad()
42 * and gst_element_remove_pad().
44 * An existing pad of an element can be retrieved by name with
45 * gst_element_get_static_pad(). A new dynamic pad can be created using
46 * gst_element_request_pad() with a #GstPadTemplate.
47 * An iterator of all pads can be retrieved with gst_element_iterate_pads().
49 * Elements can be linked through their pads.
50 * If the link is straightforward, use the gst_element_link()
51 * convenience function to link two elements, or gst_element_link_many()
52 * for more elements in a row.
53 * Use gst_element_link_filtered() to link two elements constrained by
54 * a specified set of #GstCaps.
55 * For finer control, use gst_element_link_pads() and
56 * gst_element_link_pads_filtered() to specify the pads to link on
57 * each element by name.
59 * Each element has a state (see #GstState). You can get and set the state
60 * of an element with gst_element_get_state() and gst_element_set_state().
61 * Setting a state triggers a #GstStateChange. To get a string representation
62 * of a #GstState, use gst_element_state_get_name().
64 * You can get and set a #GstClock on an element using gst_element_get_clock()
65 * and gst_element_set_clock().
66 * Some elements can provide a clock for the pipeline if
67 * the #GST_ELEMENT_FLAG_PROVIDE_CLOCK flag is set. With the
68 * gst_element_provide_clock() method one can retrieve the clock provided by
70 * Not all elements require a clock to operate correctly. If the
71 * #GST_ELEMENT_FLAG_REQUIRE_CLOCK() flag is set, a clock should be set on the
72 * element with gst_element_set_clock().
74 * Note that clock selection and distribution is normally handled by the
75 * toplevel #GstPipeline so the clock functions are only to be used in very
76 * specific situations.
79 #include "gst_private.h"
82 #include <gobject/gvaluecollector.h>
84 #include "gstelement.h"
85 #include "gstelementmetadata.h"
86 #include "gstenumtypes.h"
93 #include "gsttracerutils.h"
95 #include "gst-i18n-lib.h"
96 #include "glib-compat-private.h"
98 #ifndef GST_DISABLE_GST_DEBUG
99 #include "printf/printf.h"
102 /* Element signals and args */
118 static void gst_element_class_init (GstElementClass * klass);
119 static void gst_element_init (GstElement * element);
120 static void gst_element_base_class_init (gpointer g_class);
122 static void gst_element_constructed (GObject * object);
123 static void gst_element_dispose (GObject * object);
124 static void gst_element_finalize (GObject * object);
126 static GstStateChangeReturn gst_element_change_state_func (GstElement * element,
127 GstStateChange transition);
128 static GstStateChangeReturn gst_element_get_state_func (GstElement * element,
129 GstState * state, GstState * pending, GstClockTime timeout);
130 static GstStateChangeReturn gst_element_set_state_func (GstElement * element,
132 static gboolean gst_element_set_clock_func (GstElement * element,
134 static void gst_element_set_bus_func (GstElement * element, GstBus * bus);
135 static gboolean gst_element_post_message_default (GstElement * element,
136 GstMessage * message);
137 static void gst_element_set_context_default (GstElement * element,
138 GstContext * context);
140 static gboolean gst_element_default_send_event (GstElement * element,
142 static gboolean gst_element_default_query (GstElement * element,
145 static GstPadTemplate
146 * gst_element_class_get_request_pad_template (GstElementClass *
147 element_class, const gchar * name);
149 static void gst_element_call_async_func (gpointer data, gpointer user_data);
151 static GstObjectClass *parent_class = NULL;
152 static guint gst_element_signals[LAST_SIGNAL] = { 0 };
154 static GThreadPool *gst_element_pool = NULL;
156 /* this is used in gstelementfactory.c:gst_element_register() */
157 GQuark __gst_elementclass_factory = 0;
160 gst_element_get_type (void)
162 static volatile gsize gst_element_type = 0;
164 if (g_once_init_enter (&gst_element_type)) {
166 static const GTypeInfo element_info = {
167 sizeof (GstElementClass),
168 gst_element_base_class_init,
169 NULL, /* base_class_finalize */
170 (GClassInitFunc) gst_element_class_init,
175 (GInstanceInitFunc) gst_element_init,
179 _type = g_type_register_static (GST_TYPE_OBJECT, "GstElement",
180 &element_info, G_TYPE_FLAG_ABSTRACT);
182 __gst_elementclass_factory =
183 g_quark_from_static_string ("GST_ELEMENTCLASS_FACTORY");
184 g_once_init_leave (&gst_element_type, _type);
186 return gst_element_type;
190 gst_element_setup_thread_pool (void)
194 GST_DEBUG ("creating element thread pool");
196 g_thread_pool_new ((GFunc) gst_element_call_async_func, NULL, -1, FALSE,
199 g_critical ("could not alloc threadpool %s", err->message);
200 g_clear_error (&err);
205 gst_element_class_init (GstElementClass * klass)
207 GObjectClass *gobject_class;
209 gobject_class = (GObjectClass *) klass;
211 parent_class = g_type_class_peek_parent (klass);
214 * GstElement::pad-added:
215 * @gstelement: the object which received the signal
216 * @new_pad: the pad that has been added
218 * a new #GstPad has been added to the element. Note that this signal will
219 * usually be emitted from the context of the streaming thread. Also keep in
220 * mind that if you add new elements to the pipeline in the signal handler
221 * you will need to set them to the desired target state with
222 * gst_element_set_state() or gst_element_sync_state_with_parent().
224 gst_element_signals[PAD_ADDED] =
225 g_signal_new ("pad-added", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
226 G_STRUCT_OFFSET (GstElementClass, pad_added), NULL, NULL,
227 g_cclosure_marshal_generic, G_TYPE_NONE, 1, GST_TYPE_PAD);
229 * GstElement::pad-removed:
230 * @gstelement: the object which received the signal
231 * @old_pad: the pad that has been removed
233 * a #GstPad has been removed from the element
235 gst_element_signals[PAD_REMOVED] =
236 g_signal_new ("pad-removed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
237 G_STRUCT_OFFSET (GstElementClass, pad_removed), NULL, NULL,
238 g_cclosure_marshal_generic, G_TYPE_NONE, 1, GST_TYPE_PAD);
240 * GstElement::no-more-pads:
241 * @gstelement: the object which received the signal
243 * This signals that the element will not generate more dynamic pads.
244 * Note that this signal will usually be emitted from the context of
245 * the streaming thread.
247 gst_element_signals[NO_MORE_PADS] =
248 g_signal_new ("no-more-pads", G_TYPE_FROM_CLASS (klass),
249 G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstElementClass, no_more_pads), NULL,
250 NULL, g_cclosure_marshal_generic, G_TYPE_NONE, 0);
252 gobject_class->dispose = gst_element_dispose;
253 gobject_class->finalize = gst_element_finalize;
254 gobject_class->constructed = gst_element_constructed;
256 klass->change_state = GST_DEBUG_FUNCPTR (gst_element_change_state_func);
257 klass->set_state = GST_DEBUG_FUNCPTR (gst_element_set_state_func);
258 klass->get_state = GST_DEBUG_FUNCPTR (gst_element_get_state_func);
259 klass->set_clock = GST_DEBUG_FUNCPTR (gst_element_set_clock_func);
260 klass->set_bus = GST_DEBUG_FUNCPTR (gst_element_set_bus_func);
261 klass->query = GST_DEBUG_FUNCPTR (gst_element_default_query);
262 klass->send_event = GST_DEBUG_FUNCPTR (gst_element_default_send_event);
263 klass->numpadtemplates = 0;
264 klass->post_message = GST_DEBUG_FUNCPTR (gst_element_post_message_default);
265 klass->set_context = GST_DEBUG_FUNCPTR (gst_element_set_context_default);
267 klass->elementfactory = NULL;
269 gst_element_setup_thread_pool ();
273 gst_element_base_class_init (gpointer g_class)
275 GstElementClass *element_class = GST_ELEMENT_CLASS (g_class);
276 GList *node, *padtemplates;
278 /* Copy the element details here so elements can inherit the
279 * details from their base class and classes only need to set
280 * the details in class_init instead of base_init */
281 element_class->metadata =
282 element_class->metadata ? gst_structure_copy (element_class->metadata) :
283 gst_structure_new_empty ("metadata");
285 /* Copy the pad templates so elements inherit them
286 * from their base class but elements can add pad templates in class_init
287 * instead of base_init.
289 padtemplates = g_list_copy (element_class->padtemplates);
290 for (node = padtemplates; node != NULL; node = node->next) {
291 GstPadTemplate *tmpl = (GstPadTemplate *) node->data;
292 gst_object_ref (tmpl);
294 element_class->padtemplates = padtemplates;
296 /* set the factory, see gst_element_register() */
297 element_class->elementfactory =
298 g_type_get_qdata (G_TYPE_FROM_CLASS (element_class),
299 __gst_elementclass_factory);
300 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "type %s : factory %p",
301 G_OBJECT_CLASS_NAME (element_class), element_class->elementfactory);
305 gst_element_init (GstElement * element)
307 GST_STATE (element) = GST_STATE_NULL;
308 GST_STATE_TARGET (element) = GST_STATE_NULL;
309 GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
310 GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
311 GST_STATE_RETURN (element) = GST_STATE_CHANGE_SUCCESS;
313 g_rec_mutex_init (&element->state_lock);
314 g_cond_init (&element->state_cond);
318 gst_element_constructed (GObject * object)
320 GST_TRACER_ELEMENT_NEW (GST_ELEMENT_CAST (object));
321 G_OBJECT_CLASS (parent_class)->constructed (object);
325 * gst_element_release_request_pad:
326 * @element: a #GstElement to release the request pad of.
327 * @pad: the #GstPad to release.
329 * Makes the element free the previously requested pad as obtained
330 * with gst_element_request_pad().
332 * This does not unref the pad. If the pad was created by using
333 * gst_element_request_pad(), gst_element_release_request_pad() needs to be
334 * followed by gst_object_unref() to free the @pad.
339 gst_element_release_request_pad (GstElement * element, GstPad * pad)
341 GstElementClass *oclass;
343 g_return_if_fail (GST_IS_ELEMENT (element));
344 g_return_if_fail (GST_IS_PAD (pad));
345 g_return_if_fail (GST_PAD_PAD_TEMPLATE (pad) == NULL ||
346 GST_PAD_TEMPLATE_PRESENCE (GST_PAD_PAD_TEMPLATE (pad)) ==
348 g_return_if_fail (GST_PAD_PARENT (pad) == element);
350 oclass = GST_ELEMENT_GET_CLASS (element);
352 /* if the element implements a custom release function we call that, else we
353 * simply remove the pad from the element */
354 if (oclass->release_pad)
355 oclass->release_pad (element, pad);
357 gst_element_remove_pad (element, pad);
361 * gst_element_provide_clock:
362 * @element: a #GstElement to query
364 * Get the clock provided by the given element.
365 * <note>An element is only required to provide a clock in the PAUSED
366 * state. Some elements can provide a clock in other states.</note>
368 * Returns: (transfer full) (nullable): the GstClock provided by the
369 * element or %NULL if no clock could be provided. Unref after usage.
374 gst_element_provide_clock (GstElement * element)
376 GstClock *result = NULL;
377 GstElementClass *oclass;
379 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
381 oclass = GST_ELEMENT_GET_CLASS (element);
383 if (oclass->provide_clock)
384 result = oclass->provide_clock (element);
390 gst_element_set_clock_func (GstElement * element, GstClock * clock)
394 GST_OBJECT_LOCK (element);
395 clock_p = &element->clock;
396 gst_object_replace ((GstObject **) clock_p, (GstObject *) clock);
397 GST_OBJECT_UNLOCK (element);
403 * gst_element_set_clock:
404 * @element: a #GstElement to set the clock for.
405 * @clock: the #GstClock to set for the element.
407 * Sets the clock for the element. This function increases the
408 * refcount on the clock. Any previously set clock on the object
411 * Returns: %TRUE if the element accepted the clock. An element can refuse a
412 * clock when it, for example, is not able to slave its internal clock to the
413 * @clock or when it requires a specific clock to operate.
418 gst_element_set_clock (GstElement * element, GstClock * clock)
420 GstElementClass *oclass;
421 gboolean res = FALSE;
423 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
424 g_return_val_if_fail (clock == NULL || GST_IS_CLOCK (clock), FALSE);
426 oclass = GST_ELEMENT_GET_CLASS (element);
428 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, element, "setting clock %p", clock);
430 if (oclass->set_clock)
431 res = oclass->set_clock (element, clock);
437 * gst_element_get_clock:
438 * @element: a #GstElement to get the clock of.
440 * Gets the currently configured clock of the element. This is the clock as was
441 * last set with gst_element_set_clock().
443 * Elements in a pipeline will only have their clock set when the
444 * pipeline is in the PLAYING state.
446 * Returns: (transfer full): the #GstClock of the element. unref after usage.
451 gst_element_get_clock (GstElement * element)
455 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
457 GST_OBJECT_LOCK (element);
458 if ((result = element->clock))
459 gst_object_ref (result);
460 GST_OBJECT_UNLOCK (element);
466 * gst_element_set_base_time:
467 * @element: a #GstElement.
468 * @time: the base time to set.
470 * Set the base time of an element. See gst_element_get_base_time().
475 gst_element_set_base_time (GstElement * element, GstClockTime time)
479 g_return_if_fail (GST_IS_ELEMENT (element));
481 GST_OBJECT_LOCK (element);
482 old = element->base_time;
483 element->base_time = time;
484 GST_OBJECT_UNLOCK (element);
486 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, element,
487 "set base_time=%" GST_TIME_FORMAT ", old %" GST_TIME_FORMAT,
488 GST_TIME_ARGS (time), GST_TIME_ARGS (old));
492 * gst_element_get_base_time:
493 * @element: a #GstElement.
495 * Returns the base time of the element. The base time is the
496 * absolute time of the clock when this element was last put to
497 * PLAYING. Subtracting the base time from the clock time gives
498 * the running time of the element.
500 * Returns: the base time of the element.
505 gst_element_get_base_time (GstElement * element)
509 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_CLOCK_TIME_NONE);
511 GST_OBJECT_LOCK (element);
512 result = element->base_time;
513 GST_OBJECT_UNLOCK (element);
519 * gst_element_set_start_time:
520 * @element: a #GstElement.
521 * @time: the base time to set.
523 * Set the start time of an element. The start time of the element is the
524 * running time of the element when it last went to the PAUSED state. In READY
525 * or after a flushing seek, it is set to 0.
527 * Toplevel elements like #GstPipeline will manage the start_time and
528 * base_time on its children. Setting the start_time to #GST_CLOCK_TIME_NONE
529 * on such a toplevel element will disable the distribution of the base_time to
530 * the children and can be useful if the application manages the base_time
531 * itself, for example if you want to synchronize capture from multiple
532 * pipelines, and you can also ensure that the pipelines have the same clock.
537 gst_element_set_start_time (GstElement * element, GstClockTime time)
541 g_return_if_fail (GST_IS_ELEMENT (element));
543 GST_OBJECT_LOCK (element);
544 old = GST_ELEMENT_START_TIME (element);
545 GST_ELEMENT_START_TIME (element) = time;
546 GST_OBJECT_UNLOCK (element);
548 GST_CAT_DEBUG_OBJECT (GST_CAT_CLOCK, element,
549 "set start_time=%" GST_TIME_FORMAT ", old %" GST_TIME_FORMAT,
550 GST_TIME_ARGS (time), GST_TIME_ARGS (old));
554 * gst_element_get_start_time:
555 * @element: a #GstElement.
557 * Returns the start time of the element. The start time is the
558 * running time of the clock when this element was last put to PAUSED.
560 * Usually the start_time is managed by a toplevel element such as
565 * Returns: the start time of the element.
568 gst_element_get_start_time (GstElement * element)
572 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_CLOCK_TIME_NONE);
574 GST_OBJECT_LOCK (element);
575 result = GST_ELEMENT_START_TIME (element);
576 GST_OBJECT_UNLOCK (element);
583 * gst_element_set_index:
584 * @element: a #GstElement.
585 * @index: (transfer none): a #GstIndex.
587 * Set @index on the element. The refcount of the index
588 * will be increased, any previously set index is unreffed.
593 gst_element_set_index (GstElement * element, GstIndex * index)
595 GstElementClass *oclass;
597 g_return_if_fail (GST_IS_ELEMENT (element));
598 g_return_if_fail (index == NULL || GST_IS_INDEX (index));
600 oclass = GST_ELEMENT_GET_CLASS (element);
602 if (oclass->set_index)
603 oclass->set_index (element, index);
607 * gst_element_get_index:
608 * @element: a #GstElement.
610 * Gets the index from the element.
612 * Returns: (transfer full) (nullable): a #GstIndex or %NULL when no
613 * index was set on the element. unref after usage.
618 gst_element_get_index (GstElement * element)
620 GstElementClass *oclass;
621 GstIndex *result = NULL;
623 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
625 oclass = GST_ELEMENT_GET_CLASS (element);
627 if (oclass->get_index)
628 result = oclass->get_index (element);
635 * gst_element_add_pad:
636 * @element: a #GstElement to add the pad to.
637 * @pad: (transfer full): the #GstPad to add to the element.
639 * Adds a pad (link point) to @element. @pad's parent will be set to @element;
640 * see gst_object_set_parent() for refcounting information.
642 * Pads are not automatically activated so elements should perform the needed
643 * steps to activate the pad in case this pad is added in the PAUSED or PLAYING
644 * state. See gst_pad_set_active() for more information about activating pads.
646 * The pad and the element should be unlocked when calling this function.
648 * This function will emit the #GstElement::pad-added signal on the element.
650 * Returns: %TRUE if the pad could be added. This function can fail when
651 * a pad with the same name already existed or the pad already had another
657 gst_element_add_pad (GstElement * element, GstPad * pad)
662 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
663 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
665 /* locking pad to look at the name */
666 GST_OBJECT_LOCK (pad);
667 pad_name = g_strdup (GST_PAD_NAME (pad));
668 GST_CAT_INFO_OBJECT (GST_CAT_ELEMENT_PADS, element, "adding pad '%s'",
669 GST_STR_NULL (pad_name));
670 active = GST_PAD_IS_ACTIVE (pad);
671 GST_OBJECT_FLAG_SET (pad, GST_PAD_FLAG_NEED_PARENT);
672 GST_OBJECT_UNLOCK (pad);
674 /* then check to see if there's already a pad by that name here */
675 GST_OBJECT_LOCK (element);
676 if (G_UNLIKELY (!gst_object_check_uniqueness (element->pads, pad_name)))
679 /* try to set the pad's parent */
680 if (G_UNLIKELY (!gst_object_set_parent (GST_OBJECT_CAST (pad),
681 GST_OBJECT_CAST (element))))
684 /* check for active pads */
685 if (!active && (GST_STATE (element) > GST_STATE_READY ||
686 GST_STATE_NEXT (element) == GST_STATE_PAUSED)) {
687 g_warning ("adding inactive pad '%s' to running element '%s', you need to "
688 "use gst_pad_set_active(pad,TRUE) before adding it.",
689 GST_STR_NULL (pad_name), GST_ELEMENT_NAME (element));
690 gst_pad_set_active (pad, TRUE);
695 /* add it to the list */
696 switch (gst_pad_get_direction (pad)) {
698 element->srcpads = g_list_append (element->srcpads, pad);
699 element->numsrcpads++;
702 element->sinkpads = g_list_append (element->sinkpads, pad);
703 element->numsinkpads++;
708 element->pads = g_list_append (element->pads, pad);
710 element->pads_cookie++;
711 GST_OBJECT_UNLOCK (element);
713 /* emit the PAD_ADDED signal */
714 g_signal_emit (element, gst_element_signals[PAD_ADDED], 0, pad);
715 GST_TRACER_ELEMENT_ADD_PAD (element, pad);
721 g_critical ("Padname %s is not unique in element %s, not adding",
722 pad_name, GST_ELEMENT_NAME (element));
723 GST_OBJECT_UNLOCK (element);
730 ("Pad %s already has parent when trying to add to element %s",
731 pad_name, GST_ELEMENT_NAME (element));
732 GST_OBJECT_UNLOCK (element);
738 GST_OBJECT_LOCK (pad);
740 ("Trying to add pad %s to element %s, but it has no direction",
741 GST_OBJECT_NAME (pad), GST_ELEMENT_NAME (element));
742 GST_OBJECT_UNLOCK (pad);
743 GST_OBJECT_UNLOCK (element);
749 * gst_element_remove_pad:
750 * @element: a #GstElement to remove pad from.
751 * @pad: (transfer full): the #GstPad to remove from the element.
753 * Removes @pad from @element. @pad will be destroyed if it has not been
754 * referenced elsewhere using gst_object_unparent().
756 * This function is used by plugin developers and should not be used
757 * by applications. Pads that were dynamically requested from elements
758 * with gst_element_request_pad() should be released with the
759 * gst_element_release_request_pad() function instead.
761 * Pads are not automatically deactivated so elements should perform the needed
762 * steps to deactivate the pad in case this pad is removed in the PAUSED or
763 * PLAYING state. See gst_pad_set_active() for more information about
766 * The pad and the element should be unlocked when calling this function.
768 * This function will emit the #GstElement::pad-removed signal on the element.
770 * Returns: %TRUE if the pad could be removed. Can return %FALSE if the
771 * pad does not belong to the provided element.
776 gst_element_remove_pad (GstElement * element, GstPad * pad)
780 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
781 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
783 /* locking pad to look at the name and parent */
784 GST_OBJECT_LOCK (pad);
785 GST_CAT_INFO_OBJECT (GST_CAT_ELEMENT_PADS, element, "removing pad '%s'",
786 GST_STR_NULL (GST_PAD_NAME (pad)));
788 if (G_UNLIKELY (GST_PAD_PARENT (pad) != element))
790 GST_OBJECT_UNLOCK (pad);
793 if ((peer = gst_pad_get_peer (pad))) {
794 /* window for MT unsafeness, someone else could unlink here
795 * and then we call unlink with wrong pads. The unlink
796 * function would catch this and safely return failed. */
797 if (GST_PAD_IS_SRC (pad))
798 gst_pad_unlink (pad, peer);
800 gst_pad_unlink (peer, pad);
802 gst_object_unref (peer);
805 GST_OBJECT_LOCK (element);
806 /* remove it from the list */
807 switch (gst_pad_get_direction (pad)) {
809 element->srcpads = g_list_remove (element->srcpads, pad);
810 element->numsrcpads--;
813 element->sinkpads = g_list_remove (element->sinkpads, pad);
814 element->numsinkpads--;
817 g_critical ("Removing pad without direction???");
820 element->pads = g_list_remove (element->pads, pad);
822 element->pads_cookie++;
823 GST_OBJECT_UNLOCK (element);
825 /* emit the PAD_REMOVED signal before unparenting and losing the last ref. */
826 g_signal_emit (element, gst_element_signals[PAD_REMOVED], 0, pad);
827 GST_TRACER_ELEMENT_REMOVE_PAD (element, pad);
828 gst_object_unparent (GST_OBJECT_CAST (pad));
835 /* locking order is element > pad */
836 GST_OBJECT_UNLOCK (pad);
838 GST_OBJECT_LOCK (element);
839 GST_OBJECT_LOCK (pad);
840 g_critical ("Padname %s:%s does not belong to element %s when removing",
841 GST_DEBUG_PAD_NAME (pad), GST_ELEMENT_NAME (element));
842 GST_OBJECT_UNLOCK (pad);
843 GST_OBJECT_UNLOCK (element);
849 * gst_element_no_more_pads:
850 * @element: a #GstElement
852 * Use this function to signal that the element does not expect any more pads
853 * to show up in the current pipeline. This function should be called whenever
854 * pads have been added by the element itself. Elements with #GST_PAD_SOMETIMES
855 * pad templates use this in combination with autopluggers to figure out that
856 * the element is done initializing its pads.
858 * This function emits the #GstElement::no-more-pads signal.
863 gst_element_no_more_pads (GstElement * element)
865 g_return_if_fail (GST_IS_ELEMENT (element));
867 g_signal_emit (element, gst_element_signals[NO_MORE_PADS], 0);
871 pad_compare_name (GstPad * pad1, const gchar * name)
875 GST_OBJECT_LOCK (pad1);
876 result = strcmp (GST_PAD_NAME (pad1), name);
877 GST_OBJECT_UNLOCK (pad1);
883 * gst_element_get_static_pad:
884 * @element: a #GstElement to find a static pad of.
885 * @name: the name of the static #GstPad to retrieve.
887 * Retrieves a pad from @element by name. This version only retrieves
888 * already-existing (i.e. 'static') pads.
890 * Returns: (transfer full) (nullable): the requested #GstPad if
891 * found, otherwise %NULL. unref after usage.
896 gst_element_get_static_pad (GstElement * element, const gchar * name)
899 GstPad *result = NULL;
901 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
902 g_return_val_if_fail (name != NULL, NULL);
904 GST_OBJECT_LOCK (element);
906 g_list_find_custom (element->pads, name, (GCompareFunc) pad_compare_name);
908 result = GST_PAD_CAST (find->data);
909 gst_object_ref (result);
912 if (result == NULL) {
913 GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "no such pad '%s' in element \"%s\"",
914 name, GST_ELEMENT_NAME (element));
916 GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "found pad %s:%s",
917 GST_ELEMENT_NAME (element), name);
919 GST_OBJECT_UNLOCK (element);
925 gst_element_is_valid_request_template_name (const gchar * templ_name,
929 const gchar *templ_name_ptr, *name_ptr;
930 gboolean next_specifier;
931 guint templ_postfix_len = 0, name_postfix_len = 0;
933 g_return_val_if_fail (templ_name != NULL, FALSE);
934 g_return_val_if_fail (name != NULL, FALSE);
936 /* Is this the template name? */
937 if (strcmp (templ_name, name) == 0)
940 /* otherwise check all the specifiers */
942 /* Because of sanity checks in gst_pad_template_new(), we know that %s
943 * and %d and %u, occurring at the template_name */
944 templ_name_ptr = strchr (templ_name, '%');
946 /* check characters ahead of the specifier */
947 if (!templ_name_ptr || strlen (name) <= templ_name_ptr - templ_name
948 || strncmp (templ_name, name, templ_name_ptr - templ_name) != 0) {
952 /* %s is not allowed for multiple specifiers, just a single specifier can be
953 * accepted in gst_pad_template_new() and can not be mixed with other
954 * specifier '%u' and '%d' */
955 if (*(templ_name_ptr + 1) == 's' && g_strcmp0 (templ_name, name) == 0) {
959 name_ptr = name + (templ_name_ptr - templ_name);
961 /* search next specifier, each of specifier should be separated by '_' */
962 templ_name = strchr (templ_name_ptr, '_');
963 name = strchr (name_ptr, '_');
965 /* don't match the number of specifiers */
966 if ((templ_name && !name) || (!templ_name && name))
969 if (templ_name && name)
970 next_specifier = TRUE;
972 next_specifier = FALSE;
974 /* check characters followed by the specifier */
975 if (*(templ_name_ptr + 2) != '\0' && *(templ_name_ptr + 2) != '_') {
976 if (next_specifier) {
977 templ_postfix_len = templ_name - (templ_name_ptr + 2);
978 name_postfix_len = name - name_ptr;
980 templ_postfix_len = strlen (templ_name_ptr + 2);
981 name_postfix_len = strlen (name_ptr);
984 if (strncmp (templ_name_ptr + 2,
985 name_ptr + name_postfix_len - templ_postfix_len,
986 templ_postfix_len) != 0) {
991 /* verify the specifier */
992 if (*(name_ptr) == '%') {
995 len = (next_specifier) ? name - name_ptr : strlen (name_ptr);
997 if (strncmp (name_ptr, templ_name_ptr, len) != 0)
1001 const gchar *specifier;
1002 gchar *target = NULL;
1004 /* extract specifier when it has postfix characters */
1005 if (name_postfix_len > templ_postfix_len) {
1006 target = g_strndup (name_ptr, name_postfix_len - templ_postfix_len);
1008 specifier = target ? target : name_ptr;
1010 if (*(templ_name_ptr + 1) == 'd') {
1014 tmp = g_ascii_strtoll (specifier, &endptr, 10);
1015 if (tmp < G_MININT || tmp > G_MAXINT || (*endptr != '\0'
1018 } else if (*(templ_name_ptr + 1) == 'u') {
1022 tmp = g_ascii_strtoull (specifier, &endptr, 10);
1023 if (tmp > G_MAXUINT || (*endptr != '\0' && *endptr != '_'))
1030 /* otherwise we increment these from NULL to 1 */
1031 if (next_specifier) {
1035 } while (next_specifier);
1041 _gst_element_request_pad (GstElement * element, GstPadTemplate * templ,
1042 const gchar * name, const GstCaps * caps)
1044 GstPad *newpad = NULL;
1045 GstElementClass *oclass;
1047 oclass = GST_ELEMENT_GET_CLASS (element);
1049 #ifndef G_DISABLE_CHECKS
1050 /* Some sanity checking here */
1054 g_return_val_if_fail (gst_element_is_valid_request_template_name
1055 (templ->name_template, name), NULL);
1057 pad = gst_element_get_static_pad (element, name);
1059 gst_object_unref (pad);
1060 /* FIXME 2.0: Change this to g_return_val_if_fail() */
1061 g_critical ("Element %s already has a pad named %s, the behaviour of "
1062 " gst_element_get_request_pad() for existing pads is undefined!",
1063 GST_ELEMENT_NAME (element), name);
1068 if (oclass->request_new_pad)
1069 newpad = (oclass->request_new_pad) (element, templ, name, caps);
1072 gst_object_ref (newpad);
1078 * gst_element_get_request_pad:
1079 * @element: a #GstElement to find a request pad of.
1080 * @name: the name of the request #GstPad to retrieve.
1082 * Retrieves a pad from the element by name (e.g. "src_\%d"). This version only
1083 * retrieves request pads. The pad should be released with
1084 * gst_element_release_request_pad().
1086 * This method is slower than manually getting the pad template and calling
1087 * gst_element_request_pad() if the pads should have a specific name (e.g.
1088 * @name is "src_1" instead of "src_\%u").
1090 * Returns: (transfer full) (nullable): requested #GstPad if found,
1091 * otherwise %NULL. Release after usage.
1094 gst_element_get_request_pad (GstElement * element, const gchar * name)
1096 GstPadTemplate *templ = NULL;
1098 const gchar *req_name = NULL;
1099 gboolean templ_found = FALSE;
1101 GstElementClass *class;
1103 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1104 g_return_val_if_fail (name != NULL, NULL);
1106 class = GST_ELEMENT_GET_CLASS (element);
1108 templ = gst_element_class_get_request_pad_template (class, name);
1110 req_name = strstr (name, "%") ? NULL : name;
1113 /* there is no % in the name, try to find a matching template */
1114 list = class->padtemplates;
1115 while (!templ_found && list) {
1116 templ = (GstPadTemplate *) list->data;
1117 if (templ->presence == GST_PAD_REQUEST) {
1118 GST_CAT_DEBUG (GST_CAT_PADS, "comparing %s to %s", name,
1119 templ->name_template);
1120 if (gst_element_is_valid_request_template_name (templ->name_template,
1134 pad = _gst_element_request_pad (element, templ, req_name, NULL);
1140 * gst_element_request_pad: (virtual request_new_pad)
1141 * @element: a #GstElement to find a request pad of.
1142 * @templ: a #GstPadTemplate of which we want a pad of.
1143 * @name: (transfer none) (allow-none): the name of the request #GstPad
1144 * to retrieve. Can be %NULL.
1145 * @caps: (transfer none) (allow-none): the caps of the pad we want to
1146 * request. Can be %NULL.
1148 * Retrieves a request pad from the element according to the provided template.
1149 * Pad templates can be looked up using
1150 * gst_element_factory_get_static_pad_templates().
1152 * The pad should be released with gst_element_release_request_pad().
1154 * Returns: (transfer full) (nullable): requested #GstPad if found,
1155 * otherwise %NULL. Release after usage.
1158 gst_element_request_pad (GstElement * element,
1159 GstPadTemplate * templ, const gchar * name, const GstCaps * caps)
1161 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1162 g_return_val_if_fail (templ != NULL, NULL);
1163 g_return_val_if_fail (templ->presence == GST_PAD_REQUEST, NULL);
1165 return _gst_element_request_pad (element, templ, name, caps);
1168 static GstIterator *
1169 gst_element_iterate_pad_list (GstElement * element, GList ** padlist)
1171 GstIterator *result;
1173 GST_OBJECT_LOCK (element);
1174 result = gst_iterator_new_list (GST_TYPE_PAD,
1175 GST_OBJECT_GET_LOCK (element),
1176 &element->pads_cookie, padlist, (GObject *) element, NULL);
1177 GST_OBJECT_UNLOCK (element);
1183 * gst_element_iterate_pads:
1184 * @element: a #GstElement to iterate pads of.
1186 * Retrieves an iterator of @element's pads. The iterator should
1187 * be freed after usage. Also more specialized iterators exists such as
1188 * gst_element_iterate_src_pads() or gst_element_iterate_sink_pads().
1190 * The order of pads returned by the iterator will be the order in which
1191 * the pads were added to the element.
1193 * Returns: (transfer full): the #GstIterator of #GstPad.
1198 gst_element_iterate_pads (GstElement * element)
1200 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1202 return gst_element_iterate_pad_list (element, &element->pads);
1206 * gst_element_iterate_src_pads:
1207 * @element: a #GstElement.
1209 * Retrieves an iterator of @element's source pads.
1211 * The order of pads returned by the iterator will be the order in which
1212 * the pads were added to the element.
1214 * Returns: (transfer full): the #GstIterator of #GstPad.
1219 gst_element_iterate_src_pads (GstElement * element)
1221 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1223 return gst_element_iterate_pad_list (element, &element->srcpads);
1227 * gst_element_iterate_sink_pads:
1228 * @element: a #GstElement.
1230 * Retrieves an iterator of @element's sink pads.
1232 * The order of pads returned by the iterator will be the order in which
1233 * the pads were added to the element.
1235 * Returns: (transfer full): the #GstIterator of #GstPad.
1240 gst_element_iterate_sink_pads (GstElement * element)
1242 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1244 return gst_element_iterate_pad_list (element, &element->sinkpads);
1248 * gst_element_class_add_pad_template:
1249 * @klass: the #GstElementClass to add the pad template to.
1250 * @templ: (transfer full): a #GstPadTemplate to add to the element class.
1252 * Adds a padtemplate to an element class. This is mainly used in the _class_init
1253 * functions of classes. If a pad template with the same name as an already
1254 * existing one is added the old one is replaced by the new one.
1258 gst_element_class_add_pad_template (GstElementClass * klass,
1259 GstPadTemplate * templ)
1261 GList *template_list = klass->padtemplates;
1263 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1264 g_return_if_fail (GST_IS_PAD_TEMPLATE (templ));
1266 /* If we already have a pad template with the same name replace the
1268 while (template_list) {
1269 GstPadTemplate *padtempl = (GstPadTemplate *) template_list->data;
1271 /* Found pad with the same name, replace and return */
1272 if (strcmp (templ->name_template, padtempl->name_template) == 0) {
1273 gst_object_unref (padtempl);
1274 template_list->data = templ;
1277 template_list = g_list_next (template_list);
1280 /* Take ownership of the floating ref */
1281 gst_object_ref_sink (templ);
1283 klass->padtemplates = g_list_append (klass->padtemplates, templ);
1284 klass->numpadtemplates++;
1288 * gst_element_class_add_static_pad_template:
1289 * @klass: the #GstElementClass to add the pad template to.
1290 * @static_templ: #GstStaticPadTemplate to add as pad template to the element class.
1292 * Adds a pad template to an element class based on the static pad template
1293 * @templ. This is mainly used in the _class_init functions of element
1294 * implementations. If a pad template with the same name already exists,
1295 * the old one is replaced by the new one.
1300 gst_element_class_add_static_pad_template (GstElementClass * klass,
1301 GstStaticPadTemplate * static_templ)
1303 gst_element_class_add_pad_template (klass,
1304 gst_static_pad_template_get (static_templ));
1308 * gst_element_class_add_metadata:
1309 * @klass: class to set metadata for
1310 * @key: the key to set
1311 * @value: the value to set
1313 * Set @key with @value as metadata in @klass.
1316 gst_element_class_add_metadata (GstElementClass * klass,
1317 const gchar * key, const gchar * value)
1319 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1320 g_return_if_fail (key != NULL);
1321 g_return_if_fail (value != NULL);
1323 gst_structure_set ((GstStructure *) klass->metadata,
1324 key, G_TYPE_STRING, value, NULL);
1328 * gst_element_class_add_static_metadata:
1329 * @klass: class to set metadata for
1330 * @key: the key to set
1331 * @value: the value to set
1333 * Set @key with @value as metadata in @klass.
1335 * Same as gst_element_class_add_metadata(), but @value must be a static string
1336 * or an inlined string, as it will not be copied. (GStreamer plugins will
1337 * be made resident once loaded, so this function can be used even from
1338 * dynamically loaded plugins.)
1341 gst_element_class_add_static_metadata (GstElementClass * klass,
1342 const gchar * key, const gchar * value)
1344 GValue val = G_VALUE_INIT;
1346 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1347 g_return_if_fail (key != NULL);
1348 g_return_if_fail (value != NULL);
1350 g_value_init (&val, G_TYPE_STRING);
1351 g_value_set_static_string (&val, value);
1352 gst_structure_take_value ((GstStructure *) klass->metadata, key, &val);
1356 * gst_element_class_set_metadata:
1357 * @klass: class to set metadata for
1358 * @longname: The long English name of the element. E.g. "File Sink"
1359 * @classification: String describing the type of element, as an unordered list
1360 * separated with slashes ('/'). See draft-klass.txt of the design docs
1361 * for more details and common types. E.g: "Sink/File"
1362 * @description: Sentence describing the purpose of the element.
1363 * E.g: "Write stream to a file"
1364 * @author: Name and contact details of the author(s). Use \n to separate
1365 * multiple author metadata. E.g: "Joe Bloggs <joe.blogs at foo.com>"
1367 * Sets the detailed information for a #GstElementClass.
1368 * <note>This function is for use in _class_init functions only.</note>
1371 gst_element_class_set_metadata (GstElementClass * klass,
1372 const gchar * longname, const gchar * classification,
1373 const gchar * description, const gchar * author)
1375 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1376 g_return_if_fail (longname != NULL && *longname != '\0');
1377 g_return_if_fail (classification != NULL && *classification != '\0');
1378 g_return_if_fail (description != NULL && *description != '\0');
1379 g_return_if_fail (author != NULL && *author != '\0');
1381 gst_structure_id_set ((GstStructure *) klass->metadata,
1382 GST_QUARK (ELEMENT_METADATA_LONGNAME), G_TYPE_STRING, longname,
1383 GST_QUARK (ELEMENT_METADATA_KLASS), G_TYPE_STRING, classification,
1384 GST_QUARK (ELEMENT_METADATA_DESCRIPTION), G_TYPE_STRING, description,
1385 GST_QUARK (ELEMENT_METADATA_AUTHOR), G_TYPE_STRING, author, NULL);
1389 * gst_element_class_set_static_metadata:
1390 * @klass: class to set metadata for
1391 * @longname: The long English name of the element. E.g. "File Sink"
1392 * @classification: String describing the type of element, as an unordered list
1393 * separated with slashes ('/'). See draft-klass.txt of the design docs
1394 * for more details and common types. E.g: "Sink/File"
1395 * @description: Sentence describing the purpose of the element.
1396 * E.g: "Write stream to a file"
1397 * @author: Name and contact details of the author(s). Use \n to separate
1398 * multiple author metadata. E.g: "Joe Bloggs <joe.blogs at foo.com>"
1400 * Sets the detailed information for a #GstElementClass.
1401 * <note>This function is for use in _class_init functions only.</note>
1403 * Same as gst_element_class_set_metadata(), but @longname, @classification,
1404 * @description, and @author must be static strings or inlined strings, as
1405 * they will not be copied. (GStreamer plugins will be made resident once
1406 * loaded, so this function can be used even from dynamically loaded plugins.)
1409 gst_element_class_set_static_metadata (GstElementClass * klass,
1410 const gchar * longname, const gchar * classification,
1411 const gchar * description, const gchar * author)
1413 GstStructure *s = (GstStructure *) klass->metadata;
1414 GValue val = G_VALUE_INIT;
1416 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
1417 g_return_if_fail (longname != NULL && *longname != '\0');
1418 g_return_if_fail (classification != NULL && *classification != '\0');
1419 g_return_if_fail (description != NULL && *description != '\0');
1420 g_return_if_fail (author != NULL && *author != '\0');
1422 g_value_init (&val, G_TYPE_STRING);
1424 g_value_set_static_string (&val, longname);
1425 gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_LONGNAME), &val);
1427 g_value_set_static_string (&val, classification);
1428 gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_KLASS), &val);
1430 g_value_set_static_string (&val, description);
1431 gst_structure_id_set_value (s, GST_QUARK (ELEMENT_METADATA_DESCRIPTION),
1434 g_value_set_static_string (&val, author);
1435 gst_structure_id_take_value (s, GST_QUARK (ELEMENT_METADATA_AUTHOR), &val);
1439 * gst_element_class_get_metadata:
1440 * @klass: class to get metadata for
1441 * @key: the key to get
1443 * Get metadata with @key in @klass.
1445 * Returns: the metadata for @key.
1448 gst_element_class_get_metadata (GstElementClass * klass, const gchar * key)
1450 g_return_val_if_fail (GST_IS_ELEMENT_CLASS (klass), NULL);
1451 g_return_val_if_fail (key != NULL, NULL);
1453 return gst_structure_get_string ((GstStructure *) klass->metadata, key);
1457 * gst_element_class_get_pad_template_list:
1458 * @element_class: a #GstElementClass to get pad templates of.
1460 * Retrieves a list of the pad templates associated with @element_class. The
1461 * list must not be modified by the calling code.
1462 * <note>If you use this function in the #GInstanceInitFunc of an object class
1463 * that has subclasses, make sure to pass the g_class parameter of the
1464 * #GInstanceInitFunc here.</note>
1466 * Returns: (transfer none) (element-type Gst.PadTemplate): the #GList of
1470 gst_element_class_get_pad_template_list (GstElementClass * element_class)
1472 g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1474 return element_class->padtemplates;
1478 * gst_element_class_get_pad_template:
1479 * @element_class: a #GstElementClass to get the pad template of.
1480 * @name: the name of the #GstPadTemplate to get.
1482 * Retrieves a padtemplate from @element_class with the given name.
1483 * <note>If you use this function in the #GInstanceInitFunc of an object class
1484 * that has subclasses, make sure to pass the g_class parameter of the
1485 * #GInstanceInitFunc here.</note>
1487 * Returns: (transfer none) (nullable): the #GstPadTemplate with the
1488 * given name, or %NULL if none was found. No unreferencing is
1492 gst_element_class_get_pad_template (GstElementClass *
1493 element_class, const gchar * name)
1497 g_return_val_if_fail (GST_IS_ELEMENT_CLASS (element_class), NULL);
1498 g_return_val_if_fail (name != NULL, NULL);
1500 padlist = element_class->padtemplates;
1503 GstPadTemplate *padtempl = (GstPadTemplate *) padlist->data;
1505 if (strcmp (padtempl->name_template, name) == 0)
1508 padlist = g_list_next (padlist);
1514 static GstPadTemplate *
1515 gst_element_class_get_request_pad_template (GstElementClass *
1516 element_class, const gchar * name)
1518 GstPadTemplate *tmpl;
1520 tmpl = gst_element_class_get_pad_template (element_class, name);
1521 if (tmpl != NULL && tmpl->presence == GST_PAD_REQUEST)
1527 /* get a random pad on element of the given direction.
1528 * The pad is random in a sense that it is the first pad that is (optionaly) linked.
1531 gst_element_get_random_pad (GstElement * element,
1532 gboolean need_linked, GstPadDirection dir)
1534 GstPad *result = NULL;
1537 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "getting a random pad");
1541 GST_OBJECT_LOCK (element);
1542 pads = element->srcpads;
1545 GST_OBJECT_LOCK (element);
1546 pads = element->sinkpads;
1549 goto wrong_direction;
1551 for (; pads; pads = g_list_next (pads)) {
1552 GstPad *pad = GST_PAD_CAST (pads->data);
1554 GST_OBJECT_LOCK (pad);
1555 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "checking pad %s:%s",
1556 GST_DEBUG_PAD_NAME (pad));
1558 if (need_linked && !GST_PAD_IS_LINKED (pad)) {
1559 /* if we require a linked pad, and it is not linked, continue the
1561 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is not linked",
1562 GST_DEBUG_PAD_NAME (pad));
1563 GST_OBJECT_UNLOCK (pad);
1566 /* found a pad, stop search */
1567 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "found pad %s:%s",
1568 GST_DEBUG_PAD_NAME (pad));
1569 GST_OBJECT_UNLOCK (pad);
1575 gst_object_ref (result);
1577 GST_OBJECT_UNLOCK (element);
1581 /* ERROR handling */
1584 g_warning ("unknown pad direction %d", dir);
1590 gst_element_default_send_event (GstElement * element, GstEvent * event)
1592 gboolean result = FALSE;
1595 pad = GST_EVENT_IS_DOWNSTREAM (event) ?
1596 gst_element_get_random_pad (element, TRUE, GST_PAD_SINK) :
1597 gst_element_get_random_pad (element, TRUE, GST_PAD_SRC);
1600 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1601 "pushing %s event to random %s pad %s:%s",
1602 GST_EVENT_TYPE_NAME (event),
1603 (GST_PAD_DIRECTION (pad) == GST_PAD_SRC ? "src" : "sink"),
1604 GST_DEBUG_PAD_NAME (pad));
1606 result = gst_pad_send_event (pad, event);
1607 gst_object_unref (pad);
1609 GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "can't send %s event on element %s",
1610 GST_EVENT_TYPE_NAME (event), GST_ELEMENT_NAME (element));
1611 gst_event_unref (event);
1617 * gst_element_send_event:
1618 * @element: a #GstElement to send the event to.
1619 * @event: (transfer full): the #GstEvent to send to the element.
1621 * Sends an event to an element. If the element doesn't implement an
1622 * event handler, the event will be pushed on a random linked sink pad for
1623 * downstream events or a random linked source pad for upstream events.
1625 * This function takes ownership of the provided event so you should
1626 * gst_event_ref() it if you want to reuse the event after this call.
1630 * Returns: %TRUE if the event was handled. Events that trigger a preroll (such
1631 * as flushing seeks and steps) will emit %GST_MESSAGE_ASYNC_DONE.
1634 gst_element_send_event (GstElement * element, GstEvent * event)
1636 GstElementClass *oclass;
1637 gboolean result = FALSE;
1639 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1640 g_return_val_if_fail (event != NULL, FALSE);
1642 oclass = GST_ELEMENT_GET_CLASS (element);
1644 GST_STATE_LOCK (element);
1645 if (oclass->send_event) {
1646 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send %s event on element %s",
1647 GST_EVENT_TYPE_NAME (event), GST_ELEMENT_NAME (element));
1648 result = oclass->send_event (element, event);
1650 gst_event_unref (event);
1652 GST_STATE_UNLOCK (element);
1659 * @element: a #GstElement to send the event to.
1660 * @rate: The new playback rate
1661 * @format: The format of the seek values
1662 * @flags: The optional seek flags.
1663 * @start_type: The type and flags for the new start position
1664 * @start: The value of the new start position
1665 * @stop_type: The type and flags for the new stop position
1666 * @stop: The value of the new stop position
1668 * Sends a seek event to an element. See gst_event_new_seek() for the details of
1669 * the parameters. The seek event is sent to the element using
1670 * gst_element_send_event().
1674 * Returns: %TRUE if the event was handled. Flushing seeks will trigger a
1675 * preroll, which will emit %GST_MESSAGE_ASYNC_DONE.
1678 gst_element_seek (GstElement * element, gdouble rate, GstFormat format,
1679 GstSeekFlags flags, GstSeekType start_type, gint64 start,
1680 GstSeekType stop_type, gint64 stop)
1685 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1688 gst_event_new_seek (rate, format, flags, start_type, start, stop_type,
1690 result = gst_element_send_event (element, event);
1696 gst_element_default_query (GstElement * element, GstQuery * query)
1698 gboolean result = FALSE;
1701 pad = gst_element_get_random_pad (element, FALSE, GST_PAD_SRC);
1703 result = gst_pad_query (pad, query);
1705 gst_object_unref (pad);
1707 pad = gst_element_get_random_pad (element, TRUE, GST_PAD_SINK);
1709 GstPad *peer = gst_pad_get_peer (pad);
1712 result = gst_pad_query (peer, query);
1714 gst_object_unref (peer);
1716 gst_object_unref (pad);
1723 * gst_element_query:
1724 * @element: a #GstElement to perform the query on.
1725 * @query: (transfer none): the #GstQuery.
1727 * Performs a query on the given element.
1729 * For elements that don't implement a query handler, this function
1730 * forwards the query to a random srcpad or to the peer of a
1731 * random linked sinkpad of this element.
1733 * Please note that some queries might need a running pipeline to work.
1735 * Returns: %TRUE if the query could be performed.
1740 gst_element_query (GstElement * element, GstQuery * query)
1742 GstElementClass *klass;
1743 gboolean res = FALSE;
1745 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1746 g_return_val_if_fail (query != NULL, FALSE);
1748 GST_TRACER_ELEMENT_QUERY_PRE (element, query);
1750 klass = GST_ELEMENT_GET_CLASS (element);
1752 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "send query on element %s",
1753 GST_ELEMENT_NAME (element));
1754 res = klass->query (element, query);
1757 GST_TRACER_ELEMENT_QUERY_POST (element, query, res);
1762 gst_element_post_message_default (GstElement * element, GstMessage * message)
1765 gboolean result = FALSE;
1767 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1768 g_return_val_if_fail (message != NULL, FALSE);
1770 GST_OBJECT_LOCK (element);
1773 if (G_UNLIKELY (bus == NULL))
1776 gst_object_ref (bus);
1777 GST_OBJECT_UNLOCK (element);
1779 /* we release the element lock when posting the message so that any
1780 * (synchronous) message handlers can operate on the element */
1781 result = gst_bus_post (bus, message);
1782 gst_object_unref (bus);
1789 GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element,
1790 "not posting message %p: no bus", message);
1791 GST_OBJECT_UNLOCK (element);
1792 gst_message_unref (message);
1798 * gst_element_post_message:
1799 * @element: a #GstElement posting the message
1800 * @message: (transfer full): a #GstMessage to post
1802 * Post a message on the element's #GstBus. This function takes ownership of the
1803 * message; if you want to access the message after this call, you should add an
1804 * additional reference before calling.
1806 * Returns: %TRUE if the message was successfully posted. The function returns
1807 * %FALSE if the element did not have a bus.
1812 gst_element_post_message (GstElement * element, GstMessage * message)
1814 GstElementClass *klass;
1815 gboolean res = FALSE;
1817 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
1818 g_return_val_if_fail (message != NULL, FALSE);
1820 GST_TRACER_ELEMENT_POST_MESSAGE_PRE (element, message);
1822 klass = GST_ELEMENT_GET_CLASS (element);
1823 if (klass->post_message)
1824 res = klass->post_message (element, message);
1826 gst_message_unref (message);
1828 GST_TRACER_ELEMENT_POST_MESSAGE_POST (element, res);
1833 * _gst_element_error_printf:
1834 * @format: (allow-none): the printf-like format to use, or %NULL
1836 * This function is only used internally by the gst_element_error() macro.
1838 * Returns: (transfer full) (nullable): a newly allocated string, or
1839 * %NULL if the format was %NULL or ""
1844 _gst_element_error_printf (const gchar * format, ...)
1855 va_start (args, format);
1857 len = __gst_vasprintf (&buffer, format, args);
1868 * gst_element_message_full_with_details:
1869 * @element: a #GstElement to send message from
1870 * @type: the #GstMessageType
1871 * @domain: the GStreamer GError domain this message belongs to
1872 * @code: the GError code belonging to the domain
1873 * @text: (allow-none) (transfer full): an allocated text string to be used
1874 * as a replacement for the default message connected to code,
1876 * @debug: (allow-none) (transfer full): an allocated debug message to be
1877 * used as a replacement for the default debugging information,
1879 * @file: the source code file where the error was generated
1880 * @function: the source code function where the error was generated
1881 * @line: the source code line where the error was generated
1882 * @structure:(transfer full): optional details structure
1884 * Post an error, warning or info message on the bus from inside an element.
1886 * @type must be of #GST_MESSAGE_ERROR, #GST_MESSAGE_WARNING or
1887 * #GST_MESSAGE_INFO.
1891 void gst_element_message_full_with_details
1892 (GstElement * element, GstMessageType type,
1893 GQuark domain, gint code, gchar * text,
1894 gchar * debug, const gchar * file, const gchar * function, gint line,
1895 GstStructure * structure)
1897 GError *gerror = NULL;
1901 gboolean has_debug = TRUE;
1902 GstMessage *message = NULL;
1905 GST_CAT_DEBUG_OBJECT (GST_CAT_MESSAGE, element, "start");
1906 g_return_if_fail (GST_IS_ELEMENT (element));
1907 g_return_if_fail ((type == GST_MESSAGE_ERROR) ||
1908 (type == GST_MESSAGE_WARNING) || (type == GST_MESSAGE_INFO));
1910 /* check if we send the given text or the default error text */
1911 if ((text == NULL) || (text[0] == 0)) {
1912 /* text could have come from g_strdup_printf (""); */
1914 sent_text = gst_error_get_message (domain, code);
1918 /* construct a sent_debug with extra information from source */
1919 if ((debug == NULL) || (debug[0] == 0)) {
1920 /* debug could have come from g_strdup_printf (""); */
1924 name = gst_object_get_path_string (GST_OBJECT_CAST (element));
1926 sent_debug = g_strdup_printf ("%s(%d): %s (): %s:\n%s",
1927 file, line, function, name, debug);
1929 sent_debug = g_strdup_printf ("%s(%d): %s (): %s",
1930 file, line, function, name);
1934 /* create gerror and post message */
1935 GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posting message: %s",
1937 gerror = g_error_new_literal (domain, code, sent_text);
1940 case GST_MESSAGE_ERROR:
1942 gst_message_new_error_with_details (GST_OBJECT_CAST (element), gerror,
1943 sent_debug, structure);
1945 case GST_MESSAGE_WARNING:
1947 gst_message_new_warning_with_details (GST_OBJECT_CAST (element),
1948 gerror, sent_debug, structure);
1950 case GST_MESSAGE_INFO:
1952 gst_message_new_info_with_details (GST_OBJECT_CAST (element), gerror,
1953 sent_debug, structure);
1956 g_assert_not_reached ();
1960 gst_element_post_message (element, message);
1962 GST_CAT_INFO_OBJECT (GST_CAT_ERROR_SYSTEM, element, "posted %s message: %s",
1963 (type == GST_MESSAGE_ERROR ? "error" : "warning"), sent_text);
1966 g_error_free (gerror);
1967 g_free (sent_debug);
1972 * gst_element_message_full:
1973 * @element: a #GstElement to send message from
1974 * @type: the #GstMessageType
1975 * @domain: the GStreamer GError domain this message belongs to
1976 * @code: the GError code belonging to the domain
1977 * @text: (allow-none) (transfer full): an allocated text string to be used
1978 * as a replacement for the default message connected to code,
1980 * @debug: (allow-none) (transfer full): an allocated debug message to be
1981 * used as a replacement for the default debugging information,
1983 * @file: the source code file where the error was generated
1984 * @function: the source code function where the error was generated
1985 * @line: the source code line where the error was generated
1987 * Post an error, warning or info message on the bus from inside an element.
1989 * @type must be of #GST_MESSAGE_ERROR, #GST_MESSAGE_WARNING or
1990 * #GST_MESSAGE_INFO.
1994 void gst_element_message_full
1995 (GstElement * element, GstMessageType type,
1996 GQuark domain, gint code, gchar * text,
1997 gchar * debug, const gchar * file, const gchar * function, gint line)
1999 gst_element_message_full_with_details (element, type, domain, code, text,
2000 debug, file, function, line, NULL);
2004 * gst_element_is_locked_state:
2005 * @element: a #GstElement.
2007 * Checks if the state of an element is locked.
2008 * If the state of an element is locked, state changes of the parent don't
2009 * affect the element.
2010 * This way you can leave currently unused elements inside bins. Just lock their
2011 * state before changing the state from #GST_STATE_NULL.
2015 * Returns: %TRUE, if the element's state is locked.
2018 gst_element_is_locked_state (GstElement * element)
2022 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2024 GST_OBJECT_LOCK (element);
2025 result = GST_ELEMENT_IS_LOCKED_STATE (element);
2026 GST_OBJECT_UNLOCK (element);
2032 * gst_element_set_locked_state:
2033 * @element: a #GstElement
2034 * @locked_state: %TRUE to lock the element's state
2036 * Locks the state of an element, so state changes of the parent don't affect
2037 * this element anymore.
2041 * Returns: %TRUE if the state was changed, %FALSE if bad parameters were given
2042 * or the elements state-locking needed no change.
2045 gst_element_set_locked_state (GstElement * element, gboolean locked_state)
2049 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2051 GST_OBJECT_LOCK (element);
2052 old = GST_ELEMENT_IS_LOCKED_STATE (element);
2054 if (G_UNLIKELY (old == locked_state))
2058 GST_CAT_DEBUG (GST_CAT_STATES, "locking state of element %s",
2059 GST_ELEMENT_NAME (element));
2060 GST_OBJECT_FLAG_SET (element, GST_ELEMENT_FLAG_LOCKED_STATE);
2062 GST_CAT_DEBUG (GST_CAT_STATES, "unlocking state of element %s",
2063 GST_ELEMENT_NAME (element));
2064 GST_OBJECT_FLAG_UNSET (element, GST_ELEMENT_FLAG_LOCKED_STATE);
2066 GST_OBJECT_UNLOCK (element);
2072 GST_CAT_DEBUG (GST_CAT_STATES,
2073 "elements %s was already in locked state %d",
2074 GST_ELEMENT_NAME (element), old);
2075 GST_OBJECT_UNLOCK (element);
2082 * gst_element_sync_state_with_parent:
2083 * @element: a #GstElement.
2085 * Tries to change the state of the element to the same as its parent.
2086 * If this function returns %FALSE, the state of element is undefined.
2088 * Returns: %TRUE, if the element's state could be synced to the parent's state.
2093 gst_element_sync_state_with_parent (GstElement * element)
2097 GstStateChangeReturn ret;
2099 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2101 if ((parent = GST_ELEMENT_CAST (gst_element_get_parent (element)))) {
2102 GstState parent_current, parent_pending;
2104 GST_OBJECT_LOCK (parent);
2105 parent_current = GST_STATE (parent);
2106 parent_pending = GST_STATE_PENDING (parent);
2107 GST_OBJECT_UNLOCK (parent);
2109 /* set to pending if there is one, else we set it to the current state of
2111 if (parent_pending != GST_STATE_VOID_PENDING)
2112 target = parent_pending;
2114 target = parent_current;
2116 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2117 "syncing state (%s) to parent %s %s (%s, %s)",
2118 gst_element_state_get_name (GST_STATE (element)),
2119 GST_ELEMENT_NAME (parent), gst_element_state_get_name (target),
2120 gst_element_state_get_name (parent_current),
2121 gst_element_state_get_name (parent_pending));
2123 ret = gst_element_set_state (element, target);
2124 if (ret == GST_STATE_CHANGE_FAILURE)
2127 gst_object_unref (parent);
2131 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "element has no parent");
2138 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2139 "syncing state failed (%s)",
2140 gst_element_state_change_return_get_name (ret));
2141 gst_object_unref (parent);
2147 static GstStateChangeReturn
2148 gst_element_get_state_func (GstElement * element,
2149 GstState * state, GstState * pending, GstClockTime timeout)
2151 GstStateChangeReturn ret = GST_STATE_CHANGE_FAILURE;
2152 GstState old_pending;
2154 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "getting state, timeout %"
2155 GST_TIME_FORMAT, GST_TIME_ARGS (timeout));
2157 GST_OBJECT_LOCK (element);
2158 ret = GST_STATE_RETURN (element);
2159 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "RETURN is %s",
2160 gst_element_state_change_return_get_name (ret));
2162 /* we got an error, report immediately */
2163 if (ret == GST_STATE_CHANGE_FAILURE)
2166 /* we got no_preroll, report immediately */
2167 if (ret == GST_STATE_CHANGE_NO_PREROLL)
2170 /* no need to wait async if we are not async */
2171 if (ret != GST_STATE_CHANGE_ASYNC)
2174 old_pending = GST_STATE_PENDING (element);
2175 if (old_pending != GST_STATE_VOID_PENDING) {
2179 /* get cookie to detect state changes during waiting */
2180 cookie = element->state_cookie;
2182 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2183 "waiting for element to commit state");
2185 /* we have a pending state change, wait for it to complete */
2186 if (timeout != GST_CLOCK_TIME_NONE) {
2188 /* make timeout absolute */
2189 end_time = g_get_monotonic_time () + (timeout / 1000);
2190 signaled = GST_STATE_WAIT_UNTIL (element, end_time);
2192 GST_STATE_WAIT (element);
2197 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "timed out");
2198 /* timeout triggered */
2199 ret = GST_STATE_CHANGE_ASYNC;
2201 if (cookie != element->state_cookie)
2204 /* could be success or failure */
2205 if (old_pending == GST_STATE (element)) {
2206 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got success");
2207 ret = GST_STATE_CHANGE_SUCCESS;
2209 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "got failure");
2210 ret = GST_STATE_CHANGE_FAILURE;
2213 /* if nothing is pending anymore we can return SUCCESS */
2214 if (GST_STATE_PENDING (element) == GST_STATE_VOID_PENDING) {
2215 GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "nothing pending");
2216 ret = GST_STATE_CHANGE_SUCCESS;
2222 *state = GST_STATE (element);
2224 *pending = GST_STATE_PENDING (element);
2226 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2227 "state current: %s, pending: %s, result: %s",
2228 gst_element_state_get_name (GST_STATE (element)),
2229 gst_element_state_get_name (GST_STATE_PENDING (element)),
2230 gst_element_state_change_return_get_name (ret));
2231 GST_OBJECT_UNLOCK (element);
2238 *state = GST_STATE_VOID_PENDING;
2240 *pending = GST_STATE_VOID_PENDING;
2242 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "interruped");
2244 GST_OBJECT_UNLOCK (element);
2246 return GST_STATE_CHANGE_FAILURE;
2251 * gst_element_get_state:
2252 * @element: a #GstElement to get the state of.
2253 * @state: (out) (allow-none): a pointer to #GstState to hold the state.
2255 * @pending: (out) (allow-none): a pointer to #GstState to hold the pending
2256 * state. Can be %NULL.
2257 * @timeout: a #GstClockTime to specify the timeout for an async
2258 * state change or %GST_CLOCK_TIME_NONE for infinite timeout.
2260 * Gets the state of the element.
2262 * For elements that performed an ASYNC state change, as reported by
2263 * gst_element_set_state(), this function will block up to the
2264 * specified timeout value for the state change to complete.
2265 * If the element completes the state change or goes into
2266 * an error, this function returns immediately with a return value of
2267 * %GST_STATE_CHANGE_SUCCESS or %GST_STATE_CHANGE_FAILURE respectively.
2269 * For elements that did not return %GST_STATE_CHANGE_ASYNC, this function
2270 * returns the current and pending state immediately.
2272 * This function returns %GST_STATE_CHANGE_NO_PREROLL if the element
2273 * successfully changed its state but is not able to provide data yet.
2274 * This mostly happens for live sources that only produce data in
2275 * %GST_STATE_PLAYING. While the state change return is equivalent to
2276 * %GST_STATE_CHANGE_SUCCESS, it is returned to the application to signal that
2277 * some sink elements might not be able to complete their state change because
2278 * an element is not producing data to complete the preroll. When setting the
2279 * element to playing, the preroll will complete and playback will start.
2281 * Returns: %GST_STATE_CHANGE_SUCCESS if the element has no more pending state
2282 * and the last state change succeeded, %GST_STATE_CHANGE_ASYNC if the
2283 * element is still performing a state change or
2284 * %GST_STATE_CHANGE_FAILURE if the last state change failed.
2288 GstStateChangeReturn
2289 gst_element_get_state (GstElement * element,
2290 GstState * state, GstState * pending, GstClockTime timeout)
2292 GstElementClass *oclass;
2293 GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2295 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2297 oclass = GST_ELEMENT_GET_CLASS (element);
2299 if (oclass->get_state)
2300 result = (oclass->get_state) (element, state, pending, timeout);
2306 * gst_element_abort_state:
2307 * @element: a #GstElement to abort the state of.
2309 * Abort the state change of the element. This function is used
2310 * by elements that do asynchronous state changes and find out
2311 * something is wrong.
2313 * This function should be called with the STATE_LOCK held.
2318 gst_element_abort_state (GstElement * element)
2322 #ifndef GST_DISABLE_GST_DEBUG
2326 g_return_if_fail (GST_IS_ELEMENT (element));
2328 GST_OBJECT_LOCK (element);
2329 pending = GST_STATE_PENDING (element);
2331 if (pending == GST_STATE_VOID_PENDING ||
2332 GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2333 goto nothing_aborted;
2335 #ifndef GST_DISABLE_GST_DEBUG
2336 old_state = GST_STATE (element);
2338 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2339 "aborting state from %s to %s", gst_element_state_get_name (old_state),
2340 gst_element_state_get_name (pending));
2344 GST_STATE_RETURN (element) = GST_STATE_CHANGE_FAILURE;
2346 GST_STATE_BROADCAST (element);
2347 GST_OBJECT_UNLOCK (element);
2353 GST_OBJECT_UNLOCK (element);
2358 /* Not static because GstBin has manual state handling too */
2360 _priv_gst_element_state_changed (GstElement * element, GstState oldstate,
2361 GstState newstate, GstState pending)
2363 GstElementClass *klass = GST_ELEMENT_GET_CLASS (element);
2364 GstMessage *message;
2366 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2367 "notifying about state-changed %s to %s (%s pending)",
2368 gst_element_state_get_name (oldstate),
2369 gst_element_state_get_name (newstate),
2370 gst_element_state_get_name (pending));
2372 if (klass->state_changed)
2373 klass->state_changed (element, oldstate, newstate, pending);
2375 message = gst_message_new_state_changed (GST_OBJECT_CAST (element),
2376 oldstate, newstate, pending);
2377 gst_element_post_message (element, message);
2381 * gst_element_continue_state:
2382 * @element: a #GstElement to continue the state change of.
2383 * @ret: The previous state return value
2385 * Commit the state change of the element and proceed to the next
2386 * pending state if any. This function is used
2387 * by elements that do asynchronous state changes.
2388 * The core will normally call this method automatically when an
2389 * element returned %GST_STATE_CHANGE_SUCCESS from the state change function.
2391 * If after calling this method the element still has not reached
2392 * the pending state, the next state change is performed.
2394 * This method is used internally and should normally not be called by plugins
2397 * Returns: The result of the commit state change.
2401 GstStateChangeReturn
2402 gst_element_continue_state (GstElement * element, GstStateChangeReturn ret)
2404 GstStateChangeReturn old_ret;
2405 GstState old_state, old_next;
2406 GstState current, next, pending;
2407 GstStateChange transition;
2409 GST_OBJECT_LOCK (element);
2410 old_ret = GST_STATE_RETURN (element);
2411 GST_STATE_RETURN (element) = ret;
2412 pending = GST_STATE_PENDING (element);
2414 /* check if there is something to commit */
2415 if (pending == GST_STATE_VOID_PENDING)
2416 goto nothing_pending;
2418 old_state = GST_STATE (element);
2419 /* this is the state we should go to next */
2420 old_next = GST_STATE_NEXT (element);
2421 /* update current state */
2422 current = GST_STATE (element) = old_next;
2424 /* see if we reached the final state */
2425 if (pending == current)
2428 next = GST_STATE_GET_NEXT (current, pending);
2429 transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2431 GST_STATE_NEXT (element) = next;
2433 GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2434 GST_OBJECT_UNLOCK (element);
2436 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2437 "committing state from %s to %s, pending %s, next %s",
2438 gst_element_state_get_name (old_state),
2439 gst_element_state_get_name (old_next),
2440 gst_element_state_get_name (pending), gst_element_state_get_name (next));
2442 _priv_gst_element_state_changed (element, old_state, old_next, pending);
2444 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2445 "continue state change %s to %s, final %s",
2446 gst_element_state_get_name (current),
2447 gst_element_state_get_name (next), gst_element_state_get_name (pending));
2449 ret = gst_element_change_state (element, transition);
2455 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element, "nothing pending");
2456 GST_OBJECT_UNLOCK (element);
2461 GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2462 GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2464 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2465 "completed state change to %s", gst_element_state_get_name (pending));
2466 GST_OBJECT_UNLOCK (element);
2468 /* don't post silly messages with the same state. This can happen
2469 * when an element state is changed to what it already was. For bins
2470 * this can be the result of a lost state, which we check with the
2471 * previous return value.
2472 * We do signal the cond though as a _get_state() might be blocking
2474 if (old_state != old_next || old_ret == GST_STATE_CHANGE_ASYNC)
2475 _priv_gst_element_state_changed (element, old_state, old_next,
2476 GST_STATE_VOID_PENDING);
2478 GST_STATE_BROADCAST (element);
2485 * gst_element_lost_state:
2486 * @element: a #GstElement the state is lost of
2488 * Brings the element to the lost state. The current state of the
2489 * element is copied to the pending state so that any call to
2490 * gst_element_get_state() will return %GST_STATE_CHANGE_ASYNC.
2492 * An ASYNC_START message is posted. If the element was PLAYING, it will
2493 * go to PAUSED. The element will be restored to its PLAYING state by
2494 * the parent pipeline when it prerolls again.
2496 * This is mostly used for elements that lost their preroll buffer
2497 * in the %GST_STATE_PAUSED or %GST_STATE_PLAYING state after a flush,
2498 * they will go to their pending state again when a new preroll buffer is
2499 * queued. This function can only be called when the element is currently
2500 * not in error or an async state change.
2502 * This function is used internally and should normally not be called from
2503 * plugins or applications.
2506 gst_element_lost_state (GstElement * element)
2508 GstState old_state, new_state;
2509 GstMessage *message;
2511 g_return_if_fail (GST_IS_ELEMENT (element));
2513 GST_OBJECT_LOCK (element);
2514 if (GST_STATE_RETURN (element) == GST_STATE_CHANGE_FAILURE)
2517 if (GST_STATE_PENDING (element) != GST_STATE_VOID_PENDING)
2518 goto only_async_start;
2520 old_state = GST_STATE (element);
2522 /* when we were PLAYING, the new state is PAUSED. We will also not
2523 * automatically go to PLAYING but let the parent bin(s) set us to PLAYING
2524 * when we preroll. */
2525 if (old_state > GST_STATE_PAUSED)
2526 new_state = GST_STATE_PAUSED;
2528 new_state = old_state;
2530 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2531 "lost state of %s to %s", gst_element_state_get_name (old_state),
2532 gst_element_state_get_name (new_state));
2534 GST_STATE (element) = new_state;
2535 GST_STATE_NEXT (element) = new_state;
2536 GST_STATE_PENDING (element) = new_state;
2537 GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2538 GST_OBJECT_UNLOCK (element);
2540 _priv_gst_element_state_changed (element, new_state, new_state, new_state);
2542 message = gst_message_new_async_start (GST_OBJECT_CAST (element));
2543 gst_element_post_message (element, message);
2549 GST_OBJECT_UNLOCK (element);
2554 GST_OBJECT_UNLOCK (element);
2556 message = gst_message_new_async_start (GST_OBJECT_CAST (element));
2557 gst_element_post_message (element, message);
2563 * gst_element_set_state:
2564 * @element: a #GstElement to change state of.
2565 * @state: the element's new #GstState.
2567 * Sets the state of the element. This function will try to set the
2568 * requested state by going through all the intermediary states and calling
2569 * the class's state change function for each.
2571 * This function can return #GST_STATE_CHANGE_ASYNC, in which case the
2572 * element will perform the remainder of the state change asynchronously in
2574 * An application can use gst_element_get_state() to wait for the completion
2575 * of the state change or it can wait for a %GST_MESSAGE_ASYNC_DONE or
2576 * %GST_MESSAGE_STATE_CHANGED on the bus.
2578 * State changes to %GST_STATE_READY or %GST_STATE_NULL never return
2579 * #GST_STATE_CHANGE_ASYNC.
2581 * Returns: Result of the state change using #GstStateChangeReturn.
2585 GstStateChangeReturn
2586 gst_element_set_state (GstElement * element, GstState state)
2588 GstElementClass *oclass;
2589 GstStateChangeReturn result = GST_STATE_CHANGE_FAILURE;
2591 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2593 oclass = GST_ELEMENT_GET_CLASS (element);
2595 if (oclass->set_state)
2596 result = (oclass->set_state) (element, state);
2602 * default set state function, calculates the next state based
2603 * on current state and calls the change_state function
2605 static GstStateChangeReturn
2606 gst_element_set_state_func (GstElement * element, GstState state)
2608 GstState current, next, old_pending;
2609 GstStateChangeReturn ret;
2610 GstStateChange transition;
2611 GstStateChangeReturn old_ret;
2613 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2615 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "set_state to %s",
2616 gst_element_state_get_name (state));
2618 /* state lock is taken to protect the set_state() and get_state()
2619 * procedures, it does not lock any variables. */
2620 GST_STATE_LOCK (element);
2622 /* now calculate how to get to the new state */
2623 GST_OBJECT_LOCK (element);
2624 old_ret = GST_STATE_RETURN (element);
2625 /* previous state change returned an error, remove all pending
2626 * and next states */
2627 if (old_ret == GST_STATE_CHANGE_FAILURE) {
2628 GST_STATE_NEXT (element) = GST_STATE_VOID_PENDING;
2629 GST_STATE_PENDING (element) = GST_STATE_VOID_PENDING;
2630 GST_STATE_RETURN (element) = GST_STATE_CHANGE_SUCCESS;
2633 current = GST_STATE (element);
2634 next = GST_STATE_NEXT (element);
2635 old_pending = GST_STATE_PENDING (element);
2637 /* this is the (new) state we should go to. TARGET is the last state we set on
2639 if (state != GST_STATE_TARGET (element)) {
2640 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2641 "setting target state to %s", gst_element_state_get_name (state));
2642 GST_STATE_TARGET (element) = state;
2643 /* increment state cookie so that we can track each state change. We only do
2644 * this if this is actually a new state change. */
2645 element->state_cookie++;
2647 GST_STATE_PENDING (element) = state;
2649 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2650 "current %s, old_pending %s, next %s, old return %s",
2651 gst_element_state_get_name (current),
2652 gst_element_state_get_name (old_pending),
2653 gst_element_state_get_name (next),
2654 gst_element_state_change_return_get_name (old_ret));
2656 /* if the element was busy doing a state change, we just update the
2657 * target state, it'll get to it async then. */
2658 if (old_pending != GST_STATE_VOID_PENDING) {
2659 /* upwards state change will happen ASYNC */
2660 if (old_pending <= state)
2662 /* element is going to this state already */
2663 else if (next == state)
2665 /* element was performing an ASYNC upward state change and
2666 * we request to go downward again. Start from the next pending
2668 else if (next > state
2669 && GST_STATE_RETURN (element) == GST_STATE_CHANGE_ASYNC) {
2673 next = GST_STATE_GET_NEXT (current, state);
2674 /* now we store the next state */
2675 GST_STATE_NEXT (element) = next;
2676 /* mark busy, we need to check that there is actually a state change
2677 * to be done else we could accidentally override SUCCESS/NO_PREROLL and
2678 * the default element change_state function has no way to know what the
2679 * old value was... could consider this a FIXME...*/
2680 if (current != next)
2681 GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2683 transition = (GstStateChange) GST_STATE_TRANSITION (current, next);
2685 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2686 "%s: setting state from %s to %s",
2687 (next != state ? "intermediate" : "final"),
2688 gst_element_state_get_name (current), gst_element_state_get_name (next));
2690 /* now signal any waiters, they will error since the cookie was incremented */
2691 GST_STATE_BROADCAST (element);
2693 GST_OBJECT_UNLOCK (element);
2695 ret = gst_element_change_state (element, transition);
2697 GST_STATE_UNLOCK (element);
2699 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element, "returned %s",
2700 gst_element_state_change_return_get_name (ret));
2706 GST_STATE_RETURN (element) = GST_STATE_CHANGE_ASYNC;
2707 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2708 "element was busy with async state change");
2709 GST_OBJECT_UNLOCK (element);
2711 GST_STATE_UNLOCK (element);
2713 return GST_STATE_CHANGE_ASYNC;
2718 * gst_element_change_state:
2719 * @element: a #GstElement
2720 * @transition: the requested transition
2722 * Perform @transition on @element.
2724 * This function must be called with STATE_LOCK held and is mainly used
2727 * Returns: the #GstStateChangeReturn of the state transition.
2729 GstStateChangeReturn
2730 gst_element_change_state (GstElement * element, GstStateChange transition)
2732 GstElementClass *oclass;
2733 GstStateChangeReturn ret = GST_STATE_CHANGE_SUCCESS;
2735 oclass = GST_ELEMENT_GET_CLASS (element);
2737 GST_TRACER_ELEMENT_CHANGE_STATE_PRE (element, transition);
2739 /* call the state change function so it can set the state */
2740 if (oclass->change_state)
2741 ret = (oclass->change_state) (element, transition);
2743 ret = GST_STATE_CHANGE_FAILURE;
2745 GST_TRACER_ELEMENT_CHANGE_STATE_POST (element, transition, ret);
2748 case GST_STATE_CHANGE_FAILURE:
2749 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2750 "have FAILURE change_state return");
2751 /* state change failure */
2752 gst_element_abort_state (element);
2754 case GST_STATE_CHANGE_ASYNC:
2758 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2759 "element will change state ASYNC");
2761 target = GST_STATE_TARGET (element);
2763 if (target > GST_STATE_READY)
2766 /* else we just continue the state change downwards */
2767 GST_CAT_INFO_OBJECT (GST_CAT_STATES, element,
2768 "forcing commit state %s <= %s",
2769 gst_element_state_get_name (target),
2770 gst_element_state_get_name (GST_STATE_READY));
2772 ret = gst_element_continue_state (element, GST_STATE_CHANGE_SUCCESS);
2775 case GST_STATE_CHANGE_SUCCESS:
2776 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2777 "element changed state SUCCESS");
2778 /* we can commit the state now which will proceeed to
2780 ret = gst_element_continue_state (element, ret);
2782 case GST_STATE_CHANGE_NO_PREROLL:
2783 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
2784 "element changed state NO_PREROLL");
2785 /* we can commit the state now which will proceeed to
2787 ret = gst_element_continue_state (element, ret);
2790 goto invalid_return;
2793 GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit state change %d", ret);
2798 GST_CAT_LOG_OBJECT (GST_CAT_STATES, element, "exit async state change %d",
2806 GST_OBJECT_LOCK (element);
2807 /* somebody added a GST_STATE_ and forgot to do stuff here ! */
2808 g_critical ("%s: unknown return value %d from a state change function",
2809 GST_ELEMENT_NAME (element), ret);
2811 /* we are in error now */
2812 ret = GST_STATE_CHANGE_FAILURE;
2813 GST_STATE_RETURN (element) = ret;
2814 GST_OBJECT_UNLOCK (element);
2820 /* gst_iterator_fold functions for pads_activate
2821 * Stop the iterator if activating one pad failed, but only if that pad
2822 * has not been removed from the element. */
2824 activate_pads (const GValue * vpad, GValue * ret, gboolean * active)
2826 GstPad *pad = g_value_get_object (vpad);
2827 gboolean cont = TRUE;
2829 if (!gst_pad_set_active (pad, *active)) {
2830 if (GST_PAD_PARENT (pad) != NULL) {
2832 g_value_set_boolean (ret, FALSE);
2839 /* returns false on error or early cutout of the fold, true if all
2840 * pads in @iter were (de)activated successfully. */
2842 iterator_activate_fold_with_resync (GstIterator * iter,
2843 GstIteratorFoldFunction func, gpointer user_data)
2845 GstIteratorResult ires;
2848 /* no need to unset this later, it's just a boolean */
2849 g_value_init (&ret, G_TYPE_BOOLEAN);
2850 g_value_set_boolean (&ret, TRUE);
2853 ires = gst_iterator_fold (iter, func, &ret, user_data);
2855 case GST_ITERATOR_RESYNC:
2856 /* need to reset the result again */
2857 g_value_set_boolean (&ret, TRUE);
2858 gst_iterator_resync (iter);
2860 case GST_ITERATOR_DONE:
2861 /* all pads iterated, return collected value */
2864 /* iterator returned _ERROR or premature end with _OK,
2865 * mark an error and exit */
2866 g_value_set_boolean (&ret, FALSE);
2871 /* return collected value */
2872 return g_value_get_boolean (&ret);
2875 /* is called with STATE_LOCK
2877 * Pads are activated from source pads to sinkpads.
2880 gst_element_pads_activate (GstElement * element, gboolean active)
2885 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2886 "%s pads", active ? "activate" : "deactivate");
2888 iter = gst_element_iterate_src_pads (element);
2890 iterator_activate_fold_with_resync (iter,
2891 (GstIteratorFoldFunction) activate_pads, &active);
2892 gst_iterator_free (iter);
2893 if (G_UNLIKELY (!res))
2896 iter = gst_element_iterate_sink_pads (element);
2898 iterator_activate_fold_with_resync (iter,
2899 (GstIteratorFoldFunction) activate_pads, &active);
2900 gst_iterator_free (iter);
2901 if (G_UNLIKELY (!res))
2904 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2905 "pad %sactivation successful", active ? "" : "de");
2912 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2913 "pad %sactivation failed", active ? "" : "de");
2918 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
2919 "sink pads_activate failed");
2924 /* is called with STATE_LOCK */
2925 static GstStateChangeReturn
2926 gst_element_change_state_func (GstElement * element, GstStateChange transition)
2928 GstState state, next;
2929 GstStateChangeReturn result = GST_STATE_CHANGE_SUCCESS;
2931 g_return_val_if_fail (GST_IS_ELEMENT (element), GST_STATE_CHANGE_FAILURE);
2933 state = (GstState) GST_STATE_TRANSITION_CURRENT (transition);
2934 next = GST_STATE_TRANSITION_NEXT (transition);
2936 /* if the element already is in the given state, we just return success */
2937 if (next == GST_STATE_VOID_PENDING || state == next)
2940 GST_CAT_LOG_OBJECT (GST_CAT_STATES, element,
2941 "default handler tries setting state from %s to %s (%04x)",
2942 gst_element_state_get_name (state),
2943 gst_element_state_get_name (next), transition);
2945 switch (transition) {
2946 case GST_STATE_CHANGE_NULL_TO_READY:
2948 case GST_STATE_CHANGE_READY_TO_PAUSED:
2949 if (!gst_element_pads_activate (element, TRUE)) {
2950 result = GST_STATE_CHANGE_FAILURE;
2953 case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
2955 case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
2957 case GST_STATE_CHANGE_PAUSED_TO_READY:
2958 case GST_STATE_CHANGE_READY_TO_NULL:{
2961 /* deactivate pads in both cases, since they are activated on
2962 ready->paused but the element might not have made it to paused */
2963 if (!gst_element_pads_activate (element, FALSE)) {
2964 result = GST_STATE_CHANGE_FAILURE;
2967 /* Remove all non-persistent contexts */
2968 GST_OBJECT_LOCK (element);
2969 for (l = element->contexts; l;) {
2970 GstContext *context = l->data;
2972 if (!gst_context_is_persistent (context)) {
2975 gst_context_unref (context);
2977 element->contexts = g_list_delete_link (element->contexts, l);
2983 GST_OBJECT_UNLOCK (element);
2987 /* this will catch real but unhandled state changes;
2988 * can only be caused by:
2989 * - a new state was added
2990 * - somehow the element was asked to jump across an intermediate state
2992 g_warning ("Unhandled state change from %s to %s",
2993 gst_element_state_get_name (state),
2994 gst_element_state_get_name (next));
3001 GST_OBJECT_LOCK (element);
3002 result = GST_STATE_RETURN (element);
3003 GST_CAT_DEBUG_OBJECT (GST_CAT_STATES, element,
3004 "element is already in the %s state",
3005 gst_element_state_get_name (state));
3006 GST_OBJECT_UNLOCK (element);
3013 * gst_element_get_factory:
3014 * @element: a #GstElement to request the element factory of.
3016 * Retrieves the factory that was used to create this element.
3018 * Returns: (transfer none): the #GstElementFactory used for creating this
3019 * element. no refcounting is needed.
3022 gst_element_get_factory (GstElement * element)
3024 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
3026 return GST_ELEMENT_GET_CLASS (element)->elementfactory;
3030 gst_element_dispose (GObject * object)
3032 GstElement *element = GST_ELEMENT_CAST (object);
3035 GstElementClass *oclass;
3038 oclass = GST_ELEMENT_GET_CLASS (element);
3040 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "%p dispose", element);
3042 if (GST_STATE (element) != GST_STATE_NULL)
3045 /* start by releasing all request pads, this might also remove some dynamic
3047 walk = element->pads;
3049 GstPad *pad = GST_PAD_CAST (walk->data);
3053 if (oclass->release_pad && GST_PAD_PAD_TEMPLATE (pad) &&
3054 GST_PAD_TEMPLATE_PRESENCE (GST_PAD_PAD_TEMPLATE (pad))
3055 == GST_PAD_REQUEST) {
3056 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
3057 "removing request pad %s:%s", GST_DEBUG_PAD_NAME (pad));
3058 oclass->release_pad (element, pad);
3060 /* in case the release_pad function removed the next pad too */
3061 if (walk && g_list_position (element->pads, walk) == -1)
3062 walk = element->pads;
3065 /* remove the remaining pads */
3066 while (element->pads) {
3067 GstPad *pad = GST_PAD_CAST (element->pads->data);
3068 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
3069 "removing pad %s:%s", GST_DEBUG_PAD_NAME (pad));
3070 if (!gst_element_remove_pad (element, pad)) {
3071 /* only happens when someone unparented our pad.. */
3072 g_critical ("failed to remove pad %s:%s", GST_DEBUG_PAD_NAME (pad));
3077 GST_OBJECT_LOCK (element);
3078 clock_p = &element->clock;
3079 bus_p = &element->bus;
3080 gst_object_replace ((GstObject **) clock_p, NULL);
3081 gst_object_replace ((GstObject **) bus_p, NULL);
3082 g_list_free_full (element->contexts, (GDestroyNotify) gst_context_unref);
3083 GST_OBJECT_UNLOCK (element);
3085 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "%p parent class dispose",
3088 G_OBJECT_CLASS (parent_class)->dispose (object);
3097 is_locked = GST_ELEMENT_IS_LOCKED_STATE (element);
3099 ("\nTrying to dispose element %s, but it is in %s%s instead of the NULL"
3101 "You need to explicitly set elements to the NULL state before\n"
3102 "dropping the final reference, to allow them to clean up.\n"
3103 "This problem may also be caused by a refcounting bug in the\n"
3104 "application or some element.\n",
3105 GST_OBJECT_NAME (element),
3106 gst_element_state_get_name (GST_STATE (element)),
3107 is_locked ? " (locked)" : "");
3113 gst_element_finalize (GObject * object)
3115 GstElement *element = GST_ELEMENT_CAST (object);
3117 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "%p finalize", element);
3119 g_cond_clear (&element->state_cond);
3120 g_rec_mutex_clear (&element->state_lock);
3122 GST_CAT_INFO_OBJECT (GST_CAT_REFCOUNTING, element, "%p finalize parent",
3125 G_OBJECT_CLASS (parent_class)->finalize (object);
3129 gst_element_set_bus_func (GstElement * element, GstBus * bus)
3133 g_return_if_fail (GST_IS_ELEMENT (element));
3135 GST_CAT_DEBUG_OBJECT (GST_CAT_PARENTAGE, element, "setting bus to %p", bus);
3137 GST_OBJECT_LOCK (element);
3138 bus_p = &GST_ELEMENT_BUS (element);
3139 gst_object_replace ((GstObject **) bus_p, GST_OBJECT_CAST (bus));
3140 GST_OBJECT_UNLOCK (element);
3144 * gst_element_set_bus:
3145 * @element: a #GstElement to set the bus of.
3146 * @bus: (transfer none): the #GstBus to set.
3148 * Sets the bus of the element. Increases the refcount on the bus.
3149 * For internal use only, unless you're testing elements.
3154 gst_element_set_bus (GstElement * element, GstBus * bus)
3156 GstElementClass *oclass;
3158 g_return_if_fail (GST_IS_ELEMENT (element));
3160 oclass = GST_ELEMENT_GET_CLASS (element);
3162 if (oclass->set_bus)
3163 oclass->set_bus (element, bus);
3167 * gst_element_get_bus:
3168 * @element: a #GstElement to get the bus of.
3170 * Returns the bus of the element. Note that only a #GstPipeline will provide a
3171 * bus for the application.
3173 * Returns: (transfer full): the element's #GstBus. unref after usage.
3178 gst_element_get_bus (GstElement * element)
3180 GstBus *result = NULL;
3182 g_return_val_if_fail (GST_IS_ELEMENT (element), result);
3184 GST_OBJECT_LOCK (element);
3185 if ((result = GST_ELEMENT_BUS (element)))
3186 gst_object_ref (result);
3187 GST_OBJECT_UNLOCK (element);
3189 GST_CAT_DEBUG_OBJECT (GST_CAT_BUS, element, "got bus %" GST_PTR_FORMAT,
3196 gst_element_set_context_default (GstElement * element, GstContext * context)
3198 const gchar *context_type;
3201 g_return_if_fail (GST_IS_CONTEXT (context));
3202 context_type = gst_context_get_context_type (context);
3203 g_return_if_fail (context_type != NULL);
3205 GST_OBJECT_LOCK (element);
3206 for (l = element->contexts; l; l = l->next) {
3207 GstContext *tmp = l->data;
3208 const gchar *tmp_type = gst_context_get_context_type (tmp);
3210 /* Always store newest context but never replace
3211 * a persistent one by a non-persistent one */
3212 if (g_strcmp0 (context_type, tmp_type) == 0 &&
3213 (gst_context_is_persistent (context) ||
3214 !gst_context_is_persistent (tmp))) {
3215 gst_context_replace ((GstContext **) & l->data, context);
3219 /* Not found? Add */
3222 g_list_prepend (element->contexts, gst_context_ref (context));
3224 GST_OBJECT_UNLOCK (element);
3228 * gst_element_set_context:
3229 * @element: a #GstElement to set the context of.
3230 * @context: (transfer none): the #GstContext to set.
3232 * Sets the context of the element. Increases the refcount of the context.
3237 gst_element_set_context (GstElement * element, GstContext * context)
3239 GstElementClass *oclass;
3241 g_return_if_fail (GST_IS_ELEMENT (element));
3242 g_return_if_fail (GST_IS_CONTEXT (context));
3244 oclass = GST_ELEMENT_GET_CLASS (element);
3246 GST_CAT_DEBUG_OBJECT (GST_CAT_CONTEXT, element,
3247 "set context %p %" GST_PTR_FORMAT, context,
3248 gst_context_get_structure (context));
3250 if (oclass->set_context)
3251 oclass->set_context (element, context);
3255 * gst_element_get_contexts:
3256 * @element: a #GstElement to set the context of.
3258 * Gets the contexts set on the element.
3262 * Returns: (element-type Gst.Context) (transfer full): List of #GstContext
3267 gst_element_get_contexts (GstElement * element)
3271 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
3273 GST_OBJECT_LOCK (element);
3274 ret = g_list_copy_deep (element->contexts, (GCopyFunc) gst_context_ref, NULL);
3275 GST_OBJECT_UNLOCK (element);
3281 _match_context_type (GstContext * c1, const gchar * context_type)
3283 const gchar *c1_type;
3285 c1_type = gst_context_get_context_type (c1);
3287 return g_strcmp0 (c1_type, context_type);
3291 * gst_element_get_context_unlocked:
3292 * @element: a #GstElement to get the context of.
3293 * @context_type: a name of a context to retrieve
3295 * Gets the context with @context_type set on the element or NULL.
3297 * Returns: (transfer full): A #GstContext or NULL
3302 gst_element_get_context_unlocked (GstElement * element,
3303 const gchar * context_type)
3305 GstContext *ret = NULL;
3308 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
3311 g_list_find_custom (element->contexts, context_type,
3312 (GCompareFunc) _match_context_type);
3313 if (node && node->data)
3314 ret = gst_context_ref (node->data);
3320 * gst_element_get_context:
3321 * @element: a #GstElement to get the context of.
3322 * @context_type: a name of a context to retrieve
3324 * Gets the context with @context_type set on the element or NULL.
3328 * Returns: (transfer full): A #GstContext or NULL
3333 gst_element_get_context (GstElement * element, const gchar * context_type)
3335 GstContext *ret = NULL;
3337 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
3339 GST_OBJECT_LOCK (element);
3340 ret = gst_element_get_context_unlocked (element, context_type);
3341 GST_OBJECT_UNLOCK (element);
3347 gst_element_property_post_notify_msg (GstElement * element, GObject * obj,
3348 GParamSpec * pspec, gboolean include_value)
3350 GValue val = G_VALUE_INIT;
3353 GST_LOG_OBJECT (element, "property '%s' of object %" GST_PTR_FORMAT " has "
3354 "changed, posting message with%s value", pspec->name, obj,
3355 include_value ? "" : "out");
3357 if (include_value && (pspec->flags & G_PARAM_READABLE) != 0) {
3358 g_value_init (&val, pspec->value_type);
3359 g_object_get_property (obj, pspec->name, &val);
3364 gst_element_post_message (element,
3365 gst_message_new_property_notify (GST_OBJECT_CAST (obj), pspec->name, v));
3369 gst_element_property_deep_notify_cb (GstElement * element, GObject * prop_obj,
3370 GParamSpec * pspec, gpointer user_data)
3372 gboolean include_value = GPOINTER_TO_INT (user_data);
3374 gst_element_property_post_notify_msg (element, prop_obj, pspec,
3379 gst_element_property_notify_cb (GObject * obj, GParamSpec * pspec,
3382 gboolean include_value = GPOINTER_TO_INT (user_data);
3384 gst_element_property_post_notify_msg (GST_ELEMENT_CAST (obj), obj, pspec,
3389 * gst_element_add_property_notify_watch:
3390 * @element: a #GstElement to watch for property changes
3391 * @property_name: (allow-none): name of property to watch for changes, or
3392 * NULL to watch all properties
3393 * @include_value: whether to include the new property value in the message
3395 * Returns: a watch id, which can be used in connection with
3396 * gst_element_remove_property_notify_watch() to remove the watch again.
3401 gst_element_add_property_notify_watch (GstElement * element,
3402 const gchar * property_name, gboolean include_value)
3408 g_return_val_if_fail (GST_IS_ELEMENT (element), 0);
3410 sep = (property_name != NULL) ? "::" : NULL;
3411 signal_name = g_strconcat ("notify", sep, property_name, NULL);
3412 id = g_signal_connect (element, signal_name,
3413 G_CALLBACK (gst_element_property_notify_cb),
3414 GINT_TO_POINTER (include_value));
3415 g_free (signal_name);
3421 * gst_element_add_property_deep_notify_watch:
3422 * @element: a #GstElement to watch (recursively) for property changes
3423 * @property_name: (allow-none): name of property to watch for changes, or
3424 * NULL to watch all properties
3425 * @include_value: whether to include the new property value in the message
3427 * Returns: a watch id, which can be used in connection with
3428 * gst_element_remove_property_notify_watch() to remove the watch again.
3433 gst_element_add_property_deep_notify_watch (GstElement * element,
3434 const gchar * property_name, gboolean include_value)
3440 g_return_val_if_fail (GST_IS_ELEMENT (element), 0);
3442 sep = (property_name != NULL) ? "::" : NULL;
3443 signal_name = g_strconcat ("deep-notify", sep, property_name, NULL);
3444 id = g_signal_connect (element, signal_name,
3445 G_CALLBACK (gst_element_property_deep_notify_cb),
3446 GINT_TO_POINTER (include_value));
3447 g_free (signal_name);
3453 * gst_element_remove_property_notify_watch:
3454 * @element: a #GstElement being watched for property changes
3455 * @watch_id: watch id to remove
3460 gst_element_remove_property_notify_watch (GstElement * element, gulong watch_id)
3462 g_signal_handler_disconnect (element, watch_id);
3467 GstElement *element;
3468 GstElementCallAsyncFunc func;
3470 GDestroyNotify destroy_notify;
3471 } GstElementCallAsyncData;
3474 gst_element_call_async_func (gpointer data, gpointer user_data)
3476 GstElementCallAsyncData *async_data = data;
3478 async_data->func (async_data->element, async_data->user_data);
3479 if (async_data->destroy_notify)
3480 async_data->destroy_notify (async_data->user_data);
3481 gst_object_unref (async_data->element);
3482 g_free (async_data);
3486 * gst_element_call_async:
3487 * @element: a #GstElement
3488 * @func: Function to call asynchronously from another thread
3489 * @user_data: Data to pass to @func
3490 * @destroy_notify: GDestroyNotify for @user_data
3492 * Calls @func from another thread and passes @user_data to it. This is to be
3493 * used for cases when a state change has to be performed from a streaming
3494 * thread, directly via gst_element_set_state() or indirectly e.g. via SEEK
3497 * Calling those functions directly from the streaming thread will cause
3498 * deadlocks in many situations, as they might involve waiting for the
3499 * streaming thread to shut down from this very streaming thread.
3506 gst_element_call_async (GstElement * element, GstElementCallAsyncFunc func,
3507 gpointer user_data, GDestroyNotify destroy_notify)
3509 GstElementCallAsyncData *async_data;
3511 g_return_if_fail (GST_IS_ELEMENT (element));
3513 async_data = g_new0 (GstElementCallAsyncData, 1);
3514 async_data->element = gst_object_ref (element);
3515 async_data->func = func;
3516 async_data->user_data = user_data;
3517 async_data->destroy_notify = destroy_notify;
3519 g_thread_pool_push (gst_element_pool, async_data, NULL);
3523 _priv_gst_element_cleanup (void)
3525 if (gst_element_pool) {
3526 g_thread_pool_free (gst_element_pool, FALSE, TRUE);
3527 gst_element_setup_thread_pool ();
3532 gst_make_element_message_details (const char *name, ...)
3534 GstStructure *structure;
3540 va_start (varargs, name);
3541 structure = gst_structure_new_valist ("details", name, varargs);