2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2000 Wim Taymans <wtay@chello.be>
5 * gstpad.c: Pads for linking elements together
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, USA.
24 * @short_description: Object contained by elements that allows links to
26 * @see_also: #GstPadTemplate, #GstElement, #GstEvent
28 * A #GstElement is linked to other elements via "pads", which are extremely
29 * light-weight generic link points.
30 * After two pads are retrieved from an element with gst_element_get_pad(),
31 * the pads can be link with gst_pad_link(). (For quick links,
32 * you can also use gst_element_link(), which will make the obvious
33 * link for you if it's straightforward.)
35 * Pads are typically created from a #GstPadTemplate with
36 * gst_pad_new_from_template().
38 * Pads have #GstCaps attached to it to describe the media type they are
39 * capable of dealing with. gst_pad_get_caps() and gst_pad_set_caps() are
40 * used to manipulate the caps of the pads.
41 * Pads created from a pad template cannot set capabilities that are
42 * incompatible with the pad template capabilities.
44 * Pads without pad templates can be created with gst_pad_new(),
45 * which takes a direction and a name as an argument. If the name is NULL,
46 * then a guaranteed unique name will be assigned to it.
48 * gst_pad_get_parent() will retrieve the #GstElement that owns the pad.
50 * A #GstElement creating a pad will typically use the various
51 * gst_pad_set_*_function() calls to register callbacks for various events
54 * GstElements will use gst_pad_push() and gst_pad_pull_range() to push out
55 * or pull in a buffer.
57 * To send a #GstEvent on a pad, use gst_pad_send_event() and
58 * gst_pad_push_event().
60 * Last reviewed on 2006-07-06 (0.10.9)
63 #include "gst_private.h"
66 #include "gstpadtemplate.h"
67 #include "gstenumtypes.h"
68 #include "gstmarshal.h"
73 #include "glib-compat-private.h"
75 GST_DEBUG_CATEGORY_STATIC (debug_dataflow);
76 #define GST_CAT_DEFAULT GST_CAT_PADS
78 /* Pad signals and args */
98 typedef struct _GstPadPushCache GstPadPushCache;
100 struct _GstPadPushCache
102 GstPad *peer; /* reffed peer pad */
105 static GstPadPushCache _pad_cache_invalid = { NULL, };
107 #define PAD_CACHE_INVALID (&_pad_cache_invalid)
109 #define GST_PAD_GET_PRIVATE(obj) \
110 (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GST_TYPE_PAD, GstPadPrivate))
118 struct _GstPadPrivate
120 GstPadPushCache *cache_ptr;
122 PadEvent events[GST_EVENT_MAX_STICKY];
125 static void gst_pad_dispose (GObject * object);
126 static void gst_pad_finalize (GObject * object);
127 static void gst_pad_set_property (GObject * object, guint prop_id,
128 const GValue * value, GParamSpec * pspec);
129 static void gst_pad_get_property (GObject * object, guint prop_id,
130 GValue * value, GParamSpec * pspec);
132 static GstFlowReturn handle_pad_block (GstPad * pad);
133 static GstCaps *gst_pad_get_caps_unlocked (GstPad * pad, GstCaps * filter);
134 static void gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ);
135 static gboolean gst_pad_activate_default (GstPad * pad);
136 static gboolean gst_pad_acceptcaps_default (GstPad * pad, GstCaps * caps);
138 static GstObjectClass *parent_class = NULL;
139 static guint gst_pad_signals[LAST_SIGNAL] = { 0 };
141 static GParamSpec *pspec_caps = NULL;
143 /* quarks for probe signals */
144 static GQuark buffer_quark;
145 static GQuark event_quark;
154 static GstFlowQuarks flow_quarks[] = {
155 {GST_FLOW_CUSTOM_SUCCESS, "custom-success", 0},
156 {GST_FLOW_RESEND, "resend", 0},
157 {GST_FLOW_OK, "ok", 0},
158 {GST_FLOW_NOT_LINKED, "not-linked", 0},
159 {GST_FLOW_WRONG_STATE, "wrong-state", 0},
160 {GST_FLOW_UNEXPECTED, "unexpected", 0},
161 {GST_FLOW_NOT_NEGOTIATED, "not-negotiated", 0},
162 {GST_FLOW_ERROR, "error", 0},
163 {GST_FLOW_NOT_SUPPORTED, "not-supported", 0},
164 {GST_FLOW_CUSTOM_ERROR, "custom-error", 0}
169 * @ret: a #GstFlowReturn to get the name of.
171 * Gets a string representing the given flow return.
173 * Returns: a static string with the name of the flow return.
175 G_CONST_RETURN gchar *
176 gst_flow_get_name (GstFlowReturn ret)
180 ret = CLAMP (ret, GST_FLOW_CUSTOM_ERROR, GST_FLOW_CUSTOM_SUCCESS);
182 for (i = 0; i < G_N_ELEMENTS (flow_quarks); i++) {
183 if (ret == flow_quarks[i].ret)
184 return flow_quarks[i].name;
191 * @ret: a #GstFlowReturn to get the quark of.
193 * Get the unique quark for the given GstFlowReturn.
195 * Returns: the quark associated with the flow return or 0 if an
196 * invalid return was specified.
199 gst_flow_to_quark (GstFlowReturn ret)
203 ret = CLAMP (ret, GST_FLOW_CUSTOM_ERROR, GST_FLOW_CUSTOM_SUCCESS);
205 for (i = 0; i < G_N_ELEMENTS (flow_quarks); i++) {
206 if (ret == flow_quarks[i].ret)
207 return flow_quarks[i].quark;
216 buffer_quark = g_quark_from_static_string ("buffer"); \
217 event_quark = g_quark_from_static_string ("event"); \
219 for (i = 0; i < G_N_ELEMENTS (flow_quarks); i++) { \
220 flow_quarks[i].quark = g_quark_from_static_string (flow_quarks[i].name); \
223 GST_DEBUG_CATEGORY_INIT (debug_dataflow, "GST_DATAFLOW", \
224 GST_DEBUG_BOLD | GST_DEBUG_FG_GREEN, "dataflow inside pads"); \
227 G_DEFINE_TYPE_WITH_CODE (GstPad, gst_pad, GST_TYPE_OBJECT, _do_init);
230 _gst_do_pass_data_accumulator (GSignalInvocationHint * ihint,
231 GValue * return_accu, const GValue * handler_return, gpointer dummy)
233 gboolean ret = g_value_get_boolean (handler_return);
235 GST_DEBUG ("accumulated %d", ret);
236 g_value_set_boolean (return_accu, ret);
242 default_have_data (GstPad * pad, GstMiniObject * o)
248 gst_pad_class_init (GstPadClass * klass)
250 GObjectClass *gobject_class;
251 GstObjectClass *gstobject_class;
253 gobject_class = G_OBJECT_CLASS (klass);
254 gstobject_class = GST_OBJECT_CLASS (klass);
256 g_type_class_add_private (klass, sizeof (GstPadPrivate));
258 parent_class = g_type_class_peek_parent (klass);
260 gobject_class->dispose = gst_pad_dispose;
261 gobject_class->finalize = gst_pad_finalize;
262 gobject_class->set_property = gst_pad_set_property;
263 gobject_class->get_property = gst_pad_get_property;
267 * @pad: the pad that emitted the signal
268 * @peer: the peer pad that has been connected
270 * Signals that a pad has been linked to the peer pad.
272 gst_pad_signals[PAD_LINKED] =
273 g_signal_new ("linked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
274 G_STRUCT_OFFSET (GstPadClass, linked), NULL, NULL,
275 gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
278 * @pad: the pad that emitted the signal
279 * @peer: the peer pad that has been disconnected
281 * Signals that a pad has been unlinked from the peer pad.
283 gst_pad_signals[PAD_UNLINKED] =
284 g_signal_new ("unlinked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
285 G_STRUCT_OFFSET (GstPadClass, unlinked), NULL, NULL,
286 gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
288 * GstPad::request-link:
289 * @pad: the pad that emitted the signal
290 * @peer: the peer pad for which a connection is requested
292 * Signals that a pad connection has been requested.
294 gst_pad_signals[PAD_REQUEST_LINK] =
295 g_signal_new ("request-link", G_TYPE_FROM_CLASS (klass),
296 G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstPadClass, request_link), NULL,
297 NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 0);
301 * @pad: the pad that emitted the signal
302 * @mini_obj: new data
304 * Signals that new data is available on the pad. This signal is used
305 * internally for implementing pad probes.
306 * See gst_pad_add_*_probe functions.
308 * Returns: %TRUE to keep the data, %FALSE to drop it
310 gst_pad_signals[PAD_HAVE_DATA] =
311 g_signal_new ("have-data", G_TYPE_FROM_CLASS (klass),
312 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
313 G_STRUCT_OFFSET (GstPadClass, have_data),
314 _gst_do_pass_data_accumulator,
315 NULL, gst_marshal_BOOLEAN__POINTER, G_TYPE_BOOLEAN, 1, G_TYPE_POINTER);
317 pspec_caps = g_param_spec_boxed ("caps", "Caps",
318 "The capabilities of the pad", GST_TYPE_CAPS,
319 G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
320 g_object_class_install_property (gobject_class, PAD_PROP_CAPS, pspec_caps);
322 g_object_class_install_property (gobject_class, PAD_PROP_DIRECTION,
323 g_param_spec_enum ("direction", "Direction", "The direction of the pad",
324 GST_TYPE_PAD_DIRECTION, GST_PAD_UNKNOWN,
325 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
326 /* FIXME, Make G_PARAM_CONSTRUCT_ONLY when we fix ghostpads. */
327 g_object_class_install_property (gobject_class, PAD_PROP_TEMPLATE,
328 g_param_spec_object ("template", "Template",
329 "The GstPadTemplate of this pad", GST_TYPE_PAD_TEMPLATE,
330 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
332 gstobject_class->path_string_separator = ".";
334 /* Register common function pointer descriptions */
335 GST_DEBUG_REGISTER_FUNCPTR (gst_pad_activate_default);
336 GST_DEBUG_REGISTER_FUNCPTR (gst_pad_event_default);
337 GST_DEBUG_REGISTER_FUNCPTR (gst_pad_get_query_types_default);
338 GST_DEBUG_REGISTER_FUNCPTR (gst_pad_query_default);
339 GST_DEBUG_REGISTER_FUNCPTR (gst_pad_iterate_internal_links_default);
340 GST_DEBUG_REGISTER_FUNCPTR (gst_pad_acceptcaps_default);
342 klass->have_data = default_have_data;
346 gst_pad_init (GstPad * pad)
348 pad->priv = GST_PAD_GET_PRIVATE (pad);
350 GST_PAD_DIRECTION (pad) = GST_PAD_UNKNOWN;
352 GST_PAD_ACTIVATEFUNC (pad) = gst_pad_activate_default;
353 GST_PAD_EVENTFUNC (pad) = gst_pad_event_default;
354 GST_PAD_QUERYTYPEFUNC (pad) = gst_pad_get_query_types_default;
355 GST_PAD_QUERYFUNC (pad) = gst_pad_query_default;
356 GST_PAD_ITERINTLINKFUNC (pad) = gst_pad_iterate_internal_links_default;
358 GST_PAD_ACCEPTCAPSFUNC (pad) = gst_pad_acceptcaps_default;
360 GST_PAD_SET_FLUSHING (pad);
362 /* FIXME 0.11: Store this directly in the instance struct */
363 pad->stream_rec_lock = g_slice_new (GStaticRecMutex);
364 g_static_rec_mutex_init (pad->stream_rec_lock);
366 pad->block_cond = g_cond_new ();
369 /* called when setting the pad inactive. It removes all sticky events from
372 clear_events (PadEvent events[])
376 for (i = 0; i < GST_EVENT_MAX_STICKY; i++) {
377 gst_event_replace (&events[i].event, NULL);
378 events[i].active = FALSE;
382 /* called when elements link. The sticky events from the srcpad are
383 * copied to the sinkpad (when different) and the inactive flag is set,
384 * this will make sure that we send the event to the sinkpad event
385 * function when the next buffer of event arrives. */
387 replace_events (PadEvent srcev[], PadEvent sinkev[])
390 gboolean inactive = FALSE;
392 for (i = 0; i < GST_EVENT_MAX_STICKY; i++) {
393 if (srcev[i].event != sinkev[i].event) {
394 gst_event_replace (&sinkev[i].event, srcev[i].event);
395 sinkev[i].active = FALSE;
403 get_pad_caps (GstPad * pad)
405 GstCaps *caps = NULL;
409 idx = GST_EVENT_STICKY_IDX_TYPE (GST_EVENT_CAPS);
410 /* we can only use the caps when we have successfully send the caps
411 * event to the event function */
412 if (pad->priv->events[idx].active)
413 if ((event = pad->priv->events[idx].event))
414 gst_event_parse_caps (event, &caps);
420 gst_pad_dispose (GObject * object)
422 GstPad *pad = GST_PAD_CAST (object);
425 GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, pad, "dispose");
427 /* unlink the peer pad */
428 if ((peer = gst_pad_get_peer (pad))) {
429 /* window for MT unsafeness, someone else could unlink here
430 * and then we call unlink with wrong pads. The unlink
431 * function would catch this and safely return failed. */
432 if (GST_PAD_IS_SRC (pad))
433 gst_pad_unlink (pad, peer);
435 gst_pad_unlink (peer, pad);
437 gst_object_unref (peer);
440 gst_pad_set_pad_template (pad, NULL);
442 if (pad->block_destroy_data && pad->block_data) {
443 pad->block_destroy_data (pad->block_data);
444 pad->block_data = NULL;
447 clear_events (pad->priv->events);
449 G_OBJECT_CLASS (parent_class)->dispose (object);
453 gst_pad_finalize (GObject * object)
455 GstPad *pad = GST_PAD_CAST (object);
458 /* in case the task is still around, clean it up */
459 if ((task = GST_PAD_TASK (pad))) {
460 gst_task_join (task);
461 GST_PAD_TASK (pad) = NULL;
462 gst_object_unref (task);
465 if (pad->stream_rec_lock) {
466 g_static_rec_mutex_free (pad->stream_rec_lock);
467 g_slice_free (GStaticRecMutex, pad->stream_rec_lock);
468 pad->stream_rec_lock = NULL;
470 if (pad->block_cond) {
471 g_cond_free (pad->block_cond);
472 pad->block_cond = NULL;
475 G_OBJECT_CLASS (parent_class)->finalize (object);
479 gst_pad_set_property (GObject * object, guint prop_id,
480 const GValue * value, GParamSpec * pspec)
482 g_return_if_fail (GST_IS_PAD (object));
485 case PAD_PROP_DIRECTION:
486 GST_PAD_DIRECTION (object) = g_value_get_enum (value);
488 case PAD_PROP_TEMPLATE:
489 gst_pad_set_pad_template (GST_PAD_CAST (object),
490 (GstPadTemplate *) g_value_get_object (value));
493 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
499 gst_pad_get_property (GObject * object, guint prop_id,
500 GValue * value, GParamSpec * pspec)
502 g_return_if_fail (GST_IS_PAD (object));
506 GST_OBJECT_LOCK (object);
507 g_value_set_boxed (value, get_pad_caps (GST_PAD_CAST (object)));
508 GST_OBJECT_UNLOCK (object);
510 case PAD_PROP_DIRECTION:
511 g_value_set_enum (value, GST_PAD_DIRECTION (object));
513 case PAD_PROP_TEMPLATE:
514 g_value_set_object (value, GST_PAD_PAD_TEMPLATE (object));
517 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
524 * @name: the name of the new pad.
525 * @direction: the #GstPadDirection of the pad.
527 * Creates a new pad with the given name in the given direction.
528 * If name is NULL, a guaranteed unique name (across all pads)
530 * This function makes a copy of the name so you can safely free the name.
532 * Returns: (transfer full): a new #GstPad, or NULL in case of an error.
537 gst_pad_new (const gchar * name, GstPadDirection direction)
539 return g_object_new (GST_TYPE_PAD,
540 "name", name, "direction", direction, NULL);
544 * gst_pad_new_from_template:
545 * @templ: the pad template to use
546 * @name: the name of the element
548 * Creates a new pad with the given name from the given template.
549 * If name is NULL, a guaranteed unique name (across all pads)
551 * This function makes a copy of the name so you can safely free the name.
553 * Returns: (transfer full): a new #GstPad, or NULL in case of an error.
556 gst_pad_new_from_template (GstPadTemplate * templ, const gchar * name)
558 g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
560 return g_object_new (GST_TYPE_PAD,
561 "name", name, "direction", templ->direction, "template", templ, NULL);
565 * gst_pad_new_from_static_template:
566 * @templ: the #GstStaticPadTemplate to use
567 * @name: the name of the element
569 * Creates a new pad with the given name from the given static template.
570 * If name is NULL, a guaranteed unique name (across all pads)
572 * This function makes a copy of the name so you can safely free the name.
574 * Returns: (transfer full): a new #GstPad, or NULL in case of an error.
577 gst_pad_new_from_static_template (GstStaticPadTemplate * templ,
581 GstPadTemplate *template;
583 template = gst_static_pad_template_get (templ);
584 pad = gst_pad_new_from_template (template, name);
585 gst_object_unref (template);
590 * gst_pad_get_direction:
591 * @pad: a #GstPad to get the direction of.
593 * Gets the direction of the pad. The direction of the pad is
594 * decided at construction time so this function does not take
597 * Returns: the #GstPadDirection of the pad.
602 gst_pad_get_direction (GstPad * pad)
604 GstPadDirection result;
606 /* PAD_UNKNOWN is a little silly but we need some sort of
607 * error return value */
608 g_return_val_if_fail (GST_IS_PAD (pad), GST_PAD_UNKNOWN);
610 result = GST_PAD_DIRECTION (pad);
616 gst_pad_activate_default (GstPad * pad)
618 return gst_pad_activate_push (pad, TRUE);
622 pre_activate (GstPad * pad, GstActivateMode new_mode)
625 case GST_ACTIVATE_PUSH:
626 case GST_ACTIVATE_PULL:
627 GST_OBJECT_LOCK (pad);
628 GST_DEBUG_OBJECT (pad, "setting ACTIVATE_MODE %d, unset flushing",
630 GST_PAD_UNSET_FLUSHING (pad);
631 GST_PAD_ACTIVATE_MODE (pad) = new_mode;
632 GST_OBJECT_UNLOCK (pad);
634 case GST_ACTIVATE_NONE:
635 GST_OBJECT_LOCK (pad);
636 GST_DEBUG_OBJECT (pad, "setting ACTIVATE_MODE NONE, set flushing");
637 _priv_gst_pad_invalidate_cache (pad);
638 GST_PAD_SET_FLUSHING (pad);
639 GST_PAD_ACTIVATE_MODE (pad) = new_mode;
640 /* unlock blocked pads so element can resume and stop */
641 GST_PAD_BLOCK_BROADCAST (pad);
642 GST_OBJECT_UNLOCK (pad);
648 post_activate (GstPad * pad, GstActivateMode new_mode)
651 case GST_ACTIVATE_PUSH:
652 case GST_ACTIVATE_PULL:
655 case GST_ACTIVATE_NONE:
656 /* ensures that streaming stops */
657 GST_PAD_STREAM_LOCK (pad);
658 GST_DEBUG_OBJECT (pad, "stopped streaming");
659 GST_OBJECT_LOCK (pad);
660 clear_events (pad->priv->events);
661 GST_OBJECT_UNLOCK (pad);
662 GST_PAD_STREAM_UNLOCK (pad);
668 * gst_pad_set_active:
669 * @pad: the #GstPad to activate or deactivate.
670 * @active: whether or not the pad should be active.
672 * Activates or deactivates the given pad.
673 * Normally called from within core state change functions.
675 * If @active, makes sure the pad is active. If it is already active, either in
676 * push or pull mode, just return. Otherwise dispatches to the pad's activate
677 * function to perform the actual activation.
679 * If not @active, checks the pad's current mode and calls
680 * gst_pad_activate_push() or gst_pad_activate_pull(), as appropriate, with a
683 * Returns: #TRUE if the operation was successful.
688 gst_pad_set_active (GstPad * pad, gboolean active)
691 gboolean ret = FALSE;
693 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
695 GST_OBJECT_LOCK (pad);
696 old = GST_PAD_ACTIVATE_MODE (pad);
697 GST_OBJECT_UNLOCK (pad);
701 case GST_ACTIVATE_PUSH:
702 GST_DEBUG_OBJECT (pad, "activating pad from push");
705 case GST_ACTIVATE_PULL:
706 GST_DEBUG_OBJECT (pad, "activating pad from pull");
709 case GST_ACTIVATE_NONE:
710 GST_DEBUG_OBJECT (pad, "activating pad from none");
711 ret = (GST_PAD_ACTIVATEFUNC (pad)) (pad);
714 GST_DEBUG_OBJECT (pad, "unknown activation mode!");
719 case GST_ACTIVATE_PUSH:
720 GST_DEBUG_OBJECT (pad, "deactivating pad from push");
721 ret = gst_pad_activate_push (pad, FALSE);
723 case GST_ACTIVATE_PULL:
724 GST_DEBUG_OBJECT (pad, "deactivating pad from pull");
725 ret = gst_pad_activate_pull (pad, FALSE);
727 case GST_ACTIVATE_NONE:
728 GST_DEBUG_OBJECT (pad, "deactivating pad from none");
732 GST_DEBUG_OBJECT (pad, "unknown activation mode!");
738 GST_OBJECT_LOCK (pad);
740 g_critical ("Failed to deactivate pad %s:%s, very bad",
741 GST_DEBUG_PAD_NAME (pad));
743 GST_WARNING_OBJECT (pad, "Failed to activate pad");
745 GST_OBJECT_UNLOCK (pad);
748 GST_OBJECT_LOCK (pad);
749 GST_OBJECT_FLAG_UNSET (pad, GST_PAD_NEED_RECONFIGURE);
750 GST_OBJECT_UNLOCK (pad);
758 * gst_pad_activate_pull:
759 * @pad: the #GstPad to activate or deactivate.
760 * @active: whether or not the pad should be active.
762 * Activates or deactivates the given pad in pull mode via dispatching to the
763 * pad's activatepullfunc. For use from within pad activation functions only.
764 * When called on sink pads, will first proxy the call to the peer pad, which
765 * is expected to activate its internally linked pads from within its
766 * activate_pull function.
768 * If you don't know what this is, you probably don't want to call it.
770 * Returns: TRUE if the operation was successful.
775 gst_pad_activate_pull (GstPad * pad, gboolean active)
777 GstActivateMode old, new;
780 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
782 GST_OBJECT_LOCK (pad);
783 old = GST_PAD_ACTIVATE_MODE (pad);
784 GST_OBJECT_UNLOCK (pad);
788 case GST_ACTIVATE_PULL:
789 GST_DEBUG_OBJECT (pad, "activating pad from pull, was ok");
791 case GST_ACTIVATE_PUSH:
792 GST_DEBUG_OBJECT (pad,
793 "activating pad from push, deactivate push first");
794 /* pad was activate in the wrong direction, deactivate it
795 * and reactivate it in pull mode */
796 if (G_UNLIKELY (!gst_pad_activate_push (pad, FALSE)))
797 goto deactivate_failed;
798 /* fallthrough, pad is deactivated now. */
799 case GST_ACTIVATE_NONE:
800 GST_DEBUG_OBJECT (pad, "activating pad from none");
805 case GST_ACTIVATE_NONE:
806 GST_DEBUG_OBJECT (pad, "deactivating pad from none, was ok");
808 case GST_ACTIVATE_PUSH:
809 GST_DEBUG_OBJECT (pad, "deactivating pad from push, weird");
810 /* pad was activated in the other direction, deactivate it
811 * in push mode, this should not happen... */
812 if (G_UNLIKELY (!gst_pad_activate_push (pad, FALSE)))
813 goto deactivate_failed;
814 /* everything is fine now */
816 case GST_ACTIVATE_PULL:
817 GST_DEBUG_OBJECT (pad, "deactivating pad from pull");
822 if (gst_pad_get_direction (pad) == GST_PAD_SINK) {
823 if ((peer = gst_pad_get_peer (pad))) {
824 GST_DEBUG_OBJECT (pad, "calling peer");
825 if (G_UNLIKELY (!gst_pad_activate_pull (peer, active)))
827 gst_object_unref (peer);
829 /* there is no peer, this is only fatal when we activate. When we
830 * deactivate, we must assume the application has unlinked the peer and
831 * will deactivate it eventually. */
835 GST_DEBUG_OBJECT (pad, "deactivating unlinked pad");
838 if (G_UNLIKELY (GST_PAD_GETRANGEFUNC (pad) == NULL))
839 goto failure; /* Can't activate pull on a src without a
843 new = active ? GST_ACTIVATE_PULL : GST_ACTIVATE_NONE;
844 pre_activate (pad, new);
846 if (GST_PAD_ACTIVATEPULLFUNC (pad)) {
847 if (G_UNLIKELY (!GST_PAD_ACTIVATEPULLFUNC (pad) (pad, active)))
850 /* can happen for sinks of passthrough elements */
853 post_activate (pad, new);
855 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "%s in pull mode",
856 active ? "activated" : "deactivated");
862 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "already %s in pull mode",
863 active ? "activated" : "deactivated");
868 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
869 "failed to %s in switch to pull from mode %d",
870 (active ? "activate" : "deactivate"), old);
875 GST_OBJECT_LOCK (peer);
876 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
877 "activate_pull on peer (%s:%s) failed", GST_DEBUG_PAD_NAME (peer));
878 GST_OBJECT_UNLOCK (peer);
879 gst_object_unref (peer);
884 GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "can't activate unlinked sink "
890 GST_OBJECT_LOCK (pad);
891 GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "failed to %s in pull mode",
892 active ? "activate" : "deactivate");
893 _priv_gst_pad_invalidate_cache (pad);
894 GST_PAD_SET_FLUSHING (pad);
895 GST_PAD_ACTIVATE_MODE (pad) = old;
896 GST_OBJECT_UNLOCK (pad);
902 * gst_pad_activate_push:
903 * @pad: the #GstPad to activate or deactivate.
904 * @active: whether the pad should be active or not.
906 * Activates or deactivates the given pad in push mode via dispatching to the
907 * pad's activatepushfunc. For use from within pad activation functions only.
909 * If you don't know what this is, you probably don't want to call it.
911 * Returns: %TRUE if the operation was successful.
916 gst_pad_activate_push (GstPad * pad, gboolean active)
918 GstActivateMode old, new;
920 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
921 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "trying to set %s in push mode",
922 active ? "activated" : "deactivated");
924 GST_OBJECT_LOCK (pad);
925 old = GST_PAD_ACTIVATE_MODE (pad);
926 GST_OBJECT_UNLOCK (pad);
930 case GST_ACTIVATE_PUSH:
931 GST_DEBUG_OBJECT (pad, "activating pad from push, was ok");
933 case GST_ACTIVATE_PULL:
934 GST_DEBUG_OBJECT (pad,
935 "activating pad from push, deactivating pull first");
936 /* pad was activate in the wrong direction, deactivate it
937 * an reactivate it in push mode */
938 if (G_UNLIKELY (!gst_pad_activate_pull (pad, FALSE)))
939 goto deactivate_failed;
940 /* fallthrough, pad is deactivated now. */
941 case GST_ACTIVATE_NONE:
942 GST_DEBUG_OBJECT (pad, "activating pad from none");
947 case GST_ACTIVATE_NONE:
948 GST_DEBUG_OBJECT (pad, "deactivating pad from none, was ok");
950 case GST_ACTIVATE_PULL:
951 GST_DEBUG_OBJECT (pad, "deactivating pad from pull, weird");
952 /* pad was activated in the other direction, deactivate it
953 * in pull mode, this should not happen... */
954 if (G_UNLIKELY (!gst_pad_activate_pull (pad, FALSE)))
955 goto deactivate_failed;
956 /* everything is fine now */
958 case GST_ACTIVATE_PUSH:
959 GST_DEBUG_OBJECT (pad, "deactivating pad from push");
964 new = active ? GST_ACTIVATE_PUSH : GST_ACTIVATE_NONE;
965 pre_activate (pad, new);
967 if (GST_PAD_ACTIVATEPUSHFUNC (pad)) {
968 if (G_UNLIKELY (!GST_PAD_ACTIVATEPUSHFUNC (pad) (pad, active))) {
972 /* quite ok, element relies on state change func to prepare itself */
975 post_activate (pad, new);
977 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "%s in push mode",
978 active ? "activated" : "deactivated");
983 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "already %s in push mode",
984 active ? "activated" : "deactivated");
989 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
990 "failed to %s in switch to push from mode %d",
991 (active ? "activate" : "deactivate"), old);
996 GST_OBJECT_LOCK (pad);
997 GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "failed to %s in push mode",
998 active ? "activate" : "deactivate");
999 _priv_gst_pad_invalidate_cache (pad);
1000 GST_PAD_SET_FLUSHING (pad);
1001 GST_PAD_ACTIVATE_MODE (pad) = old;
1002 GST_OBJECT_UNLOCK (pad);
1008 * gst_pad_is_active:
1009 * @pad: the #GstPad to query
1011 * Query if a pad is active
1013 * Returns: TRUE if the pad is active.
1018 gst_pad_is_active (GstPad * pad)
1020 gboolean result = FALSE;
1022 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
1024 GST_OBJECT_LOCK (pad);
1025 result = GST_PAD_MODE_ACTIVATE (GST_PAD_ACTIVATE_MODE (pad));
1026 GST_OBJECT_UNLOCK (pad);
1032 * gst_pad_set_blocked_async_full:
1033 * @pad: the #GstPad to block or unblock
1034 * @blocked: boolean indicating whether the pad should be blocked or unblocked
1035 * @callback: #GstPadBlockCallback that will be called when the
1036 * operation succeeds
1037 * @user_data: (closure): user data passed to the callback
1038 * @destroy_data: #GDestroyNotify for user_data
1040 * Blocks or unblocks the dataflow on a pad. The provided callback
1041 * is called when the operation succeeds; this happens right before the next
1042 * attempt at pushing a buffer on the pad.
1044 * This can take a while as the pad can only become blocked when real dataflow
1046 * When the pipeline is stalled, for example in PAUSED, this can
1047 * take an indeterminate amount of time.
1048 * You can pass NULL as the callback to make this call block. Be careful with
1049 * this blocking call as it might not return for reasons stated above.
1052 * Pad block handlers are only called for source pads in push mode
1053 * and sink pads in pull mode.
1056 * Returns: TRUE if the pad could be blocked. This function can fail if the
1057 * wrong parameters were passed or the pad was already in the requested state.
1064 gst_pad_set_blocked_async_full (GstPad * pad, gboolean blocked,
1065 GstPadBlockCallback callback, gpointer user_data,
1066 GDestroyNotify destroy_data)
1068 gboolean was_blocked = FALSE;
1070 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
1072 GST_OBJECT_LOCK (pad);
1074 was_blocked = GST_PAD_IS_BLOCKED (pad);
1076 if (G_UNLIKELY (was_blocked == blocked))
1077 goto had_right_state;
1080 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "blocking pad");
1082 _priv_gst_pad_invalidate_cache (pad);
1083 GST_OBJECT_FLAG_SET (pad, GST_PAD_BLOCKED);
1085 if (pad->block_destroy_data && pad->block_data)
1086 pad->block_destroy_data (pad->block_data);
1088 pad->block_callback = callback;
1089 pad->block_data = user_data;
1090 pad->block_destroy_data = destroy_data;
1091 pad->block_callback_called = FALSE;
1093 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "waiting for block");
1094 GST_PAD_BLOCK_WAIT (pad);
1095 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "blocked");
1098 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "unblocking pad");
1100 GST_OBJECT_FLAG_UNSET (pad, GST_PAD_BLOCKED);
1102 if (pad->block_destroy_data && pad->block_data)
1103 pad->block_destroy_data (pad->block_data);
1105 pad->block_callback = callback;
1106 pad->block_data = user_data;
1107 pad->block_destroy_data = destroy_data;
1108 pad->block_callback_called = FALSE;
1110 GST_PAD_BLOCK_BROADCAST (pad);
1112 /* no callback, wait for the unblock to happen */
1113 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "waiting for unblock");
1114 GST_PAD_BLOCK_WAIT (pad);
1115 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "unblocked");
1118 GST_OBJECT_UNLOCK (pad);
1124 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
1125 "pad was in right state (%d)", was_blocked);
1126 GST_OBJECT_UNLOCK (pad);
1133 * gst_pad_set_blocked_async:
1134 * @pad: the #GstPad to block or unblock
1135 * @blocked: boolean indicating whether the pad should be blocked or unblocked
1136 * @callback: #GstPadBlockCallback that will be called when the
1137 * operation succeeds
1138 * @user_data: (closure): user data passed to the callback
1140 * Blocks or unblocks the dataflow on a pad. The provided callback
1141 * is called when the operation succeeds; this happens right before the next
1142 * attempt at pushing a buffer on the pad.
1144 * This can take a while as the pad can only become blocked when real dataflow
1146 * When the pipeline is stalled, for example in PAUSED, this can
1147 * take an indeterminate amount of time.
1148 * You can pass NULL as the callback to make this call block. Be careful with
1149 * this blocking call as it might not return for reasons stated above.
1152 * Pad block handlers are only called for source pads in push mode
1153 * and sink pads in pull mode.
1156 * Returns: TRUE if the pad could be blocked. This function can fail if the
1157 * wrong parameters were passed or the pad was already in the requested state.
1162 gst_pad_set_blocked_async (GstPad * pad, gboolean blocked,
1163 GstPadBlockCallback callback, gpointer user_data)
1165 return gst_pad_set_blocked_async_full (pad, blocked,
1166 callback, user_data, NULL);
1170 * gst_pad_set_blocked:
1171 * @pad: the #GstPad to block or unblock
1172 * @blocked: boolean indicating we should block or unblock
1174 * Blocks or unblocks the dataflow on a pad. This function is
1175 * a shortcut for gst_pad_set_blocked_async() with a NULL
1179 * Pad blocks are only possible for source pads in push mode
1180 * and sink pads in pull mode.
1183 * Returns: TRUE if the pad could be blocked. This function can fail if the
1184 * wrong parameters were passed or the pad was already in the requested state.
1189 gst_pad_set_blocked (GstPad * pad, gboolean blocked)
1191 return gst_pad_set_blocked_async (pad, blocked, NULL, NULL);
1195 * gst_pad_is_blocked:
1196 * @pad: the #GstPad to query
1198 * Checks if the pad is blocked or not. This function returns the
1199 * last requested state of the pad. It is not certain that the pad
1200 * is actually blocking at this point (see gst_pad_is_blocking()).
1202 * Returns: TRUE if the pad is blocked.
1207 gst_pad_is_blocked (GstPad * pad)
1209 gboolean result = FALSE;
1211 g_return_val_if_fail (GST_IS_PAD (pad), result);
1213 GST_OBJECT_LOCK (pad);
1214 result = GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_BLOCKED);
1215 GST_OBJECT_UNLOCK (pad);
1221 * gst_pad_is_blocking:
1222 * @pad: the #GstPad to query
1224 * Checks if the pad is blocking or not. This is a guaranteed state
1225 * of whether the pad is actually blocking on a #GstBuffer or a #GstEvent.
1227 * Returns: TRUE if the pad is blocking.
1234 gst_pad_is_blocking (GstPad * pad)
1236 gboolean result = FALSE;
1238 g_return_val_if_fail (GST_IS_PAD (pad), result);
1240 GST_OBJECT_LOCK (pad);
1241 /* the blocking flag is only valid if the pad is not flushing */
1242 result = GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_BLOCKING) &&
1243 !GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLUSHING);
1244 GST_OBJECT_UNLOCK (pad);
1250 * gst_pad_set_activate_function:
1252 * @activate: the #GstPadActivateFunction to set.
1254 * Sets the given activate function for @pad. The activate function will
1255 * dispatch to gst_pad_activate_push() or gst_pad_activate_pull() to perform
1256 * the actual activation. Only makes sense to set on sink pads.
1258 * Call this function if your sink pad can start a pull-based task.
1261 gst_pad_set_activate_function (GstPad * pad, GstPadActivateFunction activate)
1263 g_return_if_fail (GST_IS_PAD (pad));
1265 GST_PAD_ACTIVATEFUNC (pad) = activate;
1266 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "activatefunc set to %s",
1267 GST_DEBUG_FUNCPTR_NAME (activate));
1271 * gst_pad_set_activatepull_function:
1273 * @activatepull: the #GstPadActivateModeFunction to set.
1275 * Sets the given activate_pull function for the pad. An activate_pull function
1276 * prepares the element and any upstream connections for pulling. See XXX
1277 * part-activation.txt for details.
1280 gst_pad_set_activatepull_function (GstPad * pad,
1281 GstPadActivateModeFunction activatepull)
1283 g_return_if_fail (GST_IS_PAD (pad));
1285 GST_PAD_ACTIVATEPULLFUNC (pad) = activatepull;
1286 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "activatepullfunc set to %s",
1287 GST_DEBUG_FUNCPTR_NAME (activatepull));
1291 * gst_pad_set_activatepush_function:
1293 * @activatepush: the #GstPadActivateModeFunction to set.
1295 * Sets the given activate_push function for the pad. An activate_push function
1296 * prepares the element for pushing. See XXX part-activation.txt for details.
1299 gst_pad_set_activatepush_function (GstPad * pad,
1300 GstPadActivateModeFunction activatepush)
1302 g_return_if_fail (GST_IS_PAD (pad));
1304 GST_PAD_ACTIVATEPUSHFUNC (pad) = activatepush;
1305 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "activatepushfunc set to %s",
1306 GST_DEBUG_FUNCPTR_NAME (activatepush));
1310 * gst_pad_set_chain_function:
1311 * @pad: a sink #GstPad.
1312 * @chain: the #GstPadChainFunction to set.
1314 * Sets the given chain function for the pad. The chain function is called to
1315 * process a #GstBuffer input buffer. see #GstPadChainFunction for more details.
1318 gst_pad_set_chain_function (GstPad * pad, GstPadChainFunction chain)
1320 g_return_if_fail (GST_IS_PAD (pad));
1321 g_return_if_fail (GST_PAD_IS_SINK (pad));
1323 GST_PAD_CHAINFUNC (pad) = chain;
1324 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "chainfunc set to %s",
1325 GST_DEBUG_FUNCPTR_NAME (chain));
1329 * gst_pad_set_chain_list_function:
1330 * @pad: a sink #GstPad.
1331 * @chainlist: the #GstPadChainListFunction to set.
1333 * Sets the given chain list function for the pad. The chainlist function is
1334 * called to process a #GstBufferList input buffer list. See
1335 * #GstPadChainListFunction for more details.
1340 gst_pad_set_chain_list_function (GstPad * pad,
1341 GstPadChainListFunction chainlist)
1343 g_return_if_fail (GST_IS_PAD (pad));
1344 g_return_if_fail (GST_PAD_IS_SINK (pad));
1346 GST_PAD_CHAINLISTFUNC (pad) = chainlist;
1347 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "chainlistfunc set to %s",
1348 GST_DEBUG_FUNCPTR_NAME (chainlist));
1352 * gst_pad_set_getrange_function:
1353 * @pad: a source #GstPad.
1354 * @get: the #GstPadGetRangeFunction to set.
1356 * Sets the given getrange function for the pad. The getrange function is
1357 * called to produce a new #GstBuffer to start the processing pipeline. see
1358 * #GstPadGetRangeFunction for a description of the getrange function.
1361 gst_pad_set_getrange_function (GstPad * pad, GstPadGetRangeFunction get)
1363 g_return_if_fail (GST_IS_PAD (pad));
1364 g_return_if_fail (GST_PAD_IS_SRC (pad));
1366 GST_PAD_GETRANGEFUNC (pad) = get;
1368 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "getrangefunc set to %s",
1369 GST_DEBUG_FUNCPTR_NAME (get));
1373 * gst_pad_set_checkgetrange_function:
1374 * @pad: a source #GstPad.
1375 * @check: the #GstPadCheckGetRangeFunction to set.
1377 * Sets the given checkgetrange function for the pad. Implement this function
1378 * on a pad if you dynamically support getrange based scheduling on the pad.
1381 gst_pad_set_checkgetrange_function (GstPad * pad,
1382 GstPadCheckGetRangeFunction check)
1384 g_return_if_fail (GST_IS_PAD (pad));
1385 g_return_if_fail (GST_PAD_IS_SRC (pad));
1387 GST_PAD_CHECKGETRANGEFUNC (pad) = check;
1389 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "checkgetrangefunc set to %s",
1390 GST_DEBUG_FUNCPTR_NAME (check));
1394 * gst_pad_set_event_function:
1395 * @pad: a #GstPad of either direction.
1396 * @event: the #GstPadEventFunction to set.
1398 * Sets the given event handler for the pad.
1401 gst_pad_set_event_function (GstPad * pad, GstPadEventFunction event)
1403 g_return_if_fail (GST_IS_PAD (pad));
1405 GST_PAD_EVENTFUNC (pad) = event;
1407 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "eventfunc for set to %s",
1408 GST_DEBUG_FUNCPTR_NAME (event));
1412 * gst_pad_set_query_function:
1413 * @pad: a #GstPad of either direction.
1414 * @query: the #GstPadQueryFunction to set.
1416 * Set the given query function for the pad.
1419 gst_pad_set_query_function (GstPad * pad, GstPadQueryFunction query)
1421 g_return_if_fail (GST_IS_PAD (pad));
1423 GST_PAD_QUERYFUNC (pad) = query;
1425 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "queryfunc set to %s",
1426 GST_DEBUG_FUNCPTR_NAME (query));
1430 * gst_pad_set_query_type_function:
1431 * @pad: a #GstPad of either direction.
1432 * @type_func: the #GstPadQueryTypeFunction to set.
1434 * Set the given query type function for the pad.
1437 gst_pad_set_query_type_function (GstPad * pad,
1438 GstPadQueryTypeFunction type_func)
1440 g_return_if_fail (GST_IS_PAD (pad));
1442 GST_PAD_QUERYTYPEFUNC (pad) = type_func;
1444 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "querytypefunc set to %s",
1445 GST_DEBUG_FUNCPTR_NAME (type_func));
1449 * gst_pad_get_query_types:
1452 * Get an array of supported queries that can be performed
1455 * Returns: (transfer none) (array zero-terminated=1): a zero-terminated array
1458 const GstQueryType *
1459 gst_pad_get_query_types (GstPad * pad)
1461 GstPadQueryTypeFunction func;
1463 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1465 if (G_UNLIKELY ((func = GST_PAD_QUERYTYPEFUNC (pad)) == NULL))
1477 gst_pad_get_query_types_dispatcher (GstPad * pad, const GstQueryType ** data)
1479 *data = gst_pad_get_query_types (pad);
1485 * gst_pad_get_query_types_default:
1488 * Invoke the default dispatcher for the query types on
1491 * Returns: (transfer none) (array zero-terminated=1): a zero-terminated array
1492 * of #GstQueryType, or NULL if none of the internally-linked pads has a
1493 * query types function.
1495 const GstQueryType *
1496 gst_pad_get_query_types_default (GstPad * pad)
1498 GstQueryType *result = NULL;
1500 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1502 gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
1503 gst_pad_get_query_types_dispatcher, &result);
1509 * gst_pad_set_iterate_internal_links_function:
1510 * @pad: a #GstPad of either direction.
1511 * @iterintlink: the #GstPadIterIntLinkFunction to set.
1513 * Sets the given internal link iterator function for the pad.
1518 gst_pad_set_iterate_internal_links_function (GstPad * pad,
1519 GstPadIterIntLinkFunction iterintlink)
1521 g_return_if_fail (GST_IS_PAD (pad));
1523 GST_PAD_ITERINTLINKFUNC (pad) = iterintlink;
1524 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "internal link iterator set to %s",
1525 GST_DEBUG_FUNCPTR_NAME (iterintlink));
1529 * gst_pad_set_link_function:
1531 * @link: the #GstPadLinkFunction to set.
1533 * Sets the given link function for the pad. It will be called when
1534 * the pad is linked with another pad.
1536 * The return value #GST_PAD_LINK_OK should be used when the connection can be
1539 * The return value #GST_PAD_LINK_REFUSED should be used when the connection
1540 * cannot be made for some reason.
1542 * If @link is installed on a source pad, it should call the #GstPadLinkFunction
1543 * of the peer sink pad, if present.
1546 gst_pad_set_link_function (GstPad * pad, GstPadLinkFunction link)
1548 g_return_if_fail (GST_IS_PAD (pad));
1550 GST_PAD_LINKFUNC (pad) = link;
1551 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "linkfunc set to %s",
1552 GST_DEBUG_FUNCPTR_NAME (link));
1556 * gst_pad_set_unlink_function:
1558 * @unlink: the #GstPadUnlinkFunction to set.
1560 * Sets the given unlink function for the pad. It will be called
1561 * when the pad is unlinked.
1564 gst_pad_set_unlink_function (GstPad * pad, GstPadUnlinkFunction unlink)
1566 g_return_if_fail (GST_IS_PAD (pad));
1568 GST_PAD_UNLINKFUNC (pad) = unlink;
1569 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "unlinkfunc set to %s",
1570 GST_DEBUG_FUNCPTR_NAME (unlink));
1574 * gst_pad_set_getcaps_function:
1576 * @getcaps: the #GstPadGetCapsFunction to set.
1578 * Sets the given getcaps function for the pad. @getcaps should return the
1579 * allowable caps for a pad in the context of the element's state, its link to
1580 * other elements, and the devices or files it has opened. These caps must be a
1581 * subset of the pad template caps. In the NULL state with no links, @getcaps
1582 * should ideally return the same caps as the pad template. In rare
1583 * circumstances, an object property can affect the caps returned by @getcaps,
1584 * but this is discouraged.
1586 * You do not need to call this function if @pad's allowed caps are always the
1587 * same as the pad template caps. This can only be true if the padtemplate
1588 * has fixed simple caps.
1590 * For most filters, the caps returned by @getcaps is directly affected by the
1591 * allowed caps on other pads. For demuxers and decoders, the caps returned by
1592 * the srcpad's getcaps function is directly related to the stream data. Again,
1593 * @getcaps should return the most specific caps it reasonably can, since this
1594 * helps with autoplugging.
1596 * Note that the return value from @getcaps is owned by the caller, so the
1597 * caller should unref the caps after usage.
1600 gst_pad_set_getcaps_function (GstPad * pad, GstPadGetCapsFunction getcaps)
1602 g_return_if_fail (GST_IS_PAD (pad));
1604 GST_PAD_GETCAPSFUNC (pad) = getcaps;
1605 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "getcapsfunc set to %s",
1606 GST_DEBUG_FUNCPTR_NAME (getcaps));
1610 * gst_pad_set_acceptcaps_function:
1612 * @acceptcaps: the #GstPadAcceptCapsFunction to set.
1614 * Sets the given acceptcaps function for the pad. The acceptcaps function
1615 * will be called to check if the pad can accept the given caps. Setting the
1616 * acceptcaps function to NULL restores the default behaviour of allowing
1617 * any caps that matches the caps from gst_pad_get_caps().
1620 gst_pad_set_acceptcaps_function (GstPad * pad,
1621 GstPadAcceptCapsFunction acceptcaps)
1623 g_return_if_fail (GST_IS_PAD (pad));
1625 GST_PAD_ACCEPTCAPSFUNC (pad) = acceptcaps;
1626 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "acceptcapsfunc set to %s",
1627 GST_DEBUG_FUNCPTR_NAME (acceptcaps));
1631 * gst_pad_set_fixatecaps_function:
1633 * @fixatecaps: the #GstPadFixateCapsFunction to set.
1635 * Sets the given fixatecaps function for the pad. The fixatecaps function
1636 * will be called whenever the default values for a GstCaps needs to be
1640 gst_pad_set_fixatecaps_function (GstPad * pad,
1641 GstPadFixateCapsFunction fixatecaps)
1643 g_return_if_fail (GST_IS_PAD (pad));
1645 GST_PAD_FIXATECAPSFUNC (pad) = fixatecaps;
1646 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "fixatecapsfunc set to %s",
1647 GST_DEBUG_FUNCPTR_NAME (fixatecaps));
1651 * gst_pad_set_setcaps_function:
1653 * @setcaps: the #GstPadSetCapsFunction to set.
1655 * Sets the given setcaps function for the pad. The setcaps function
1656 * will be called whenever a buffer with a new media type is pushed or
1657 * pulled from the pad. The pad/element needs to update its internal
1658 * structures to process the new media type. If this new type is not
1659 * acceptable, the setcaps function should return FALSE.
1662 gst_pad_set_setcaps_function (GstPad * pad, GstPadSetCapsFunction setcaps)
1664 g_return_if_fail (GST_IS_PAD (pad));
1666 GST_PAD_SETCAPSFUNC (pad) = setcaps;
1667 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "setcapsfunc set to %s",
1668 GST_DEBUG_FUNCPTR_NAME (setcaps));
1673 * @srcpad: the source #GstPad to unlink.
1674 * @sinkpad: the sink #GstPad to unlink.
1676 * Unlinks the source pad from the sink pad. Will emit the #GstPad::unlinked
1677 * signal on both pads.
1679 * Returns: TRUE if the pads were unlinked. This function returns FALSE if
1680 * the pads were not linked together.
1685 gst_pad_unlink (GstPad * srcpad, GstPad * sinkpad)
1687 gboolean result = FALSE;
1688 GstElement *parent = NULL;
1690 g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
1691 g_return_val_if_fail (GST_PAD_IS_SRC (srcpad), FALSE);
1692 g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
1693 g_return_val_if_fail (GST_PAD_IS_SINK (sinkpad), FALSE);
1695 GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "unlinking %s:%s(%p) and %s:%s(%p)",
1696 GST_DEBUG_PAD_NAME (srcpad), srcpad,
1697 GST_DEBUG_PAD_NAME (sinkpad), sinkpad);
1699 /* We need to notify the parent before taking any pad locks as the bin in
1700 * question might be waiting for a lock on the pad while holding its lock
1701 * that our message will try to take. */
1702 if ((parent = GST_ELEMENT_CAST (gst_pad_get_parent (srcpad)))) {
1703 if (GST_IS_ELEMENT (parent)) {
1704 gst_element_post_message (parent,
1705 gst_message_new_structure_change (GST_OBJECT_CAST (sinkpad),
1706 GST_STRUCTURE_CHANGE_TYPE_PAD_UNLINK, parent, TRUE));
1708 gst_object_unref (parent);
1713 GST_OBJECT_LOCK (srcpad);
1715 GST_OBJECT_LOCK (sinkpad);
1717 if (G_UNLIKELY (GST_PAD_PEER (srcpad) != sinkpad))
1718 goto not_linked_together;
1720 if (GST_PAD_UNLINKFUNC (srcpad)) {
1721 GST_PAD_UNLINKFUNC (srcpad) (srcpad);
1723 if (GST_PAD_UNLINKFUNC (sinkpad)) {
1724 GST_PAD_UNLINKFUNC (sinkpad) (sinkpad);
1727 _priv_gst_pad_invalidate_cache (srcpad);
1729 /* first clear peers */
1730 GST_PAD_PEER (srcpad) = NULL;
1731 GST_PAD_PEER (sinkpad) = NULL;
1733 GST_OBJECT_UNLOCK (sinkpad);
1734 GST_OBJECT_UNLOCK (srcpad);
1736 /* fire off a signal to each of the pads telling them
1737 * that they've been unlinked */
1738 g_signal_emit (srcpad, gst_pad_signals[PAD_UNLINKED], 0, sinkpad);
1739 g_signal_emit (sinkpad, gst_pad_signals[PAD_UNLINKED], 0, srcpad);
1741 GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "unlinked %s:%s and %s:%s",
1742 GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1747 if (parent != NULL) {
1748 gst_element_post_message (parent,
1749 gst_message_new_structure_change (GST_OBJECT_CAST (sinkpad),
1750 GST_STRUCTURE_CHANGE_TYPE_PAD_UNLINK, parent, FALSE));
1751 gst_object_unref (parent);
1756 not_linked_together:
1758 /* we do not emit a warning in this case because unlinking cannot
1759 * be made MT safe.*/
1760 GST_OBJECT_UNLOCK (sinkpad);
1761 GST_OBJECT_UNLOCK (srcpad);
1767 * gst_pad_is_linked:
1768 * @pad: pad to check
1770 * Checks if a @pad is linked to another pad or not.
1772 * Returns: TRUE if the pad is linked, FALSE otherwise.
1777 gst_pad_is_linked (GstPad * pad)
1781 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
1783 GST_OBJECT_LOCK (pad);
1784 result = (GST_PAD_PEER (pad) != NULL);
1785 GST_OBJECT_UNLOCK (pad);
1790 /* get the caps from both pads and see if the intersection
1793 * This function should be called with the pad LOCK on both
1797 gst_pad_link_check_compatible_unlocked (GstPad * src, GstPad * sink,
1798 GstPadLinkCheck flags)
1800 GstCaps *srccaps = NULL;
1801 GstCaps *sinkcaps = NULL;
1802 gboolean compatible = FALSE;
1804 if (!(flags & (GST_PAD_LINK_CHECK_CAPS | GST_PAD_LINK_CHECK_TEMPLATE_CAPS)))
1807 /* Doing the expensive caps checking takes priority over only checking the template caps */
1808 if (flags & GST_PAD_LINK_CHECK_CAPS) {
1809 srccaps = gst_pad_get_caps_unlocked (src, NULL);
1810 sinkcaps = gst_pad_get_caps_unlocked (sink, NULL);
1812 /* If one of the two pads doesn't have a template, consider the intersection
1814 if (G_UNLIKELY ((GST_PAD_PAD_TEMPLATE (src) == NULL)
1815 || (GST_PAD_PAD_TEMPLATE (sink) == NULL))) {
1819 srccaps = gst_caps_ref (GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (src)));
1821 gst_caps_ref (GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (sink)));
1824 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, src, "src caps %" GST_PTR_FORMAT,
1826 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, sink, "sink caps %" GST_PTR_FORMAT,
1829 /* if we have caps on both pads we can check the intersection. If one
1830 * of the caps is NULL, we return TRUE. */
1831 if (G_UNLIKELY (srccaps == NULL || sinkcaps == NULL)) {
1833 gst_caps_unref (srccaps);
1835 gst_caps_unref (sinkcaps);
1839 compatible = gst_caps_can_intersect (srccaps, sinkcaps);
1840 gst_caps_unref (srccaps);
1841 gst_caps_unref (sinkcaps);
1844 GST_CAT_DEBUG (GST_CAT_CAPS, "caps are %scompatible",
1845 (compatible ? "" : "not"));
1850 /* check if the grandparents of both pads are the same.
1851 * This check is required so that we don't try to link
1852 * pads from elements in different bins without ghostpads.
1854 * The LOCK should be held on both pads
1857 gst_pad_link_check_hierarchy (GstPad * src, GstPad * sink)
1859 GstObject *psrc, *psink;
1861 psrc = GST_OBJECT_PARENT (src);
1862 psink = GST_OBJECT_PARENT (sink);
1864 /* if one of the pads has no parent, we allow the link */
1865 if (G_UNLIKELY (psrc == NULL || psink == NULL))
1868 /* only care about parents that are elements */
1869 if (G_UNLIKELY (!GST_IS_ELEMENT (psrc) || !GST_IS_ELEMENT (psink)))
1870 goto no_element_parent;
1872 /* if the parents are the same, we have a loop */
1873 if (G_UNLIKELY (psrc == psink))
1876 /* if they both have a parent, we check the grandparents. We can not lock
1877 * the parent because we hold on the child (pad) and the locking order is
1878 * parent >> child. */
1879 psrc = GST_OBJECT_PARENT (psrc);
1880 psink = GST_OBJECT_PARENT (psink);
1882 /* if they have grandparents but they are not the same */
1883 if (G_UNLIKELY (psrc != psink))
1884 goto wrong_grandparents;
1891 GST_CAT_DEBUG (GST_CAT_CAPS,
1892 "one of the pads has no parent %" GST_PTR_FORMAT " and %"
1893 GST_PTR_FORMAT, psrc, psink);
1898 GST_CAT_DEBUG (GST_CAT_CAPS,
1899 "one of the pads has no element parent %" GST_PTR_FORMAT " and %"
1900 GST_PTR_FORMAT, psrc, psink);
1905 GST_CAT_DEBUG (GST_CAT_CAPS, "pads have same parent %" GST_PTR_FORMAT,
1911 GST_CAT_DEBUG (GST_CAT_CAPS,
1912 "pads have different grandparents %" GST_PTR_FORMAT " and %"
1913 GST_PTR_FORMAT, psrc, psink);
1918 /* FIXME leftover from an attempt at refactoring... */
1919 /* call with the two pads unlocked, when this function returns GST_PAD_LINK_OK,
1920 * the two pads will be locked in the srcpad, sinkpad order. */
1921 static GstPadLinkReturn
1922 gst_pad_link_prepare (GstPad * srcpad, GstPad * sinkpad, GstPadLinkCheck flags)
1924 GST_CAT_INFO (GST_CAT_PADS, "trying to link %s:%s and %s:%s",
1925 GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1927 GST_OBJECT_LOCK (srcpad);
1929 if (G_UNLIKELY (GST_PAD_PEER (srcpad) != NULL))
1930 goto src_was_linked;
1932 GST_OBJECT_LOCK (sinkpad);
1934 if (G_UNLIKELY (GST_PAD_PEER (sinkpad) != NULL))
1935 goto sink_was_linked;
1937 /* check hierarchy, pads can only be linked if the grandparents
1939 if ((flags & GST_PAD_LINK_CHECK_HIERARCHY)
1940 && !gst_pad_link_check_hierarchy (srcpad, sinkpad))
1941 goto wrong_hierarchy;
1943 /* check pad caps for non-empty intersection */
1944 if (!gst_pad_link_check_compatible_unlocked (srcpad, sinkpad, flags))
1947 /* FIXME check pad scheduling for non-empty intersection */
1949 return GST_PAD_LINK_OK;
1953 GST_CAT_INFO (GST_CAT_PADS, "src %s:%s was already linked to %s:%s",
1954 GST_DEBUG_PAD_NAME (srcpad),
1955 GST_DEBUG_PAD_NAME (GST_PAD_PEER (srcpad)));
1956 /* we do not emit a warning in this case because unlinking cannot
1957 * be made MT safe.*/
1958 GST_OBJECT_UNLOCK (srcpad);
1959 return GST_PAD_LINK_WAS_LINKED;
1963 GST_CAT_INFO (GST_CAT_PADS, "sink %s:%s was already linked to %s:%s",
1964 GST_DEBUG_PAD_NAME (sinkpad),
1965 GST_DEBUG_PAD_NAME (GST_PAD_PEER (sinkpad)));
1966 /* we do not emit a warning in this case because unlinking cannot
1967 * be made MT safe.*/
1968 GST_OBJECT_UNLOCK (sinkpad);
1969 GST_OBJECT_UNLOCK (srcpad);
1970 return GST_PAD_LINK_WAS_LINKED;
1974 GST_CAT_INFO (GST_CAT_PADS, "pads have wrong hierarchy");
1975 GST_OBJECT_UNLOCK (sinkpad);
1976 GST_OBJECT_UNLOCK (srcpad);
1977 return GST_PAD_LINK_WRONG_HIERARCHY;
1981 GST_CAT_INFO (GST_CAT_PADS, "caps are incompatible");
1982 GST_OBJECT_UNLOCK (sinkpad);
1983 GST_OBJECT_UNLOCK (srcpad);
1984 return GST_PAD_LINK_NOFORMAT;
1990 * @srcpad: the source #GstPad.
1991 * @sinkpad: the sink #GstPad.
1993 * Checks if the source pad and the sink pad are compatible so they can be
1996 * Returns: TRUE if the pads can be linked.
1999 gst_pad_can_link (GstPad * srcpad, GstPad * sinkpad)
2001 GstPadLinkReturn result;
2003 /* generic checks */
2004 g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
2005 g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
2007 GST_CAT_INFO (GST_CAT_PADS, "check if %s:%s can link with %s:%s",
2008 GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
2010 /* gst_pad_link_prepare does everything for us, we only release the locks
2011 * on the pads that it gets us. If this function returns !OK the locks are not
2013 result = gst_pad_link_prepare (srcpad, sinkpad, GST_PAD_LINK_CHECK_DEFAULT);
2014 if (result != GST_PAD_LINK_OK)
2017 GST_OBJECT_UNLOCK (srcpad);
2018 GST_OBJECT_UNLOCK (sinkpad);
2021 return result == GST_PAD_LINK_OK;
2025 * gst_pad_link_full:
2026 * @srcpad: the source #GstPad to link.
2027 * @sinkpad: the sink #GstPad to link.
2028 * @flags: the checks to validate when linking
2030 * Links the source pad and the sink pad.
2032 * This variant of #gst_pad_link provides a more granular control on the
2033 * checks being done when linking. While providing some considerable speedups
2034 * the caller of this method must be aware that wrong usage of those flags
2035 * can cause severe issues. Refer to the documentation of #GstPadLinkCheck
2036 * for more information.
2040 * Returns: A result code indicating if the connection worked or
2046 gst_pad_link_full (GstPad * srcpad, GstPad * sinkpad, GstPadLinkCheck flags)
2048 GstPadLinkReturn result;
2051 g_return_val_if_fail (GST_IS_PAD (srcpad), GST_PAD_LINK_REFUSED);
2052 g_return_val_if_fail (GST_PAD_IS_SRC (srcpad), GST_PAD_LINK_WRONG_DIRECTION);
2053 g_return_val_if_fail (GST_IS_PAD (sinkpad), GST_PAD_LINK_REFUSED);
2054 g_return_val_if_fail (GST_PAD_IS_SINK (sinkpad),
2055 GST_PAD_LINK_WRONG_DIRECTION);
2057 /* Notify the parent early. See gst_pad_unlink for details. */
2058 if ((parent = GST_ELEMENT_CAST (gst_pad_get_parent (srcpad)))) {
2059 if (GST_IS_ELEMENT (parent)) {
2060 gst_element_post_message (parent,
2061 gst_message_new_structure_change (GST_OBJECT_CAST (sinkpad),
2062 GST_STRUCTURE_CHANGE_TYPE_PAD_LINK, parent, TRUE));
2064 gst_object_unref (parent);
2069 /* prepare will also lock the two pads */
2070 result = gst_pad_link_prepare (srcpad, sinkpad, flags);
2072 if (result != GST_PAD_LINK_OK)
2075 /* must set peers before calling the link function */
2076 GST_PAD_PEER (srcpad) = sinkpad;
2077 GST_PAD_PEER (sinkpad) = srcpad;
2079 /* make sure we push the events from the source to this new peer, for this we
2080 * copy the events on the sinkpad and mark EVENTS_PENDING */
2081 if (replace_events (srcpad->priv->events, sinkpad->priv->events))
2082 GST_OBJECT_FLAG_SET (sinkpad, GST_PAD_NEED_EVENTS);
2084 GST_OBJECT_UNLOCK (sinkpad);
2085 GST_OBJECT_UNLOCK (srcpad);
2087 /* FIXME released the locks here, concurrent thread might link
2088 * something else. */
2089 if (GST_PAD_LINKFUNC (srcpad)) {
2090 /* this one will call the peer link function */
2091 result = GST_PAD_LINKFUNC (srcpad) (srcpad, sinkpad);
2092 } else if (GST_PAD_LINKFUNC (sinkpad)) {
2093 /* if no source link function, we need to call the sink link
2094 * function ourselves. */
2095 result = GST_PAD_LINKFUNC (sinkpad) (sinkpad, srcpad);
2097 result = GST_PAD_LINK_OK;
2100 GST_OBJECT_LOCK (srcpad);
2101 GST_OBJECT_LOCK (sinkpad);
2103 if (result == GST_PAD_LINK_OK) {
2104 GST_OBJECT_UNLOCK (sinkpad);
2105 GST_OBJECT_UNLOCK (srcpad);
2107 /* fire off a signal to each of the pads telling them
2108 * that they've been linked */
2109 g_signal_emit (srcpad, gst_pad_signals[PAD_LINKED], 0, sinkpad);
2110 g_signal_emit (sinkpad, gst_pad_signals[PAD_LINKED], 0, srcpad);
2112 GST_CAT_INFO (GST_CAT_PADS, "linked %s:%s and %s:%s, successful",
2113 GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
2115 gst_pad_send_event (srcpad, gst_event_new_reconfigure ());
2117 GST_CAT_INFO (GST_CAT_PADS, "link between %s:%s and %s:%s failed",
2118 GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
2120 GST_PAD_PEER (srcpad) = NULL;
2121 GST_PAD_PEER (sinkpad) = NULL;
2123 GST_OBJECT_UNLOCK (sinkpad);
2124 GST_OBJECT_UNLOCK (srcpad);
2129 gst_element_post_message (parent,
2130 gst_message_new_structure_change (GST_OBJECT_CAST (sinkpad),
2131 GST_STRUCTURE_CHANGE_TYPE_PAD_LINK, parent, FALSE));
2132 gst_object_unref (parent);
2140 * @srcpad: the source #GstPad to link.
2141 * @sinkpad: the sink #GstPad to link.
2143 * Links the source pad and the sink pad.
2145 * Returns: A result code indicating if the connection worked or
2151 gst_pad_link (GstPad * srcpad, GstPad * sinkpad)
2153 return gst_pad_link_full (srcpad, sinkpad, GST_PAD_LINK_CHECK_DEFAULT);
2157 gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ)
2159 GstPadTemplate **template_p;
2161 /* this function would need checks if it weren't static */
2163 GST_OBJECT_LOCK (pad);
2164 template_p = &pad->padtemplate;
2165 gst_object_replace ((GstObject **) template_p, (GstObject *) templ);
2166 GST_OBJECT_UNLOCK (pad);
2169 gst_pad_template_pad_created (templ, pad);
2173 * gst_pad_get_pad_template:
2176 * Gets the template for @pad.
2178 * Returns: (transfer full): the #GstPadTemplate from which this pad was
2179 * instantiated, or %NULL if this pad has no template. Unref after
2183 gst_pad_get_pad_template (GstPad * pad)
2185 GstPadTemplate *templ;
2187 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2189 templ = GST_PAD_PAD_TEMPLATE (pad);
2191 return (templ ? gst_object_ref (templ) : NULL);
2194 /* should be called with the pad LOCK held */
2195 /* refs the caps, so caller is responsible for getting it unreffed */
2197 gst_pad_get_caps_unlocked (GstPad * pad, GstCaps * filter)
2199 GstCaps *result = NULL;
2200 GstPadTemplate *templ;
2201 gboolean fixed_caps;
2203 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get pad caps");
2205 fixed_caps = GST_PAD_IS_FIXED_CAPS (pad);
2207 if (!fixed_caps && GST_PAD_GETCAPSFUNC (pad)) {
2208 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2209 "dispatching to pad getcaps function with "
2210 "filter %" GST_PTR_FORMAT, filter);
2212 GST_OBJECT_FLAG_SET (pad, GST_PAD_IN_GETCAPS);
2213 GST_OBJECT_UNLOCK (pad);
2214 result = GST_PAD_GETCAPSFUNC (pad) (pad, filter);
2215 GST_OBJECT_LOCK (pad);
2216 GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_GETCAPS);
2218 if (result == NULL) {
2219 g_critical ("pad %s:%s returned NULL caps from getcaps function",
2220 GST_DEBUG_PAD_NAME (pad));
2222 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2223 "pad getcaps returned %" GST_PTR_FORMAT, result);
2224 #ifndef G_DISABLE_ASSERT
2225 /* check that the returned caps are a real subset of the template caps */
2226 if (GST_PAD_PAD_TEMPLATE (pad)) {
2227 const GstCaps *templ_caps =
2228 GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad));
2229 if (!gst_caps_is_subset (result, templ_caps)) {
2232 GST_CAT_ERROR_OBJECT (GST_CAT_CAPS, pad,
2233 "pad returned caps %" GST_PTR_FORMAT
2234 " which are not a real subset of its template caps %"
2235 GST_PTR_FORMAT, result, templ_caps);
2237 ("pad %s:%s returned caps which are not a real "
2238 "subset of its template caps", GST_DEBUG_PAD_NAME (pad));
2239 temp = gst_caps_intersect (templ_caps, result);
2240 gst_caps_unref (result);
2245 if (!gst_caps_is_subset (result, filter)) {
2248 GST_CAT_ERROR_OBJECT (GST_CAT_CAPS, pad,
2249 "pad returned caps %" GST_PTR_FORMAT
2250 " which are not a real subset of the filter caps %"
2251 GST_PTR_FORMAT, result, filter);
2252 g_warning ("pad %s:%s returned caps which are not a real "
2253 "subset of the filter caps", GST_DEBUG_PAD_NAME (pad));
2254 /* FIXME: Order? But shouldn't happen anyway... */
2256 gst_caps_intersect_full (filter, result,
2257 GST_CAPS_INTERSECT_FIRST);
2258 gst_caps_unref (result);
2266 if (fixed_caps && (result = get_pad_caps (pad))) {
2268 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2269 "using pad caps %p %" GST_PTR_FORMAT " with filter %p %"
2270 GST_PTR_FORMAT, result, result, filter, filter);
2272 gst_caps_intersect_full (filter, result, GST_CAPS_INTERSECT_FIRST);
2273 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "result %p %" GST_PTR_FORMAT,
2276 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2277 "using pad caps %p %" GST_PTR_FORMAT, result, result);
2278 result = gst_caps_ref (result);
2282 if ((templ = GST_PAD_PAD_TEMPLATE (pad))) {
2283 result = GST_PAD_TEMPLATE_CAPS (templ);
2286 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2287 "using pad template %p with caps %p %" GST_PTR_FORMAT
2288 " and filter %p %" GST_PTR_FORMAT, templ, result, result, filter,
2291 gst_caps_intersect_full (filter, result, GST_CAPS_INTERSECT_FIRST);
2292 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "result %p %" GST_PTR_FORMAT,
2295 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2296 "using pad template %p with caps %p %" GST_PTR_FORMAT, templ, result,
2298 result = gst_caps_ref (result);
2303 if (!fixed_caps && (result = get_pad_caps (pad))) {
2305 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2306 "using pad caps %p %" GST_PTR_FORMAT " with filter %p %"
2307 GST_PTR_FORMAT, result, result, filter, filter);
2309 gst_caps_intersect_full (filter, result, GST_CAPS_INTERSECT_FIRST);
2310 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "result %p %" GST_PTR_FORMAT,
2313 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2314 "using pad caps %p %" GST_PTR_FORMAT, result, result);
2315 result = gst_caps_ref (result);
2321 /* this almost never happens */
2322 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "pad has no caps");
2323 result = gst_caps_new_empty ();
2330 * gst_pad_has_current_caps:
2331 * @pad: a #GstPad to check
2333 * Check if @pad has caps set on it with gst_pad_set_caps().
2335 * Returns: TRUE when @pad has caps associated with it.
2338 gst_pad_has_current_caps (GstPad * pad)
2342 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2344 GST_OBJECT_LOCK (pad);
2345 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "check current pad caps");
2346 result = (get_pad_caps (pad) != NULL);
2347 GST_OBJECT_UNLOCK (pad);
2353 * gst_pad_get_current_caps:
2354 * @pad: a #GstPad to get the current capabilities of.
2356 * Gets the capabilities currently configured on @pad with the last call to
2357 * gst_pad_set_caps().
2359 * Returns: the current caps of the pad with incremented ref-count.
2362 gst_pad_get_current_caps (GstPad * pad)
2366 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2368 GST_OBJECT_LOCK (pad);
2369 if ((result = get_pad_caps (pad)))
2370 gst_caps_ref (result);
2371 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2372 "get current pad caps %" GST_PTR_FORMAT, result);
2373 GST_OBJECT_UNLOCK (pad);
2380 * @pad: a #GstPad to get the capabilities of.
2381 * @filter: suggested #GstCaps.
2383 * Gets the capabilities this pad can produce or consume.
2384 * Note that this method doesn't necessarily return the caps set by
2385 * gst_pad_set_caps() - use gst_pad_get_current_caps() for that instead.
2386 * gst_pad_get_caps returns all possible caps a pad can operate with, using
2387 * the pad's get_caps function;
2388 * this returns the pad template caps if not explicitly set.
2390 * When called on sinkpads @filter contains the caps that
2391 * upstream could produce in the order preferred by upstream. When
2392 * called on srcpads @filter contains the caps accepted by
2393 * downstream in the preffered order. @filter might be %NULL but
2394 * if it is not %NULL the returned caps will be a subset of @filter.
2396 * Note that this function does not return writable #GstCaps, use
2397 * gst_caps_make_writable() before modifying the caps.
2399 * Returns: the caps of the pad with incremented ref-count.
2402 gst_pad_get_caps (GstPad * pad, GstCaps * filter)
2404 GstCaps *result = NULL;
2406 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2407 g_return_val_if_fail (filter == NULL || GST_IS_CAPS (filter), NULL);
2409 GST_OBJECT_LOCK (pad);
2411 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get pad caps");
2413 result = gst_pad_get_caps_unlocked (pad, filter);
2415 GST_OBJECT_UNLOCK (pad);
2422 * gst_pad_peer_get_caps:
2423 * @pad: a #GstPad to get the capabilities of.
2424 * @filter: a #GstCaps filter.
2426 * Gets the capabilities of the peer connected to this pad. Similar to
2427 * gst_pad_get_caps().
2429 * When called on srcpads @filter contains the caps that
2430 * upstream could produce in the order preferred by upstream. When
2431 * called on sinkpads @filter contains the caps accepted by
2432 * downstream in the preffered order. @filter might be %NULL but
2433 * if it is not %NULL the returned caps will be a subset of @filter.
2435 * Returns: the caps of the peer pad with incremented ref-count. This function
2436 * returns %NULL when there is no peer pad.
2439 gst_pad_peer_get_caps (GstPad * pad, GstCaps * filter)
2442 GstCaps *result = NULL;
2444 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2445 g_return_val_if_fail (filter == NULL || GST_IS_CAPS (filter), NULL);
2447 GST_OBJECT_LOCK (pad);
2449 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get peer caps");
2451 peerpad = GST_PAD_PEER (pad);
2452 if (G_UNLIKELY (peerpad == NULL))
2455 gst_object_ref (peerpad);
2456 GST_OBJECT_UNLOCK (pad);
2458 result = gst_pad_get_caps (peerpad, filter);
2460 gst_object_unref (peerpad);
2466 GST_OBJECT_UNLOCK (pad);
2472 fixate_value (GValue * dest, const GValue * src)
2474 if (G_VALUE_TYPE (src) == GST_TYPE_INT_RANGE) {
2475 g_value_init (dest, G_TYPE_INT);
2476 g_value_set_int (dest, gst_value_get_int_range_min (src));
2477 } else if (G_VALUE_TYPE (src) == GST_TYPE_DOUBLE_RANGE) {
2478 g_value_init (dest, G_TYPE_DOUBLE);
2479 g_value_set_double (dest, gst_value_get_double_range_min (src));
2480 } else if (G_VALUE_TYPE (src) == GST_TYPE_FRACTION_RANGE) {
2481 gst_value_init_and_copy (dest, gst_value_get_fraction_range_min (src));
2482 } else if (G_VALUE_TYPE (src) == GST_TYPE_LIST) {
2483 GValue temp = { 0 };
2485 /* list could be empty */
2486 if (gst_value_list_get_size (src) <= 0)
2489 gst_value_init_and_copy (&temp, gst_value_list_get_value (src, 0));
2491 if (!fixate_value (dest, &temp))
2492 gst_value_init_and_copy (dest, &temp);
2493 g_value_unset (&temp);
2494 } else if (G_VALUE_TYPE (src) == GST_TYPE_ARRAY) {
2495 gboolean res = FALSE;
2498 len = gst_value_array_get_size (src);
2499 g_value_init (dest, GST_TYPE_ARRAY);
2500 for (n = 0; n < len; n++) {
2502 const GValue *orig_kid = gst_value_array_get_value (src, n);
2504 if (!fixate_value (&kid, orig_kid))
2505 gst_value_init_and_copy (&kid, orig_kid);
2508 gst_value_array_append_value (dest, &kid);
2509 g_value_unset (&kid);
2513 g_value_unset (dest);
2524 gst_pad_default_fixate (GQuark field_id, const GValue * value, gpointer data)
2526 GstStructure *s = data;
2529 if (fixate_value (&v, value)) {
2530 gst_structure_id_set_value (s, field_id, &v);
2538 * gst_pad_fixate_caps:
2539 * @pad: a #GstPad to fixate
2540 * @caps: the #GstCaps to fixate
2542 * Fixate a caps on the given pad. Modifies the caps in place, so you should
2543 * make sure that the caps are actually writable (see gst_caps_make_writable()).
2546 gst_pad_fixate_caps (GstPad * pad, GstCaps * caps)
2548 GstPadFixateCapsFunction fixatefunc;
2551 g_return_if_fail (GST_IS_PAD (pad));
2552 g_return_if_fail (caps != NULL);
2553 g_return_if_fail (!gst_caps_is_empty (caps));
2554 g_return_if_fail (!gst_caps_is_any (caps));
2556 if (gst_caps_is_fixed (caps) || gst_caps_is_any (caps))
2559 fixatefunc = GST_PAD_FIXATECAPSFUNC (pad);
2561 fixatefunc (pad, caps);
2564 /* default fixation */
2565 gst_caps_truncate (caps);
2566 s = gst_caps_get_structure (caps, 0);
2567 gst_structure_foreach (s, gst_pad_default_fixate, s);
2570 /* Default accept caps implementation just checks against
2571 * against the allowed caps for the pad */
2573 gst_pad_acceptcaps_default (GstPad * pad, GstCaps * caps)
2575 /* get the caps and see if it intersects to something not empty */
2577 gboolean result = FALSE;
2579 GST_DEBUG_OBJECT (pad, "caps %" GST_PTR_FORMAT, caps);
2581 allowed = gst_pad_get_caps (pad, NULL);
2583 goto nothing_allowed;
2585 GST_DEBUG_OBJECT (pad, "allowed caps %" GST_PTR_FORMAT, allowed);
2587 result = gst_caps_can_intersect (allowed, caps);
2589 gst_caps_unref (allowed);
2596 GST_DEBUG_OBJECT (pad, "no caps allowed on the pad");
2602 * gst_pad_accept_caps:
2603 * @pad: a #GstPad to check
2604 * @caps: a #GstCaps to check on the pad
2606 * Check if the given pad accepts the caps.
2608 * Returns: TRUE if the pad can accept the caps.
2611 gst_pad_accept_caps (GstPad * pad, GstCaps * caps)
2614 GstPadAcceptCapsFunction acceptfunc;
2616 GstCaps *existing = NULL;
2619 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2621 /* any pad can be unnegotiated */
2625 /* lock for checking the existing caps */
2626 GST_OBJECT_LOCK (pad);
2627 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "accept caps of %p", caps);
2629 /* The current caps on a pad are trivially acceptable */
2630 if (G_LIKELY ((existing = GST_PAD_CAPS (pad)))) {
2631 if (caps == existing || gst_caps_is_equal (caps, existing))
2635 acceptfunc = GST_PAD_ACCEPTCAPSFUNC (pad);
2636 GST_OBJECT_UNLOCK (pad);
2638 if (G_LIKELY (acceptfunc)) {
2639 /* we can call the function */
2640 result = acceptfunc (pad, caps);
2641 GST_DEBUG_OBJECT (pad, "acceptfunc returned %d", result);
2643 /* Only null if the element explicitly unset it */
2644 result = gst_pad_acceptcaps_default (pad, caps);
2645 GST_DEBUG_OBJECT (pad, "default acceptcaps returned %d", result);
2652 GST_DEBUG_OBJECT (pad, "pad had same caps");
2653 GST_OBJECT_UNLOCK (pad);
2660 * gst_pad_peer_accept_caps:
2661 * @pad: a #GstPad to check the peer of
2662 * @caps: a #GstCaps to check on the pad
2664 * Check if the peer of @pad accepts @caps. If @pad has no peer, this function
2667 * Returns: TRUE if the peer of @pad can accept the caps or @pad has no peer.
2670 gst_pad_peer_accept_caps (GstPad * pad, GstCaps * caps)
2675 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2677 GST_OBJECT_LOCK (pad);
2679 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "peer accept caps of (%p)", pad);
2681 peerpad = GST_PAD_PEER (pad);
2682 if (G_UNLIKELY (peerpad == NULL))
2685 gst_object_ref (peerpad);
2686 /* release lock before calling external methods but keep ref to pad */
2687 GST_OBJECT_UNLOCK (pad);
2689 result = gst_pad_accept_caps (peerpad, caps);
2691 gst_object_unref (peerpad);
2697 GST_OBJECT_UNLOCK (pad);
2704 * @pad: a #GstPad to set the capabilities of.
2705 * @caps: (transfer none): a #GstCaps to set.
2707 * Sets the capabilities of this pad. The caps must be fixed. Any previous
2708 * caps on the pad will be unreffed. This function refs the caps so you should
2709 * unref if as soon as you don't need it anymore.
2710 * It is possible to set NULL caps, which will make the pad unnegotiated
2713 * Returns: TRUE if the caps could be set. FALSE if the caps were not fixed
2714 * or bad parameters were provided to this function.
2719 gst_pad_set_caps (GstPad * pad, GstCaps * caps)
2722 gboolean res = TRUE;
2724 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2725 g_return_val_if_fail (caps != NULL && gst_caps_is_fixed (caps), FALSE);
2727 event = gst_event_new_caps (caps);
2729 if (GST_PAD_IS_SRC (pad))
2730 gst_pad_push_event (pad, event);
2732 res = gst_pad_send_event (pad, event);
2738 gst_pad_call_setcaps (GstPad * pad, GstCaps * caps)
2740 GstPadSetCapsFunction setcaps;
2742 GST_OBJECT_LOCK (pad);
2743 setcaps = GST_PAD_SETCAPSFUNC (pad);
2745 /* call setcaps function to configure the pad only if the
2746 * caps is not NULL */
2747 if (setcaps != NULL) {
2748 if (!GST_PAD_IS_IN_SETCAPS (pad)) {
2749 GST_OBJECT_FLAG_SET (pad, GST_PAD_IN_SETCAPS);
2750 GST_OBJECT_UNLOCK (pad);
2751 if (!setcaps (pad, caps))
2752 goto setcaps_failed;
2753 GST_OBJECT_LOCK (pad);
2754 GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_SETCAPS);
2756 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "pad was dispatching");
2759 GST_OBJECT_UNLOCK (pad);
2761 g_object_notify_by_pspec ((GObject *) pad, pspec_caps);
2773 do_event_function (GstPad * pad, GstEvent * event,
2774 GstPadEventFunction eventfunc)
2776 gboolean result = TRUE;
2777 GstCaps *caps, *templ;
2779 switch (GST_EVENT_TYPE (event)) {
2780 case GST_EVENT_CAPS:
2782 /* backwards compatibility mode for caps */
2783 gst_event_parse_caps (event, &caps);
2785 /* See if pad accepts the caps */
2786 templ = gst_pad_get_pad_template_caps (pad);
2787 if (!gst_caps_can_intersect (caps, templ))
2790 if (!gst_pad_call_setcaps (pad, caps))
2793 gst_caps_unref (templ);
2800 GST_DEBUG_OBJECT (pad, "calling event function with event %p", event);
2801 result = eventfunc (pad, event);
2808 gst_caps_unref (templ);
2809 gst_event_unref (event);
2810 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2811 "caps %" GST_PTR_FORMAT " not accepted", caps);
2816 /* function to send all inactive events on the sinkpad to the event
2817 * function and collect the results. This function should be called with
2818 * the object lock. The object lock might be released by this function.
2820 static GstFlowReturn
2821 gst_pad_update_events (GstPad * pad)
2823 GstFlowReturn ret = GST_FLOW_OK;
2825 GstPadEventFunction eventfunc;
2828 if (G_UNLIKELY ((eventfunc = GST_PAD_EVENTFUNC (pad)) == NULL))
2832 for (i = 0; i < GST_EVENT_MAX_STICKY; i++) {
2833 /* skip already active events */
2834 if (pad->priv->events[i].active)
2837 if ((event = pad->priv->events[i].event)) {
2840 gst_event_ref (event);
2841 GST_OBJECT_UNLOCK (pad);
2843 res = do_event_function (pad, event, eventfunc);
2845 GST_OBJECT_LOCK (pad);
2846 /* things could have changed while we release the lock, check if we still
2847 * are handling the same event, if we don't something changed and we have
2848 * to try again. FIXME. we need a cookie here. */
2849 if (event != pad->priv->events[i].event) {
2850 GST_DEBUG_OBJECT (pad, "events changed, restarting");
2854 pad->priv->events[i].active = res;
2855 /* remove the event when the event function did not accept it */
2857 gst_event_replace (&pad->priv->events[i].event, NULL);
2858 ret = GST_FLOW_ERROR;
2862 /* when we get here all events were successfully updated. */
2869 g_warning ("pad %s:%s has no event handler, file a bug.",
2870 GST_DEBUG_PAD_NAME (pad));
2871 return GST_FLOW_NOT_SUPPORTED;
2876 * gst_pad_get_pad_template_caps:
2877 * @pad: a #GstPad to get the template capabilities from.
2879 * Gets the capabilities for @pad's template.
2881 * Returns: (transfer full): the #GstCaps of this pad template.
2882 * Unref after usage.
2885 gst_pad_get_pad_template_caps (GstPad * pad)
2887 static GstStaticCaps anycaps = GST_STATIC_CAPS ("ANY");
2889 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2891 if (GST_PAD_PAD_TEMPLATE (pad))
2892 return gst_pad_template_get_caps (GST_PAD_PAD_TEMPLATE (pad));
2894 return gst_static_caps_get (&anycaps);
2899 * @pad: a #GstPad to get the peer of.
2901 * Gets the peer of @pad. This function refs the peer pad so
2902 * you need to unref it after use.
2904 * Returns: (transfer full): the peer #GstPad. Unref after usage.
2909 gst_pad_get_peer (GstPad * pad)
2913 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2915 GST_OBJECT_LOCK (pad);
2916 result = GST_PAD_PEER (pad);
2918 gst_object_ref (result);
2919 GST_OBJECT_UNLOCK (pad);
2925 * gst_pad_get_allowed_caps:
2928 * Gets the capabilities of the allowed media types that can flow through
2929 * @pad and its peer.
2931 * The allowed capabilities is calculated as the intersection of the results of
2932 * calling gst_pad_get_caps() on @pad and its peer. The caller owns a reference
2933 * on the resulting caps.
2935 * Returns: (transfer full): the allowed #GstCaps of the pad link. Unref the
2936 * caps when you no longer need it. This function returns NULL when @pad
2942 gst_pad_get_allowed_caps (GstPad * pad)
2949 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2951 GST_OBJECT_LOCK (pad);
2952 peer = GST_PAD_PEER (pad);
2953 if (G_UNLIKELY (peer == NULL))
2956 GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "getting allowed caps");
2958 gst_object_ref (peer);
2959 GST_OBJECT_UNLOCK (pad);
2960 mycaps = gst_pad_get_caps (pad, NULL);
2962 peercaps = gst_pad_get_caps (peer, NULL);
2963 gst_object_unref (peer);
2965 caps = gst_caps_intersect (mycaps, peercaps);
2966 gst_caps_unref (peercaps);
2967 gst_caps_unref (mycaps);
2969 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "allowed caps %" GST_PTR_FORMAT,
2976 GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "no peer");
2977 GST_OBJECT_UNLOCK (pad);
2984 * gst_pad_get_negotiated_caps:
2987 * Gets the capabilities of the media type that currently flows through @pad
2990 * This function can be used on both src and sinkpads. Note that srcpads are
2991 * always negotiated before sinkpads so it is possible that the negotiated caps
2992 * on the srcpad do not match the negotiated caps of the peer.
2994 * Returns: (transfer full): the negotiated #GstCaps of the pad link. Unref
2995 * the caps when you no longer need it. This function returns NULL when
2996 * the @pad has no peer or is not negotiated yet.
3001 gst_pad_get_negotiated_caps (GstPad * pad)
3003 GstCaps *caps = NULL;
3006 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
3008 GST_OBJECT_LOCK (pad);
3010 if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
3013 GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "getting negotiated caps");
3015 if ((caps = get_pad_caps (pad)))
3016 gst_caps_ref (caps);
3018 GST_OBJECT_UNLOCK (pad);
3020 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "negotiated caps %" GST_PTR_FORMAT,
3027 GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "no peer");
3028 GST_OBJECT_UNLOCK (pad);
3034 * gst_pad_iterate_internal_links_default:
3035 * @pad: the #GstPad to get the internal links of.
3037 * Iterate the list of pads to which the given pad is linked to inside of
3038 * the parent element.
3039 * This is the default handler, and thus returns an iterator of all of the
3040 * pads inside the parent element with opposite direction.
3042 * The caller must free this iterator after use with gst_iterator_free().
3044 * Returns: a #GstIterator of #GstPad, or NULL if @pad has no parent. Unref each
3045 * returned pad with gst_object_unref().
3050 gst_pad_iterate_internal_links_default (GstPad * pad)
3058 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
3063 GST_OBJECT_LOCK (pad);
3064 parent = GST_PAD_PARENT (pad);
3065 if (!parent || !GST_IS_ELEMENT (parent))
3068 gst_object_ref (parent);
3069 GST_OBJECT_UNLOCK (pad);
3071 if (pad->direction == GST_PAD_SRC)
3072 padlist = &parent->sinkpads;
3074 padlist = &parent->srcpads;
3076 GST_DEBUG_OBJECT (pad, "Making iterator");
3078 cookie = &parent->pads_cookie;
3080 lock = GST_OBJECT_GET_LOCK (parent);
3083 res = gst_iterator_new_list (GST_TYPE_PAD,
3084 lock, cookie, padlist, (GObject *) owner, NULL);
3086 gst_object_unref (owner);
3093 GST_OBJECT_UNLOCK (pad);
3094 GST_DEBUG_OBJECT (pad, "no parent element");
3100 * gst_pad_iterate_internal_links:
3101 * @pad: the GstPad to get the internal links of.
3103 * Gets an iterator for the pads to which the given pad is linked to inside
3104 * of the parent element.
3106 * Each #GstPad element yielded by the iterator will have its refcount increased,
3107 * so unref after use.
3109 * Free-function: gst_iterator_free
3111 * Returns: (transfer full): a new #GstIterator of #GstPad or %NULL when the
3112 * pad does not have an iterator function configured. Use
3113 * gst_iterator_free() after usage.
3118 gst_pad_iterate_internal_links (GstPad * pad)
3120 GstIterator *res = NULL;
3122 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
3124 if (GST_PAD_ITERINTLINKFUNC (pad))
3125 res = GST_PAD_ITERINTLINKFUNC (pad) (pad);
3131 gst_pad_event_default_dispatch (GstPad * pad, GstEvent * event)
3133 gboolean result = FALSE;
3135 gboolean done = FALSE;
3136 GValue item = { 0, };
3138 GList *pushed_pads = NULL;
3140 GST_INFO_OBJECT (pad, "Sending event %p (%s) to all internally linked pads",
3141 event, GST_EVENT_TYPE_NAME (event));
3143 iter = gst_pad_iterate_internal_links (pad);
3149 switch (gst_iterator_next (iter, &item)) {
3150 case GST_ITERATOR_OK:
3151 eventpad = g_value_get_object (&item);
3153 /* if already pushed, skip */
3154 if (g_list_find (pushed_pads, eventpad)) {
3155 g_value_reset (&item);
3159 if (GST_PAD_IS_SRC (eventpad)) {
3160 /* for each pad we send to, we should ref the event; it's up
3161 * to downstream to unref again when handled. */
3162 GST_LOG_OBJECT (pad, "Reffing and sending event %p (%s) to %s:%s",
3163 event, GST_EVENT_TYPE_NAME (event),
3164 GST_DEBUG_PAD_NAME (eventpad));
3165 gst_event_ref (event);
3166 result |= gst_pad_push_event (eventpad, event);
3168 /* we only send the event on one pad, multi-sinkpad elements
3169 * should implement a handler */
3170 GST_LOG_OBJECT (pad, "sending event %p (%s) to one sink pad %s:%s",
3171 event, GST_EVENT_TYPE_NAME (event),
3172 GST_DEBUG_PAD_NAME (eventpad));
3173 result = gst_pad_push_event (eventpad, event);
3178 pushed_pads = g_list_prepend (pushed_pads, eventpad);
3180 g_value_reset (&item);
3182 case GST_ITERATOR_RESYNC:
3183 /* We don't reset the result here because we don't push the event
3184 * again on pads that got the event already and because we need
3185 * to consider the result of the previous pushes */
3186 gst_iterator_resync (iter);
3188 case GST_ITERATOR_ERROR:
3189 GST_ERROR_OBJECT (pad, "Could not iterate over internally linked pads");
3192 case GST_ITERATOR_DONE:
3197 g_value_unset (&item);
3198 gst_iterator_free (iter);
3202 /* If this is a sinkpad and we don't have pads to send the event to, we
3203 * return TRUE. This is so that when using the default handler on a sink
3204 * element, we don't fail to push it. */
3206 result = GST_PAD_IS_SINK (pad);
3208 g_list_free (pushed_pads);
3210 /* we handled the incoming event so we unref once */
3212 GST_LOG_OBJECT (pad, "handled event %p, unreffing", event);
3213 gst_event_unref (event);
3220 * gst_pad_event_default:
3221 * @pad: a #GstPad to call the default event handler on.
3222 * @event: (transfer full): the #GstEvent to handle.
3224 * Invokes the default event handler for the given pad. End-of-stream and
3225 * discontinuity events are handled specially, and then the event is sent to all
3226 * pads internally linked to @pad. Note that if there are many possible sink
3227 * pads that are internally linked to @pad, only one will be sent an event.
3228 * Multi-sinkpad elements should implement custom event handlers.
3230 * Returns: TRUE if the event was sent succesfully.
3233 gst_pad_event_default (GstPad * pad, GstEvent * event)
3235 gboolean result = TRUE, forward = TRUE;
3237 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3238 g_return_val_if_fail (event != NULL, FALSE);
3240 GST_LOG_OBJECT (pad, "default event handler");
3242 switch (GST_EVENT_TYPE (event)) {
3245 GST_DEBUG_OBJECT (pad, "pausing task because of eos");
3246 gst_pad_pause_task (pad);
3249 case GST_EVENT_CAPS:
3251 /* don't forward by default */
3260 result = gst_pad_event_default_dispatch (pad, event);
3262 gst_event_unref (event);
3268 * gst_pad_dispatcher:
3269 * @pad: a #GstPad to dispatch.
3270 * @dispatch: the #GstPadDispatcherFunction to call.
3271 * @data: (closure): gpointer user data passed to the dispatcher function.
3273 * Invokes the given dispatcher function on each respective peer of
3274 * all pads that are internally linked to the given pad.
3275 * The GstPadDispatcherFunction should return TRUE when no further pads
3276 * need to be processed.
3278 * Returns: TRUE if one of the dispatcher functions returned TRUE.
3281 gst_pad_dispatcher (GstPad * pad, GstPadDispatcherFunction dispatch,
3284 gboolean res = FALSE;
3285 GstIterator *iter = NULL;
3286 gboolean done = FALSE;
3287 GValue item = { 0, };
3289 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3290 g_return_val_if_fail (dispatch != NULL, FALSE);
3292 iter = gst_pad_iterate_internal_links (pad);
3298 switch (gst_iterator_next (iter, &item)) {
3299 case GST_ITERATOR_OK:
3301 GstPad *int_pad = g_value_get_object (&item);
3302 GstPad *int_peer = gst_pad_get_peer (int_pad);
3305 GST_DEBUG_OBJECT (int_pad, "dispatching to peer %s:%s",
3306 GST_DEBUG_PAD_NAME (int_peer));
3307 done = res = dispatch (int_peer, data);
3308 gst_object_unref (int_peer);
3310 GST_DEBUG_OBJECT (int_pad, "no peer");
3312 g_value_reset (&item);
3315 case GST_ITERATOR_RESYNC:
3316 gst_iterator_resync (iter);
3318 case GST_ITERATOR_ERROR:
3320 GST_ERROR_OBJECT (pad, "Could not iterate internally linked pads");
3322 case GST_ITERATOR_DONE:
3327 g_value_unset (&item);
3328 gst_iterator_free (iter);
3330 GST_DEBUG_OBJECT (pad, "done, result %d", res);
3339 * @pad: a #GstPad to invoke the default query on.
3340 * @query: (transfer none): the #GstQuery to perform.
3342 * Dispatches a query to a pad. The query should have been allocated by the
3343 * caller via one of the type-specific allocation functions. The element that
3344 * the pad belongs to is responsible for filling the query with an appropriate
3345 * response, which should then be parsed with a type-specific query parsing
3348 * Again, the caller is responsible for both the allocation and deallocation of
3349 * the query structure.
3351 * Please also note that some queries might need a running pipeline to work.
3353 * Returns: TRUE if the query could be performed.
3356 gst_pad_query (GstPad * pad, GstQuery * query)
3358 GstPadQueryFunction func;
3360 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3361 g_return_val_if_fail (GST_IS_QUERY (query), FALSE);
3363 GST_DEBUG_OBJECT (pad, "sending query %p", query);
3365 if ((func = GST_PAD_QUERYFUNC (pad)) == NULL)
3368 return func (pad, query);
3372 GST_DEBUG_OBJECT (pad, "had no query function");
3378 * gst_pad_peer_query:
3379 * @pad: a #GstPad to invoke the peer query on.
3380 * @query: (transfer none): the #GstQuery to perform.
3382 * Performs gst_pad_query() on the peer of @pad.
3384 * The caller is responsible for both the allocation and deallocation of
3385 * the query structure.
3387 * Returns: TRUE if the query could be performed. This function returns %FALSE
3388 * if @pad has no peer.
3393 gst_pad_peer_query (GstPad * pad, GstQuery * query)
3398 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3399 g_return_val_if_fail (GST_IS_QUERY (query), FALSE);
3401 GST_OBJECT_LOCK (pad);
3403 GST_DEBUG_OBJECT (pad, "peer query");
3405 peerpad = GST_PAD_PEER (pad);
3406 if (G_UNLIKELY (peerpad == NULL))
3409 gst_object_ref (peerpad);
3410 GST_OBJECT_UNLOCK (pad);
3412 result = gst_pad_query (peerpad, query);
3414 gst_object_unref (peerpad);
3421 GST_WARNING_OBJECT (pad, "pad has no peer");
3422 GST_OBJECT_UNLOCK (pad);
3428 * gst_pad_query_default:
3429 * @pad: a #GstPad to call the default query handler on.
3430 * @query: (transfer none): the #GstQuery to handle.
3432 * Invokes the default query handler for the given pad.
3433 * The query is sent to all pads internally linked to @pad. Note that
3434 * if there are many possible sink pads that are internally linked to
3435 * @pad, only one will be sent the query.
3436 * Multi-sinkpad elements should implement custom query handlers.
3438 * Returns: TRUE if the query was performed succesfully.
3441 gst_pad_query_default (GstPad * pad, GstQuery * query)
3443 switch (GST_QUERY_TYPE (query)) {
3444 case GST_QUERY_POSITION:
3445 case GST_QUERY_SEEKING:
3446 case GST_QUERY_FORMATS:
3447 case GST_QUERY_LATENCY:
3448 case GST_QUERY_JITTER:
3449 case GST_QUERY_RATE:
3450 case GST_QUERY_CONVERT:
3452 return gst_pad_dispatcher
3453 (pad, (GstPadDispatcherFunction) gst_pad_query, query);
3458 * should be called with pad OBJECT_LOCK and STREAM_LOCK held.
3459 * GST_PAD_IS_BLOCKED (pad) == TRUE when this function is
3462 * This function performs the pad blocking when an event, buffer push
3463 * is performed on a _SRC_ pad. It blocks the streaming thread after
3464 * informing the pad has been blocked.
3466 * An application can with this method wait and block any streaming
3467 * thread and perform operations such as seeking or linking.
3469 * Two methods are available for notifying the application of the
3471 * - the callback method, which happens in the STREAMING thread with
3472 * the STREAM_LOCK held. With this method, the most useful way of
3473 * dealing with the callback is to post a message to the main thread
3474 * where the pad block can then be handled outside of the streaming
3475 * thread. With the last method one can perform all operations such
3476 * as doing a state change, linking, unblocking, seeking etc on the
3478 * - the GCond signal method, which makes any thread unblock when
3479 * the pad block happens.
3481 * During the actual blocking state, the GST_PAD_BLOCKING flag is set.
3482 * The GST_PAD_BLOCKING flag is unset when the pad was unblocked.
3486 static GstFlowReturn
3487 handle_pad_block (GstPad * pad)
3489 GstPadBlockCallback callback;
3491 GstFlowReturn ret = GST_FLOW_OK;
3493 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "signal block taken");
3495 /* flushing, don't bother trying to block and return WRONG_STATE
3497 if (GST_PAD_IS_FLUSHING (pad))
3498 goto flushingnonref;
3500 /* we grab an extra ref for the callbacks, this is probably not
3501 * needed (callback code does not have a ref and cannot unref). I
3502 * think this was done to make it possible to unref the element in
3503 * the callback, which is in the end totally impossible as it
3504 * requires grabbing the STREAM_LOCK and OBJECT_LOCK which are
3505 * all taken when calling this function. */
3506 gst_object_ref (pad);
3508 while (GST_PAD_IS_BLOCKED (pad)) {
3510 /* we either have a callback installed to notify the block or
3511 * some other thread is doing a GCond wait. */
3512 callback = pad->block_callback;
3513 pad->block_callback_called = TRUE;
3515 /* there is a callback installed, call it. We release the
3516 * lock so that the callback can do something usefull with the
3518 user_data = pad->block_data;
3519 GST_OBJECT_UNLOCK (pad);
3520 callback (pad, TRUE, user_data);
3521 GST_OBJECT_LOCK (pad);
3523 /* we released the lock, recheck flushing */
3524 if (GST_PAD_IS_FLUSHING (pad))
3527 /* no callback, signal the thread that is doing a GCond wait
3529 GST_PAD_BLOCK_BROADCAST (pad);
3531 } while (pad->block_callback_called == FALSE && GST_PAD_IS_BLOCKED (pad));
3533 /* OBJECT_LOCK could have been released when we did the callback, which
3534 * then could have made the pad unblock so we need to check the blocking
3535 * condition again. */
3536 if (!GST_PAD_IS_BLOCKED (pad))
3539 /* now we block the streaming thread. It can be unlocked when we
3540 * deactivate the pad (which will also set the FLUSHING flag) or
3541 * when the pad is unblocked. A flushing event will also unblock
3542 * the pad after setting the FLUSHING flag. */
3543 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3544 "Waiting to be unblocked or set flushing");
3545 GST_OBJECT_FLAG_SET (pad, GST_PAD_BLOCKING);
3546 GST_PAD_BLOCK_WAIT (pad);
3547 GST_OBJECT_FLAG_UNSET (pad, GST_PAD_BLOCKING);
3549 /* see if we got unblocked by a flush or not */
3550 if (GST_PAD_IS_FLUSHING (pad))
3554 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "got unblocked");
3556 /* when we get here, the pad is unblocked again and we perform
3557 * the needed unblock code. */
3558 callback = pad->block_callback;
3560 /* we need to call the callback */
3561 user_data = pad->block_data;
3562 GST_OBJECT_UNLOCK (pad);
3563 callback (pad, FALSE, user_data);
3564 GST_OBJECT_LOCK (pad);
3566 /* we need to signal the thread waiting on the GCond */
3567 GST_PAD_BLOCK_BROADCAST (pad);
3570 gst_object_unref (pad);
3576 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "pad was flushing");
3577 return GST_FLOW_WRONG_STATE;
3581 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "pad became flushing");
3582 gst_object_unref (pad);
3583 return GST_FLOW_WRONG_STATE;
3590 * gst_pad_get_offset:
3593 * Get the offset applied to the running time of @pad.
3595 * Returns: the offset.
3598 gst_pad_get_offset (GstPad * pad)
3602 g_return_val_if_fail (GST_IS_PAD (pad), 0);
3604 GST_OBJECT_LOCK (pad);
3605 result = pad->offset;
3606 GST_OBJECT_UNLOCK (pad);
3612 * gst_pad_set_offset:
3614 * @offset: the offset
3616 * Set the offset that will be applied to the running time of @pad.
3619 gst_pad_set_offset (GstPad * pad, gint64 offset)
3621 g_return_if_fail (GST_IS_PAD (pad));
3623 GST_OBJECT_LOCK (pad);
3624 pad->offset = offset;
3625 GST_OBJECT_UNLOCK (pad);
3629 /**********************************************************************
3630 * Data passing functions
3634 gst_pad_emit_have_data_signal (GstPad * pad, GstMiniObject * obj)
3637 GValue args[2] = { {0}, {0} };
3642 g_value_init (&ret, G_TYPE_BOOLEAN);
3643 g_value_set_boolean (&ret, TRUE);
3644 g_value_init (&args[0], GST_TYPE_PAD);
3645 g_value_set_object (&args[0], pad);
3646 g_value_init (&args[1], GST_MINI_OBJECT_TYPE (obj));
3647 g_value_set_boxed (&args[1], obj);
3649 if (GST_IS_EVENT (obj))
3650 detail = event_quark;
3652 detail = buffer_quark;
3655 g_signal_emitv (args, gst_pad_signals[PAD_HAVE_DATA], detail, &ret);
3656 res = g_value_get_boolean (&ret);
3659 g_value_unset (&ret);
3660 g_value_unset (&args[0]);
3661 g_value_unset (&args[1]);
3667 gst_pad_data_unref (gboolean is_buffer, void *data)
3669 if (G_LIKELY (is_buffer)) {
3670 gst_buffer_unref (data);
3672 gst_buffer_list_unref (data);
3676 /* this is the chain function that does not perform the additional argument
3677 * checking for that little extra speed.
3679 static inline GstFlowReturn
3680 gst_pad_chain_data_unchecked (GstPad * pad, gboolean is_buffer, void *data,
3681 GstPadPushCache * cache)
3683 gboolean needs_events;
3685 gboolean emit_signal;
3687 GST_PAD_STREAM_LOCK (pad);
3689 GST_OBJECT_LOCK (pad);
3690 if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
3693 needs_events = GST_PAD_NEEDS_EVENTS (pad);
3694 if (G_UNLIKELY (needs_events)) {
3695 GST_OBJECT_FLAG_UNSET (pad, GST_PAD_NEED_EVENTS);
3697 GST_DEBUG_OBJECT (pad, "need to update all events");
3698 ret = gst_pad_update_events (pad);
3699 if (G_UNLIKELY (ret != GST_FLOW_OK))
3702 emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
3703 GST_OBJECT_UNLOCK (pad);
3705 /* see if the signal should be emited */
3706 if (G_UNLIKELY (emit_signal)) {
3708 if (G_LIKELY (is_buffer)) {
3709 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT_CAST (data)))
3712 /* chain all groups in the buffer list one by one to avoid problems with
3713 * buffer probes that push buffers or events */
3718 /* NOTE: we read the chainfunc unlocked.
3719 * we cannot hold the lock for the pad so we might send
3720 * the data to the wrong function. This is not really a
3721 * problem since functions are assigned at creation time
3722 * and don't change that often... */
3723 if (G_LIKELY (is_buffer)) {
3724 GstPadChainFunction chainfunc;
3726 if (G_UNLIKELY ((chainfunc = GST_PAD_CHAINFUNC (pad)) == NULL))
3729 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3730 "calling chainfunction &%s with buffer %p",
3731 GST_DEBUG_FUNCPTR_NAME (chainfunc), data);
3734 cache->peer = gst_object_ref (pad);
3737 ret = chainfunc (pad, GST_BUFFER_CAST (data));
3739 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3740 "called chainfunction &%s with buffer %p, returned %s",
3741 GST_DEBUG_FUNCPTR_NAME (chainfunc), data, gst_flow_get_name (ret));
3743 GstPadChainListFunction chainlistfunc;
3745 if (G_UNLIKELY ((chainlistfunc = GST_PAD_CHAINLISTFUNC (pad)) == NULL))
3748 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3749 "calling chainlistfunction &%s",
3750 GST_DEBUG_FUNCPTR_NAME (chainlistfunc));
3752 ret = chainlistfunc (pad, GST_BUFFER_LIST_CAST (data));
3754 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3755 "called chainlistfunction &%s, returned %s",
3756 GST_DEBUG_FUNCPTR_NAME (chainlistfunc), gst_flow_get_name (ret));
3759 GST_PAD_STREAM_UNLOCK (pad);
3765 GstBufferList *list;
3769 GST_PAD_STREAM_UNLOCK (pad);
3771 GST_INFO_OBJECT (pad, "chaining each group in list as a merged buffer");
3773 list = GST_BUFFER_LIST_CAST (data);
3774 len = gst_buffer_list_len (list);
3777 for (i = 0; i < len; i++) {
3778 buffer = gst_buffer_list_get (list, i);
3780 gst_pad_chain_data_unchecked (pad, TRUE, gst_buffer_ref (buffer),
3782 if (ret != GST_FLOW_OK)
3785 gst_buffer_list_unref (list);
3793 gst_pad_data_unref (is_buffer, data);
3794 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3795 "pushing, but pad was flushing");
3796 GST_OBJECT_UNLOCK (pad);
3797 GST_PAD_STREAM_UNLOCK (pad);
3798 return GST_FLOW_WRONG_STATE;
3802 gst_pad_data_unref (is_buffer, data);
3803 GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
3804 GST_PAD_STREAM_UNLOCK (pad);
3809 gst_pad_data_unref (is_buffer, data);
3810 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "events were not accepted");
3811 GST_OBJECT_UNLOCK (pad);
3812 GST_PAD_STREAM_UNLOCK (pad);
3817 gst_pad_data_unref (is_buffer, data);
3818 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3819 "pushing, but not chainhandler");
3820 GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
3821 ("push on pad %s:%s but it has no chainfunction",
3822 GST_DEBUG_PAD_NAME (pad)));
3823 GST_PAD_STREAM_UNLOCK (pad);
3824 return GST_FLOW_NOT_SUPPORTED;
3830 * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
3831 * @buffer: (transfer full): the #GstBuffer to send, return GST_FLOW_ERROR
3834 * Chain a buffer to @pad.
3836 * The function returns #GST_FLOW_WRONG_STATE if the pad was flushing.
3838 * If the caps on @buffer are different from the current caps on @pad, this
3839 * function will call any setcaps function (see gst_pad_set_setcaps_function())
3840 * installed on @pad. If the new caps are not acceptable for @pad, this
3841 * function returns #GST_FLOW_NOT_NEGOTIATED.
3843 * The function proceeds calling the chain function installed on @pad (see
3844 * gst_pad_set_chain_function()) and the return value of that function is
3845 * returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no
3848 * In all cases, success or failure, the caller loses its reference to @buffer
3849 * after calling this function.
3851 * Returns: a #GstFlowReturn from the pad.
3856 gst_pad_chain (GstPad * pad, GstBuffer * buffer)
3858 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3859 g_return_val_if_fail (GST_PAD_IS_SINK (pad), GST_FLOW_ERROR);
3860 g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
3862 return gst_pad_chain_data_unchecked (pad, TRUE, buffer, NULL);
3866 * gst_pad_chain_list:
3867 * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
3868 * @list: (transfer full): the #GstBufferList to send, return GST_FLOW_ERROR
3871 * Chain a bufferlist to @pad.
3873 * The function returns #GST_FLOW_WRONG_STATE if the pad was flushing.
3875 * If the caps on the first buffer of @list are different from the current
3876 * caps on @pad, this function will call any setcaps function
3877 * (see gst_pad_set_setcaps_function()) installed on @pad. If the new caps
3878 * are not acceptable for @pad, this function returns #GST_FLOW_NOT_NEGOTIATED.
3880 * The function proceeds calling the chainlist function installed on @pad (see
3881 * gst_pad_set_chain_list_function()) and the return value of that function is
3882 * returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no
3883 * chainlist function.
3885 * In all cases, success or failure, the caller loses its reference to @list
3886 * after calling this function.
3890 * Returns: a #GstFlowReturn from the pad.
3895 gst_pad_chain_list (GstPad * pad, GstBufferList * list)
3897 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
3898 g_return_val_if_fail (GST_PAD_IS_SINK (pad), GST_FLOW_ERROR);
3899 g_return_val_if_fail (GST_IS_BUFFER_LIST (list), GST_FLOW_ERROR);
3901 return gst_pad_chain_data_unchecked (pad, FALSE, list, NULL);
3904 static GstFlowReturn
3905 gst_pad_push_data (GstPad * pad, gboolean is_buffer, void *data,
3906 GstPadPushCache * cache)
3911 GST_OBJECT_LOCK (pad);
3913 /* FIXME: this check can go away; pad_set_blocked could be implemented with
3914 * probes completely or probes with an extended pad block. */
3915 while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
3916 if ((ret = handle_pad_block (pad)) != GST_FLOW_OK)
3919 /* we emit signals on the pad arg, the peer will have a chance to
3920 * emit in the _chain() function */
3921 if (G_UNLIKELY (GST_PAD_DO_BUFFER_SIGNALS (pad) > 0)) {
3923 /* unlock before emitting */
3924 GST_OBJECT_UNLOCK (pad);
3926 if (G_LIKELY (is_buffer)) {
3927 /* if the signal handler returned FALSE, it means we should just drop the
3929 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT_CAST (data)))
3932 /* push all buffers in the list */
3935 GST_OBJECT_LOCK (pad);
3938 if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
3941 /* take ref to peer pad before releasing the lock */
3942 gst_object_ref (peer);
3943 GST_OBJECT_UNLOCK (pad);
3945 ret = gst_pad_chain_data_unchecked (peer, is_buffer, data, cache);
3947 gst_object_unref (peer);
3953 GstBufferList *list;
3957 GST_INFO_OBJECT (pad, "pushing each group in list as a merged buffer");
3959 list = GST_BUFFER_LIST_CAST (data);
3960 len = gst_buffer_list_len (list);
3962 for (i = 0; i < len; i++) {
3963 buffer = gst_buffer_list_get (list, i);
3964 ret = gst_pad_push_data (pad, TRUE, gst_buffer_ref (buffer), NULL);
3965 if (ret != GST_FLOW_OK)
3968 gst_buffer_list_unref (list);
3973 /* ERROR recovery here */
3976 gst_pad_data_unref (is_buffer, data);
3977 GST_DEBUG_OBJECT (pad, "pad block stopped by flush");
3978 GST_OBJECT_UNLOCK (pad);
3983 gst_pad_data_unref (is_buffer, data);
3984 GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
3989 gst_pad_data_unref (is_buffer, data);
3990 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3991 "pushing, but it was not linked");
3992 GST_OBJECT_UNLOCK (pad);
3993 return GST_FLOW_NOT_LINKED;
3997 static inline GstPadPushCache *
3998 pad_take_cache (GstPad * pad, gpointer * cache_ptr)
4000 GstPadPushCache *cache;
4002 /* try to get the cached data */
4004 cache = g_atomic_pointer_get (cache_ptr);
4005 /* now try to replace the pointer with NULL to mark that we are busy
4007 } while (!g_atomic_pointer_compare_and_exchange (cache_ptr, cache, NULL));
4009 /* we could have a leftover invalid entry */
4010 if (G_UNLIKELY (cache == PAD_CACHE_INVALID))
4017 pad_free_cache (GstPadPushCache * cache)
4019 gst_object_unref (cache->peer);
4020 g_slice_free (GstPadPushCache, cache);
4024 pad_put_cache (GstPad * pad, GstPadPushCache * cache, gpointer * cache_ptr)
4027 if (!g_atomic_pointer_compare_and_exchange (cache_ptr, NULL, cache)) {
4028 /* something changed, clean up our cache */
4029 pad_free_cache (cache);
4033 /* must be called with the pad lock */
4035 _priv_gst_pad_invalidate_cache (GstPad * pad)
4037 GstPadPushCache *cache;
4038 gpointer *cache_ptr;
4040 GST_LOG_OBJECT (pad, "Invalidating pad cache");
4042 /* we hold the pad lock here so we can get the peer and it stays
4043 * alive during this call */
4044 if (GST_PAD_IS_SINK (pad)) {
4045 if (!(pad = GST_PAD_PEER (pad)))
4049 cache_ptr = (gpointer *) & pad->priv->cache_ptr;
4051 /* try to get the cached data */
4053 cache = g_atomic_pointer_get (cache_ptr);
4054 /* now try to replace the pointer with INVALID. If nothing is busy with this
4055 * caps, we get the cache and clean it up. If something is busy, we replace
4056 * with INVALID so that when the function finishes and tries to put the
4057 * cache back, it'll fail and cleanup */
4058 } while (!g_atomic_pointer_compare_and_exchange (cache_ptr, cache,
4059 PAD_CACHE_INVALID));
4061 if (G_LIKELY (cache && cache != PAD_CACHE_INVALID))
4062 pad_free_cache (cache);
4067 * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not.
4068 * @buffer: (transfer full): the #GstBuffer to push returns GST_FLOW_ERROR
4071 * Pushes a buffer to the peer of @pad.
4073 * This function will call an installed pad block before triggering any
4074 * installed pad probes.
4076 * If the caps on @buffer are different from the currently configured caps on
4077 * @pad, this function will call any installed setcaps function on @pad (see
4078 * gst_pad_set_setcaps_function()). In case of failure to renegotiate the new
4079 * format, this function returns #GST_FLOW_NOT_NEGOTIATED.
4081 * The function proceeds calling gst_pad_chain() on the peer pad and returns
4082 * the value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will
4085 * In all cases, success or failure, the caller loses its reference to @buffer
4086 * after calling this function.
4088 * Returns: a #GstFlowReturn from the peer pad.
4093 gst_pad_push (GstPad * pad, GstBuffer * buffer)
4095 GstPadPushCache *cache;
4097 gpointer *cache_ptr;
4100 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4101 g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
4102 g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
4104 cache_ptr = (gpointer *) & pad->priv->cache_ptr;
4106 cache = pad_take_cache (pad, cache_ptr);
4108 if (G_UNLIKELY (cache == NULL))
4113 GST_PAD_STREAM_LOCK (peer);
4114 if (G_UNLIKELY (g_atomic_pointer_get (cache_ptr) == PAD_CACHE_INVALID))
4117 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4118 "calling chainfunction &%s with buffer %p",
4119 GST_DEBUG_FUNCPTR_NAME (GST_PAD_CHAINFUNC (peer)), buffer);
4121 ret = GST_PAD_CHAINFUNC (peer) (peer, buffer);
4123 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4124 "called chainfunction &%s with buffer %p, returned %s",
4125 GST_DEBUG_FUNCPTR_NAME (GST_PAD_CHAINFUNC (peer)), buffer,
4126 gst_flow_get_name (ret));
4128 GST_PAD_STREAM_UNLOCK (peer);
4130 pad_put_cache (pad, cache, cache_ptr);
4137 GstPadPushCache scache = { NULL, };
4139 GST_LOG_OBJECT (pad, "Taking slow path");
4141 ret = gst_pad_push_data (pad, TRUE, buffer, &scache);
4144 GstPadPushCache *ncache;
4146 GST_LOG_OBJECT (pad, "Caching push data");
4148 /* make cache structure */
4149 ncache = g_slice_new (GstPadPushCache);
4152 pad_put_cache (pad, ncache, cache_ptr);
4158 GST_PAD_STREAM_UNLOCK (peer);
4159 pad_free_cache (cache);
4165 * gst_pad_push_list:
4166 * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not.
4167 * @list: (transfer full): the #GstBufferList to push returns GST_FLOW_ERROR
4170 * Pushes a buffer list to the peer of @pad.
4172 * This function will call an installed pad block before triggering any
4173 * installed pad probes.
4175 * If the caps on the first buffer in the first group of @list are different
4176 * from the currently configured caps on @pad, this function will call any
4177 * installed setcaps function on @pad (see gst_pad_set_setcaps_function()). In
4178 * case of failure to renegotiate the new format, this function returns
4179 * #GST_FLOW_NOT_NEGOTIATED.
4181 * If there are any probes installed on @pad every group of the buffer list
4182 * will be merged into a normal #GstBuffer and pushed via gst_pad_push and the
4183 * buffer list will be unreffed.
4185 * The function proceeds calling the chain function on the peer pad and returns
4186 * the value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will
4187 * be returned. If the peer pad does not have any installed chainlist function
4188 * every group buffer of the list will be merged into a normal #GstBuffer and
4189 * chained via gst_pad_chain().
4191 * In all cases, success or failure, the caller loses its reference to @list
4192 * after calling this function.
4194 * Returns: a #GstFlowReturn from the peer pad.
4201 gst_pad_push_list (GstPad * pad, GstBufferList * list)
4203 GstPadPushCache *cache;
4205 gpointer *cache_ptr;
4208 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4209 g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
4210 g_return_val_if_fail (GST_IS_BUFFER_LIST (list), GST_FLOW_ERROR);
4212 cache_ptr = (gpointer *) & pad->priv->cache_ptr;
4214 cache = pad_take_cache (pad, cache_ptr);
4216 if (G_UNLIKELY (cache == NULL))
4221 GST_PAD_STREAM_LOCK (peer);
4222 if (G_UNLIKELY (g_atomic_pointer_get (cache_ptr) == PAD_CACHE_INVALID))
4225 ret = GST_PAD_CHAINLISTFUNC (peer) (peer, list);
4227 GST_PAD_STREAM_UNLOCK (peer);
4229 pad_put_cache (pad, cache, cache_ptr);
4236 GstPadPushCache scache = { NULL, };
4238 GST_LOG_OBJECT (pad, "Taking slow path");
4240 ret = gst_pad_push_data (pad, FALSE, list, &scache);
4243 GstPadPushCache *ncache;
4245 GST_LOG_OBJECT (pad, "Caching push data");
4247 /* make cache structure */
4248 ncache = g_slice_new (GstPadPushCache);
4251 pad_put_cache (pad, ncache, cache_ptr);
4257 GST_PAD_STREAM_UNLOCK (peer);
4258 pad_free_cache (cache);
4264 * gst_pad_check_pull_range:
4265 * @pad: a sink #GstPad.
4267 * Checks if a gst_pad_pull_range() can be performed on the peer
4268 * source pad. This function is used by plugins that want to check
4269 * if they can use random access on the peer source pad.
4271 * The peer sourcepad can implement a custom #GstPadCheckGetRangeFunction
4272 * if it needs to perform some logic to determine if pull_range is
4275 * Returns: a gboolean with the result.
4280 gst_pad_check_pull_range (GstPad * pad)
4284 GstPadCheckGetRangeFunction checkgetrangefunc;
4286 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4288 GST_OBJECT_LOCK (pad);
4289 if (!GST_PAD_IS_SINK (pad))
4290 goto wrong_direction;
4292 if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
4295 gst_object_ref (peer);
4296 GST_OBJECT_UNLOCK (pad);
4298 /* see note in above function */
4299 if (G_LIKELY ((checkgetrangefunc = peer->checkgetrangefunc) == NULL)) {
4300 /* FIXME, kindoff ghetto */
4301 ret = GST_PAD_GETRANGEFUNC (peer) != NULL;
4302 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4303 "no checkgetrangefunc, assuming %d", ret);
4305 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4306 "calling checkgetrangefunc %s of peer pad %s:%s",
4307 GST_DEBUG_FUNCPTR_NAME (checkgetrangefunc), GST_DEBUG_PAD_NAME (peer));
4309 ret = checkgetrangefunc (peer);
4312 gst_object_unref (peer);
4316 /* ERROR recovery here */
4319 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4320 "checking pull range, but pad must be a sinkpad");
4321 GST_OBJECT_UNLOCK (pad);
4326 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4327 "checking pull range, but it was not linked");
4328 GST_OBJECT_UNLOCK (pad);
4333 static GstFlowReturn
4334 gst_pad_get_range_unchecked (GstPad * pad, guint64 offset, guint size,
4335 GstBuffer ** buffer)
4338 GstPadGetRangeFunction getrangefunc;
4339 gboolean emit_signal;
4341 GST_PAD_STREAM_LOCK (pad);
4343 GST_OBJECT_LOCK (pad);
4344 if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4347 emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
4348 GST_OBJECT_UNLOCK (pad);
4350 if (G_UNLIKELY ((getrangefunc = GST_PAD_GETRANGEFUNC (pad)) == NULL))
4353 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4354 "calling getrangefunc %s, offset %"
4355 G_GUINT64_FORMAT ", size %u",
4356 GST_DEBUG_FUNCPTR_NAME (getrangefunc), offset, size);
4358 ret = getrangefunc (pad, offset, size, buffer);
4360 /* can only fire the signal if we have a valid buffer */
4361 if (G_UNLIKELY (emit_signal) && (ret == GST_FLOW_OK)) {
4362 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT_CAST (*buffer)))
4365 GST_PAD_STREAM_UNLOCK (pad);
4367 if (G_UNLIKELY (ret != GST_FLOW_OK))
4368 goto get_range_failed;
4375 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4376 "pulling range, but pad was flushing");
4377 GST_OBJECT_UNLOCK (pad);
4378 GST_PAD_STREAM_UNLOCK (pad);
4379 return GST_FLOW_WRONG_STATE;
4383 GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
4384 ("pullrange on pad %s:%s but it has no getrangefunction",
4385 GST_DEBUG_PAD_NAME (pad)));
4386 GST_PAD_STREAM_UNLOCK (pad);
4387 return GST_FLOW_NOT_SUPPORTED;
4391 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4392 "Dropping data after FALSE probe return");
4393 GST_PAD_STREAM_UNLOCK (pad);
4394 gst_buffer_unref (*buffer);
4396 return GST_FLOW_UNEXPECTED;
4401 GST_CAT_LEVEL_LOG (GST_CAT_SCHEDULING,
4402 (ret >= GST_FLOW_UNEXPECTED) ? GST_LEVEL_INFO : GST_LEVEL_WARNING,
4403 pad, "getrange failed, flow: %s", gst_flow_get_name (ret));
4409 * gst_pad_get_range:
4410 * @pad: a src #GstPad, returns #GST_FLOW_ERROR if not.
4411 * @offset: The start offset of the buffer
4412 * @size: The length of the buffer
4413 * @buffer: (out callee-allocates): a pointer to hold the #GstBuffer,
4414 * returns #GST_FLOW_ERROR if %NULL.
4416 * When @pad is flushing this function returns #GST_FLOW_WRONG_STATE
4417 * immediatly and @buffer is %NULL.
4419 * Calls the getrange function of @pad, see #GstPadGetRangeFunction for a
4420 * description of a getrange function. If @pad has no getrange function
4421 * installed (see gst_pad_set_getrange_function()) this function returns
4422 * #GST_FLOW_NOT_SUPPORTED.
4424 * This is a lowlevel function. Usualy gst_pad_pull_range() is used.
4426 * Returns: a #GstFlowReturn from the pad.
4431 gst_pad_get_range (GstPad * pad, guint64 offset, guint size,
4432 GstBuffer ** buffer)
4434 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4435 g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
4436 g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
4438 return gst_pad_get_range_unchecked (pad, offset, size, buffer);
4442 * gst_pad_pull_range:
4443 * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
4444 * @offset: The start offset of the buffer
4445 * @size: The length of the buffer
4446 * @buffer: (out callee-allocates): a pointer to hold the #GstBuffer, returns
4447 * GST_FLOW_ERROR if %NULL.
4449 * Pulls a @buffer from the peer pad.
4451 * This function will first trigger the pad block signal if it was
4454 * When @pad is not linked #GST_FLOW_NOT_LINKED is returned else this
4455 * function returns the result of gst_pad_get_range() on the peer pad.
4456 * See gst_pad_get_range() for a list of return values and for the
4457 * semantics of the arguments of this function.
4459 * @buffer's caps must either be unset or the same as what is already
4460 * configured on @pad. Renegotiation within a running pull-mode pipeline is not
4463 * Returns: a #GstFlowReturn from the peer pad.
4464 * When this function returns #GST_FLOW_OK, @buffer will contain a valid
4465 * #GstBuffer that should be freed with gst_buffer_unref() after usage.
4466 * @buffer may not be used or freed when any other return value than
4467 * #GST_FLOW_OK is returned.
4472 gst_pad_pull_range (GstPad * pad, guint64 offset, guint size,
4473 GstBuffer ** buffer)
4477 gboolean emit_signal;
4478 gboolean needs_events;
4480 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4481 g_return_val_if_fail (GST_PAD_IS_SINK (pad), GST_FLOW_ERROR);
4482 g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
4484 GST_OBJECT_LOCK (pad);
4486 while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
4487 handle_pad_block (pad);
4489 if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
4492 /* signal emision for the pad, peer has chance to emit when
4493 * we call _get_range() */
4494 emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
4496 gst_object_ref (peer);
4497 GST_OBJECT_UNLOCK (pad);
4499 ret = gst_pad_get_range_unchecked (peer, offset, size, buffer);
4501 gst_object_unref (peer);
4503 if (G_UNLIKELY (ret != GST_FLOW_OK))
4504 goto pull_range_failed;
4506 /* can only fire the signal if we have a valid buffer */
4507 if (G_UNLIKELY (emit_signal)) {
4508 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT_CAST (*buffer)))
4512 GST_OBJECT_LOCK (pad);
4514 needs_events = GST_PAD_NEEDS_EVENTS (pad);
4515 if (G_UNLIKELY (needs_events)) {
4516 GST_OBJECT_FLAG_UNSET (pad, GST_PAD_NEED_EVENTS);
4518 GST_DEBUG_OBJECT (pad, "we need to update the events");
4519 ret = gst_pad_update_events (pad);
4520 if (G_UNLIKELY (ret != GST_FLOW_OK))
4523 GST_OBJECT_UNLOCK (pad);
4527 /* ERROR recovery here */
4530 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4531 "pulling range, but it was not linked");
4532 GST_OBJECT_UNLOCK (pad);
4533 return GST_FLOW_NOT_LINKED;
4538 GST_CAT_LEVEL_LOG (GST_CAT_SCHEDULING,
4539 (ret >= GST_FLOW_UNEXPECTED) ? GST_LEVEL_INFO : GST_LEVEL_WARNING,
4540 pad, "pullrange failed, flow: %s", gst_flow_get_name (ret));
4545 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4546 "Dropping data after FALSE probe return");
4547 gst_buffer_unref (*buffer);
4549 return GST_FLOW_UNEXPECTED;
4553 GST_OBJECT_UNLOCK (pad);
4554 gst_buffer_unref (*buffer);
4556 GST_CAT_WARNING_OBJECT (GST_CAT_SCHEDULING, pad,
4557 "pullrange returned events that were not accepted");
4563 * gst_pad_push_event:
4564 * @pad: a #GstPad to push the event to.
4565 * @event: (transfer full): the #GstEvent to send to the pad.
4567 * Sends the event to the peer of the given pad. This function is
4568 * mainly used by elements to send events to their peer
4571 * This function takes owership of the provided event so you should
4572 * gst_event_ref() it if you want to reuse the event after this call.
4574 * Returns: TRUE if the event was handled.
4579 gst_pad_push_event (GstPad * pad, GstEvent * event)
4584 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4585 g_return_val_if_fail (event != NULL, FALSE);
4586 g_return_val_if_fail (GST_IS_EVENT (event), FALSE);
4588 GST_LOG_OBJECT (pad, "event: %s", GST_EVENT_TYPE_NAME (event));
4590 GST_OBJECT_LOCK (pad);
4592 /* Two checks to be made:
4593 * . (un)set the FLUSHING flag for flushing events,
4594 * . handle pad blocking */
4595 switch (GST_EVENT_TYPE (event)) {
4596 case GST_EVENT_FLUSH_START:
4597 _priv_gst_pad_invalidate_cache (pad);
4598 GST_PAD_SET_FLUSHING (pad);
4600 if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
4601 /* flush start will have set the FLUSHING flag and will then
4602 * unlock all threads doing a GCond wait on the blocking pad. This
4603 * will typically unblock the STREAMING thread blocked on a pad. */
4604 GST_LOG_OBJECT (pad, "Pad is blocked, not forwarding flush-start, "
4605 "doing block signal.");
4606 GST_PAD_BLOCK_BROADCAST (pad);
4610 case GST_EVENT_FLUSH_STOP:
4611 GST_PAD_UNSET_FLUSHING (pad);
4613 /* if we are blocked, flush away the FLUSH_STOP event */
4614 if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
4615 GST_LOG_OBJECT (pad, "Pad is blocked, not forwarding flush-stop");
4619 case GST_EVENT_RECONFIGURE:
4620 if (GST_PAD_IS_SINK (pad))
4621 GST_OBJECT_FLAG_SET (pad, GST_PAD_NEED_RECONFIGURE);
4623 while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
4624 /* block the event as long as the pad is blocked */
4625 if (handle_pad_block (pad) != GST_FLOW_OK)
4631 if (G_UNLIKELY (GST_PAD_DO_EVENT_SIGNALS (pad) > 0)) {
4632 GST_OBJECT_UNLOCK (pad);
4634 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT_CAST (event)))
4637 GST_OBJECT_LOCK (pad);
4640 /* store the event on the pad, but only on srcpads */
4641 if (GST_PAD_IS_SRC (pad) && GST_EVENT_IS_STICKY (event)) {
4644 idx = GST_EVENT_STICKY_IDX (event);
4645 GST_LOG_OBJECT (pad, "storing sticky event %s at index %u",
4646 GST_EVENT_TYPE_NAME (event), idx);
4648 /* srcpad sticky events always become active immediately */
4649 gst_event_replace (&pad->priv->events[idx].event, event);
4650 pad->priv->events[idx].active = TRUE;
4653 if ((peerpad = GST_PAD_PEER (pad)))
4654 gst_object_ref (peerpad);
4655 GST_OBJECT_UNLOCK (pad);
4657 /* backwards compatibility mode for caps */
4658 if (GST_EVENT_TYPE (event) == GST_EVENT_CAPS) {
4660 gst_event_parse_caps (event, &caps);
4661 /* FIXME, this is awkward because we don't check flushing here which means
4662 * that we can call the setcaps functions on flushing pads, this is not
4663 * quite what we want */
4664 gst_pad_call_setcaps (pad, caps);
4667 /* now check the peer pad */
4668 if (peerpad == NULL)
4671 GST_LOG_OBJECT (pad, "sending event %s to peerpad %" GST_PTR_FORMAT,
4672 GST_EVENT_TYPE_NAME (event), peerpad);
4674 result = gst_pad_send_event (peerpad, event);
4676 /* Note: we gave away ownership of the event at this point */
4677 GST_LOG_OBJECT (pad, "sent event to peerpad %" GST_PTR_FORMAT ", result %d",
4680 gst_object_unref (peerpad);
4684 /* ERROR handling */
4687 GST_DEBUG_OBJECT (pad, "Dropping event after FALSE probe return");
4688 gst_event_unref (event);
4693 GST_DEBUG_OBJECT (pad, "Dropping event because pad is not linked");
4694 gst_event_unref (event);
4699 GST_DEBUG_OBJECT (pad,
4700 "Not forwarding event since we're flushing and blocking");
4701 gst_event_unref (event);
4702 GST_OBJECT_UNLOCK (pad);
4708 * gst_pad_send_event:
4709 * @pad: a #GstPad to send the event to.
4710 * @event: (transfer full): the #GstEvent to send to the pad.
4712 * Sends the event to the pad. This function can be used
4713 * by applications to send events in the pipeline.
4715 * If @pad is a source pad, @event should be an upstream event. If @pad is a
4716 * sink pad, @event should be a downstream event. For example, you would not
4717 * send a #GST_EVENT_EOS on a src pad; EOS events only propagate downstream.
4718 * Furthermore, some downstream events have to be serialized with data flow,
4719 * like EOS, while some can travel out-of-band, like #GST_EVENT_FLUSH_START. If
4720 * the event needs to be serialized with data flow, this function will take the
4721 * pad's stream lock while calling its event function.
4723 * To find out whether an event type is upstream, downstream, or downstream and
4724 * serialized, see #GstEventTypeFlags, gst_event_type_get_flags(),
4725 * #GST_EVENT_IS_UPSTREAM, #GST_EVENT_IS_DOWNSTREAM, and
4726 * #GST_EVENT_IS_SERIALIZED. Note that in practice that an application or
4727 * plugin doesn't need to bother itself with this information; the core handles
4728 * all necessary locks and checks.
4730 * This function takes owership of the provided event so you should
4731 * gst_event_ref() it if you want to reuse the event after this call.
4733 * Returns: TRUE if the event was handled.
4736 gst_pad_send_event (GstPad * pad, GstEvent * event)
4738 gboolean result = FALSE;
4739 gboolean serialized, need_unlock = FALSE, needs_events, sticky;
4741 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4742 g_return_val_if_fail (event != NULL, FALSE);
4744 GST_OBJECT_LOCK (pad);
4745 if (GST_PAD_IS_SINK (pad)) {
4746 if (G_UNLIKELY (!GST_EVENT_IS_DOWNSTREAM (event)))
4747 goto wrong_direction;
4748 serialized = GST_EVENT_IS_SERIALIZED (event);
4749 sticky = GST_EVENT_IS_STICKY (event);
4750 } else if (GST_PAD_IS_SRC (pad)) {
4751 if (G_UNLIKELY (!GST_EVENT_IS_UPSTREAM (event)))
4752 goto wrong_direction;
4753 /* events on srcpad never are serialized and sticky */
4754 serialized = sticky = FALSE;
4756 goto unknown_direction;
4759 if (G_UNLIKELY (GST_PAD_DO_EVENT_SIGNALS (pad) > 0)) {
4760 GST_OBJECT_UNLOCK (pad);
4762 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT_CAST (event)))
4765 GST_OBJECT_LOCK (pad);
4767 /* get the flag first, we clear it when we have a FLUSH or a non-serialized
4769 needs_events = GST_PAD_NEEDS_EVENTS (pad);
4771 switch (GST_EVENT_TYPE (event)) {
4772 case GST_EVENT_FLUSH_START:
4773 GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad,
4774 "have event type %d (FLUSH_START)", GST_EVENT_TYPE (event));
4776 /* can't even accept a flush begin event when flushing */
4777 if (GST_PAD_IS_FLUSHING (pad))
4780 _priv_gst_pad_invalidate_cache (pad);
4781 GST_PAD_SET_FLUSHING (pad);
4782 GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "set flush flag");
4783 needs_events = FALSE;
4785 case GST_EVENT_FLUSH_STOP:
4786 if (G_LIKELY (GST_PAD_ACTIVATE_MODE (pad) != GST_ACTIVATE_NONE)) {
4787 GST_PAD_UNSET_FLUSHING (pad);
4788 GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "cleared flush flag");
4790 GST_OBJECT_UNLOCK (pad);
4791 /* grab stream lock */
4792 GST_PAD_STREAM_LOCK (pad);
4794 GST_OBJECT_LOCK (pad);
4795 needs_events = FALSE;
4797 case GST_EVENT_RECONFIGURE:
4798 if (GST_PAD_IS_SRC (pad))
4799 GST_OBJECT_FLAG_SET (pad, GST_PAD_NEED_RECONFIGURE);
4801 GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "have event type %s",
4802 GST_EVENT_TYPE_NAME (event));
4805 /* lock order: STREAM_LOCK, LOCK, recheck flushing. */
4806 GST_OBJECT_UNLOCK (pad);
4807 GST_PAD_STREAM_LOCK (pad);
4809 GST_OBJECT_LOCK (pad);
4811 /* don't forward events on non-serialized events */
4812 needs_events = FALSE;
4815 /* store the event on the pad, but only on srcpads. We need to store the
4816 * event before checking the flushing flag. */
4820 idx = GST_EVENT_STICKY_IDX (event);
4821 GST_LOG_OBJECT (pad, "storing sticky event %s at index %u",
4822 GST_EVENT_TYPE_NAME (event), idx);
4824 if (pad->priv->events[idx].event != event) {
4825 gst_event_replace (&pad->priv->events[idx].event, event);
4826 pad->priv->events[idx].active = FALSE;
4827 /* set the flag so that we update the events next time. We would
4828 * usually update below but we might be flushing too. */
4829 GST_OBJECT_FLAG_SET (pad, GST_PAD_NEED_EVENTS);
4830 needs_events = TRUE;
4833 /* now check the flushing flag */
4834 if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4840 if (G_UNLIKELY (needs_events)) {
4843 GST_OBJECT_FLAG_UNSET (pad, GST_PAD_NEED_EVENTS);
4845 GST_DEBUG_OBJECT (pad, "need to update all events");
4846 ret = gst_pad_update_events (pad);
4847 if (ret != GST_FLOW_OK)
4849 GST_OBJECT_UNLOCK (pad);
4851 gst_event_unref (event);
4855 GstPadEventFunction eventfunc;
4857 if (G_UNLIKELY ((eventfunc = GST_PAD_EVENTFUNC (pad)) == NULL))
4860 GST_OBJECT_UNLOCK (pad);
4862 result = do_event_function (pad, event, eventfunc);
4866 GST_PAD_STREAM_UNLOCK (pad);
4868 GST_DEBUG_OBJECT (pad, "sent event, result %d", result);
4872 /* ERROR handling */
4875 g_warning ("pad %s:%s sending %s event in wrong direction",
4876 GST_DEBUG_PAD_NAME (pad), GST_EVENT_TYPE_NAME (event));
4877 GST_OBJECT_UNLOCK (pad);
4878 gst_event_unref (event);
4883 g_warning ("pad %s:%s has invalid direction", GST_DEBUG_PAD_NAME (pad));
4884 GST_OBJECT_UNLOCK (pad);
4885 gst_event_unref (event);
4890 g_warning ("pad %s:%s has no event handler, file a bug.",
4891 GST_DEBUG_PAD_NAME (pad));
4892 GST_OBJECT_UNLOCK (pad);
4894 GST_PAD_STREAM_UNLOCK (pad);
4895 gst_event_unref (event);
4900 GST_OBJECT_UNLOCK (pad);
4902 GST_PAD_STREAM_UNLOCK (pad);
4903 GST_CAT_INFO_OBJECT (GST_CAT_EVENT, pad,
4904 "Received event on flushing pad. Discarding");
4905 gst_event_unref (event);
4910 GST_DEBUG_OBJECT (pad, "Dropping event after FALSE probe return");
4911 gst_event_unref (event);
4916 GST_OBJECT_UNLOCK (pad);
4918 GST_PAD_STREAM_UNLOCK (pad);
4919 GST_CAT_INFO_OBJECT (GST_CAT_EVENT, pad, "Update events failed");
4920 gst_event_unref (event);
4926 * gst_pad_set_element_private:
4927 * @pad: the #GstPad to set the private data of.
4928 * @priv: The private data to attach to the pad.
4930 * Set the given private data gpointer on the pad.
4931 * This function can only be used by the element that owns the pad.
4932 * No locking is performed in this function.
4935 gst_pad_set_element_private (GstPad * pad, gpointer priv)
4937 pad->element_private = priv;
4941 * gst_pad_get_element_private:
4942 * @pad: the #GstPad to get the private data of.
4944 * Gets the private data of a pad.
4945 * No locking is performed in this function.
4947 * Returns: (transfer none): a #gpointer to the private data.
4950 gst_pad_get_element_private (GstPad * pad)
4952 return pad->element_private;
4956 * gst_pad_get_sticky_event:
4957 * @pad: the #GstPad to get the event from.
4958 * @event_type: the #GstEventType that should be retrieved.
4959 * @active: If only active events should be retrieved
4961 * Returns a new reference of the sticky event of type @event_type
4962 * from the event. If @active is #TRUE only active events that
4963 * were accepted downstream are returned.
4965 * Returns: (transfer full): a #GstEvent of type @event_type. Unref after usage.
4968 gst_pad_get_sticky_event (GstPad * pad, GstEventType event_type,
4971 GstEvent *event = NULL;
4974 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
4975 g_return_val_if_fail ((event_type & GST_EVENT_TYPE_STICKY) != 0, NULL);
4977 idx = GST_EVENT_STICKY_IDX_TYPE (event_type);
4979 GST_OBJECT_LOCK (pad);
4980 if (!active || pad->priv->events[idx].active) {
4981 if ((event = pad->priv->events[idx].event)) {
4982 gst_event_ref (event);
4985 GST_OBJECT_UNLOCK (pad);
4991 do_stream_status (GstPad * pad, GstStreamStatusType type,
4992 GThread * thread, GstTask * task)
4996 GST_DEBUG_OBJECT (pad, "doing stream-status %d", type);
4998 if ((parent = GST_ELEMENT_CAST (gst_pad_get_parent (pad)))) {
4999 if (GST_IS_ELEMENT (parent)) {
5000 GstMessage *message;
5001 GValue value = { 0 };
5003 if (type == GST_STREAM_STATUS_TYPE_ENTER) {
5004 gchar *tname, *ename, *pname;
5006 /* create a good task name */
5007 ename = gst_element_get_name (parent);
5008 pname = gst_pad_get_name (pad);
5009 tname = g_strdup_printf ("%s:%s", ename, pname);
5013 gst_object_set_name (GST_OBJECT_CAST (task), tname);
5017 message = gst_message_new_stream_status (GST_OBJECT_CAST (pad),
5020 g_value_init (&value, GST_TYPE_TASK);
5021 g_value_set_object (&value, task);
5022 gst_message_set_stream_status_object (message, &value);
5023 g_value_unset (&value);
5025 GST_DEBUG_OBJECT (pad, "posting stream-status %d", type);
5026 gst_element_post_message (parent, message);
5028 gst_object_unref (parent);
5033 pad_enter_thread (GstTask * task, GThread * thread, gpointer user_data)
5035 do_stream_status (GST_PAD_CAST (user_data), GST_STREAM_STATUS_TYPE_ENTER,
5040 pad_leave_thread (GstTask * task, GThread * thread, gpointer user_data)
5042 do_stream_status (GST_PAD_CAST (user_data), GST_STREAM_STATUS_TYPE_LEAVE,
5046 static GstTaskThreadCallbacks thr_callbacks = {
5052 * gst_pad_start_task:
5053 * @pad: the #GstPad to start the task of
5054 * @func: the task function to call
5055 * @data: data passed to the task function
5057 * Starts a task that repeatedly calls @func with @data. This function
5058 * is mostly used in pad activation functions to start the dataflow.
5059 * The #GST_PAD_STREAM_LOCK of @pad will automatically be acquired
5060 * before @func is called.
5062 * Returns: a %TRUE if the task could be started.
5065 gst_pad_start_task (GstPad * pad, GstTaskFunction func, gpointer data)
5070 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
5071 g_return_val_if_fail (func != NULL, FALSE);
5073 GST_DEBUG_OBJECT (pad, "start task");
5075 GST_OBJECT_LOCK (pad);
5076 task = GST_PAD_TASK (pad);
5078 task = gst_task_create (func, data);
5079 gst_task_set_lock (task, GST_PAD_GET_STREAM_LOCK (pad));
5080 gst_task_set_thread_callbacks (task, &thr_callbacks, pad, NULL);
5081 GST_DEBUG_OBJECT (pad, "created task");
5082 GST_PAD_TASK (pad) = task;
5083 gst_object_ref (task);
5084 /* release lock to post the message */
5085 GST_OBJECT_UNLOCK (pad);
5087 do_stream_status (pad, GST_STREAM_STATUS_TYPE_CREATE, NULL, task);
5089 gst_object_unref (task);
5091 GST_OBJECT_LOCK (pad);
5092 /* nobody else is supposed to have changed the pad now */
5093 if (GST_PAD_TASK (pad) != task)
5094 goto concurrent_stop;
5096 res = gst_task_set_state (task, GST_TASK_STARTED);
5097 GST_OBJECT_UNLOCK (pad);
5104 GST_OBJECT_UNLOCK (pad);
5110 * gst_pad_pause_task:
5111 * @pad: the #GstPad to pause the task of
5113 * Pause the task of @pad. This function will also wait until the
5114 * function executed by the task is finished if this function is not
5115 * called from the task function.
5117 * Returns: a TRUE if the task could be paused or FALSE when the pad
5121 gst_pad_pause_task (GstPad * pad)
5126 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
5128 GST_DEBUG_OBJECT (pad, "pause task");
5130 GST_OBJECT_LOCK (pad);
5131 task = GST_PAD_TASK (pad);
5134 res = gst_task_set_state (task, GST_TASK_PAUSED);
5135 GST_OBJECT_UNLOCK (pad);
5137 /* wait for task function to finish, this lock is recursive so it does nothing
5138 * when the pause is called from the task itself */
5139 GST_PAD_STREAM_LOCK (pad);
5140 GST_PAD_STREAM_UNLOCK (pad);
5146 GST_DEBUG_OBJECT (pad, "pad has no task");
5147 GST_OBJECT_UNLOCK (pad);
5153 * gst_pad_stop_task:
5154 * @pad: the #GstPad to stop the task of
5156 * Stop the task of @pad. This function will also make sure that the
5157 * function executed by the task will effectively stop if not called
5158 * from the GstTaskFunction.
5160 * This function will deadlock if called from the GstTaskFunction of
5161 * the task. Use gst_task_pause() instead.
5163 * Regardless of whether the pad has a task, the stream lock is acquired and
5164 * released so as to ensure that streaming through this pad has finished.
5166 * Returns: a TRUE if the task could be stopped or FALSE on error.
5169 gst_pad_stop_task (GstPad * pad)
5174 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
5176 GST_DEBUG_OBJECT (pad, "stop task");
5178 GST_OBJECT_LOCK (pad);
5179 task = GST_PAD_TASK (pad);
5182 GST_PAD_TASK (pad) = NULL;
5183 res = gst_task_set_state (task, GST_TASK_STOPPED);
5184 GST_OBJECT_UNLOCK (pad);
5186 GST_PAD_STREAM_LOCK (pad);
5187 GST_PAD_STREAM_UNLOCK (pad);
5189 if (!gst_task_join (task))
5192 gst_object_unref (task);
5198 GST_DEBUG_OBJECT (pad, "no task");
5199 GST_OBJECT_UNLOCK (pad);
5201 GST_PAD_STREAM_LOCK (pad);
5202 GST_PAD_STREAM_UNLOCK (pad);
5204 /* this is not an error */
5209 /* this is bad, possibly the application tried to join the task from
5210 * the task's thread. We install the task again so that it will be stopped
5211 * again from the right thread next time hopefully. */
5212 GST_OBJECT_LOCK (pad);
5213 GST_DEBUG_OBJECT (pad, "join failed");
5214 /* we can only install this task if there was no other task */
5215 if (GST_PAD_TASK (pad) == NULL)
5216 GST_PAD_TASK (pad) = task;
5217 GST_OBJECT_UNLOCK (pad);