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 #define GST_PAD_GET_PRIVATE(obj) \
99 (G_TYPE_INSTANCE_GET_PRIVATE ((obj), GST_TYPE_PAD, GstPadPrivate))
101 #define GST_PAD_CHAINLISTFUNC(pad) ((pad)->abidata.ABI.priv->chainlistfunc)
103 struct _GstPadPrivate
105 GstPadChainListFunction chainlistfunc;
108 static void gst_pad_dispose (GObject * object);
109 static void gst_pad_finalize (GObject * object);
110 static void gst_pad_set_property (GObject * object, guint prop_id,
111 const GValue * value, GParamSpec * pspec);
112 static void gst_pad_get_property (GObject * object, guint prop_id,
113 GValue * value, GParamSpec * pspec);
115 static GstFlowReturn handle_pad_block (GstPad * pad);
116 static GstCaps *gst_pad_get_caps_unlocked (GstPad * pad);
117 static void gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ);
118 static gboolean gst_pad_activate_default (GstPad * pad);
119 static gboolean gst_pad_acceptcaps_default (GstPad * pad, GstCaps * caps);
121 #ifndef GST_DISABLE_LOADSAVE
122 static xmlNodePtr gst_pad_save_thyself (GstObject * object, xmlNodePtr parent);
125 static GstObjectClass *parent_class = NULL;
126 static guint gst_pad_signals[LAST_SIGNAL] = { 0 };
128 /* quarks for probe signals */
129 static GQuark buffer_quark;
130 static GQuark event_quark;
139 static GstFlowQuarks flow_quarks[] = {
140 {GST_FLOW_CUSTOM_SUCCESS, "custom-success", 0},
141 {GST_FLOW_RESEND, "resend", 0},
142 {GST_FLOW_OK, "ok", 0},
143 {GST_FLOW_NOT_LINKED, "not-linked", 0},
144 {GST_FLOW_WRONG_STATE, "wrong-state", 0},
145 {GST_FLOW_UNEXPECTED, "unexpected", 0},
146 {GST_FLOW_NOT_NEGOTIATED, "not-negotiated", 0},
147 {GST_FLOW_ERROR, "error", 0},
148 {GST_FLOW_NOT_SUPPORTED, "not-supported", 0},
149 {GST_FLOW_CUSTOM_ERROR, "custom-error", 0}
154 * @ret: a #GstFlowReturn to get the name of.
156 * Gets a string representing the given flow return.
158 * Returns: a static string with the name of the flow return.
160 G_CONST_RETURN gchar *
161 gst_flow_get_name (GstFlowReturn ret)
165 ret = CLAMP (ret, GST_FLOW_CUSTOM_ERROR, GST_FLOW_CUSTOM_SUCCESS);
167 for (i = 0; i < G_N_ELEMENTS (flow_quarks); i++) {
168 if (ret == flow_quarks[i].ret)
169 return flow_quarks[i].name;
176 * @ret: a #GstFlowReturn to get the quark of.
178 * Get the unique quark for the given GstFlowReturn.
180 * Returns: the quark associated with the flow return or 0 if an
181 * invalid return was specified.
184 gst_flow_to_quark (GstFlowReturn ret)
188 ret = CLAMP (ret, GST_FLOW_CUSTOM_ERROR, GST_FLOW_CUSTOM_SUCCESS);
190 for (i = 0; i < G_N_ELEMENTS (flow_quarks); i++) {
191 if (ret == flow_quarks[i].ret)
192 return flow_quarks[i].quark;
201 buffer_quark = g_quark_from_static_string ("buffer"); \
202 event_quark = g_quark_from_static_string ("event"); \
204 for (i = 0; i < G_N_ELEMENTS (flow_quarks); i++) { \
205 flow_quarks[i].quark = g_quark_from_static_string (flow_quarks[i].name); \
208 GST_DEBUG_CATEGORY_INIT (debug_dataflow, "GST_DATAFLOW", \
209 GST_DEBUG_BOLD | GST_DEBUG_FG_GREEN, "dataflow inside pads"); \
212 G_DEFINE_TYPE_WITH_CODE (GstPad, gst_pad, GST_TYPE_OBJECT, _do_init);
215 _gst_do_pass_data_accumulator (GSignalInvocationHint * ihint,
216 GValue * return_accu, const GValue * handler_return, gpointer dummy)
218 gboolean ret = g_value_get_boolean (handler_return);
220 GST_DEBUG ("accumulated %d", ret);
221 g_value_set_boolean (return_accu, ret);
227 default_have_data (GstPad * pad, GstMiniObject * o)
233 gst_pad_class_init (GstPadClass * klass)
235 GObjectClass *gobject_class;
236 GstObjectClass *gstobject_class;
238 gobject_class = G_OBJECT_CLASS (klass);
239 gstobject_class = GST_OBJECT_CLASS (klass);
241 g_type_class_add_private (klass, sizeof (GstPadPrivate));
243 parent_class = g_type_class_peek_parent (klass);
245 gobject_class->dispose = GST_DEBUG_FUNCPTR (gst_pad_dispose);
246 gobject_class->finalize = GST_DEBUG_FUNCPTR (gst_pad_finalize);
247 gobject_class->set_property = GST_DEBUG_FUNCPTR (gst_pad_set_property);
248 gobject_class->get_property = GST_DEBUG_FUNCPTR (gst_pad_get_property);
252 * @pad: the pad that emitted the signal
253 * @peer: the peer pad that has been connected
255 * Signals that a pad has been linked to the peer pad.
257 gst_pad_signals[PAD_LINKED] =
258 g_signal_new ("linked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
259 G_STRUCT_OFFSET (GstPadClass, linked), NULL, NULL,
260 gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
263 * @pad: the pad that emitted the signal
264 * @peer: the peer pad that has been disconnected
266 * Signals that a pad has been unlinked from the peer pad.
268 gst_pad_signals[PAD_UNLINKED] =
269 g_signal_new ("unlinked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
270 G_STRUCT_OFFSET (GstPadClass, unlinked), NULL, NULL,
271 gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
273 * GstPad::request-link:
274 * @pad: the pad that emitted the signal
275 * @peer: the peer pad for which a connection is requested
277 * Signals that a pad connection has been requested.
279 gst_pad_signals[PAD_REQUEST_LINK] =
280 g_signal_new ("request-link", G_TYPE_FROM_CLASS (klass),
281 G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstPadClass, request_link), NULL,
282 NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 0);
286 * @pad: the pad that emitted the signal
287 * @mini_obj: new data
289 * Signals that new data is available on the pad. This signal is used
290 * internally for implementing pad probes.
291 * See gst_pad_add_*_probe functions.
293 * Returns: %TRUE to keep the data, %FALSE to drop it
295 gst_pad_signals[PAD_HAVE_DATA] =
296 g_signal_new ("have-data", G_TYPE_FROM_CLASS (klass),
297 G_SIGNAL_RUN_LAST | G_SIGNAL_DETAILED,
298 G_STRUCT_OFFSET (GstPadClass, have_data),
299 _gst_do_pass_data_accumulator,
300 NULL, gst_marshal_BOOLEAN__POINTER, G_TYPE_BOOLEAN, 1,
301 GST_TYPE_MINI_OBJECT);
303 g_object_class_install_property (gobject_class, PAD_PROP_CAPS,
304 g_param_spec_boxed ("caps", "Caps", "The capabilities of the pad",
305 GST_TYPE_CAPS, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
306 g_object_class_install_property (gobject_class, PAD_PROP_DIRECTION,
307 g_param_spec_enum ("direction", "Direction", "The direction of the pad",
308 GST_TYPE_PAD_DIRECTION, GST_PAD_UNKNOWN,
309 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
310 /* FIXME, Make G_PARAM_CONSTRUCT_ONLY when we fix ghostpads. */
311 g_object_class_install_property (gobject_class, PAD_PROP_TEMPLATE,
312 g_param_spec_object ("template", "Template",
313 "The GstPadTemplate of this pad", GST_TYPE_PAD_TEMPLATE,
314 G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
316 #ifndef GST_DISABLE_LOADSAVE
317 gstobject_class->save_thyself = GST_DEBUG_FUNCPTR (gst_pad_save_thyself);
319 gstobject_class->path_string_separator = ".";
321 klass->have_data = default_have_data;
325 gst_pad_init (GstPad * pad)
327 pad->abidata.ABI.priv = GST_PAD_GET_PRIVATE (pad);
329 GST_PAD_DIRECTION (pad) = GST_PAD_UNKNOWN;
330 GST_PAD_PEER (pad) = NULL;
332 GST_PAD_CHAINFUNC (pad) = NULL;
334 GST_PAD_LINKFUNC (pad) = NULL;
336 GST_PAD_CAPS (pad) = NULL;
337 GST_PAD_GETCAPSFUNC (pad) = NULL;
339 GST_PAD_ACTIVATEFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_activate_default);
340 GST_PAD_EVENTFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_event_default);
341 GST_PAD_QUERYTYPEFUNC (pad) =
342 GST_DEBUG_FUNCPTR (gst_pad_get_query_types_default);
343 GST_PAD_QUERYFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_query_default);
344 GST_PAD_INTLINKFUNC (pad) =
345 GST_DEBUG_FUNCPTR (gst_pad_get_internal_links_default);
346 GST_PAD_ITERINTLINKFUNC (pad) =
347 GST_DEBUG_FUNCPTR (gst_pad_iterate_internal_links_default);
349 GST_PAD_ACCEPTCAPSFUNC (pad) = GST_DEBUG_FUNCPTR (gst_pad_acceptcaps_default);
351 pad->do_buffer_signals = 0;
352 pad->do_event_signals = 0;
354 GST_PAD_SET_FLUSHING (pad);
356 pad->preroll_lock = g_mutex_new ();
357 pad->preroll_cond = g_cond_new ();
359 pad->stream_rec_lock = g_new (GStaticRecMutex, 1);
360 g_static_rec_mutex_init (pad->stream_rec_lock);
362 pad->block_cond = g_cond_new ();
366 gst_pad_dispose (GObject * object)
368 GstPad *pad = GST_PAD (object);
371 GST_CAT_DEBUG_OBJECT (GST_CAT_REFCOUNTING, pad, "dispose");
373 /* unlink the peer pad */
374 if ((peer = gst_pad_get_peer (pad))) {
375 /* window for MT unsafeness, someone else could unlink here
376 * and then we call unlink with wrong pads. The unlink
377 * function would catch this and safely return failed. */
378 if (GST_PAD_IS_SRC (pad))
379 gst_pad_unlink (pad, peer);
381 gst_pad_unlink (peer, pad);
383 gst_object_unref (peer);
387 gst_caps_replace (&GST_PAD_CAPS (pad), NULL);
389 gst_pad_set_pad_template (pad, NULL);
391 if (pad->block_destroy_data && pad->block_data) {
392 pad->block_destroy_data (pad->block_data);
393 pad->block_data = NULL;
396 G_OBJECT_CLASS (parent_class)->dispose (object);
400 gst_pad_finalize (GObject * object)
402 GstPad *pad = GST_PAD (object);
405 /* in case the task is still around, clean it up */
406 if ((task = GST_PAD_TASK (pad))) {
407 gst_task_join (task);
408 GST_PAD_TASK (pad) = NULL;
409 gst_object_unref (task);
412 if (pad->stream_rec_lock) {
413 g_static_rec_mutex_free (pad->stream_rec_lock);
414 g_free (pad->stream_rec_lock);
415 pad->stream_rec_lock = NULL;
417 if (pad->preroll_lock) {
418 g_mutex_free (pad->preroll_lock);
419 g_cond_free (pad->preroll_cond);
420 pad->preroll_lock = NULL;
421 pad->preroll_cond = NULL;
423 if (pad->block_cond) {
424 g_cond_free (pad->block_cond);
425 pad->block_cond = NULL;
428 G_OBJECT_CLASS (parent_class)->finalize (object);
432 gst_pad_set_property (GObject * object, guint prop_id,
433 const GValue * value, GParamSpec * pspec)
435 g_return_if_fail (GST_IS_PAD (object));
438 case PAD_PROP_DIRECTION:
439 GST_PAD_DIRECTION (object) = g_value_get_enum (value);
441 case PAD_PROP_TEMPLATE:
442 gst_pad_set_pad_template (GST_PAD_CAST (object),
443 (GstPadTemplate *) g_value_get_object (value));
446 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
452 gst_pad_get_property (GObject * object, guint prop_id,
453 GValue * value, GParamSpec * pspec)
455 g_return_if_fail (GST_IS_PAD (object));
459 GST_OBJECT_LOCK (object);
460 g_value_set_boxed (value, GST_PAD_CAPS (object));
461 GST_OBJECT_UNLOCK (object);
463 case PAD_PROP_DIRECTION:
464 g_value_set_enum (value, GST_PAD_DIRECTION (object));
466 case PAD_PROP_TEMPLATE:
467 g_value_set_object (value, GST_PAD_PAD_TEMPLATE (object));
470 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
477 * @name: the name of the new pad.
478 * @direction: the #GstPadDirection of the pad.
480 * Creates a new pad with the given name in the given direction.
481 * If name is NULL, a guaranteed unique name (across all pads)
483 * This function makes a copy of the name so you can safely free the name.
485 * Returns: a new #GstPad, or NULL in case of an error.
490 gst_pad_new (const gchar * name, GstPadDirection direction)
492 return g_object_new (GST_TYPE_PAD,
493 "name", name, "direction", direction, NULL);
497 * gst_pad_new_from_template:
498 * @templ: the pad template to use
499 * @name: the name of the element
501 * Creates a new pad with the given name from the given template.
502 * If name is NULL, a guaranteed unique name (across all pads)
504 * This function makes a copy of the name so you can safely free the name.
506 * Returns: a new #GstPad, or NULL in case of an error.
509 gst_pad_new_from_template (GstPadTemplate * templ, const gchar * name)
511 g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
513 return g_object_new (GST_TYPE_PAD,
514 "name", name, "direction", templ->direction, "template", templ, NULL);
518 * gst_pad_new_from_static_template:
519 * @templ: the #GstStaticPadTemplate to use
520 * @name: the name of the element
522 * Creates a new pad with the given name from the given static template.
523 * If name is NULL, a guaranteed unique name (across all pads)
525 * This function makes a copy of the name so you can safely free the name.
527 * Returns: a new #GstPad, or NULL in case of an error.
530 gst_pad_new_from_static_template (GstStaticPadTemplate * templ,
534 GstPadTemplate *template;
536 template = gst_static_pad_template_get (templ);
537 pad = gst_pad_new_from_template (template, name);
538 gst_object_unref (template);
543 * gst_pad_get_direction:
544 * @pad: a #GstPad to get the direction of.
546 * Gets the direction of the pad. The direction of the pad is
547 * decided at construction time so this function does not take
550 * Returns: the #GstPadDirection of the pad.
555 gst_pad_get_direction (GstPad * pad)
557 GstPadDirection result;
559 /* PAD_UNKNOWN is a little silly but we need some sort of
560 * error return value */
561 g_return_val_if_fail (GST_IS_PAD (pad), GST_PAD_UNKNOWN);
563 result = GST_PAD_DIRECTION (pad);
569 gst_pad_activate_default (GstPad * pad)
571 return gst_pad_activate_push (pad, TRUE);
575 pre_activate (GstPad * pad, GstActivateMode new_mode)
578 case GST_ACTIVATE_PUSH:
579 case GST_ACTIVATE_PULL:
580 GST_OBJECT_LOCK (pad);
581 GST_DEBUG_OBJECT (pad, "setting ACTIVATE_MODE %d, unset flushing",
583 GST_PAD_UNSET_FLUSHING (pad);
584 GST_PAD_ACTIVATE_MODE (pad) = new_mode;
585 GST_OBJECT_UNLOCK (pad);
587 case GST_ACTIVATE_NONE:
588 GST_OBJECT_LOCK (pad);
589 GST_DEBUG_OBJECT (pad, "setting ACTIVATE_MODE NONE, set flushing");
590 GST_PAD_SET_FLUSHING (pad);
591 GST_PAD_ACTIVATE_MODE (pad) = new_mode;
592 /* unlock blocked pads so element can resume and stop */
593 GST_PAD_BLOCK_BROADCAST (pad);
594 GST_OBJECT_UNLOCK (pad);
600 post_activate (GstPad * pad, GstActivateMode new_mode)
603 case GST_ACTIVATE_PUSH:
604 case GST_ACTIVATE_PULL:
607 case GST_ACTIVATE_NONE:
608 /* ensures that streaming stops */
609 GST_PAD_STREAM_LOCK (pad);
610 GST_DEBUG_OBJECT (pad, "stopped streaming");
611 GST_PAD_STREAM_UNLOCK (pad);
617 * gst_pad_set_active:
618 * @pad: the #GstPad to activate or deactivate.
619 * @active: whether or not the pad should be active.
621 * Activates or deactivates the given pad.
622 * Normally called from within core state change functions.
624 * If @active, makes sure the pad is active. If it is already active, either in
625 * push or pull mode, just return. Otherwise dispatches to the pad's activate
626 * function to perform the actual activation.
628 * If not @active, checks the pad's current mode and calls
629 * gst_pad_activate_push() or gst_pad_activate_pull(), as appropriate, with a
632 * Returns: #TRUE if the operation was successful.
637 gst_pad_set_active (GstPad * pad, gboolean active)
640 gboolean ret = FALSE;
642 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
644 GST_OBJECT_LOCK (pad);
645 old = GST_PAD_ACTIVATE_MODE (pad);
646 GST_OBJECT_UNLOCK (pad);
650 case GST_ACTIVATE_PUSH:
651 GST_DEBUG_OBJECT (pad, "activating pad from push");
654 case GST_ACTIVATE_PULL:
655 GST_DEBUG_OBJECT (pad, "activating pad from pull");
658 case GST_ACTIVATE_NONE:
659 GST_DEBUG_OBJECT (pad, "activating pad from none");
660 ret = (GST_PAD_ACTIVATEFUNC (pad)) (pad);
665 case GST_ACTIVATE_PUSH:
666 GST_DEBUG_OBJECT (pad, "deactivating pad from push");
667 ret = gst_pad_activate_push (pad, FALSE);
669 case GST_ACTIVATE_PULL:
670 GST_DEBUG_OBJECT (pad, "deactivating pad from pull");
671 ret = gst_pad_activate_pull (pad, FALSE);
673 case GST_ACTIVATE_NONE:
674 GST_DEBUG_OBJECT (pad, "deactivating pad from none");
681 GST_OBJECT_LOCK (pad);
683 g_critical ("Failed to deactivate pad %s:%s, very bad",
684 GST_DEBUG_PAD_NAME (pad));
686 GST_WARNING_OBJECT (pad, "Failed to activate pad");
688 GST_OBJECT_UNLOCK (pad);
695 * gst_pad_activate_pull:
696 * @pad: the #GstPad to activate or deactivate.
697 * @active: whether or not the pad should be active.
699 * Activates or deactivates the given pad in pull mode via dispatching to the
700 * pad's activatepullfunc. For use from within pad activation functions only.
701 * When called on sink pads, will first proxy the call to the peer pad, which
702 * is expected to activate its internally linked pads from within its
703 * activate_pull function.
705 * If you don't know what this is, you probably don't want to call it.
707 * Returns: TRUE if the operation was successful.
712 gst_pad_activate_pull (GstPad * pad, gboolean active)
714 GstActivateMode old, new;
717 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
719 GST_OBJECT_LOCK (pad);
720 old = GST_PAD_ACTIVATE_MODE (pad);
721 GST_OBJECT_UNLOCK (pad);
725 case GST_ACTIVATE_PULL:
726 GST_DEBUG_OBJECT (pad, "activating pad from pull, was ok");
728 case GST_ACTIVATE_PUSH:
729 GST_DEBUG_OBJECT (pad,
730 "activating pad from push, deactivate push first");
731 /* pad was activate in the wrong direction, deactivate it
732 * and reactivate it in pull mode */
733 if (G_UNLIKELY (!gst_pad_activate_push (pad, FALSE)))
734 goto deactivate_failed;
735 /* fallthrough, pad is deactivated now. */
736 case GST_ACTIVATE_NONE:
737 GST_DEBUG_OBJECT (pad, "activating pad from none");
742 case GST_ACTIVATE_NONE:
743 GST_DEBUG_OBJECT (pad, "deactivating pad from none, was ok");
745 case GST_ACTIVATE_PUSH:
746 GST_DEBUG_OBJECT (pad, "deactivating pad from push, weird");
747 /* pad was activated in the other direction, deactivate it
748 * in push mode, this should not happen... */
749 if (G_UNLIKELY (!gst_pad_activate_push (pad, FALSE)))
750 goto deactivate_failed;
751 /* everything is fine now */
753 case GST_ACTIVATE_PULL:
754 GST_DEBUG_OBJECT (pad, "deactivating pad from pull");
759 if (gst_pad_get_direction (pad) == GST_PAD_SINK) {
760 if ((peer = gst_pad_get_peer (pad))) {
761 GST_DEBUG_OBJECT (pad, "calling peer");
762 if (G_UNLIKELY (!gst_pad_activate_pull (peer, active)))
764 gst_object_unref (peer);
766 /* there is no peer, this is only fatal when we activate. When we
767 * deactivate, we must assume the application has unlinked the peer and
768 * will deactivate it eventually. */
772 GST_DEBUG_OBJECT (pad, "deactivating unlinked pad");
775 if (G_UNLIKELY (GST_PAD_GETRANGEFUNC (pad) == NULL))
776 goto failure; /* Can't activate pull on a src without a
780 new = active ? GST_ACTIVATE_PULL : GST_ACTIVATE_NONE;
781 pre_activate (pad, new);
783 if (GST_PAD_ACTIVATEPULLFUNC (pad)) {
784 if (G_UNLIKELY (!GST_PAD_ACTIVATEPULLFUNC (pad) (pad, active)))
787 /* can happen for sinks of passthrough elements */
790 post_activate (pad, new);
792 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "%s in pull mode",
793 active ? "activated" : "deactivated");
799 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "already %s in pull mode",
800 active ? "activated" : "deactivated");
805 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
806 "failed to %s in switch to pull from mode %d",
807 (active ? "activate" : "deactivate"), old);
812 GST_OBJECT_LOCK (peer);
813 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
814 "activate_pull on peer (%s:%s) failed", GST_DEBUG_PAD_NAME (peer));
815 GST_OBJECT_UNLOCK (peer);
816 gst_object_unref (peer);
821 GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "can't activate unlinked sink "
827 GST_OBJECT_LOCK (pad);
828 GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "failed to %s in pull mode",
829 active ? "activate" : "deactivate");
830 GST_PAD_SET_FLUSHING (pad);
831 GST_PAD_ACTIVATE_MODE (pad) = old;
832 GST_OBJECT_UNLOCK (pad);
838 * gst_pad_activate_push:
839 * @pad: the #GstPad to activate or deactivate.
840 * @active: whether the pad should be active or not.
842 * Activates or deactivates the given pad in push mode via dispatching to the
843 * pad's activatepushfunc. For use from within pad activation functions only.
845 * If you don't know what this is, you probably don't want to call it.
847 * Returns: %TRUE if the operation was successful.
852 gst_pad_activate_push (GstPad * pad, gboolean active)
854 GstActivateMode old, new;
856 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
857 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "trying to set %s in push mode",
858 active ? "activated" : "deactivated");
860 GST_OBJECT_LOCK (pad);
861 old = GST_PAD_ACTIVATE_MODE (pad);
862 GST_OBJECT_UNLOCK (pad);
866 case GST_ACTIVATE_PUSH:
867 GST_DEBUG_OBJECT (pad, "activating pad from push, was ok");
869 case GST_ACTIVATE_PULL:
870 GST_DEBUG_OBJECT (pad,
871 "activating pad from push, deactivating pull first");
872 /* pad was activate in the wrong direction, deactivate it
873 * an reactivate it in push mode */
874 if (G_UNLIKELY (!gst_pad_activate_pull (pad, FALSE)))
875 goto deactivate_failed;
876 /* fallthrough, pad is deactivated now. */
877 case GST_ACTIVATE_NONE:
878 GST_DEBUG_OBJECT (pad, "activating pad from none");
883 case GST_ACTIVATE_NONE:
884 GST_DEBUG_OBJECT (pad, "deactivating pad from none, was ok");
886 case GST_ACTIVATE_PULL:
887 GST_DEBUG_OBJECT (pad, "deactivating pad from pull, weird");
888 /* pad was activated in the other direction, deactivate it
889 * in pull mode, this should not happen... */
890 if (G_UNLIKELY (!gst_pad_activate_pull (pad, FALSE)))
891 goto deactivate_failed;
892 /* everything is fine now */
894 case GST_ACTIVATE_PUSH:
895 GST_DEBUG_OBJECT (pad, "deactivating pad from push");
900 new = active ? GST_ACTIVATE_PUSH : GST_ACTIVATE_NONE;
901 pre_activate (pad, new);
903 if (GST_PAD_ACTIVATEPUSHFUNC (pad)) {
904 if (G_UNLIKELY (!GST_PAD_ACTIVATEPUSHFUNC (pad) (pad, active))) {
908 /* quite ok, element relies on state change func to prepare itself */
911 post_activate (pad, new);
913 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "%s in push mode",
914 active ? "activated" : "deactivated");
919 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "already %s in push mode",
920 active ? "activated" : "deactivated");
925 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
926 "failed to %s in switch to push from mode %d",
927 (active ? "activate" : "deactivate"), old);
932 GST_OBJECT_LOCK (pad);
933 GST_CAT_INFO_OBJECT (GST_CAT_PADS, pad, "failed to %s in push mode",
934 active ? "activate" : "deactivate");
935 GST_PAD_SET_FLUSHING (pad);
936 GST_PAD_ACTIVATE_MODE (pad) = old;
937 GST_OBJECT_UNLOCK (pad);
944 * @pad: the #GstPad to query
946 * Query if a pad is active
948 * Returns: TRUE if the pad is active.
953 gst_pad_is_active (GstPad * pad)
955 gboolean result = FALSE;
957 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
959 GST_OBJECT_LOCK (pad);
960 result = GST_PAD_MODE_ACTIVATE (GST_PAD_ACTIVATE_MODE (pad));
961 GST_OBJECT_UNLOCK (pad);
967 * gst_pad_set_blocked_async_full:
968 * @pad: the #GstPad to block or unblock
969 * @blocked: boolean indicating whether the pad should be blocked or unblocked
970 * @callback: #GstPadBlockCallback that will be called when the
972 * @user_data: user data passed to the callback
973 * @destroy_data: #GDestroyNotify for user_data
975 * Blocks or unblocks the dataflow on a pad. The provided callback
976 * is called when the operation succeeds; this happens right before the next
977 * attempt at pushing a buffer on the pad.
979 * This can take a while as the pad can only become blocked when real dataflow
981 * When the pipeline is stalled, for example in PAUSED, this can
982 * take an indeterminate amount of time.
983 * You can pass NULL as the callback to make this call block. Be careful with
984 * this blocking call as it might not return for reasons stated above.
986 * Returns: TRUE if the pad could be blocked. This function can fail if the
987 * wrong parameters were passed or the pad was already in the requested state.
994 gst_pad_set_blocked_async_full (GstPad * pad, gboolean blocked,
995 GstPadBlockCallback callback, gpointer user_data,
996 GDestroyNotify destroy_data)
998 gboolean was_blocked = FALSE;
1000 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
1002 GST_OBJECT_LOCK (pad);
1004 was_blocked = GST_PAD_IS_BLOCKED (pad);
1006 if (G_UNLIKELY (was_blocked == blocked))
1007 goto had_right_state;
1010 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "blocking pad");
1012 GST_OBJECT_FLAG_SET (pad, GST_PAD_BLOCKED);
1014 if (pad->block_destroy_data && pad->block_data &&
1015 pad->block_data != user_data)
1016 pad->block_destroy_data (pad->block_data);
1018 pad->block_callback = callback;
1019 pad->block_data = user_data;
1020 pad->block_destroy_data = destroy_data;
1021 pad->abidata.ABI.block_callback_called = FALSE;
1023 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "waiting for block");
1024 GST_PAD_BLOCK_WAIT (pad);
1025 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "blocked");
1028 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "unblocking pad");
1030 GST_OBJECT_FLAG_UNSET (pad, GST_PAD_BLOCKED);
1032 if (pad->block_destroy_data && pad->block_data &&
1033 pad->block_data != user_data)
1034 pad->block_destroy_data (pad->block_data);
1036 pad->block_callback = callback;
1037 pad->block_data = user_data;
1038 pad->block_destroy_data = destroy_data;
1039 pad->abidata.ABI.block_callback_called = FALSE;
1041 GST_PAD_BLOCK_BROADCAST (pad);
1043 /* no callback, wait for the unblock to happen */
1044 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "waiting for unblock");
1045 GST_PAD_BLOCK_WAIT (pad);
1046 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "unblocked");
1049 GST_OBJECT_UNLOCK (pad);
1055 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
1056 "pad was in right state (%d)", was_blocked);
1057 GST_OBJECT_UNLOCK (pad);
1064 * gst_pad_set_blocked_async:
1065 * @pad: the #GstPad to block or unblock
1066 * @blocked: boolean indicating whether the pad should be blocked or unblocked
1067 * @callback: #GstPadBlockCallback that will be called when the
1068 * operation succeeds
1069 * @user_data: user data passed to the callback
1071 * Blocks or unblocks the dataflow on a pad. The provided callback
1072 * is called when the operation succeeds; this happens right before the next
1073 * attempt at pushing a buffer on the pad.
1075 * This can take a while as the pad can only become blocked when real dataflow
1077 * When the pipeline is stalled, for example in PAUSED, this can
1078 * take an indeterminate amount of time.
1079 * You can pass NULL as the callback to make this call block. Be careful with
1080 * this blocking call as it might not return for reasons stated above.
1082 * Returns: TRUE if the pad could be blocked. This function can fail if the
1083 * wrong parameters were passed or the pad was already in the requested state.
1088 gst_pad_set_blocked_async (GstPad * pad, gboolean blocked,
1089 GstPadBlockCallback callback, gpointer user_data)
1091 return gst_pad_set_blocked_async_full (pad, blocked,
1092 callback, user_data, NULL);
1096 * gst_pad_set_blocked:
1097 * @pad: the #GstPad to block or unblock
1098 * @blocked: boolean indicating we should block or unblock
1100 * Blocks or unblocks the dataflow on a pad. This function is
1101 * a shortcut for gst_pad_set_blocked_async() with a NULL
1104 * Returns: TRUE if the pad could be blocked. This function can fail if the
1105 * wrong parameters were passed or the pad was already in the requested state.
1110 gst_pad_set_blocked (GstPad * pad, gboolean blocked)
1112 return gst_pad_set_blocked_async (pad, blocked, NULL, NULL);
1116 * gst_pad_is_blocked:
1117 * @pad: the #GstPad to query
1119 * Checks if the pad is blocked or not. This function returns the
1120 * last requested state of the pad. It is not certain that the pad
1121 * is actually blocking at this point (see gst_pad_is_blocking()).
1123 * Returns: TRUE if the pad is blocked.
1128 gst_pad_is_blocked (GstPad * pad)
1130 gboolean result = FALSE;
1132 g_return_val_if_fail (GST_IS_PAD (pad), result);
1134 GST_OBJECT_LOCK (pad);
1135 result = GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_BLOCKED);
1136 GST_OBJECT_UNLOCK (pad);
1142 * gst_pad_is_blocking:
1143 * @pad: the #GstPad to query
1145 * Checks if the pad is blocking or not. This is a guaranteed state
1146 * of whether the pad is actually blocking on a #GstBuffer or a #GstEvent.
1148 * Returns: TRUE if the pad is blocking.
1155 gst_pad_is_blocking (GstPad * pad)
1157 gboolean result = FALSE;
1159 g_return_val_if_fail (GST_IS_PAD (pad), result);
1161 GST_OBJECT_LOCK (pad);
1162 /* the blocking flag is only valid if the pad is not flushing */
1163 result = GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_BLOCKING) &&
1164 !GST_OBJECT_FLAG_IS_SET (pad, GST_PAD_FLUSHING);
1165 GST_OBJECT_UNLOCK (pad);
1171 * gst_pad_set_activate_function:
1173 * @activate: the #GstPadActivateFunction to set.
1175 * Sets the given activate function for @pad. The activate function will
1176 * dispatch to gst_pad_activate_push() or gst_pad_activate_pull() to perform
1177 * the actual activation. Only makes sense to set on sink pads.
1179 * Call this function if your sink pad can start a pull-based task.
1182 gst_pad_set_activate_function (GstPad * pad, GstPadActivateFunction activate)
1184 g_return_if_fail (GST_IS_PAD (pad));
1186 GST_PAD_ACTIVATEFUNC (pad) = activate;
1187 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "activatefunc set to %s",
1188 GST_DEBUG_FUNCPTR_NAME (activate));
1192 * gst_pad_set_activatepull_function:
1194 * @activatepull: the #GstPadActivateModeFunction to set.
1196 * Sets the given activate_pull function for the pad. An activate_pull function
1197 * prepares the element and any upstream connections for pulling. See XXX
1198 * part-activation.txt for details.
1201 gst_pad_set_activatepull_function (GstPad * pad,
1202 GstPadActivateModeFunction activatepull)
1204 g_return_if_fail (GST_IS_PAD (pad));
1206 GST_PAD_ACTIVATEPULLFUNC (pad) = activatepull;
1207 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "activatepullfunc set to %s",
1208 GST_DEBUG_FUNCPTR_NAME (activatepull));
1212 * gst_pad_set_activatepush_function:
1214 * @activatepush: the #GstPadActivateModeFunction to set.
1216 * Sets the given activate_push function for the pad. An activate_push function
1217 * prepares the element for pushing. See XXX part-activation.txt for details.
1220 gst_pad_set_activatepush_function (GstPad * pad,
1221 GstPadActivateModeFunction activatepush)
1223 g_return_if_fail (GST_IS_PAD (pad));
1225 GST_PAD_ACTIVATEPUSHFUNC (pad) = activatepush;
1226 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "activatepushfunc set to %s",
1227 GST_DEBUG_FUNCPTR_NAME (activatepush));
1231 * gst_pad_set_chain_function:
1232 * @pad: a sink #GstPad.
1233 * @chain: the #GstPadChainFunction to set.
1235 * Sets the given chain function for the pad. The chain function is called to
1236 * process a #GstBuffer input buffer. see #GstPadChainFunction for more details.
1239 gst_pad_set_chain_function (GstPad * pad, GstPadChainFunction chain)
1241 g_return_if_fail (GST_IS_PAD (pad));
1242 g_return_if_fail (GST_PAD_IS_SINK (pad));
1244 GST_PAD_CHAINFUNC (pad) = chain;
1245 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "chainfunc set to %s",
1246 GST_DEBUG_FUNCPTR_NAME (chain));
1250 * gst_pad_set_chain_list_function:
1251 * @pad: a sink #GstPad.
1252 * @chainlist: the #GstPadChainListFunction to set.
1254 * Sets the given chain list function for the pad. The chainlist function is
1255 * called to process a #GstBufferList input buffer list. See
1256 * #GstPadChainListFunction for more details.
1261 gst_pad_set_chain_list_function (GstPad * pad,
1262 GstPadChainListFunction chainlist)
1264 g_return_if_fail (GST_IS_PAD (pad));
1265 g_return_if_fail (GST_PAD_IS_SINK (pad));
1267 GST_PAD_CHAINLISTFUNC (pad) = chainlist;
1268 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "chainlistfunc set to %s",
1269 GST_DEBUG_FUNCPTR_NAME (chainlist));
1273 * gst_pad_set_getrange_function:
1274 * @pad: a source #GstPad.
1275 * @get: the #GstPadGetRangeFunction to set.
1277 * Sets the given getrange function for the pad. The getrange function is
1278 * called to produce a new #GstBuffer to start the processing pipeline. see
1279 * #GstPadGetRangeFunction for a description of the getrange function.
1282 gst_pad_set_getrange_function (GstPad * pad, GstPadGetRangeFunction get)
1284 g_return_if_fail (GST_IS_PAD (pad));
1285 g_return_if_fail (GST_PAD_IS_SRC (pad));
1287 GST_PAD_GETRANGEFUNC (pad) = get;
1289 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "getrangefunc set to %s",
1290 GST_DEBUG_FUNCPTR_NAME (get));
1294 * gst_pad_set_checkgetrange_function:
1295 * @pad: a source #GstPad.
1296 * @check: the #GstPadCheckGetRangeFunction to set.
1298 * Sets the given checkgetrange function for the pad. Implement this function
1299 * on a pad if you dynamically support getrange based scheduling on the pad.
1302 gst_pad_set_checkgetrange_function (GstPad * pad,
1303 GstPadCheckGetRangeFunction check)
1305 g_return_if_fail (GST_IS_PAD (pad));
1306 g_return_if_fail (GST_PAD_IS_SRC (pad));
1308 GST_PAD_CHECKGETRANGEFUNC (pad) = check;
1310 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "checkgetrangefunc set to %s",
1311 GST_DEBUG_FUNCPTR_NAME (check));
1315 * gst_pad_set_event_function:
1316 * @pad: a #GstPad of either direction.
1317 * @event: the #GstPadEventFunction to set.
1319 * Sets the given event handler for the pad.
1322 gst_pad_set_event_function (GstPad * pad, GstPadEventFunction event)
1324 g_return_if_fail (GST_IS_PAD (pad));
1326 GST_PAD_EVENTFUNC (pad) = event;
1328 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "eventfunc for set to %s",
1329 GST_DEBUG_FUNCPTR_NAME (event));
1333 * gst_pad_set_query_function:
1334 * @pad: a #GstPad of either direction.
1335 * @query: the #GstPadQueryFunction to set.
1337 * Set the given query function for the pad.
1340 gst_pad_set_query_function (GstPad * pad, GstPadQueryFunction query)
1342 g_return_if_fail (GST_IS_PAD (pad));
1344 GST_PAD_QUERYFUNC (pad) = query;
1346 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "queryfunc set to %s",
1347 GST_DEBUG_FUNCPTR_NAME (query));
1351 * gst_pad_set_query_type_function:
1352 * @pad: a #GstPad of either direction.
1353 * @type_func: the #GstPadQueryTypeFunction to set.
1355 * Set the given query type function for the pad.
1358 gst_pad_set_query_type_function (GstPad * pad,
1359 GstPadQueryTypeFunction type_func)
1361 g_return_if_fail (GST_IS_PAD (pad));
1363 GST_PAD_QUERYTYPEFUNC (pad) = type_func;
1365 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "querytypefunc set to %s",
1366 GST_DEBUG_FUNCPTR_NAME (type_func));
1370 * gst_pad_get_query_types:
1373 * Get an array of supported queries that can be performed
1376 * Returns: a zero-terminated array of #GstQueryType.
1378 const GstQueryType *
1379 gst_pad_get_query_types (GstPad * pad)
1381 GstPadQueryTypeFunction func;
1383 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1385 if (G_UNLIKELY ((func = GST_PAD_QUERYTYPEFUNC (pad)) == NULL))
1397 gst_pad_get_query_types_dispatcher (GstPad * pad, const GstQueryType ** data)
1399 *data = gst_pad_get_query_types (pad);
1405 * gst_pad_get_query_types_default:
1408 * Invoke the default dispatcher for the query types on
1411 * Returns: an zero-terminated array of #GstQueryType, or NULL if none of the
1412 * internally-linked pads has a query types function.
1414 const GstQueryType *
1415 gst_pad_get_query_types_default (GstPad * pad)
1417 GstQueryType *result = NULL;
1419 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1421 gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
1422 gst_pad_get_query_types_dispatcher, &result);
1428 * gst_pad_set_iterate_internal_links_function:
1429 * @pad: a #GstPad of either direction.
1430 * @iterintlink: the #GstPadIterIntLinkFunction to set.
1432 * Sets the given internal link iterator function for the pad.
1437 gst_pad_set_iterate_internal_links_function (GstPad * pad,
1438 GstPadIterIntLinkFunction iterintlink)
1440 g_return_if_fail (GST_IS_PAD (pad));
1442 GST_PAD_ITERINTLINKFUNC (pad) = iterintlink;
1443 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "internal link iterator set to %s",
1444 GST_DEBUG_FUNCPTR_NAME (iterintlink));
1448 * gst_pad_set_internal_link_function:
1449 * @pad: a #GstPad of either direction.
1450 * @intlink: the #GstPadIntLinkFunction to set.
1452 * Sets the given internal link function for the pad.
1454 * Deprecated: Use the thread-safe gst_pad_set_iterate_internal_links_function()
1456 #ifndef GST_REMOVE_DEPRECATED
1458 gst_pad_set_internal_link_function (GstPad * pad, GstPadIntLinkFunction intlink)
1460 g_return_if_fail (GST_IS_PAD (pad));
1462 GST_PAD_INTLINKFUNC (pad) = intlink;
1463 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "internal link set to %s",
1464 GST_DEBUG_FUNCPTR_NAME (intlink));
1466 #endif /* GST_REMOVE_DEPRECATED */
1469 * gst_pad_set_link_function:
1471 * @link: the #GstPadLinkFunction to set.
1473 * Sets the given link function for the pad. It will be called when
1474 * the pad is linked with another pad.
1476 * The return value #GST_PAD_LINK_OK should be used when the connection can be
1479 * The return value #GST_PAD_LINK_REFUSED should be used when the connection
1480 * cannot be made for some reason.
1482 * If @link is installed on a source pad, it should call the #GstPadLinkFunction
1483 * of the peer sink pad, if present.
1486 gst_pad_set_link_function (GstPad * pad, GstPadLinkFunction link)
1488 g_return_if_fail (GST_IS_PAD (pad));
1490 GST_PAD_LINKFUNC (pad) = link;
1491 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "linkfunc set to %s",
1492 GST_DEBUG_FUNCPTR_NAME (link));
1496 * gst_pad_set_unlink_function:
1498 * @unlink: the #GstPadUnlinkFunction to set.
1500 * Sets the given unlink function for the pad. It will be called
1501 * when the pad is unlinked.
1504 gst_pad_set_unlink_function (GstPad * pad, GstPadUnlinkFunction unlink)
1506 g_return_if_fail (GST_IS_PAD (pad));
1508 GST_PAD_UNLINKFUNC (pad) = unlink;
1509 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "unlinkfunc set to %s",
1510 GST_DEBUG_FUNCPTR_NAME (unlink));
1514 * gst_pad_set_getcaps_function:
1516 * @getcaps: the #GstPadGetCapsFunction to set.
1518 * Sets the given getcaps function for the pad. @getcaps should return the
1519 * allowable caps for a pad in the context of the element's state, its link to
1520 * other elements, and the devices or files it has opened. These caps must be a
1521 * subset of the pad template caps. In the NULL state with no links, @getcaps
1522 * should ideally return the same caps as the pad template. In rare
1523 * circumstances, an object property can affect the caps returned by @getcaps,
1524 * but this is discouraged.
1526 * You do not need to call this function if @pad's allowed caps are always the
1527 * same as the pad template caps. This can only be true if the padtemplate
1528 * has fixed simple caps.
1530 * For most filters, the caps returned by @getcaps is directly affected by the
1531 * allowed caps on other pads. For demuxers and decoders, the caps returned by
1532 * the srcpad's getcaps function is directly related to the stream data. Again,
1533 * @getcaps should return the most specific caps it reasonably can, since this
1534 * helps with autoplugging.
1536 * Note that the return value from @getcaps is owned by the caller, so the
1537 * caller should unref the caps after usage.
1540 gst_pad_set_getcaps_function (GstPad * pad, GstPadGetCapsFunction getcaps)
1542 g_return_if_fail (GST_IS_PAD (pad));
1544 GST_PAD_GETCAPSFUNC (pad) = getcaps;
1545 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "getcapsfunc set to %s",
1546 GST_DEBUG_FUNCPTR_NAME (getcaps));
1550 * gst_pad_set_acceptcaps_function:
1552 * @acceptcaps: the #GstPadAcceptCapsFunction to set.
1554 * Sets the given acceptcaps function for the pad. The acceptcaps function
1555 * will be called to check if the pad can accept the given caps. Setting the
1556 * acceptcaps function to NULL restores the default behaviour of allowing
1557 * any caps that matches the caps from gst_pad_get_caps.
1560 gst_pad_set_acceptcaps_function (GstPad * pad,
1561 GstPadAcceptCapsFunction acceptcaps)
1563 g_return_if_fail (GST_IS_PAD (pad));
1565 GST_PAD_ACCEPTCAPSFUNC (pad) = acceptcaps;
1566 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "acceptcapsfunc set to %s",
1567 GST_DEBUG_FUNCPTR_NAME (acceptcaps));
1571 * gst_pad_set_fixatecaps_function:
1573 * @fixatecaps: the #GstPadFixateCapsFunction to set.
1575 * Sets the given fixatecaps function for the pad. The fixatecaps function
1576 * will be called whenever the default values for a GstCaps needs to be
1580 gst_pad_set_fixatecaps_function (GstPad * pad,
1581 GstPadFixateCapsFunction fixatecaps)
1583 g_return_if_fail (GST_IS_PAD (pad));
1585 GST_PAD_FIXATECAPSFUNC (pad) = fixatecaps;
1586 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "fixatecapsfunc set to %s",
1587 GST_DEBUG_FUNCPTR_NAME (fixatecaps));
1591 * gst_pad_set_setcaps_function:
1593 * @setcaps: the #GstPadSetCapsFunction to set.
1595 * Sets the given setcaps function for the pad. The setcaps function
1596 * will be called whenever a buffer with a new media type is pushed or
1597 * pulled from the pad. The pad/element needs to update its internal
1598 * structures to process the new media type. If this new type is not
1599 * acceptable, the setcaps function should return FALSE.
1602 gst_pad_set_setcaps_function (GstPad * pad, GstPadSetCapsFunction setcaps)
1604 g_return_if_fail (GST_IS_PAD (pad));
1606 GST_PAD_SETCAPSFUNC (pad) = setcaps;
1607 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "setcapsfunc set to %s",
1608 GST_DEBUG_FUNCPTR_NAME (setcaps));
1612 * gst_pad_set_bufferalloc_function:
1613 * @pad: a sink #GstPad.
1614 * @bufalloc: the #GstPadBufferAllocFunction to set.
1616 * Sets the given bufferalloc function for the pad. Note that the
1617 * bufferalloc function can only be set on sinkpads.
1620 gst_pad_set_bufferalloc_function (GstPad * pad,
1621 GstPadBufferAllocFunction bufalloc)
1623 g_return_if_fail (GST_IS_PAD (pad));
1624 g_return_if_fail (GST_PAD_IS_SINK (pad));
1626 GST_PAD_BUFFERALLOCFUNC (pad) = bufalloc;
1627 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "bufferallocfunc set to %s",
1628 GST_DEBUG_FUNCPTR_NAME (bufalloc));
1633 * @srcpad: the source #GstPad to unlink.
1634 * @sinkpad: the sink #GstPad to unlink.
1636 * Unlinks the source pad from the sink pad. Will emit the #GstPad::unlinked
1637 * signal on both pads.
1639 * Returns: TRUE if the pads were unlinked. This function returns FALSE if
1640 * the pads were not linked together.
1645 gst_pad_unlink (GstPad * srcpad, GstPad * sinkpad)
1647 gboolean result = FALSE;
1648 GstElement *parent = NULL;
1650 g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
1651 g_return_val_if_fail (GST_PAD_IS_SRC (srcpad), FALSE);
1652 g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
1653 g_return_val_if_fail (GST_PAD_IS_SINK (sinkpad), FALSE);
1655 GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "unlinking %s:%s(%p) and %s:%s(%p)",
1656 GST_DEBUG_PAD_NAME (srcpad), srcpad,
1657 GST_DEBUG_PAD_NAME (sinkpad), sinkpad);
1659 /* We need to notify the parent before taking any pad locks as the bin in
1660 * question might be waiting for a lock on the pad while holding its lock
1661 * that our message will try to take. */
1662 if ((parent = GST_ELEMENT_CAST (gst_pad_get_parent (srcpad)))) {
1663 if (GST_IS_ELEMENT (parent)) {
1664 gst_element_post_message (parent,
1665 gst_message_new_structure_change (GST_OBJECT_CAST (srcpad),
1666 GST_STRUCTURE_CHANGE_TYPE_PAD_UNLINK, parent, TRUE));
1668 gst_object_unref (parent);
1673 GST_OBJECT_LOCK (srcpad);
1675 GST_OBJECT_LOCK (sinkpad);
1677 if (G_UNLIKELY (GST_PAD_PEER (srcpad) != sinkpad))
1678 goto not_linked_together;
1680 if (GST_PAD_UNLINKFUNC (srcpad)) {
1681 GST_PAD_UNLINKFUNC (srcpad) (srcpad);
1683 if (GST_PAD_UNLINKFUNC (sinkpad)) {
1684 GST_PAD_UNLINKFUNC (sinkpad) (sinkpad);
1687 /* first clear peers */
1688 GST_PAD_PEER (srcpad) = NULL;
1689 GST_PAD_PEER (sinkpad) = NULL;
1691 GST_OBJECT_UNLOCK (sinkpad);
1692 GST_OBJECT_UNLOCK (srcpad);
1694 /* fire off a signal to each of the pads telling them
1695 * that they've been unlinked */
1696 g_signal_emit (G_OBJECT (srcpad), gst_pad_signals[PAD_UNLINKED], 0, sinkpad);
1697 g_signal_emit (G_OBJECT (sinkpad), gst_pad_signals[PAD_UNLINKED], 0, srcpad);
1699 GST_CAT_INFO (GST_CAT_ELEMENT_PADS, "unlinked %s:%s and %s:%s",
1700 GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1705 if (parent != NULL) {
1706 gst_element_post_message (parent,
1707 gst_message_new_structure_change (GST_OBJECT_CAST (srcpad),
1708 GST_STRUCTURE_CHANGE_TYPE_PAD_UNLINK, parent, FALSE));
1709 gst_object_unref (parent);
1714 not_linked_together:
1716 /* we do not emit a warning in this case because unlinking cannot
1717 * be made MT safe.*/
1718 GST_OBJECT_UNLOCK (sinkpad);
1719 GST_OBJECT_UNLOCK (srcpad);
1725 * gst_pad_is_linked:
1726 * @pad: pad to check
1728 * Checks if a @pad is linked to another pad or not.
1730 * Returns: TRUE if the pad is linked, FALSE otherwise.
1735 gst_pad_is_linked (GstPad * pad)
1739 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
1741 GST_OBJECT_LOCK (pad);
1742 result = (GST_PAD_PEER (pad) != NULL);
1743 GST_OBJECT_UNLOCK (pad);
1748 /* get the caps from both pads and see if the intersection
1751 * This function should be called with the pad LOCK on both
1755 gst_pad_link_check_compatible_unlocked (GstPad * src, GstPad * sink)
1761 srccaps = gst_pad_get_caps_unlocked (src);
1762 sinkcaps = gst_pad_get_caps_unlocked (sink);
1764 GST_CAT_DEBUG (GST_CAT_CAPS, "src caps %" GST_PTR_FORMAT, srccaps);
1765 GST_CAT_DEBUG (GST_CAT_CAPS, "sink caps %" GST_PTR_FORMAT, sinkcaps);
1767 /* if we have caps on both pads we can check the intersection. If one
1768 * of the caps is NULL, we return TRUE. */
1769 if (G_UNLIKELY (srccaps == NULL || sinkcaps == NULL)) {
1771 gst_caps_unref (srccaps);
1773 gst_caps_unref (sinkcaps);
1777 icaps = gst_caps_intersect (srccaps, sinkcaps);
1778 gst_caps_unref (srccaps);
1779 gst_caps_unref (sinkcaps);
1784 GST_CAT_DEBUG (GST_CAT_CAPS,
1785 "intersection caps %p %" GST_PTR_FORMAT, icaps, icaps);
1787 if (gst_caps_is_empty (icaps))
1790 gst_caps_unref (icaps);
1795 /* incompatible cases */
1798 GST_CAT_DEBUG (GST_CAT_CAPS, "intersection gave NULL");
1803 GST_CAT_DEBUG (GST_CAT_CAPS, "intersection is EMPTY");
1804 gst_caps_unref (icaps);
1809 /* check if the grandparents of both pads are the same.
1810 * This check is required so that we don't try to link
1811 * pads from elements in different bins without ghostpads.
1813 * The LOCK should be held on both pads
1816 gst_pad_link_check_hierarchy (GstPad * src, GstPad * sink)
1818 GstObject *psrc, *psink;
1820 psrc = GST_OBJECT_PARENT (src);
1821 psink = GST_OBJECT_PARENT (sink);
1823 /* if one of the pads has no parent, we allow the link */
1824 if (G_UNLIKELY (psrc == NULL || psink == NULL))
1827 /* only care about parents that are elements */
1828 if (G_UNLIKELY (!GST_IS_ELEMENT (psrc) || !GST_IS_ELEMENT (psink)))
1829 goto no_element_parent;
1831 /* if the parents are the same, we have a loop */
1832 if (G_UNLIKELY (psrc == psink))
1835 /* if they both have a parent, we check the grandparents. We can not lock
1836 * the parent because we hold on the child (pad) and the locking order is
1837 * parent >> child. */
1838 psrc = GST_OBJECT_PARENT (psrc);
1839 psink = GST_OBJECT_PARENT (psink);
1841 /* if they have grandparents but they are not the same */
1842 if (G_UNLIKELY (psrc != psink))
1843 goto wrong_grandparents;
1850 GST_CAT_DEBUG (GST_CAT_CAPS,
1851 "one of the pads has no parent %" GST_PTR_FORMAT " and %"
1852 GST_PTR_FORMAT, psrc, psink);
1857 GST_CAT_DEBUG (GST_CAT_CAPS,
1858 "one of the pads has no element parent %" GST_PTR_FORMAT " and %"
1859 GST_PTR_FORMAT, psrc, psink);
1864 GST_CAT_DEBUG (GST_CAT_CAPS, "pads have same parent %" GST_PTR_FORMAT,
1870 GST_CAT_DEBUG (GST_CAT_CAPS,
1871 "pads have different grandparents %" GST_PTR_FORMAT " and %"
1872 GST_PTR_FORMAT, psrc, psink);
1877 /* FIXME leftover from an attempt at refactoring... */
1878 /* call with the two pads unlocked, when this function returns GST_PAD_LINK_OK,
1879 * the two pads will be locked in the srcpad, sinkpad order. */
1880 static GstPadLinkReturn
1881 gst_pad_link_prepare (GstPad * srcpad, GstPad * sinkpad)
1883 GST_CAT_INFO (GST_CAT_PADS, "trying to link %s:%s and %s:%s",
1884 GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1886 GST_OBJECT_LOCK (srcpad);
1888 if (G_UNLIKELY (GST_PAD_PEER (srcpad) != NULL))
1889 goto src_was_linked;
1891 GST_OBJECT_LOCK (sinkpad);
1893 if (G_UNLIKELY (GST_PAD_PEER (sinkpad) != NULL))
1894 goto sink_was_linked;
1896 /* check hierarchy, pads can only be linked if the grandparents
1898 if (!gst_pad_link_check_hierarchy (srcpad, sinkpad))
1899 goto wrong_hierarchy;
1901 /* check pad caps for non-empty intersection */
1902 if (!gst_pad_link_check_compatible_unlocked (srcpad, sinkpad))
1905 /* FIXME check pad scheduling for non-empty intersection */
1907 return GST_PAD_LINK_OK;
1911 GST_CAT_INFO (GST_CAT_PADS, "src %s:%s was already linked to %s:%s",
1912 GST_DEBUG_PAD_NAME (srcpad),
1913 GST_DEBUG_PAD_NAME (GST_PAD_PEER (srcpad)));
1914 /* we do not emit a warning in this case because unlinking cannot
1915 * be made MT safe.*/
1916 GST_OBJECT_UNLOCK (srcpad);
1917 return GST_PAD_LINK_WAS_LINKED;
1921 GST_CAT_INFO (GST_CAT_PADS, "sink %s:%s was already linked to %s:%s",
1922 GST_DEBUG_PAD_NAME (sinkpad),
1923 GST_DEBUG_PAD_NAME (GST_PAD_PEER (sinkpad)));
1924 /* we do not emit a warning in this case because unlinking cannot
1925 * be made MT safe.*/
1926 GST_OBJECT_UNLOCK (sinkpad);
1927 GST_OBJECT_UNLOCK (srcpad);
1928 return GST_PAD_LINK_WAS_LINKED;
1932 GST_CAT_INFO (GST_CAT_PADS, "pads have wrong hierarchy");
1933 GST_OBJECT_UNLOCK (sinkpad);
1934 GST_OBJECT_UNLOCK (srcpad);
1935 return GST_PAD_LINK_WRONG_HIERARCHY;
1939 GST_CAT_INFO (GST_CAT_PADS, "caps are incompatible");
1940 GST_OBJECT_UNLOCK (sinkpad);
1941 GST_OBJECT_UNLOCK (srcpad);
1942 return GST_PAD_LINK_NOFORMAT;
1948 * @srcpad: the source #GstPad.
1949 * @sinkpad: the sink #GstPad.
1951 * Checks if the source pad and the sink pad are compatible so they can be
1954 * Returns: TRUE if the pads can be linked.
1957 gst_pad_can_link (GstPad * srcpad, GstPad * sinkpad)
1959 GstPadLinkReturn result;
1961 /* generic checks */
1962 g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
1963 g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
1965 GST_CAT_INFO (GST_CAT_PADS, "check if %s:%s can link with %s:%s",
1966 GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1968 /* gst_pad_link_prepare does everything for us, we only release the locks
1969 * on the pads that it gets us. If this function returns !OK the locks are not
1971 result = gst_pad_link_prepare (srcpad, sinkpad);
1972 if (result != GST_PAD_LINK_OK)
1975 GST_OBJECT_UNLOCK (srcpad);
1976 GST_OBJECT_UNLOCK (sinkpad);
1979 return result == GST_PAD_LINK_OK;
1984 * @srcpad: the source #GstPad to link.
1985 * @sinkpad: the sink #GstPad to link.
1987 * Links the source pad and the sink pad.
1989 * Returns: A result code indicating if the connection worked or
1995 gst_pad_link (GstPad * srcpad, GstPad * sinkpad)
1997 GstPadLinkReturn result;
2000 g_return_val_if_fail (GST_IS_PAD (srcpad), GST_PAD_LINK_REFUSED);
2001 g_return_val_if_fail (GST_PAD_IS_SRC (srcpad), GST_PAD_LINK_WRONG_DIRECTION);
2002 g_return_val_if_fail (GST_IS_PAD (sinkpad), GST_PAD_LINK_REFUSED);
2003 g_return_val_if_fail (GST_PAD_IS_SINK (sinkpad),
2004 GST_PAD_LINK_WRONG_DIRECTION);
2006 /* Notify the parent early. See gst_pad_unlink for details. */
2007 if ((parent = GST_ELEMENT_CAST (gst_pad_get_parent (srcpad)))) {
2008 if (GST_IS_ELEMENT (parent)) {
2009 gst_element_post_message (parent,
2010 gst_message_new_structure_change (GST_OBJECT_CAST (srcpad),
2011 GST_STRUCTURE_CHANGE_TYPE_PAD_LINK, parent, TRUE));
2013 gst_object_unref (parent);
2018 /* prepare will also lock the two pads */
2019 result = gst_pad_link_prepare (srcpad, sinkpad);
2021 if (result != GST_PAD_LINK_OK)
2024 /* must set peers before calling the link function */
2025 GST_PAD_PEER (srcpad) = sinkpad;
2026 GST_PAD_PEER (sinkpad) = srcpad;
2028 GST_OBJECT_UNLOCK (sinkpad);
2029 GST_OBJECT_UNLOCK (srcpad);
2031 /* FIXME released the locks here, concurrent thread might link
2032 * something else. */
2033 if (GST_PAD_LINKFUNC (srcpad)) {
2034 /* this one will call the peer link function */
2035 result = GST_PAD_LINKFUNC (srcpad) (srcpad, sinkpad);
2036 } else if (GST_PAD_LINKFUNC (sinkpad)) {
2037 /* if no source link function, we need to call the sink link
2038 * function ourselves. */
2039 result = GST_PAD_LINKFUNC (sinkpad) (sinkpad, srcpad);
2041 result = GST_PAD_LINK_OK;
2044 GST_OBJECT_LOCK (srcpad);
2045 GST_OBJECT_LOCK (sinkpad);
2047 if (result == GST_PAD_LINK_OK) {
2048 GST_OBJECT_UNLOCK (sinkpad);
2049 GST_OBJECT_UNLOCK (srcpad);
2051 /* fire off a signal to each of the pads telling them
2052 * that they've been linked */
2053 g_signal_emit (G_OBJECT (srcpad), gst_pad_signals[PAD_LINKED], 0, sinkpad);
2054 g_signal_emit (G_OBJECT (sinkpad), gst_pad_signals[PAD_LINKED], 0, srcpad);
2056 GST_CAT_INFO (GST_CAT_PADS, "linked %s:%s and %s:%s, successful",
2057 GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
2059 GST_CAT_INFO (GST_CAT_PADS, "link between %s:%s and %s:%s failed",
2060 GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
2062 GST_PAD_PEER (srcpad) = NULL;
2063 GST_PAD_PEER (sinkpad) = NULL;
2065 GST_OBJECT_UNLOCK (sinkpad);
2066 GST_OBJECT_UNLOCK (srcpad);
2071 gst_element_post_message (parent,
2072 gst_message_new_structure_change (GST_OBJECT_CAST (srcpad),
2073 GST_STRUCTURE_CHANGE_TYPE_PAD_LINK, parent, FALSE));
2074 gst_object_unref (parent);
2081 gst_pad_set_pad_template (GstPad * pad, GstPadTemplate * templ)
2083 GstPadTemplate **template_p;
2085 /* this function would need checks if it weren't static */
2087 GST_OBJECT_LOCK (pad);
2088 template_p = &pad->padtemplate;
2089 gst_object_replace ((GstObject **) template_p, (GstObject *) templ);
2090 GST_OBJECT_UNLOCK (pad);
2093 gst_pad_template_pad_created (templ, pad);
2097 * gst_pad_get_pad_template:
2100 * Gets the template for @pad.
2102 * Returns: the #GstPadTemplate from which this pad was instantiated, or %NULL
2103 * if this pad has no template.
2105 * FIXME: currently returns an unrefcounted padtemplate.
2108 gst_pad_get_pad_template (GstPad * pad)
2110 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2112 return GST_PAD_PAD_TEMPLATE (pad);
2116 /* should be called with the pad LOCK held */
2117 /* refs the caps, so caller is responsible for getting it unreffed */
2119 gst_pad_get_caps_unlocked (GstPad * pad)
2121 GstCaps *result = NULL;
2122 GstPadTemplate *templ;
2124 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get pad caps");
2126 if (GST_PAD_GETCAPSFUNC (pad)) {
2127 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2128 "dispatching to pad getcaps function");
2130 GST_OBJECT_FLAG_SET (pad, GST_PAD_IN_GETCAPS);
2131 GST_OBJECT_UNLOCK (pad);
2132 result = GST_PAD_GETCAPSFUNC (pad) (pad);
2133 GST_OBJECT_LOCK (pad);
2134 GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_GETCAPS);
2136 if (result == NULL) {
2137 g_critical ("pad %s:%s returned NULL caps from getcaps function",
2138 GST_DEBUG_PAD_NAME (pad));
2140 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2141 "pad getcaps returned %" GST_PTR_FORMAT, result);
2142 #ifndef G_DISABLE_ASSERT
2143 /* check that the returned caps are a real subset of the template caps */
2144 if (GST_PAD_PAD_TEMPLATE (pad)) {
2145 const GstCaps *templ_caps =
2146 GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad));
2147 if (!gst_caps_is_subset (result, templ_caps)) {
2150 GST_CAT_ERROR_OBJECT (GST_CAT_CAPS, pad,
2151 "pad returned caps %" GST_PTR_FORMAT
2152 " which are not a real subset of its template caps %"
2153 GST_PTR_FORMAT, result, templ_caps);
2155 ("pad %s:%s returned caps which are not a real "
2156 "subset of its template caps", GST_DEBUG_PAD_NAME (pad));
2157 temp = gst_caps_intersect (templ_caps, result);
2158 gst_caps_unref (result);
2166 if ((templ = GST_PAD_PAD_TEMPLATE (pad))) {
2167 result = GST_PAD_TEMPLATE_CAPS (templ);
2168 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2169 "using pad template %p with caps %p %" GST_PTR_FORMAT, templ, result,
2172 result = gst_caps_ref (result);
2175 if ((result = GST_PAD_CAPS (pad))) {
2176 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2177 "using pad caps %p %" GST_PTR_FORMAT, result, result);
2179 result = gst_caps_ref (result);
2183 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "pad has no caps");
2184 result = gst_caps_new_empty ();
2192 * @pad: a #GstPad to get the capabilities of.
2194 * Gets the capabilities this pad can produce or consume.
2195 * Note that this method doesn't necessarily return the caps set by
2196 * gst_pad_set_caps() - use GST_PAD_CAPS() for that instead.
2197 * gst_pad_get_caps returns all possible caps a pad can operate with, using
2198 * the pad's get_caps function;
2199 * this returns the pad template caps if not explicitly set.
2201 * Returns: a newly allocated copy of the #GstCaps of this pad.
2206 gst_pad_get_caps (GstPad * pad)
2208 GstCaps *result = NULL;
2210 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2212 GST_OBJECT_LOCK (pad);
2214 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get pad caps");
2216 result = gst_pad_get_caps_unlocked (pad);
2218 /* be sure that we have a copy */
2220 result = gst_caps_make_writable (result);
2222 GST_OBJECT_UNLOCK (pad);
2228 * gst_pad_peer_get_caps:
2229 * @pad: a #GstPad to get the peer capabilities of.
2231 * Gets the capabilities of the peer connected to this pad.
2233 * Returns: the #GstCaps of the peer pad. This function returns a new caps, so
2234 * use gst_caps_unref to get rid of it. this function returns NULL if there is
2238 gst_pad_peer_get_caps (GstPad * pad)
2241 GstCaps *result = NULL;
2243 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2245 GST_OBJECT_LOCK (pad);
2247 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "get peer caps");
2249 peerpad = GST_PAD_PEER (pad);
2250 if (G_UNLIKELY (peerpad == NULL))
2253 gst_object_ref (peerpad);
2254 GST_OBJECT_UNLOCK (pad);
2256 result = gst_pad_get_caps (peerpad);
2258 gst_object_unref (peerpad);
2264 GST_OBJECT_UNLOCK (pad);
2270 fixate_value (GValue * dest, const GValue * src)
2272 if (G_VALUE_TYPE (src) == GST_TYPE_INT_RANGE) {
2273 g_value_init (dest, G_TYPE_INT);
2274 g_value_set_int (dest, gst_value_get_int_range_min (src));
2275 } else if (G_VALUE_TYPE (src) == GST_TYPE_DOUBLE_RANGE) {
2276 g_value_init (dest, G_TYPE_DOUBLE);
2277 g_value_set_double (dest, gst_value_get_double_range_min (src));
2278 } else if (G_VALUE_TYPE (src) == GST_TYPE_FRACTION_RANGE) {
2279 gst_value_init_and_copy (dest, gst_value_get_fraction_range_min (src));
2280 } else if (G_VALUE_TYPE (src) == GST_TYPE_LIST) {
2281 GValue temp = { 0 };
2283 /* list could be empty */
2284 if (gst_value_list_get_size (src) <= 0)
2287 gst_value_init_and_copy (&temp, gst_value_list_get_value (src, 0));
2289 if (!fixate_value (dest, &temp))
2290 gst_value_init_and_copy (dest, &temp);
2291 g_value_unset (&temp);
2292 } else if (G_VALUE_TYPE (src) == GST_TYPE_ARRAY) {
2293 gboolean res = FALSE;
2296 len = gst_value_array_get_size (src);
2297 g_value_init (dest, GST_TYPE_ARRAY);
2298 for (n = 0; n < len; n++) {
2300 const GValue *orig_kid = gst_value_array_get_value (src, n);
2302 if (!fixate_value (&kid, orig_kid))
2303 gst_value_init_and_copy (&kid, orig_kid);
2306 gst_value_array_append_value (dest, &kid);
2307 g_value_unset (&kid);
2311 g_value_unset (dest);
2322 gst_pad_default_fixate (GQuark field_id, const GValue * value, gpointer data)
2324 GstStructure *s = data;
2327 if (fixate_value (&v, value)) {
2328 gst_structure_id_set_value (s, field_id, &v);
2336 * gst_pad_fixate_caps:
2337 * @pad: a #GstPad to fixate
2338 * @caps: the #GstCaps to fixate
2340 * Fixate a caps on the given pad. Modifies the caps in place, so you should
2341 * make sure that the caps are actually writable (see gst_caps_make_writable()).
2344 gst_pad_fixate_caps (GstPad * pad, GstCaps * caps)
2346 GstPadFixateCapsFunction fixatefunc;
2349 g_return_if_fail (GST_IS_PAD (pad));
2350 g_return_if_fail (caps != NULL);
2352 if (gst_caps_is_fixed (caps))
2355 fixatefunc = GST_PAD_FIXATECAPSFUNC (pad);
2357 fixatefunc (pad, caps);
2360 /* default fixation */
2361 len = gst_caps_get_size (caps);
2362 for (n = 0; n < len; n++) {
2363 GstStructure *s = gst_caps_get_structure (caps, n);
2365 gst_structure_foreach (s, gst_pad_default_fixate, s);
2369 /* Default accept caps implementation just checks against
2370 * against the allowed caps for the pad */
2372 gst_pad_acceptcaps_default (GstPad * pad, GstCaps * caps)
2374 /* get the caps and see if it intersects to something
2378 gboolean result = FALSE;
2380 GST_DEBUG_OBJECT (pad, "caps %" GST_PTR_FORMAT, caps);
2382 allowed = gst_pad_get_caps (pad);
2384 goto nothing_allowed;
2386 GST_DEBUG_OBJECT (pad, "allowed caps %" GST_PTR_FORMAT, allowed);
2388 intersect = gst_caps_intersect (allowed, caps);
2390 GST_DEBUG_OBJECT (pad, "intersection %" GST_PTR_FORMAT, intersect);
2392 result = !gst_caps_is_empty (intersect);
2394 gst_caps_unref (allowed);
2395 gst_caps_unref (intersect);
2402 GST_DEBUG_OBJECT (pad, "no caps allowed on the pad");
2408 * gst_pad_accept_caps:
2409 * @pad: a #GstPad to check
2410 * @caps: a #GstCaps to check on the pad
2412 * Check if the given pad accepts the caps.
2414 * Returns: TRUE if the pad can accept the caps.
2417 gst_pad_accept_caps (GstPad * pad, GstCaps * caps)
2420 GstPadAcceptCapsFunction acceptfunc;
2421 GstCaps *existing = NULL;
2423 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2425 /* any pad can be unnegotiated */
2429 /* lock for checking the existing caps */
2430 GST_OBJECT_LOCK (pad);
2431 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "accept caps of %p", caps);
2432 /* The current caps on a pad are trivially acceptable */
2433 if (G_LIKELY ((existing = GST_PAD_CAPS (pad)))) {
2434 if (caps == existing || gst_caps_is_equal (caps, existing))
2437 acceptfunc = GST_PAD_ACCEPTCAPSFUNC (pad);
2438 GST_OBJECT_UNLOCK (pad);
2440 if (G_LIKELY (acceptfunc)) {
2441 /* we can call the function */
2442 result = acceptfunc (pad, caps);
2443 GST_DEBUG_OBJECT (pad, "acceptfunc returned %d", result);
2445 /* Only null if the element explicitly unset it */
2446 result = gst_pad_acceptcaps_default (pad, caps);
2447 GST_DEBUG_OBJECT (pad, "default acceptcaps returned %d", result);
2453 GST_DEBUG_OBJECT (pad, "pad had same caps");
2454 GST_OBJECT_UNLOCK (pad);
2460 * gst_pad_peer_accept_caps:
2461 * @pad: a #GstPad to check the peer of
2462 * @caps: a #GstCaps to check on the pad
2464 * Check if the peer of @pad accepts @caps. If @pad has no peer, this function
2467 * Returns: TRUE if the peer of @pad can accept the caps or @pad has no peer.
2470 gst_pad_peer_accept_caps (GstPad * pad, GstCaps * caps)
2475 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2477 GST_OBJECT_LOCK (pad);
2479 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "peer accept caps of (%p)", pad);
2481 peerpad = GST_PAD_PEER (pad);
2482 if (G_UNLIKELY (peerpad == NULL))
2485 gst_object_ref (peerpad);
2486 /* release lock before calling external methods but keep ref to pad */
2487 GST_OBJECT_UNLOCK (pad);
2489 result = gst_pad_accept_caps (peerpad, caps);
2491 gst_object_unref (peerpad);
2497 GST_OBJECT_UNLOCK (pad);
2504 * @pad: a #GstPad to set the capabilities of.
2505 * @caps: a #GstCaps to set.
2507 * Sets the capabilities of this pad. The caps must be fixed. Any previous
2508 * caps on the pad will be unreffed. This function refs the caps so you should
2509 * unref if as soon as you don't need it anymore.
2510 * It is possible to set NULL caps, which will make the pad unnegotiated
2513 * Returns: TRUE if the caps could be set. FALSE if the caps were not fixed
2514 * or bad parameters were provided to this function.
2519 gst_pad_set_caps (GstPad * pad, GstCaps * caps)
2521 GstPadSetCapsFunction setcaps;
2524 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2525 g_return_val_if_fail (caps == NULL || gst_caps_is_fixed (caps), FALSE);
2527 GST_OBJECT_LOCK (pad);
2528 existing = GST_PAD_CAPS (pad);
2529 if (existing == caps)
2532 if (gst_caps_is_equal (caps, existing))
2533 goto setting_same_caps;
2535 setcaps = GST_PAD_SETCAPSFUNC (pad);
2537 /* call setcaps function to configure the pad only if the
2538 * caps is not NULL */
2539 if (setcaps != NULL && caps) {
2540 if (!GST_PAD_IS_IN_SETCAPS (pad)) {
2541 GST_OBJECT_FLAG_SET (pad, GST_PAD_IN_SETCAPS);
2542 GST_OBJECT_UNLOCK (pad);
2543 if (!setcaps (pad, caps))
2545 GST_OBJECT_LOCK (pad);
2546 GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_SETCAPS);
2548 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "pad was dispatching");
2552 gst_caps_replace (&GST_PAD_CAPS (pad), caps);
2553 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "caps %" GST_PTR_FORMAT, caps);
2554 GST_OBJECT_UNLOCK (pad);
2556 g_object_notify (G_OBJECT (pad), "caps");
2562 GST_OBJECT_UNLOCK (pad);
2567 gst_caps_replace (&GST_PAD_CAPS (pad), caps);
2568 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2569 "caps %" GST_PTR_FORMAT " same as existing, updating ptr only", caps);
2570 GST_OBJECT_UNLOCK (pad);
2577 GST_OBJECT_LOCK (pad);
2578 GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_SETCAPS);
2579 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2580 "caps %" GST_PTR_FORMAT " could not be set", caps);
2581 GST_OBJECT_UNLOCK (pad);
2588 gst_pad_configure_sink (GstPad * pad, GstCaps * caps)
2592 /* See if pad accepts the caps */
2593 if (!gst_pad_accept_caps (pad, caps))
2596 /* set caps on pad if call succeeds */
2597 res = gst_pad_set_caps (pad, caps);
2598 /* no need to unref the caps here, set_caps takes a ref and
2599 * our ref goes away when we leave this function. */
2605 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2606 "caps %" GST_PTR_FORMAT " not accepted", caps);
2611 /* returns TRUE if the src pad could be configured to accept the given caps */
2613 gst_pad_configure_src (GstPad * pad, GstCaps * caps, gboolean dosetcaps)
2618 /* See if pad accepts the caps */
2619 if (!gst_pad_accept_caps (pad, caps))
2622 res = gst_pad_set_caps (pad, caps);
2630 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2631 "caps %" GST_PTR_FORMAT " not accepted", caps);
2637 * gst_pad_get_pad_template_caps:
2638 * @pad: a #GstPad to get the template capabilities from.
2640 * Gets the capabilities for @pad's template.
2642 * Returns: the #GstCaps of this pad template. If you intend to keep a
2643 * reference on the caps, make a copy (see gst_caps_copy ()).
2646 gst_pad_get_pad_template_caps (GstPad * pad)
2648 static GstStaticCaps anycaps = GST_STATIC_CAPS ("ANY");
2650 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2652 if (GST_PAD_PAD_TEMPLATE (pad))
2653 return GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad));
2655 return gst_static_caps_get (&anycaps);
2660 * @pad: a #GstPad to get the peer of.
2662 * Gets the peer of @pad. This function refs the peer pad so
2663 * you need to unref it after use.
2665 * Returns: the peer #GstPad. Unref after usage.
2670 gst_pad_get_peer (GstPad * pad)
2674 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2676 GST_OBJECT_LOCK (pad);
2677 result = GST_PAD_PEER (pad);
2679 gst_object_ref (result);
2680 GST_OBJECT_UNLOCK (pad);
2686 * gst_pad_get_allowed_caps:
2689 * Gets the capabilities of the allowed media types that can flow through
2690 * @pad and its peer.
2692 * The allowed capabilities is calculated as the intersection of the results of
2693 * calling gst_pad_get_caps() on @pad and its peer. The caller owns a reference
2694 * on the resulting caps.
2696 * Returns: the allowed #GstCaps of the pad link. Unref the caps when you no
2697 * longer need it. This function returns NULL when @pad has no peer.
2702 gst_pad_get_allowed_caps (GstPad * pad)
2709 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2711 GST_OBJECT_LOCK (pad);
2713 peer = GST_PAD_PEER (pad);
2714 if (G_UNLIKELY (peer == NULL))
2717 GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "getting allowed caps");
2719 gst_object_ref (peer);
2720 GST_OBJECT_UNLOCK (pad);
2721 mycaps = gst_pad_get_caps (pad);
2723 peercaps = gst_pad_get_caps (peer);
2724 gst_object_unref (peer);
2726 caps = gst_caps_intersect (mycaps, peercaps);
2727 gst_caps_unref (peercaps);
2728 gst_caps_unref (mycaps);
2730 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "allowed caps %" GST_PTR_FORMAT,
2737 GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "no peer");
2738 GST_OBJECT_UNLOCK (pad);
2745 * gst_pad_get_negotiated_caps:
2748 * Gets the capabilities of the media type that currently flows through @pad
2751 * This function can be used on both src and sinkpads. Note that srcpads are
2752 * always negotiated before sinkpads so it is possible that the negotiated caps
2753 * on the srcpad do not match the negotiated caps of the peer.
2755 * Returns: the negotiated #GstCaps of the pad link. Unref the caps when
2756 * you no longer need it. This function returns NULL when the @pad has no
2757 * peer or is not negotiated yet.
2762 gst_pad_get_negotiated_caps (GstPad * pad)
2767 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2769 GST_OBJECT_LOCK (pad);
2771 if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
2774 GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "getting negotiated caps");
2776 caps = GST_PAD_CAPS (pad);
2778 gst_caps_ref (caps);
2779 GST_OBJECT_UNLOCK (pad);
2781 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "negotiated caps %" GST_PTR_FORMAT,
2788 GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "no peer");
2789 GST_OBJECT_UNLOCK (pad);
2795 /* calls the buffer_alloc function on the given pad */
2796 static GstFlowReturn
2797 gst_pad_buffer_alloc_unchecked (GstPad * pad, guint64 offset, gint size,
2798 GstCaps * caps, GstBuffer ** buf)
2801 GstPadBufferAllocFunction bufferallocfunc;
2803 GST_OBJECT_LOCK (pad);
2804 /* when the pad is flushing we cannot give a buffer */
2805 if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
2808 bufferallocfunc = pad->bufferallocfunc;
2810 if (offset == GST_BUFFER_OFFSET_NONE) {
2811 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2812 "calling bufferallocfunc &%s (@%p) for size %d offset NONE",
2813 GST_DEBUG_FUNCPTR_NAME (bufferallocfunc), bufferallocfunc, size);
2815 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2816 "calling bufferallocfunc &%s (@%p) of for size %d offset %"
2817 G_GUINT64_FORMAT, GST_DEBUG_FUNCPTR_NAME (bufferallocfunc),
2818 bufferallocfunc, size, offset);
2820 GST_OBJECT_UNLOCK (pad);
2822 /* G_LIKELY for now since most elements don't implement a buffer alloc
2823 * function and there is no default alloc proxy function as this is usually
2825 if (G_LIKELY (bufferallocfunc == NULL))
2828 ret = bufferallocfunc (pad, offset, size, caps, buf);
2830 if (G_UNLIKELY (ret != GST_FLOW_OK))
2833 /* no error, but NULL buffer means fallback to the default */
2834 if (G_UNLIKELY (*buf == NULL))
2837 /* If the buffer alloc function didn't set up the caps like it should,
2839 if (G_UNLIKELY (caps && (GST_BUFFER_CAPS (*buf) == NULL))) {
2840 GST_WARNING_OBJECT (pad,
2841 "Buffer allocation function did not set caps. Setting");
2842 gst_buffer_set_caps (*buf, caps);
2848 /* pad was flushing */
2849 GST_OBJECT_UNLOCK (pad);
2850 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "pad was flushing");
2851 return GST_FLOW_WRONG_STATE;
2855 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2856 "alloc function returned error (%d) %s", ret, gst_flow_get_name (ret));
2861 /* fallback case, allocate a buffer of our own, add pad caps. */
2862 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "fallback buffer alloc");
2864 if ((*buf = gst_buffer_try_new_and_alloc (size))) {
2865 GST_BUFFER_OFFSET (*buf) = offset;
2866 gst_buffer_set_caps (*buf, caps);
2869 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2870 "out of memory allocating %d bytes", size);
2871 return GST_FLOW_ERROR;
2876 /* FIXME 0.11: size should be unsigned */
2877 static GstFlowReturn
2878 gst_pad_alloc_buffer_full (GstPad * pad, guint64 offset, gint size,
2879 GstCaps * caps, GstBuffer ** buf, gboolean setcaps)
2884 gboolean caps_changed;
2886 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
2887 g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
2888 g_return_val_if_fail (buf != NULL, GST_FLOW_ERROR);
2889 g_return_val_if_fail (size >= 0, GST_FLOW_ERROR);
2891 GST_DEBUG_OBJECT (pad, "offset %" G_GUINT64_FORMAT ", size %d, caps %"
2892 GST_PTR_FORMAT, offset, size, caps);
2894 GST_OBJECT_LOCK (pad);
2895 while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
2896 if ((ret = handle_pad_block (pad)) != GST_FLOW_OK)
2899 if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
2902 gst_object_ref (peer);
2903 GST_OBJECT_UNLOCK (pad);
2905 ret = gst_pad_buffer_alloc_unchecked (peer, offset, size, caps, buf);
2906 gst_object_unref (peer);
2908 if (G_UNLIKELY (ret != GST_FLOW_OK))
2911 /* FIXME, move capnego this into a base class? */
2912 newcaps = GST_BUFFER_CAPS (*buf);
2914 /* Lock for checking caps, pretty pointless as the _pad_push() function might
2915 * change it concurrently, one of the problems with automatic caps setting in
2916 * pad_alloc_and_set_caps. Worst case, if does a check too much, but only
2917 * when there is heavy renegotiation going on in both directions. */
2918 GST_OBJECT_LOCK (pad);
2919 caps_changed = newcaps && newcaps != GST_PAD_CAPS (pad);
2920 GST_OBJECT_UNLOCK (pad);
2922 /* we got a new datatype on the pad, see if it can handle it */
2923 if (G_UNLIKELY (caps_changed)) {
2924 GST_DEBUG_OBJECT (pad,
2925 "caps changed from %" GST_PTR_FORMAT " to %p %" GST_PTR_FORMAT,
2926 GST_PAD_CAPS (pad), newcaps, newcaps);
2927 if (G_UNLIKELY (!gst_pad_configure_src (pad, newcaps, setcaps)))
2928 goto not_negotiated;
2931 /* sanity check (only if caps are the same) */
2932 if (G_LIKELY (newcaps == caps) && G_UNLIKELY (GST_BUFFER_SIZE (*buf) < size))
2933 goto wrong_size_fallback;
2939 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "pad block stopped by flush");
2940 GST_OBJECT_UNLOCK (pad);
2945 /* pad has no peer */
2946 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2947 "called bufferallocfunc but had no peer");
2948 GST_OBJECT_UNLOCK (pad);
2949 return GST_FLOW_NOT_LINKED;
2953 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
2954 "alloc function returned error %s", gst_flow_get_name (ret));
2959 gst_buffer_unref (*buf);
2961 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
2962 "alloc function returned unacceptable buffer");
2963 return GST_FLOW_NOT_NEGOTIATED;
2965 wrong_size_fallback:
2967 GST_CAT_ERROR_OBJECT (GST_CAT_PADS, pad, "buffer returned by alloc "
2968 "function is too small (%u < %d), doing fallback buffer alloc",
2969 GST_BUFFER_SIZE (*buf), size);
2971 gst_buffer_unref (*buf);
2973 if ((*buf = gst_buffer_try_new_and_alloc (size))) {
2974 GST_BUFFER_OFFSET (*buf) = offset;
2975 gst_buffer_set_caps (*buf, caps);
2978 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2979 "out of memory allocating %d bytes", size);
2980 return GST_FLOW_ERROR;
2986 * gst_pad_alloc_buffer:
2987 * @pad: a source #GstPad
2988 * @offset: the offset of the new buffer in the stream
2989 * @size: the size of the new buffer
2990 * @caps: the caps of the new buffer
2991 * @buf: a newly allocated buffer
2993 * Allocates a new, empty buffer optimized to push to pad @pad. This
2994 * function only works if @pad is a source pad and has a peer.
2996 * A new, empty #GstBuffer will be put in the @buf argument.
2997 * You need to check the caps of the buffer after performing this
2998 * function and renegotiate to the format if needed. If the caps changed, it is
2999 * possible that the buffer returned in @buf is not of the right size for the
3000 * new format, @buf needs to be unreffed and reallocated if this is the case.
3002 * Returns: a result code indicating success of the operation. Any
3003 * result code other than #GST_FLOW_OK is an error and @buf should
3005 * An error can occur if the pad is not connected or when the downstream
3006 * peer elements cannot provide an acceptable buffer.
3011 /* FIXME 0.11: size should be unsigned */
3013 gst_pad_alloc_buffer (GstPad * pad, guint64 offset, gint size, GstCaps * caps,
3016 return gst_pad_alloc_buffer_full (pad, offset, size, caps, buf, FALSE);
3020 * gst_pad_alloc_buffer_and_set_caps:
3021 * @pad: a source #GstPad
3022 * @offset: the offset of the new buffer in the stream
3023 * @size: the size of the new buffer
3024 * @caps: the caps of the new buffer
3025 * @buf: a newly allocated buffer
3027 * In addition to the function gst_pad_alloc_buffer(), this function
3028 * automatically calls gst_pad_set_caps() when the caps of the
3029 * newly allocated buffer are different from the @pad caps.
3031 * After a renegotiation, the size of the new buffer returned in @buf could
3032 * be of the wrong size for the new format and must be unreffed an reallocated
3035 * Returns: a result code indicating success of the operation. Any
3036 * result code other than #GST_FLOW_OK is an error and @buf should
3038 * An error can occur if the pad is not connected or when the downstream
3039 * peer elements cannot provide an acceptable buffer.
3044 /* FIXME 0.11: size should be unsigned */
3046 gst_pad_alloc_buffer_and_set_caps (GstPad * pad, guint64 offset, gint size,
3047 GstCaps * caps, GstBuffer ** buf)
3049 return gst_pad_alloc_buffer_full (pad, offset, size, caps, buf, TRUE);
3053 #ifndef GST_REMOVE_DEPRECATED
3061 int_link_iter_data_free (IntLinkIterData * data)
3063 g_list_free (data->list);
3068 static GstIteratorItem
3069 iterate_pad (GstIterator * it, GstPad * pad)
3071 gst_object_ref (pad);
3072 return GST_ITERATOR_ITEM_PASS;
3076 * gst_pad_iterate_internal_links_default:
3077 * @pad: the #GstPad to get the internal links of.
3079 * Iterate the list of pads to which the given pad is linked to inside of
3080 * the parent element.
3081 * This is the default handler, and thus returns an iterator of all of the
3082 * pads inside the parent element with opposite direction.
3084 * The caller must free this iterator after use with gst_iterator_free().
3086 * Returns: a #GstIterator of #GstPad, or NULL if @pad has no parent. Unref each
3087 * returned pad with gst_object_unref().
3092 gst_pad_iterate_internal_links_default (GstPad * pad)
3099 GstIteratorDisposeFunction dispose;
3101 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
3103 #ifndef GST_REMOVE_DEPRECATED
3104 /* when we get here, the default handler for the iterate links is called,
3105 * which means that the user has not installed a custom one. We first check if
3106 * there is maybe a custom legacy function we can call. */
3107 if (GST_PAD_INTLINKFUNC (pad) &&
3108 GST_PAD_INTLINKFUNC (pad) != gst_pad_get_internal_links_default) {
3109 IntLinkIterData *data;
3111 /* make an iterator for the list. We can't protect the list with a
3112 * cookie. If we would take the cookie of the parent element, we need to
3113 * have a parent, which is not required for GST_PAD_INTLINKFUNC(). We could
3114 * cache the per-pad list and invalidate the list when a new call to
3115 * INTLINKFUNC() returned a different list but then this would only work if
3116 * two concurrent iterators were used and the last iterator would still be
3117 * thread-unsafe. Just don't use this method anymore. */
3118 data = g_new0 (IntLinkIterData, 1);
3119 data->list = GST_PAD_INTLINKFUNC (pad) (pad);
3122 GST_WARNING_OBJECT (pad, "Making unsafe iterator");
3124 cookie = &data->cookie;
3125 padlist = &data->list;
3127 dispose = (GstIteratorDisposeFunction) int_link_iter_data_free;
3128 /* reuse the pad lock, it's all we have here */
3129 lock = GST_OBJECT_GET_LOCK (pad);
3135 GST_OBJECT_LOCK (pad);
3136 parent = GST_PAD_PARENT (pad);
3137 if (!parent || !GST_IS_ELEMENT (parent))
3140 gst_object_ref (parent);
3141 GST_OBJECT_UNLOCK (pad);
3143 if (pad->direction == GST_PAD_SRC)
3144 padlist = &parent->sinkpads;
3146 padlist = &parent->srcpads;
3148 GST_DEBUG_OBJECT (pad, "Making iterator");
3150 cookie = &parent->pads_cookie;
3152 dispose = (GstIteratorDisposeFunction) gst_object_unref;
3153 lock = GST_OBJECT_GET_LOCK (parent);
3156 res = gst_iterator_new_list (GST_TYPE_PAD,
3157 lock, cookie, padlist, owner, (GstIteratorItemFunction) iterate_pad,
3165 GST_OBJECT_UNLOCK (pad);
3166 GST_DEBUG_OBJECT (pad, "no parent element");
3172 * gst_pad_iterate_internal_links:
3173 * @pad: the GstPad to get the internal links of.
3175 * Gets an iterator for the pads to which the given pad is linked to inside
3176 * of the parent element.
3178 * Each #GstPad element yielded by the iterator will have its refcount increased,
3179 * so unref after use.
3181 * Returns: a new #GstIterator of #GstPad or %NULL when the pad does not have an
3182 * iterator function configured. Use gst_iterator_free() after usage.
3187 gst_pad_iterate_internal_links (GstPad * pad)
3189 GstIterator *res = NULL;
3191 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
3193 if (GST_PAD_ITERINTLINKFUNC (pad))
3194 res = GST_PAD_ITERINTLINKFUNC (pad) (pad);
3199 #ifndef GST_REMOVE_DEPRECATED
3201 add_unref_pad_to_list (GstPad * pad, GList * list)
3203 list = g_list_prepend (list, pad);
3204 gst_object_unref (pad);
3209 * gst_pad_get_internal_links_default:
3210 * @pad: the #GstPad to get the internal links of.
3212 * Gets a list of pads to which the given pad is linked to
3213 * inside of the parent element.
3214 * This is the default handler, and thus returns a list of all of the
3215 * pads inside the parent element with opposite direction.
3217 * The caller must free this list after use with g_list_free().
3219 * Returns: a newly allocated #GList of pads, or NULL if the pad has no parent.
3223 * Deprecated: This function does not ref the pads in the list so that they
3224 * could become invalid by the time the application accesses them. It's also
3225 * possible that the list changes while handling the pads, which the caller of
3226 * this function is unable to know. Use the thread-safe
3227 * gst_pad_iterate_internal_links_default() instead.
3229 #ifndef GST_REMOVE_DEPRECATED
3231 gst_pad_get_internal_links_default (GstPad * pad)
3236 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
3238 GST_WARNING_OBJECT (pad, "Unsafe internal links used");
3240 /* when we get here, the default handler for get_internal_links is called,
3241 * which means that the user has not installed a custom one. We first check if
3242 * there is maybe a custom iterate function we can call. */
3243 if (GST_PAD_ITERINTLINKFUNC (pad) &&
3244 GST_PAD_ITERINTLINKFUNC (pad) != gst_pad_iterate_internal_links_default) {
3246 GstIteratorResult ires;
3247 gboolean done = FALSE;
3249 it = gst_pad_iterate_internal_links (pad);
3250 /* loop over the iterator and put all elements into a list, we also
3251 * immediatly unref them, which is bad. */
3253 ires = gst_iterator_foreach (it, (GFunc) add_unref_pad_to_list, res);
3255 case GST_ITERATOR_OK:
3256 case GST_ITERATOR_DONE:
3257 case GST_ITERATOR_ERROR:
3260 case GST_ITERATOR_RESYNC:
3261 /* restart, discard previous list */
3262 gst_iterator_resync (it);
3269 gst_iterator_free (it);
3271 /* lock pad, check and ref parent */
3272 GST_OBJECT_LOCK (pad);
3273 parent = GST_PAD_PARENT (pad);
3274 if (!parent || !GST_IS_ELEMENT (parent))
3277 parent = gst_object_ref (parent);
3278 GST_OBJECT_UNLOCK (pad);
3280 /* now lock the parent while we copy the pads */
3281 GST_OBJECT_LOCK (parent);
3282 if (pad->direction == GST_PAD_SRC)
3283 res = g_list_copy (parent->sinkpads);
3285 res = g_list_copy (parent->srcpads);
3286 GST_OBJECT_UNLOCK (parent);
3288 gst_object_unref (parent);
3291 /* At this point pads can be changed and unreffed. Nothing we can do about it
3292 * because for compatibility reasons this function cannot ref the pads or
3293 * notify the app that the list changed. */
3299 GST_DEBUG_OBJECT (pad, "no parent");
3300 GST_OBJECT_UNLOCK (pad);
3304 #endif /* GST_REMOVE_DEPRECATED */
3307 * gst_pad_get_internal_links:
3308 * @pad: the #GstPad to get the internal links of.
3310 * Gets a list of pads to which the given pad is linked to
3311 * inside of the parent element.
3312 * The caller must free this list after use.
3316 * Returns: a newly allocated #GList of pads, free with g_list_free().
3318 * Deprecated: This function does not ref the pads in the list so that they
3319 * could become invalid by the time the application accesses them. It's also
3320 * possible that the list changes while handling the pads, which the caller of
3321 * this function is unable to know. Use the thread-safe
3322 * gst_pad_iterate_internal_links() instead.
3324 #ifndef GST_REMOVE_DEPRECATED
3326 gst_pad_get_internal_links (GstPad * pad)
3330 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
3332 GST_WARNING_OBJECT (pad, "Calling unsafe internal links");
3334 if (GST_PAD_INTLINKFUNC (pad))
3335 res = GST_PAD_INTLINKFUNC (pad) (pad);
3339 #endif /* GST_REMOVE_DEPRECATED */
3342 gst_pad_event_default_dispatch (GstPad * pad, GstEvent * event)
3344 gboolean result = FALSE;
3346 gboolean done = FALSE;
3349 GList *pushed_pads = NULL;
3351 GST_INFO_OBJECT (pad, "Sending event %p (%s) to all internally linked pads",
3352 event, GST_EVENT_TYPE_NAME (event));
3354 iter = gst_pad_iterate_internal_links (pad);
3360 switch (gst_iterator_next (iter, &item)) {
3361 case GST_ITERATOR_OK:
3362 eventpad = GST_PAD (item);
3364 /* if already pushed, skip */
3365 if (g_list_find (pushed_pads, eventpad)) {
3366 gst_object_unref (item);
3370 if (GST_PAD_IS_SRC (eventpad)) {
3371 /* for each pad we send to, we should ref the event; it's up
3372 * to downstream to unref again when handled. */
3373 GST_LOG_OBJECT (pad, "Reffing and sending event %p (%s) to %s:%s",
3374 event, GST_EVENT_TYPE_NAME (event),
3375 GST_DEBUG_PAD_NAME (eventpad));
3376 gst_event_ref (event);
3377 result |= gst_pad_push_event (eventpad, event);
3379 /* we only send the event on one pad, multi-sinkpad elements
3380 * should implement a handler */
3381 GST_LOG_OBJECT (pad, "sending event %p (%s) to one sink pad %s:%s",
3382 event, GST_EVENT_TYPE_NAME (event),
3383 GST_DEBUG_PAD_NAME (eventpad));
3384 result = gst_pad_push_event (eventpad, event);
3389 pushed_pads = g_list_prepend (pushed_pads, eventpad);
3391 gst_object_unref (item);
3393 case GST_ITERATOR_RESYNC:
3394 /* FIXME, if we want to reset the result value we need to remember which
3395 * pads pushed with which result */
3396 gst_iterator_resync (iter);
3398 case GST_ITERATOR_ERROR:
3399 GST_ERROR_OBJECT (pad, "Could not iterate over internally linked pads");
3402 case GST_ITERATOR_DONE:
3407 gst_iterator_free (iter);
3411 /* If this is a sinkpad and we don't have pads to send the event to, we
3412 * return TRUE. This is so that when using the default handler on a sink
3413 * element, we don't fail to push it. */
3415 result = GST_PAD_IS_SINK (pad);
3417 g_list_free (pushed_pads);
3419 /* we handled the incoming event so we unref once */
3421 GST_LOG_OBJECT (pad, "handled event %p, unreffing", event);
3422 gst_event_unref (event);
3429 * gst_pad_event_default:
3430 * @pad: a #GstPad to call the default event handler on.
3431 * @event: the #GstEvent to handle.
3433 * Invokes the default event handler for the given pad. End-of-stream and
3434 * discontinuity events are handled specially, and then the event is sent to all
3435 * pads internally linked to @pad. Note that if there are many possible sink
3436 * pads that are internally linked to @pad, only one will be sent an event.
3437 * Multi-sinkpad elements should implement custom event handlers.
3439 * Returns: TRUE if the event was sent succesfully.
3442 gst_pad_event_default (GstPad * pad, GstEvent * event)
3444 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3445 g_return_val_if_fail (event != NULL, FALSE);
3447 GST_LOG_OBJECT (pad, "default event handler");
3449 switch (GST_EVENT_TYPE (event)) {
3452 GST_DEBUG_OBJECT (pad, "pausing task because of eos");
3453 gst_pad_pause_task (pad);
3460 return gst_pad_event_default_dispatch (pad, event);
3464 * gst_pad_dispatcher:
3465 * @pad: a #GstPad to dispatch.
3466 * @dispatch: the #GstDispatcherFunction to call.
3467 * @data: gpointer user data passed to the dispatcher function.
3469 * Invokes the given dispatcher function on each respective peer of
3470 * all pads that are internally linked to the given pad.
3471 * The GstPadDispatcherFunction should return TRUE when no further pads
3472 * need to be processed.
3474 * Returns: TRUE if one of the dispatcher functions returned TRUE.
3477 gst_pad_dispatcher (GstPad * pad, GstPadDispatcherFunction dispatch,
3480 gboolean res = FALSE;
3481 GstIterator *iter = NULL;
3482 gboolean done = FALSE;
3485 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3486 g_return_val_if_fail (dispatch != NULL, FALSE);
3488 iter = gst_pad_iterate_internal_links (pad);
3494 switch (gst_iterator_next (iter, &item)) {
3495 case GST_ITERATOR_OK:
3497 GstPad *int_pad = GST_PAD_CAST (item);
3498 GstPad *int_peer = gst_pad_get_peer (int_pad);
3501 GST_DEBUG_OBJECT (int_pad, "dispatching to peer %s:%s",
3502 GST_DEBUG_PAD_NAME (int_peer));
3503 done = res = dispatch (int_peer, data);
3504 gst_object_unref (int_peer);
3506 GST_DEBUG_OBJECT (int_pad, "no peer");
3509 gst_object_unref (item);
3511 case GST_ITERATOR_RESYNC:
3512 gst_iterator_resync (iter);
3514 case GST_ITERATOR_ERROR:
3516 GST_ERROR_OBJECT (pad, "Could not iterate internally linked pads");
3518 case GST_ITERATOR_DONE:
3523 gst_iterator_free (iter);
3525 GST_DEBUG_OBJECT (pad, "done, result %d", res);
3534 * @pad: a #GstPad to invoke the default query on.
3535 * @query: the #GstQuery to perform.
3537 * Dispatches a query to a pad. The query should have been allocated by the
3538 * caller via one of the type-specific allocation functions in gstquery.h. The
3539 * element is responsible for filling the query with an appropriate response,
3540 * which should then be parsed with a type-specific query parsing function.
3542 * Again, the caller is responsible for both the allocation and deallocation of
3543 * the query structure.
3545 * Returns: TRUE if the query could be performed.
3548 gst_pad_query (GstPad * pad, GstQuery * query)
3550 GstPadQueryFunction func;
3552 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3553 g_return_val_if_fail (GST_IS_QUERY (query), FALSE);
3555 GST_DEBUG_OBJECT (pad, "sending query %p", query);
3557 if ((func = GST_PAD_QUERYFUNC (pad)) == NULL)
3560 return func (pad, query);
3564 GST_DEBUG_OBJECT (pad, "had no query function");
3570 * gst_pad_peer_query:
3571 * @pad: a #GstPad to invoke the peer query on.
3572 * @query: the #GstQuery to perform.
3574 * Performs gst_pad_query() on the peer of @pad.
3576 * The caller is responsible for both the allocation and deallocation of
3577 * the query structure.
3579 * Returns: TRUE if the query could be performed. This function returns %FALSE
3580 * if @pad has no peer.
3585 gst_pad_peer_query (GstPad * pad, GstQuery * query)
3590 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3591 g_return_val_if_fail (GST_IS_QUERY (query), FALSE);
3593 GST_OBJECT_LOCK (pad);
3595 GST_DEBUG_OBJECT (pad, "peer query");
3597 peerpad = GST_PAD_PEER (pad);
3598 if (G_UNLIKELY (peerpad == NULL))
3601 gst_object_ref (peerpad);
3602 GST_OBJECT_UNLOCK (pad);
3604 result = gst_pad_query (peerpad, query);
3606 gst_object_unref (peerpad);
3613 GST_WARNING_OBJECT (pad, "pad has no peer");
3614 GST_OBJECT_UNLOCK (pad);
3620 * gst_pad_query_default:
3621 * @pad: a #GstPad to call the default query handler on.
3622 * @query: the #GstQuery to handle.
3624 * Invokes the default query handler for the given pad.
3625 * The query is sent to all pads internally linked to @pad. Note that
3626 * if there are many possible sink pads that are internally linked to
3627 * @pad, only one will be sent the query.
3628 * Multi-sinkpad elements should implement custom query handlers.
3630 * Returns: TRUE if the query was performed succesfully.
3633 gst_pad_query_default (GstPad * pad, GstQuery * query)
3635 switch (GST_QUERY_TYPE (query)) {
3636 case GST_QUERY_POSITION:
3637 case GST_QUERY_SEEKING:
3638 case GST_QUERY_FORMATS:
3639 case GST_QUERY_LATENCY:
3640 case GST_QUERY_JITTER:
3641 case GST_QUERY_RATE:
3642 case GST_QUERY_CONVERT:
3644 return gst_pad_dispatcher
3645 (pad, (GstPadDispatcherFunction) gst_pad_query, query);
3649 #ifndef GST_DISABLE_LOADSAVE
3650 /* FIXME: why isn't this on a GstElement ? */
3652 * gst_pad_load_and_link:
3653 * @self: an #xmlNodePtr to read the description from.
3654 * @parent: the #GstObject element that owns the pad.
3656 * Reads the pad definition from the XML node and links the given pad
3657 * in the element to a pad of an element up in the hierarchy.
3660 gst_pad_load_and_link (xmlNodePtr self, GstObject * parent)
3662 xmlNodePtr field = self->xmlChildrenNode;
3663 GstPad *pad = NULL, *targetpad;
3664 GstPadTemplate *tmpl;
3668 GstObject *grandparent;
3672 if (!strcmp ((char *) field->name, "name")) {
3673 name = (gchar *) xmlNodeGetContent (field);
3674 pad = gst_element_get_static_pad (GST_ELEMENT (parent), name);
3675 if ((!pad) || ((tmpl = gst_pad_get_pad_template (pad))
3676 && (GST_PAD_REQUEST == GST_PAD_TEMPLATE_PRESENCE (tmpl))))
3677 pad = gst_element_get_request_pad (GST_ELEMENT (parent), name);
3679 } else if (!strcmp ((char *) field->name, "peer")) {
3680 peer = (gchar *) xmlNodeGetContent (field);
3682 field = field->next;
3684 g_return_if_fail (pad != NULL);
3689 split = g_strsplit (peer, ".", 2);
3691 if (split[0] == NULL || split[1] == NULL) {
3692 GST_CAT_DEBUG_OBJECT (GST_CAT_XML, pad,
3693 "Could not parse peer '%s', leaving unlinked", peer);
3700 g_return_if_fail (split[0] != NULL);
3701 g_return_if_fail (split[1] != NULL);
3703 grandparent = gst_object_get_parent (parent);
3705 if (grandparent && GST_IS_BIN (grandparent)) {
3706 target = gst_bin_get_by_name_recurse_up (GST_BIN (grandparent), split[0]);
3713 targetpad = gst_element_get_static_pad (target, split[1]);
3715 targetpad = gst_element_get_request_pad (target, split[1]);
3717 if (targetpad == NULL)
3720 if (gst_pad_get_direction (pad) == GST_PAD_SRC)
3721 gst_pad_link (pad, targetpad);
3723 gst_pad_link (targetpad, pad);
3730 * gst_pad_save_thyself:
3731 * @pad: a #GstPad to save.
3732 * @parent: the parent #xmlNodePtr to save the description in.
3734 * Saves the pad into an xml representation.
3736 * Returns: the #xmlNodePtr representation of the pad.
3739 gst_pad_save_thyself (GstObject * object, xmlNodePtr parent)
3744 g_return_val_if_fail (GST_IS_PAD (object), NULL);
3746 pad = GST_PAD (object);
3748 xmlNewChild (parent, NULL, (xmlChar *) "name",
3749 (xmlChar *) GST_PAD_NAME (pad));
3751 if (GST_PAD_IS_SRC (pad)) {
3752 xmlNewChild (parent, NULL, (xmlChar *) "direction", (xmlChar *) "source");
3753 } else if (GST_PAD_IS_SINK (pad)) {
3754 xmlNewChild (parent, NULL, (xmlChar *) "direction", (xmlChar *) "sink");
3756 xmlNewChild (parent, NULL, (xmlChar *) "direction", (xmlChar *) "unknown");
3759 if (GST_PAD_PEER (pad) != NULL) {
3762 peer = GST_PAD_PEER (pad);
3763 /* first check to see if the peer's parent's parent is the same */
3764 /* we just save it off */
3765 content = g_strdup_printf ("%s.%s",
3766 GST_OBJECT_NAME (GST_PAD_PARENT (peer)), GST_PAD_NAME (peer));
3767 xmlNewChild (parent, NULL, (xmlChar *) "peer", (xmlChar *) content);
3770 xmlNewChild (parent, NULL, (xmlChar *) "peer", NULL);
3777 * gst_ghost_pad_save_thyself:
3778 * @pad: a ghost #GstPad to save.
3779 * @parent: the parent #xmlNodePtr to save the description in.
3781 * Saves the ghost pad into an xml representation.
3783 * Returns: the #xmlNodePtr representation of the pad.
3786 gst_ghost_pad_save_thyself (GstPad * pad, xmlNodePtr parent)
3790 g_return_val_if_fail (GST_IS_GHOST_PAD (pad), NULL);
3792 self = xmlNewChild (parent, NULL, (xmlChar *) "ghostpad", NULL);
3793 xmlNewChild (self, NULL, (xmlChar *) "name", (xmlChar *) GST_PAD_NAME (pad));
3794 xmlNewChild (self, NULL, (xmlChar *) "parent",
3795 (xmlChar *) GST_OBJECT_NAME (GST_PAD_PARENT (pad)));
3797 /* FIXME FIXME FIXME! */
3802 #endif /* GST_DISABLE_LOADSAVE */
3805 * should be called with pad OBJECT_LOCK and STREAM_LOCK held.
3806 * GST_PAD_IS_BLOCKED (pad) == TRUE when this function is
3809 * This function performs the pad blocking when an event, buffer push
3810 * or buffer_alloc is performed on a _SRC_ pad. It blocks the
3811 * streaming thread after informing the pad has been blocked.
3813 * An application can with this method wait and block any streaming
3814 * thread and perform operations such as seeking or linking.
3816 * Two methods are available for notifying the application of the
3818 * - the callback method, which happens in the STREAMING thread with
3819 * the STREAM_LOCK held. With this method, the most useful way of
3820 * dealing with the callback is to post a message to the main thread
3821 * where the pad block can then be handled outside of the streaming
3822 * thread. With the last method one can perform all operations such
3823 * as doing a state change, linking, unblocking, seeking etc on the
3825 * - the GCond signal method, which makes any thread unblock when
3826 * the pad block happens.
3828 * During the actual blocking state, the GST_PAD_BLOCKING flag is set.
3829 * The GST_PAD_BLOCKING flag is unset when the pad was unblocked.
3833 static GstFlowReturn
3834 handle_pad_block (GstPad * pad)
3836 GstPadBlockCallback callback;
3838 GstFlowReturn ret = GST_FLOW_OK;
3840 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "signal block taken");
3842 /* flushing, don't bother trying to block and return WRONG_STATE
3844 if (GST_PAD_IS_FLUSHING (pad))
3845 goto flushingnonref;
3847 /* we grab an extra ref for the callbacks, this is probably not
3848 * needed (callback code does not have a ref and cannot unref). I
3849 * think this was done to make it possible to unref the element in
3850 * the callback, which is in the end totally impossible as it
3851 * requires grabbing the STREAM_LOCK and OBJECT_LOCK which are
3852 * all taken when calling this function. */
3853 gst_object_ref (pad);
3855 while (GST_PAD_IS_BLOCKED (pad)) {
3857 /* we either have a callback installed to notify the block or
3858 * some other thread is doing a GCond wait. */
3859 callback = pad->block_callback;
3860 pad->abidata.ABI.block_callback_called = TRUE;
3862 /* there is a callback installed, call it. We release the
3863 * lock so that the callback can do something usefull with the
3865 user_data = pad->block_data;
3866 GST_OBJECT_UNLOCK (pad);
3867 callback (pad, TRUE, user_data);
3868 GST_OBJECT_LOCK (pad);
3870 /* we released the lock, recheck flushing */
3871 if (GST_PAD_IS_FLUSHING (pad))
3874 /* no callback, signal the thread that is doing a GCond wait
3876 GST_PAD_BLOCK_BROADCAST (pad);
3878 } while (pad->abidata.ABI.block_callback_called == FALSE
3879 && GST_PAD_IS_BLOCKED (pad));
3881 /* OBJECT_LOCK could have been released when we did the callback, which
3882 * then could have made the pad unblock so we need to check the blocking
3883 * condition again. */
3884 if (!GST_PAD_IS_BLOCKED (pad))
3887 /* now we block the streaming thread. It can be unlocked when we
3888 * deactivate the pad (which will also set the FLUSHING flag) or
3889 * when the pad is unblocked. A flushing event will also unblock
3890 * the pad after setting the FLUSHING flag. */
3891 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3892 "Waiting to be unblocked or set flushing");
3893 GST_OBJECT_FLAG_SET (pad, GST_PAD_BLOCKING);
3894 GST_PAD_BLOCK_WAIT (pad);
3895 GST_OBJECT_FLAG_UNSET (pad, GST_PAD_BLOCKING);
3897 /* see if we got unblocked by a flush or not */
3898 if (GST_PAD_IS_FLUSHING (pad))
3902 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "got unblocked");
3904 /* when we get here, the pad is unblocked again and we perform
3905 * the needed unblock code. */
3906 callback = pad->block_callback;
3908 /* we need to call the callback */
3909 user_data = pad->block_data;
3910 GST_OBJECT_UNLOCK (pad);
3911 callback (pad, FALSE, user_data);
3912 GST_OBJECT_LOCK (pad);
3914 /* we need to signal the thread waiting on the GCond */
3915 GST_PAD_BLOCK_BROADCAST (pad);
3918 gst_object_unref (pad);
3924 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "pad was flushing");
3925 return GST_FLOW_WRONG_STATE;
3929 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "pad became flushing");
3930 gst_object_unref (pad);
3931 return GST_FLOW_WRONG_STATE;
3935 /**********************************************************************
3936 * Data passing functions
3940 gst_pad_emit_have_data_signal (GstPad * pad, GstMiniObject * obj)
3943 GValue args[2] = { {0}, {0} };
3948 g_value_init (&ret, G_TYPE_BOOLEAN);
3949 g_value_set_boolean (&ret, TRUE);
3950 g_value_init (&args[0], GST_TYPE_PAD);
3951 g_value_set_object (&args[0], pad);
3952 g_value_init (&args[1], GST_TYPE_MINI_OBJECT);
3953 gst_value_set_mini_object (&args[1], obj);
3955 if (GST_IS_EVENT (obj))
3956 detail = event_quark;
3958 detail = buffer_quark;
3961 g_signal_emitv (args, gst_pad_signals[PAD_HAVE_DATA], detail, &ret);
3962 res = g_value_get_boolean (&ret);
3965 g_value_unset (&ret);
3966 g_value_unset (&args[0]);
3967 g_value_unset (&args[1]);
3973 gst_pad_data_unref (gboolean is_buffer, void *data)
3975 if (G_LIKELY (is_buffer)) {
3976 gst_buffer_unref (data);
3978 gst_buffer_list_unref (data);
3983 gst_pad_data_get_caps (gboolean is_buffer, void *data)
3987 if (G_LIKELY (is_buffer)) {
3988 caps = GST_BUFFER_CAPS (data);
3992 if ((buf = gst_buffer_list_get (GST_BUFFER_LIST_CAST (data), 0, 0)))
3993 caps = GST_BUFFER_CAPS (buf);
4000 /* this is the chain function that does not perform the additional argument
4001 * checking for that little extra speed.
4003 static inline GstFlowReturn
4004 gst_pad_chain_data_unchecked (GstPad * pad, gboolean is_buffer, void *data)
4007 gboolean caps_changed;
4009 gboolean emit_signal;
4011 GST_PAD_STREAM_LOCK (pad);
4013 GST_OBJECT_LOCK (pad);
4014 if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4017 caps = gst_pad_data_get_caps (is_buffer, data);
4018 caps_changed = caps && caps != GST_PAD_CAPS (pad);
4020 emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
4021 GST_OBJECT_UNLOCK (pad);
4023 /* see if the signal should be emited, we emit before caps nego as
4024 * we might drop the buffer and do capsnego for nothing. */
4025 if (G_UNLIKELY (emit_signal)) {
4026 if (G_LIKELY (is_buffer)) {
4027 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (data)))
4030 /* chain all groups in the buffer list one by one to avoid problems with
4031 * buffer probes that push buffers or events */
4036 /* we got a new datatype on the pad, see if it can handle it */
4037 if (G_UNLIKELY (caps_changed)) {
4038 GST_DEBUG_OBJECT (pad, "caps changed to %p %" GST_PTR_FORMAT, caps, caps);
4039 if (G_UNLIKELY (!gst_pad_configure_sink (pad, caps)))
4040 goto not_negotiated;
4043 /* NOTE: we read the chainfunc unlocked.
4044 * we cannot hold the lock for the pad so we might send
4045 * the data to the wrong function. This is not really a
4046 * problem since functions are assigned at creation time
4047 * and don't change that often... */
4048 if (G_LIKELY (is_buffer)) {
4049 GstPadChainFunction chainfunc;
4051 if (G_UNLIKELY ((chainfunc = GST_PAD_CHAINFUNC (pad)) == NULL))
4054 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4055 "calling chainfunction &%s", GST_DEBUG_FUNCPTR_NAME (chainfunc));
4057 ret = chainfunc (pad, GST_BUFFER_CAST (data));
4059 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4060 "called chainfunction &%s, returned %s",
4061 GST_DEBUG_FUNCPTR_NAME (chainfunc), gst_flow_get_name (ret));
4063 GstPadChainListFunction chainlistfunc;
4065 if (G_UNLIKELY ((chainlistfunc = GST_PAD_CHAINLISTFUNC (pad)) == NULL))
4068 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4069 "calling chainlistfunction &%s",
4070 GST_DEBUG_FUNCPTR_NAME (chainlistfunc));
4072 ret = chainlistfunc (pad, GST_BUFFER_LIST_CAST (data));
4074 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4075 "called chainlistfunction &%s, returned %s",
4076 GST_DEBUG_FUNCPTR_NAME (chainlistfunc), gst_flow_get_name (ret));
4079 GST_PAD_STREAM_UNLOCK (pad);
4085 GstBufferList *list;
4086 GstBufferListIterator *it;
4089 GST_PAD_STREAM_UNLOCK (pad);
4091 GST_INFO_OBJECT (pad, "chaining each group in list as a merged buffer");
4093 list = GST_BUFFER_LIST_CAST (data);
4094 it = gst_buffer_list_iterate (list);
4097 if (gst_buffer_list_iterator_next_group (it)) {
4099 group = gst_buffer_list_iterator_merge_group (it);
4100 if (group == NULL) {
4101 group = gst_buffer_new ();
4102 GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "chaining empty group");
4104 GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "chaining group");
4106 ret = gst_pad_chain_data_unchecked (pad, TRUE, group);
4107 } while (ret == GST_FLOW_OK && gst_buffer_list_iterator_next_group (it));
4109 GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "chaining empty group");
4110 ret = gst_pad_chain_data_unchecked (pad, TRUE, gst_buffer_new ());
4113 gst_buffer_list_iterator_free (it);
4114 gst_buffer_list_unref (list);
4122 gst_pad_data_unref (is_buffer, data);
4123 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4124 "pushing, but pad was flushing");
4125 GST_OBJECT_UNLOCK (pad);
4126 GST_PAD_STREAM_UNLOCK (pad);
4127 return GST_FLOW_WRONG_STATE;
4131 gst_pad_data_unref (is_buffer, data);
4132 GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
4133 GST_PAD_STREAM_UNLOCK (pad);
4138 gst_pad_data_unref (is_buffer, data);
4139 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4140 "pushing data but pad did not accept");
4141 GST_PAD_STREAM_UNLOCK (pad);
4142 return GST_FLOW_NOT_NEGOTIATED;
4146 gst_pad_data_unref (is_buffer, data);
4147 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4148 "pushing, but not chainhandler");
4149 GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
4150 ("push on pad %s:%s but it has no chainfunction",
4151 GST_DEBUG_PAD_NAME (pad)));
4152 GST_PAD_STREAM_UNLOCK (pad);
4153 return GST_FLOW_NOT_SUPPORTED;
4159 * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
4160 * @buffer: the #GstBuffer to send, return GST_FLOW_ERROR if not.
4162 * Chain a buffer to @pad.
4164 * The function returns #GST_FLOW_WRONG_STATE if the pad was flushing.
4166 * If the caps on @buffer are different from the current caps on @pad, this
4167 * function will call any setcaps function (see gst_pad_set_setcaps_function())
4168 * installed on @pad. If the new caps are not acceptable for @pad, this
4169 * function returns #GST_FLOW_NOT_NEGOTIATED.
4171 * The function proceeds calling the chain function installed on @pad (see
4172 * gst_pad_set_chain_function()) and the return value of that function is
4173 * returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no
4176 * In all cases, success or failure, the caller loses its reference to @buffer
4177 * after calling this function.
4179 * Returns: a #GstFlowReturn from the pad.
4184 gst_pad_chain (GstPad * pad, GstBuffer * buffer)
4186 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4187 g_return_val_if_fail (GST_PAD_IS_SINK (pad), GST_FLOW_ERROR);
4188 g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
4190 return gst_pad_chain_data_unchecked (pad, TRUE, buffer);
4194 * gst_pad_chain_list:
4195 * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
4196 * @list: the #GstBufferList to send, return GST_FLOW_ERROR if not.
4198 * Chain a bufferlist to @pad.
4200 * The function returns #GST_FLOW_WRONG_STATE if the pad was flushing.
4202 * If the caps on the first buffer of @list are different from the current
4203 * caps on @pad, this function will call any setcaps function
4204 * (see gst_pad_set_setcaps_function()) installed on @pad. If the new caps
4205 * are not acceptable for @pad, this function returns #GST_FLOW_NOT_NEGOTIATED.
4207 * The function proceeds calling the chainlist function installed on @pad (see
4208 * gst_pad_set_chain_list_function()) and the return value of that function is
4209 * returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no
4210 * chainlist function.
4212 * In all cases, success or failure, the caller loses its reference to @list
4213 * after calling this function.
4217 * Returns: a #GstFlowReturn from the pad.
4222 gst_pad_chain_list (GstPad * pad, GstBufferList * list)
4224 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4225 g_return_val_if_fail (GST_PAD_IS_SINK (pad), GST_FLOW_ERROR);
4226 g_return_val_if_fail (GST_IS_BUFFER_LIST (list), GST_FLOW_ERROR);
4228 return gst_pad_chain_data_unchecked (pad, FALSE, list);
4231 static GstFlowReturn
4232 gst_pad_push_data (GstPad * pad, gboolean is_buffer, void *data)
4237 gboolean caps_changed;
4239 GST_OBJECT_LOCK (pad);
4241 /* FIXME: this check can go away; pad_set_blocked could be implemented with
4242 * probes completely or probes with an extended pad block. */
4243 while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
4244 if ((ret = handle_pad_block (pad)) != GST_FLOW_OK)
4247 /* we emit signals on the pad arg, the peer will have a chance to
4248 * emit in the _chain() function */
4249 if (G_UNLIKELY (GST_PAD_DO_BUFFER_SIGNALS (pad) > 0)) {
4250 /* unlock before emitting */
4251 GST_OBJECT_UNLOCK (pad);
4253 if (G_LIKELY (is_buffer)) {
4254 /* if the signal handler returned FALSE, it means we should just drop the
4256 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (data)))
4259 /* push all buffers in the list */
4262 GST_OBJECT_LOCK (pad);
4265 if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
4268 /* Before pushing the buffer to the peer pad, ensure that caps
4269 * are set on this pad */
4270 caps = gst_pad_data_get_caps (is_buffer, data);
4271 caps_changed = caps && caps != GST_PAD_CAPS (pad);
4273 /* take ref to peer pad before releasing the lock */
4274 gst_object_ref (peer);
4276 GST_OBJECT_UNLOCK (pad);
4278 /* we got a new datatype from the pad, it had better handle it */
4279 if (G_UNLIKELY (caps_changed)) {
4280 GST_DEBUG_OBJECT (pad,
4281 "caps changed from %" GST_PTR_FORMAT " to %p %" GST_PTR_FORMAT,
4282 GST_PAD_CAPS (pad), caps, caps);
4283 if (G_UNLIKELY (!gst_pad_configure_src (pad, caps, TRUE)))
4284 goto not_negotiated;
4287 ret = gst_pad_chain_data_unchecked (peer, is_buffer, data);
4289 gst_object_unref (peer);
4295 GstBufferList *list;
4296 GstBufferListIterator *it;
4299 GST_INFO_OBJECT (pad, "pushing each group in list as a merged buffer");
4301 list = GST_BUFFER_LIST_CAST (data);
4302 it = gst_buffer_list_iterate (list);
4305 if (gst_buffer_list_iterator_next_group (it)) {
4307 group = gst_buffer_list_iterator_merge_group (it);
4308 if (group == NULL) {
4309 group = gst_buffer_new ();
4310 GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "pushing empty group");
4312 GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "pushing group");
4314 ret = gst_pad_push_data (pad, TRUE, group);
4315 } while (ret == GST_FLOW_OK && gst_buffer_list_iterator_next_group (it));
4317 GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "pushing empty group");
4318 ret = gst_pad_push_data (pad, TRUE, gst_buffer_new ());
4321 gst_buffer_list_iterator_free (it);
4322 gst_buffer_list_unref (list);
4327 /* ERROR recovery here */
4330 gst_pad_data_unref (is_buffer, data);
4331 GST_DEBUG_OBJECT (pad, "pad block stopped by flush");
4332 GST_OBJECT_UNLOCK (pad);
4337 gst_pad_data_unref (is_buffer, data);
4338 GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
4343 gst_pad_data_unref (is_buffer, data);
4344 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4345 "pushing, but it was not linked");
4346 GST_OBJECT_UNLOCK (pad);
4347 return GST_FLOW_NOT_LINKED;
4351 gst_pad_data_unref (is_buffer, data);
4352 gst_object_unref (peer);
4353 GST_CAT_DEBUG_OBJECT (GST_CAT_SCHEDULING, pad,
4354 "element pushed data then refused to accept the caps");
4355 return GST_FLOW_NOT_NEGOTIATED;
4361 * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not.
4362 * @buffer: the #GstBuffer to push returns GST_FLOW_ERROR if not.
4364 * Pushes a buffer to the peer of @pad.
4366 * This function will call an installed pad block before triggering any
4367 * installed pad probes.
4369 * If the caps on @buffer are different from the currently configured caps on
4370 * @pad, this function will call any installed setcaps function on @pad (see
4371 * gst_pad_set_setcaps_function()). In case of failure to renegotiate the new
4372 * format, this function returns #GST_FLOW_NOT_NEGOTIATED.
4374 * The function proceeds calling gst_pad_chain() on the peer pad and returns
4375 * the value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will
4378 * In all cases, success or failure, the caller loses its reference to @buffer
4379 * after calling this function.
4381 * Returns: a #GstFlowReturn from the peer pad.
4386 gst_pad_push (GstPad * pad, GstBuffer * buffer)
4388 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4389 g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
4390 g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
4392 return gst_pad_push_data (pad, TRUE, buffer);
4396 * gst_pad_push_list:
4397 * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not.
4398 * @list: the #GstBufferList to push returns GST_FLOW_ERROR if not.
4400 * Pushes a buffer list to the peer of @pad.
4402 * This function will call an installed pad block before triggering any
4403 * installed pad probes.
4405 * If the caps on the first buffer in the first group of @list are different
4406 * from the currently configured caps on @pad, this function will call any
4407 * installed setcaps function on @pad (see gst_pad_set_setcaps_function()). In
4408 * case of failure to renegotiate the new format, this function returns
4409 * #GST_FLOW_NOT_NEGOTIATED.
4411 * If there are any probes installed on @pad every group of the buffer list
4412 * will be merged into a normal #GstBuffer and pushed via gst_pad_push and the
4413 * buffer list will be unreffed.
4415 * The function proceeds calling the chain function on the peer pad and returns
4416 * the value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will
4417 * be returned. If the peer pad does not have any installed chainlist function
4418 * every group buffer of the list will be merged into a normal #GstBuffer and
4419 * chained via gst_pad_chain().
4421 * In all cases, success or failure, the caller loses its reference to @list
4422 * after calling this function.
4424 * Returns: a #GstFlowReturn from the peer pad.
4431 gst_pad_push_list (GstPad * pad, GstBufferList * list)
4433 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4434 g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
4435 g_return_val_if_fail (GST_IS_BUFFER_LIST (list), GST_FLOW_ERROR);
4437 return gst_pad_push_data (pad, FALSE, list);
4441 * gst_pad_check_pull_range:
4442 * @pad: a sink #GstPad.
4444 * Checks if a gst_pad_pull_range() can be performed on the peer
4445 * source pad. This function is used by plugins that want to check
4446 * if they can use random access on the peer source pad.
4448 * The peer sourcepad can implement a custom #GstPadCheckGetRangeFunction
4449 * if it needs to perform some logic to determine if pull_range is
4452 * Returns: a gboolean with the result.
4457 gst_pad_check_pull_range (GstPad * pad)
4461 GstPadCheckGetRangeFunction checkgetrangefunc;
4463 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4465 GST_OBJECT_LOCK (pad);
4466 if (!GST_PAD_IS_SINK (pad))
4467 goto wrong_direction;
4469 if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
4472 gst_object_ref (peer);
4473 GST_OBJECT_UNLOCK (pad);
4475 /* see note in above function */
4476 if (G_LIKELY ((checkgetrangefunc = peer->checkgetrangefunc) == NULL)) {
4477 /* FIXME, kindoff ghetto */
4478 ret = GST_PAD_GETRANGEFUNC (peer) != NULL;
4479 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4480 "no checkgetrangefunc, assuming %d", ret);
4482 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4483 "calling checkgetrangefunc %s of peer pad %s:%s",
4484 GST_DEBUG_FUNCPTR_NAME (checkgetrangefunc), GST_DEBUG_PAD_NAME (peer));
4486 ret = checkgetrangefunc (peer);
4489 gst_object_unref (peer);
4493 /* ERROR recovery here */
4496 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4497 "checking pull range, but pad must be a sinkpad");
4498 GST_OBJECT_UNLOCK (pad);
4503 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4504 "checking pull range, but it was not linked");
4505 GST_OBJECT_UNLOCK (pad);
4511 * gst_pad_get_range:
4512 * @pad: a src #GstPad, returns #GST_FLOW_ERROR if not.
4513 * @offset: The start offset of the buffer
4514 * @size: The length of the buffer
4515 * @buffer: a pointer to hold the #GstBuffer, returns #GST_FLOW_ERROR if %NULL.
4517 * When @pad is flushing this function returns #GST_FLOW_WRONG_STATE
4520 * Calls the getrange function of @pad, see #GstPadGetRangeFunction for a
4521 * description of a getrange function. If @pad has no getrange function
4522 * installed (see gst_pad_set_getrange_function()) this function returns
4523 * #GST_FLOW_NOT_SUPPORTED.
4525 * This is a lowlevel function. Usualy gst_pad_pull_range() is used.
4527 * Returns: a #GstFlowReturn from the pad.
4532 gst_pad_get_range (GstPad * pad, guint64 offset, guint size,
4533 GstBuffer ** buffer)
4536 GstPadGetRangeFunction getrangefunc;
4537 gboolean emit_signal;
4539 gboolean caps_changed;
4541 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4542 g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
4543 g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
4545 GST_PAD_STREAM_LOCK (pad);
4547 GST_OBJECT_LOCK (pad);
4548 if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4551 emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
4552 GST_OBJECT_UNLOCK (pad);
4554 if (G_UNLIKELY ((getrangefunc = GST_PAD_GETRANGEFUNC (pad)) == NULL))
4557 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4558 "calling getrangefunc %s, offset %"
4559 G_GUINT64_FORMAT ", size %u",
4560 GST_DEBUG_FUNCPTR_NAME (getrangefunc), offset, size);
4562 ret = getrangefunc (pad, offset, size, buffer);
4564 /* can only fire the signal if we have a valid buffer */
4565 if (G_UNLIKELY (emit_signal) && (ret == GST_FLOW_OK)) {
4566 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (*buffer)))
4570 GST_PAD_STREAM_UNLOCK (pad);
4572 if (G_UNLIKELY (ret != GST_FLOW_OK))
4573 goto get_range_failed;
4575 GST_OBJECT_LOCK (pad);
4576 /* Before pushing the buffer to the peer pad, ensure that caps
4577 * are set on this pad */
4578 caps = GST_BUFFER_CAPS (*buffer);
4579 caps_changed = caps && caps != GST_PAD_CAPS (pad);
4580 GST_OBJECT_UNLOCK (pad);
4582 if (G_UNLIKELY (caps_changed)) {
4583 GST_DEBUG_OBJECT (pad, "caps changed to %p %" GST_PTR_FORMAT, caps, caps);
4584 /* this should usually work because the element produced the buffer */
4585 if (G_UNLIKELY (!gst_pad_configure_src (pad, caps, TRUE)))
4586 goto not_negotiated;
4593 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4594 "pulling range, but pad was flushing");
4595 GST_OBJECT_UNLOCK (pad);
4596 GST_PAD_STREAM_UNLOCK (pad);
4597 return GST_FLOW_WRONG_STATE;
4601 GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
4602 ("pullrange on pad %s:%s but it has no getrangefunction",
4603 GST_DEBUG_PAD_NAME (pad)));
4604 GST_PAD_STREAM_UNLOCK (pad);
4605 return GST_FLOW_NOT_SUPPORTED;
4609 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4610 "Dropping data after FALSE probe return");
4611 GST_PAD_STREAM_UNLOCK (pad);
4612 gst_buffer_unref (*buffer);
4614 return GST_FLOW_UNEXPECTED;
4619 GST_CAT_WARNING_OBJECT (GST_CAT_SCHEDULING, pad,
4620 "getrange failed %s", gst_flow_get_name (ret));
4625 gst_buffer_unref (*buffer);
4627 GST_CAT_WARNING_OBJECT (GST_CAT_SCHEDULING, pad,
4628 "getrange returned buffer of unaccaptable caps");
4629 return GST_FLOW_NOT_NEGOTIATED;
4635 * gst_pad_pull_range:
4636 * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
4637 * @offset: The start offset of the buffer
4638 * @size: The length of the buffer
4639 * @buffer: a pointer to hold the #GstBuffer, returns GST_FLOW_ERROR if %NULL.
4641 * Pulls a @buffer from the peer pad.
4643 * This function will first trigger the pad block signal if it was
4646 * When @pad is not linked #GST_FLOW_NOT_LINKED is returned else this
4647 * function returns the result of gst_pad_get_range() on the peer pad.
4648 * See gst_pad_get_range() for a list of return values and for the
4649 * semantics of the arguments of this function.
4651 * @buffer's caps must either be unset or the same as what is already
4652 * configured on @pad. Renegotiation within a running pull-mode pipeline is not
4655 * Returns: a #GstFlowReturn from the peer pad.
4656 * When this function returns #GST_FLOW_OK, @buffer will contain a valid
4657 * #GstBuffer that should be freed with gst_buffer_unref() after usage.
4658 * @buffer may not be used or freed when any other return value than
4659 * #GST_FLOW_OK is returned.
4664 gst_pad_pull_range (GstPad * pad, guint64 offset, guint size,
4665 GstBuffer ** buffer)
4669 gboolean emit_signal;
4671 gboolean caps_changed;
4673 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4674 g_return_val_if_fail (GST_PAD_IS_SINK (pad), GST_FLOW_ERROR);
4675 g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
4677 GST_OBJECT_LOCK (pad);
4679 while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
4680 handle_pad_block (pad);
4682 if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
4685 /* signal emision for the pad, peer has chance to emit when
4686 * we call _get_range() */
4687 emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
4689 gst_object_ref (peer);
4690 GST_OBJECT_UNLOCK (pad);
4692 ret = gst_pad_get_range (peer, offset, size, buffer);
4694 gst_object_unref (peer);
4696 if (G_UNLIKELY (ret != GST_FLOW_OK))
4697 goto pull_range_failed;
4699 /* can only fire the signal if we have a valid buffer */
4700 if (G_UNLIKELY (emit_signal)) {
4701 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (*buffer)))
4705 GST_OBJECT_LOCK (pad);
4706 /* Before pushing the buffer to the peer pad, ensure that caps
4707 * are set on this pad */
4708 caps = GST_BUFFER_CAPS (*buffer);
4709 caps_changed = caps && caps != GST_PAD_CAPS (pad);
4710 GST_OBJECT_UNLOCK (pad);
4712 /* we got a new datatype on the pad, see if it can handle it */
4713 if (G_UNLIKELY (caps_changed)) {
4714 GST_DEBUG_OBJECT (pad, "caps changed to %p %" GST_PTR_FORMAT, caps, caps);
4715 if (G_UNLIKELY (!gst_pad_configure_sink (pad, caps)))
4716 goto not_negotiated;
4720 /* ERROR recovery here */
4723 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4724 "pulling range, but it was not linked");
4725 GST_OBJECT_UNLOCK (pad);
4726 return GST_FLOW_NOT_LINKED;
4731 GST_CAT_WARNING_OBJECT (GST_CAT_SCHEDULING, pad,
4732 "pullrange failed %s", gst_flow_get_name (ret));
4737 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4738 "Dropping data after FALSE probe return");
4739 gst_buffer_unref (*buffer);
4741 return GST_FLOW_UNEXPECTED;
4745 gst_buffer_unref (*buffer);
4747 GST_CAT_WARNING_OBJECT (GST_CAT_SCHEDULING, pad,
4748 "pullrange returned buffer of different caps");
4749 return GST_FLOW_NOT_NEGOTIATED;
4754 * gst_pad_push_event:
4755 * @pad: a #GstPad to push the event to.
4756 * @event: the #GstEvent to send to the pad.
4758 * Sends the event to the peer of the given pad. This function is
4759 * mainly used by elements to send events to their peer
4762 * This function takes owership of the provided event so you should
4763 * gst_event_ref() it if you want to reuse the event after this call.
4765 * Returns: TRUE if the event was handled.
4770 gst_pad_push_event (GstPad * pad, GstEvent * event)
4775 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4776 g_return_val_if_fail (event != NULL, FALSE);
4777 g_return_val_if_fail (GST_IS_EVENT (event), FALSE);
4779 GST_LOG_OBJECT (pad, "event: %s", GST_EVENT_TYPE_NAME (event));
4781 GST_OBJECT_LOCK (pad);
4783 /* Two checks to be made:
4784 * . (un)set the FLUSHING flag for flushing events,
4785 * . handle pad blocking */
4786 switch (GST_EVENT_TYPE (event)) {
4787 case GST_EVENT_FLUSH_START:
4788 GST_PAD_SET_FLUSHING (pad);
4790 if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
4791 /* flush start will have set the FLUSHING flag and will then
4792 * unlock all threads doing a GCond wait on the blocking pad. This
4793 * will typically unblock the STREAMING thread blocked on a pad. */
4794 GST_LOG_OBJECT (pad, "Pad is blocked, not forwarding flush-start, "
4795 "doing block signal.");
4796 GST_PAD_BLOCK_BROADCAST (pad);
4800 case GST_EVENT_FLUSH_STOP:
4801 GST_PAD_UNSET_FLUSHING (pad);
4803 /* if we are blocked, flush away the FLUSH_STOP event */
4804 if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
4805 GST_LOG_OBJECT (pad, "Pad is blocked, not forwarding flush-stop");
4810 while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
4811 /* block the event as long as the pad is blocked */
4812 if (handle_pad_block (pad) != GST_FLOW_OK)
4818 if (G_UNLIKELY (GST_PAD_DO_EVENT_SIGNALS (pad) > 0)) {
4819 GST_OBJECT_UNLOCK (pad);
4821 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (event)))
4824 GST_OBJECT_LOCK (pad);
4826 peerpad = GST_PAD_PEER (pad);
4827 if (peerpad == NULL)
4830 GST_LOG_OBJECT (pad, "sending event %s to peerpad %" GST_PTR_FORMAT,
4831 GST_EVENT_TYPE_NAME (event), peerpad);
4832 gst_object_ref (peerpad);
4833 GST_OBJECT_UNLOCK (pad);
4835 result = gst_pad_send_event (peerpad, event);
4837 /* Note: we gave away ownership of the event at this point */
4838 GST_LOG_OBJECT (pad, "sent event to peerpad %" GST_PTR_FORMAT ", result %d",
4840 gst_object_unref (peerpad);
4844 /* ERROR handling */
4847 GST_DEBUG_OBJECT (pad, "Dropping event after FALSE probe return");
4848 gst_event_unref (event);
4853 GST_DEBUG_OBJECT (pad, "Dropping event because pad is not linked");
4854 gst_event_unref (event);
4855 GST_OBJECT_UNLOCK (pad);
4860 GST_DEBUG_OBJECT (pad,
4861 "Not forwarding event since we're flushing and blocking");
4862 gst_event_unref (event);
4863 GST_OBJECT_UNLOCK (pad);
4869 * gst_pad_send_event:
4870 * @pad: a #GstPad to send the event to.
4871 * @event: the #GstEvent to send to the pad.
4873 * Sends the event to the pad. This function can be used
4874 * by applications to send events in the pipeline.
4876 * If @pad is a source pad, @event should be an upstream event. If @pad is a
4877 * sink pad, @event should be a downstream event. For example, you would not
4878 * send a #GST_EVENT_EOS on a src pad; EOS events only propagate downstream.
4879 * Furthermore, some downstream events have to be serialized with data flow,
4880 * like EOS, while some can travel out-of-band, like #GST_EVENT_FLUSH_START. If
4881 * the event needs to be serialized with data flow, this function will take the
4882 * pad's stream lock while calling its event function.
4884 * To find out whether an event type is upstream, downstream, or downstream and
4885 * serialized, see #GstEventTypeFlags, gst_event_type_get_flags(),
4886 * #GST_EVENT_IS_UPSTREAM, #GST_EVENT_IS_DOWNSTREAM, and
4887 * #GST_EVENT_IS_SERIALIZED. Note that in practice that an application or
4888 * plugin doesn't need to bother itself with this information; the core handles
4889 * all necessary locks and checks.
4891 * This function takes owership of the provided event so you should
4892 * gst_event_ref() it if you want to reuse the event after this call.
4894 * Returns: TRUE if the event was handled.
4897 gst_pad_send_event (GstPad * pad, GstEvent * event)
4899 gboolean result = FALSE;
4900 GstPadEventFunction eventfunc;
4901 gboolean serialized, need_unlock = FALSE;
4903 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4904 g_return_val_if_fail (event != NULL, FALSE);
4906 GST_OBJECT_LOCK (pad);
4907 if (GST_PAD_IS_SINK (pad)) {
4908 if (G_UNLIKELY (!GST_EVENT_IS_DOWNSTREAM (event)))
4909 goto wrong_direction;
4910 serialized = GST_EVENT_IS_SERIALIZED (event);
4911 } else if (GST_PAD_IS_SRC (pad)) {
4912 if (G_UNLIKELY (!GST_EVENT_IS_UPSTREAM (event)))
4913 goto wrong_direction;
4914 /* events on srcpad never are serialized */
4917 goto unknown_direction;
4919 if (G_UNLIKELY (GST_EVENT_SRC (event) == NULL)) {
4920 GST_LOG_OBJECT (pad, "event had no source, setting pad as event source");
4921 GST_EVENT_SRC (event) = gst_object_ref (pad);
4925 if (G_UNLIKELY (GST_PAD_DO_EVENT_SIGNALS (pad) > 0)) {
4926 GST_OBJECT_UNLOCK (pad);
4928 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT_CAST (event)))
4931 GST_OBJECT_LOCK (pad);
4934 switch (GST_EVENT_TYPE (event)) {
4935 case GST_EVENT_FLUSH_START:
4936 GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad,
4937 "have event type %d (FLUSH_START)", GST_EVENT_TYPE (event));
4939 /* can't even accept a flush begin event when flushing */
4940 if (GST_PAD_IS_FLUSHING (pad))
4942 GST_PAD_SET_FLUSHING (pad);
4943 GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "set flush flag");
4945 case GST_EVENT_FLUSH_STOP:
4946 GST_PAD_UNSET_FLUSHING (pad);
4947 GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "cleared flush flag");
4948 GST_OBJECT_UNLOCK (pad);
4949 /* grab stream lock */
4950 GST_PAD_STREAM_LOCK (pad);
4952 GST_OBJECT_LOCK (pad);
4955 GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "have event type %s",
4956 GST_EVENT_TYPE_NAME (event));
4958 /* make this a little faster, no point in grabbing the lock
4959 * if the pad is allready flushing. */
4960 if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4964 /* lock order: STREAM_LOCK, LOCK, recheck flushing. */
4965 GST_OBJECT_UNLOCK (pad);
4966 GST_PAD_STREAM_LOCK (pad);
4968 GST_OBJECT_LOCK (pad);
4969 if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4974 if (G_UNLIKELY ((eventfunc = GST_PAD_EVENTFUNC (pad)) == NULL))
4977 GST_OBJECT_UNLOCK (pad);
4979 result = eventfunc (pad, event);
4982 GST_PAD_STREAM_UNLOCK (pad);
4984 GST_DEBUG_OBJECT (pad, "sent event, result %d", result);
4988 /* ERROR handling */
4991 g_warning ("pad %s:%s sending %s event in wrong direction",
4992 GST_DEBUG_PAD_NAME (pad), GST_EVENT_TYPE_NAME (event));
4993 GST_OBJECT_UNLOCK (pad);
4994 gst_event_unref (event);
4999 g_warning ("pad %s:%s has invalid direction", GST_DEBUG_PAD_NAME (pad));
5000 GST_OBJECT_UNLOCK (pad);
5001 gst_event_unref (event);
5006 g_warning ("pad %s:%s has no event handler, file a bug.",
5007 GST_DEBUG_PAD_NAME (pad));
5008 GST_OBJECT_UNLOCK (pad);
5010 GST_PAD_STREAM_UNLOCK (pad);
5011 gst_event_unref (event);
5016 GST_OBJECT_UNLOCK (pad);
5018 GST_PAD_STREAM_UNLOCK (pad);
5019 GST_CAT_INFO_OBJECT (GST_CAT_EVENT, pad,
5020 "Received event on flushing pad. Discarding");
5021 gst_event_unref (event);
5026 GST_DEBUG_OBJECT (pad, "Dropping event after FALSE probe return");
5027 gst_event_unref (event);
5033 * gst_pad_set_element_private:
5034 * @pad: the #GstPad to set the private data of.
5035 * @priv: The private data to attach to the pad.
5037 * Set the given private data gpointer on the pad.
5038 * This function can only be used by the element that owns the pad.
5039 * No locking is performed in this function.
5042 gst_pad_set_element_private (GstPad * pad, gpointer priv)
5044 pad->element_private = priv;
5048 * gst_pad_get_element_private:
5049 * @pad: the #GstPad to get the private data of.
5051 * Gets the private data of a pad.
5052 * No locking is performed in this function.
5054 * Returns: a #gpointer to the private data.
5057 gst_pad_get_element_private (GstPad * pad)
5059 return pad->element_private;
5063 do_stream_status (GstPad * pad, GstStreamStatusType type,
5064 GThread * thread, GstTask * task)
5068 GST_DEBUG_OBJECT (pad, "doing stream-status %d", type);
5070 if ((parent = GST_ELEMENT_CAST (gst_pad_get_parent (pad)))) {
5071 if (GST_IS_ELEMENT (parent)) {
5072 GstMessage *message;
5073 GValue value = { 0 };
5075 message = gst_message_new_stream_status (GST_OBJECT_CAST (pad),
5078 g_value_init (&value, GST_TYPE_TASK);
5079 g_value_set_object (&value, task);
5080 gst_message_set_stream_status_object (message, &value);
5081 g_value_unset (&value);
5083 GST_DEBUG_OBJECT (pad, "posting stream-status %d", type);
5084 gst_element_post_message (parent, message);
5086 gst_object_unref (parent);
5091 pad_enter_thread (GstTask * task, GThread * thread, gpointer user_data)
5093 do_stream_status (GST_PAD_CAST (user_data), GST_STREAM_STATUS_TYPE_ENTER,
5098 pad_leave_thread (GstTask * task, GThread * thread, gpointer user_data)
5100 do_stream_status (GST_PAD_CAST (user_data), GST_STREAM_STATUS_TYPE_LEAVE,
5104 static GstTaskThreadCallbacks thr_callbacks = {
5110 * gst_pad_start_task:
5111 * @pad: the #GstPad to start the task of
5112 * @func: the task function to call
5113 * @data: data passed to the task function
5115 * Starts a task that repeatedly calls @func with @data. This function
5116 * is mostly used in pad activation functions to start the dataflow.
5117 * The #GST_PAD_STREAM_LOCK of @pad will automatically be acquired
5118 * before @func is called.
5120 * Returns: a %TRUE if the task could be started.
5123 gst_pad_start_task (GstPad * pad, GstTaskFunction func, gpointer data)
5128 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
5129 g_return_val_if_fail (func != NULL, FALSE);
5131 GST_DEBUG_OBJECT (pad, "start task");
5133 GST_OBJECT_LOCK (pad);
5134 task = GST_PAD_TASK (pad);
5136 task = gst_task_create (func, data);
5137 gst_task_set_lock (task, GST_PAD_GET_STREAM_LOCK (pad));
5138 gst_task_set_thread_callbacks (task, &thr_callbacks, pad, NULL);
5139 GST_DEBUG_OBJECT (pad, "created task");
5140 GST_PAD_TASK (pad) = task;
5141 gst_object_ref (task);
5142 /* release lock to post the message */
5143 GST_OBJECT_UNLOCK (pad);
5145 do_stream_status (pad, GST_STREAM_STATUS_TYPE_CREATE, NULL, task);
5147 gst_object_unref (task);
5149 GST_OBJECT_LOCK (pad);
5150 /* nobody else is supposed to have changed the pad now */
5151 if (GST_PAD_TASK (pad) != task)
5152 goto concurrent_stop;
5154 res = gst_task_set_state (task, GST_TASK_STARTED);
5155 GST_OBJECT_UNLOCK (pad);
5162 GST_OBJECT_UNLOCK (pad);
5168 * gst_pad_pause_task:
5169 * @pad: the #GstPad to pause the task of
5171 * Pause the task of @pad. This function will also wait until the
5172 * function executed by the task is finished if this function is not
5173 * called from the task function.
5175 * Returns: a TRUE if the task could be paused or FALSE when the pad
5179 gst_pad_pause_task (GstPad * pad)
5184 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
5186 GST_DEBUG_OBJECT (pad, "pause task");
5188 GST_OBJECT_LOCK (pad);
5189 task = GST_PAD_TASK (pad);
5192 res = gst_task_set_state (task, GST_TASK_PAUSED);
5193 GST_OBJECT_UNLOCK (pad);
5195 /* wait for task function to finish, this lock is recursive so it does nothing
5196 * when the pause is called from the task itself */
5197 GST_PAD_STREAM_LOCK (pad);
5198 GST_PAD_STREAM_UNLOCK (pad);
5204 GST_DEBUG_OBJECT (pad, "pad has no task");
5205 GST_OBJECT_UNLOCK (pad);
5211 * gst_pad_stop_task:
5212 * @pad: the #GstPad to stop the task of
5214 * Stop the task of @pad. This function will also make sure that the
5215 * function executed by the task will effectively stop if not called
5216 * from the GstTaskFunction.
5218 * This function will deadlock if called from the GstTaskFunction of
5219 * the task. Use gst_task_pause() instead.
5221 * Regardless of whether the pad has a task, the stream lock is acquired and
5222 * released so as to ensure that streaming through this pad has finished.
5224 * Returns: a TRUE if the task could be stopped or FALSE on error.
5227 gst_pad_stop_task (GstPad * pad)
5232 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
5234 GST_DEBUG_OBJECT (pad, "stop task");
5236 GST_OBJECT_LOCK (pad);
5237 task = GST_PAD_TASK (pad);
5240 GST_PAD_TASK (pad) = NULL;
5241 res = gst_task_set_state (task, GST_TASK_STOPPED);
5242 GST_OBJECT_UNLOCK (pad);
5244 GST_PAD_STREAM_LOCK (pad);
5245 GST_PAD_STREAM_UNLOCK (pad);
5247 if (!gst_task_join (task))
5250 gst_object_unref (task);
5256 GST_DEBUG_OBJECT (pad, "no task");
5257 GST_OBJECT_UNLOCK (pad);
5259 GST_PAD_STREAM_LOCK (pad);
5260 GST_PAD_STREAM_UNLOCK (pad);
5262 /* this is not an error */
5267 /* this is bad, possibly the application tried to join the task from
5268 * the task's thread. We install the task again so that it will be stopped
5269 * again from the right thread next time hopefully. */
5270 GST_OBJECT_LOCK (pad);
5271 GST_DEBUG_OBJECT (pad, "join failed");
5272 /* we can only install this task if there was no other task */
5273 if (GST_PAD_TASK (pad) == NULL)
5274 GST_PAD_TASK (pad) = task;
5275 GST_OBJECT_UNLOCK (pad);