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 %p %" GST_PTR_FORMAT, caps,
2555 GST_OBJECT_UNLOCK (pad);
2557 g_object_notify (G_OBJECT (pad), "caps");
2563 GST_OBJECT_UNLOCK (pad);
2568 gst_caps_replace (&GST_PAD_CAPS (pad), caps);
2569 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2570 "caps %p %" GST_PTR_FORMAT " same as existing, updating ptr only", caps,
2572 GST_OBJECT_UNLOCK (pad);
2579 GST_OBJECT_LOCK (pad);
2580 GST_OBJECT_FLAG_UNSET (pad, GST_PAD_IN_SETCAPS);
2581 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2582 "caps %" GST_PTR_FORMAT " could not be set", caps);
2583 GST_OBJECT_UNLOCK (pad);
2590 gst_pad_configure_sink (GstPad * pad, GstCaps * caps)
2594 /* See if pad accepts the caps */
2595 if (!gst_pad_accept_caps (pad, caps))
2598 /* set caps on pad if call succeeds */
2599 res = gst_pad_set_caps (pad, caps);
2600 /* no need to unref the caps here, set_caps takes a ref and
2601 * our ref goes away when we leave this function. */
2607 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2608 "caps %" GST_PTR_FORMAT " not accepted", caps);
2613 /* returns TRUE if the src pad could be configured to accept the given caps */
2615 gst_pad_configure_src (GstPad * pad, GstCaps * caps, gboolean dosetcaps)
2620 /* See if pad accepts the caps */
2621 if (!gst_pad_accept_caps (pad, caps))
2624 res = gst_pad_set_caps (pad, caps);
2632 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad,
2633 "caps %" GST_PTR_FORMAT " not accepted", caps);
2639 * gst_pad_get_pad_template_caps:
2640 * @pad: a #GstPad to get the template capabilities from.
2642 * Gets the capabilities for @pad's template.
2644 * Returns: the #GstCaps of this pad template. If you intend to keep a
2645 * reference on the caps, make a copy (see gst_caps_copy ()).
2648 gst_pad_get_pad_template_caps (GstPad * pad)
2650 static GstStaticCaps anycaps = GST_STATIC_CAPS ("ANY");
2652 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2654 if (GST_PAD_PAD_TEMPLATE (pad))
2655 return GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad));
2657 return gst_static_caps_get (&anycaps);
2662 * @pad: a #GstPad to get the peer of.
2664 * Gets the peer of @pad. This function refs the peer pad so
2665 * you need to unref it after use.
2667 * Returns: the peer #GstPad. Unref after usage.
2672 gst_pad_get_peer (GstPad * pad)
2676 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2678 GST_OBJECT_LOCK (pad);
2679 result = GST_PAD_PEER (pad);
2681 gst_object_ref (result);
2682 GST_OBJECT_UNLOCK (pad);
2688 * gst_pad_get_allowed_caps:
2691 * Gets the capabilities of the allowed media types that can flow through
2692 * @pad and its peer.
2694 * The allowed capabilities is calculated as the intersection of the results of
2695 * calling gst_pad_get_caps() on @pad and its peer. The caller owns a reference
2696 * on the resulting caps.
2698 * Returns: the allowed #GstCaps of the pad link. Unref the caps when you no
2699 * longer need it. This function returns NULL when @pad has no peer.
2704 gst_pad_get_allowed_caps (GstPad * pad)
2711 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2713 GST_OBJECT_LOCK (pad);
2715 peer = GST_PAD_PEER (pad);
2716 if (G_UNLIKELY (peer == NULL))
2719 GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "getting allowed caps");
2721 gst_object_ref (peer);
2722 GST_OBJECT_UNLOCK (pad);
2723 mycaps = gst_pad_get_caps (pad);
2725 peercaps = gst_pad_get_caps (peer);
2726 gst_object_unref (peer);
2728 caps = gst_caps_intersect (mycaps, peercaps);
2729 gst_caps_unref (peercaps);
2730 gst_caps_unref (mycaps);
2732 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "allowed caps %" GST_PTR_FORMAT,
2739 GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "no peer");
2740 GST_OBJECT_UNLOCK (pad);
2747 * gst_pad_get_negotiated_caps:
2750 * Gets the capabilities of the media type that currently flows through @pad
2753 * This function can be used on both src and sinkpads. Note that srcpads are
2754 * always negotiated before sinkpads so it is possible that the negotiated caps
2755 * on the srcpad do not match the negotiated caps of the peer.
2757 * Returns: the negotiated #GstCaps of the pad link. Unref the caps when
2758 * you no longer need it. This function returns NULL when the @pad has no
2759 * peer or is not negotiated yet.
2764 gst_pad_get_negotiated_caps (GstPad * pad)
2769 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2771 GST_OBJECT_LOCK (pad);
2773 if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
2776 GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "getting negotiated caps");
2778 caps = GST_PAD_CAPS (pad);
2780 gst_caps_ref (caps);
2781 GST_OBJECT_UNLOCK (pad);
2783 GST_CAT_DEBUG_OBJECT (GST_CAT_CAPS, pad, "negotiated caps %" GST_PTR_FORMAT,
2790 GST_CAT_DEBUG_OBJECT (GST_CAT_PROPERTIES, pad, "no peer");
2791 GST_OBJECT_UNLOCK (pad);
2797 /* calls the buffer_alloc function on the given pad */
2798 static GstFlowReturn
2799 gst_pad_buffer_alloc_unchecked (GstPad * pad, guint64 offset, gint size,
2800 GstCaps * caps, GstBuffer ** buf)
2803 GstPadBufferAllocFunction bufferallocfunc;
2805 GST_OBJECT_LOCK (pad);
2806 /* when the pad is flushing we cannot give a buffer */
2807 if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
2810 bufferallocfunc = pad->bufferallocfunc;
2812 if (offset == GST_BUFFER_OFFSET_NONE) {
2813 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2814 "calling bufferallocfunc &%s (@%p) for size %d offset NONE",
2815 GST_DEBUG_FUNCPTR_NAME (bufferallocfunc), bufferallocfunc, size);
2817 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2818 "calling bufferallocfunc &%s (@%p) of for size %d offset %"
2819 G_GUINT64_FORMAT, GST_DEBUG_FUNCPTR_NAME (bufferallocfunc),
2820 bufferallocfunc, size, offset);
2822 GST_OBJECT_UNLOCK (pad);
2824 /* G_LIKELY for now since most elements don't implement a buffer alloc
2825 * function and there is no default alloc proxy function as this is usually
2827 if (G_LIKELY (bufferallocfunc == NULL))
2830 ret = bufferallocfunc (pad, offset, size, caps, buf);
2832 if (G_UNLIKELY (ret != GST_FLOW_OK))
2835 /* no error, but NULL buffer means fallback to the default */
2836 if (G_UNLIKELY (*buf == NULL))
2839 /* If the buffer alloc function didn't set up the caps like it should,
2841 if (G_UNLIKELY (caps && (GST_BUFFER_CAPS (*buf) == NULL))) {
2842 GST_WARNING_OBJECT (pad,
2843 "Buffer allocation function did not set caps. Setting");
2844 gst_buffer_set_caps (*buf, caps);
2850 /* pad was flushing */
2851 GST_OBJECT_UNLOCK (pad);
2852 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "pad was flushing");
2853 return GST_FLOW_WRONG_STATE;
2857 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2858 "alloc function returned error (%d) %s", ret, gst_flow_get_name (ret));
2863 /* fallback case, allocate a buffer of our own, add pad caps. */
2864 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "fallback buffer alloc");
2866 if ((*buf = gst_buffer_try_new_and_alloc (size))) {
2867 GST_BUFFER_OFFSET (*buf) = offset;
2868 gst_buffer_set_caps (*buf, caps);
2871 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2872 "out of memory allocating %d bytes", size);
2873 return GST_FLOW_ERROR;
2878 /* FIXME 0.11: size should be unsigned */
2879 static GstFlowReturn
2880 gst_pad_alloc_buffer_full (GstPad * pad, guint64 offset, gint size,
2881 GstCaps * caps, GstBuffer ** buf, gboolean setcaps)
2886 gboolean caps_changed;
2888 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
2889 g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
2890 g_return_val_if_fail (buf != NULL, GST_FLOW_ERROR);
2891 g_return_val_if_fail (size >= 0, GST_FLOW_ERROR);
2893 GST_DEBUG_OBJECT (pad, "offset %" G_GUINT64_FORMAT ", size %d, caps %"
2894 GST_PTR_FORMAT, offset, size, caps);
2896 GST_OBJECT_LOCK (pad);
2897 while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
2898 if ((ret = handle_pad_block (pad)) != GST_FLOW_OK)
2901 if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
2904 gst_object_ref (peer);
2905 GST_OBJECT_UNLOCK (pad);
2907 ret = gst_pad_buffer_alloc_unchecked (peer, offset, size, caps, buf);
2908 gst_object_unref (peer);
2910 if (G_UNLIKELY (ret != GST_FLOW_OK))
2913 /* FIXME, move capnego this into a base class? */
2914 newcaps = GST_BUFFER_CAPS (*buf);
2916 /* Lock for checking caps, pretty pointless as the _pad_push() function might
2917 * change it concurrently, one of the problems with automatic caps setting in
2918 * pad_alloc_and_set_caps. Worst case, if does a check too much, but only
2919 * when there is heavy renegotiation going on in both directions. */
2920 GST_OBJECT_LOCK (pad);
2921 caps_changed = newcaps && newcaps != GST_PAD_CAPS (pad);
2922 GST_OBJECT_UNLOCK (pad);
2924 /* we got a new datatype on the pad, see if it can handle it */
2925 if (G_UNLIKELY (caps_changed)) {
2926 GST_DEBUG_OBJECT (pad,
2927 "caps changed from %" GST_PTR_FORMAT " to %p %" GST_PTR_FORMAT,
2928 GST_PAD_CAPS (pad), newcaps, newcaps);
2929 if (G_UNLIKELY (!gst_pad_configure_src (pad, newcaps, setcaps)))
2930 goto not_negotiated;
2933 /* sanity check (only if caps are the same) */
2934 if (G_LIKELY (newcaps == caps) && G_UNLIKELY (GST_BUFFER_SIZE (*buf) < size))
2935 goto wrong_size_fallback;
2941 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "pad block stopped by flush");
2942 GST_OBJECT_UNLOCK (pad);
2947 /* pad has no peer */
2948 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2949 "called bufferallocfunc but had no peer");
2950 GST_OBJECT_UNLOCK (pad);
2951 return GST_FLOW_NOT_LINKED;
2955 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
2956 "alloc function returned error %s", gst_flow_get_name (ret));
2961 gst_buffer_unref (*buf);
2963 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
2964 "alloc function returned unacceptable buffer");
2965 return GST_FLOW_NOT_NEGOTIATED;
2967 wrong_size_fallback:
2969 GST_CAT_ERROR_OBJECT (GST_CAT_PADS, pad, "buffer returned by alloc "
2970 "function is too small (%u < %d), doing fallback buffer alloc",
2971 GST_BUFFER_SIZE (*buf), size);
2973 gst_buffer_unref (*buf);
2975 if ((*buf = gst_buffer_try_new_and_alloc (size))) {
2976 GST_BUFFER_OFFSET (*buf) = offset;
2977 gst_buffer_set_caps (*buf, caps);
2980 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
2981 "out of memory allocating %d bytes", size);
2982 return GST_FLOW_ERROR;
2988 * gst_pad_alloc_buffer:
2989 * @pad: a source #GstPad
2990 * @offset: the offset of the new buffer in the stream
2991 * @size: the size of the new buffer
2992 * @caps: the caps of the new buffer
2993 * @buf: a newly allocated buffer
2995 * Allocates a new, empty buffer optimized to push to pad @pad. This
2996 * function only works if @pad is a source pad and has a peer.
2998 * A new, empty #GstBuffer will be put in the @buf argument.
2999 * You need to check the caps of the buffer after performing this
3000 * function and renegotiate to the format if needed. If the caps changed, it is
3001 * possible that the buffer returned in @buf is not of the right size for the
3002 * new format, @buf needs to be unreffed and reallocated if this is the case.
3004 * Returns: a result code indicating success of the operation. Any
3005 * result code other than #GST_FLOW_OK is an error and @buf should
3007 * An error can occur if the pad is not connected or when the downstream
3008 * peer elements cannot provide an acceptable buffer.
3013 /* FIXME 0.11: size should be unsigned */
3015 gst_pad_alloc_buffer (GstPad * pad, guint64 offset, gint size, GstCaps * caps,
3018 return gst_pad_alloc_buffer_full (pad, offset, size, caps, buf, FALSE);
3022 * gst_pad_alloc_buffer_and_set_caps:
3023 * @pad: a source #GstPad
3024 * @offset: the offset of the new buffer in the stream
3025 * @size: the size of the new buffer
3026 * @caps: the caps of the new buffer
3027 * @buf: a newly allocated buffer
3029 * In addition to the function gst_pad_alloc_buffer(), this function
3030 * automatically calls gst_pad_set_caps() when the caps of the
3031 * newly allocated buffer are different from the @pad caps.
3033 * After a renegotiation, the size of the new buffer returned in @buf could
3034 * be of the wrong size for the new format and must be unreffed an reallocated
3037 * Returns: a result code indicating success of the operation. Any
3038 * result code other than #GST_FLOW_OK is an error and @buf should
3040 * An error can occur if the pad is not connected or when the downstream
3041 * peer elements cannot provide an acceptable buffer.
3046 /* FIXME 0.11: size should be unsigned */
3048 gst_pad_alloc_buffer_and_set_caps (GstPad * pad, guint64 offset, gint size,
3049 GstCaps * caps, GstBuffer ** buf)
3051 return gst_pad_alloc_buffer_full (pad, offset, size, caps, buf, TRUE);
3055 #ifndef GST_REMOVE_DEPRECATED
3063 int_link_iter_data_free (IntLinkIterData * data)
3065 g_list_free (data->list);
3070 static GstIteratorItem
3071 iterate_pad (GstIterator * it, GstPad * pad)
3073 gst_object_ref (pad);
3074 return GST_ITERATOR_ITEM_PASS;
3078 * gst_pad_iterate_internal_links_default:
3079 * @pad: the #GstPad to get the internal links of.
3081 * Iterate the list of pads to which the given pad is linked to inside of
3082 * the parent element.
3083 * This is the default handler, and thus returns an iterator of all of the
3084 * pads inside the parent element with opposite direction.
3086 * The caller must free this iterator after use with gst_iterator_free().
3088 * Returns: a #GstIterator of #GstPad, or NULL if @pad has no parent. Unref each
3089 * returned pad with gst_object_unref().
3094 gst_pad_iterate_internal_links_default (GstPad * pad)
3101 GstIteratorDisposeFunction dispose;
3103 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
3105 #ifndef GST_REMOVE_DEPRECATED
3106 /* when we get here, the default handler for the iterate links is called,
3107 * which means that the user has not installed a custom one. We first check if
3108 * there is maybe a custom legacy function we can call. */
3109 if (GST_PAD_INTLINKFUNC (pad) &&
3110 GST_PAD_INTLINKFUNC (pad) != gst_pad_get_internal_links_default) {
3111 IntLinkIterData *data;
3113 /* make an iterator for the list. We can't protect the list with a
3114 * cookie. If we would take the cookie of the parent element, we need to
3115 * have a parent, which is not required for GST_PAD_INTLINKFUNC(). We could
3116 * cache the per-pad list and invalidate the list when a new call to
3117 * INTLINKFUNC() returned a different list but then this would only work if
3118 * two concurrent iterators were used and the last iterator would still be
3119 * thread-unsafe. Just don't use this method anymore. */
3120 data = g_new0 (IntLinkIterData, 1);
3121 data->list = GST_PAD_INTLINKFUNC (pad) (pad);
3124 GST_WARNING_OBJECT (pad, "Making unsafe iterator");
3126 cookie = &data->cookie;
3127 padlist = &data->list;
3129 dispose = (GstIteratorDisposeFunction) int_link_iter_data_free;
3130 /* reuse the pad lock, it's all we have here */
3131 lock = GST_OBJECT_GET_LOCK (pad);
3137 GST_OBJECT_LOCK (pad);
3138 parent = GST_PAD_PARENT (pad);
3139 if (!parent || !GST_IS_ELEMENT (parent))
3142 gst_object_ref (parent);
3143 GST_OBJECT_UNLOCK (pad);
3145 if (pad->direction == GST_PAD_SRC)
3146 padlist = &parent->sinkpads;
3148 padlist = &parent->srcpads;
3150 GST_DEBUG_OBJECT (pad, "Making iterator");
3152 cookie = &parent->pads_cookie;
3154 dispose = (GstIteratorDisposeFunction) gst_object_unref;
3155 lock = GST_OBJECT_GET_LOCK (parent);
3158 res = gst_iterator_new_list (GST_TYPE_PAD,
3159 lock, cookie, padlist, owner, (GstIteratorItemFunction) iterate_pad,
3167 GST_OBJECT_UNLOCK (pad);
3168 GST_DEBUG_OBJECT (pad, "no parent element");
3174 * gst_pad_iterate_internal_links:
3175 * @pad: the GstPad to get the internal links of.
3177 * Gets an iterator for the pads to which the given pad is linked to inside
3178 * of the parent element.
3180 * Each #GstPad element yielded by the iterator will have its refcount increased,
3181 * so unref after use.
3183 * Returns: a new #GstIterator of #GstPad or %NULL when the pad does not have an
3184 * iterator function configured. Use gst_iterator_free() after usage.
3189 gst_pad_iterate_internal_links (GstPad * pad)
3191 GstIterator *res = NULL;
3193 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
3195 if (GST_PAD_ITERINTLINKFUNC (pad))
3196 res = GST_PAD_ITERINTLINKFUNC (pad) (pad);
3201 #ifndef GST_REMOVE_DEPRECATED
3203 add_unref_pad_to_list (GstPad * pad, GList * list)
3205 list = g_list_prepend (list, pad);
3206 gst_object_unref (pad);
3211 * gst_pad_get_internal_links_default:
3212 * @pad: the #GstPad to get the internal links of.
3214 * Gets a list of pads to which the given pad is linked to
3215 * inside of the parent element.
3216 * This is the default handler, and thus returns a list of all of the
3217 * pads inside the parent element with opposite direction.
3219 * The caller must free this list after use with g_list_free().
3221 * Returns: a newly allocated #GList of pads, or NULL if the pad has no parent.
3225 * Deprecated: This function does not ref the pads in the list so that they
3226 * could become invalid by the time the application accesses them. It's also
3227 * possible that the list changes while handling the pads, which the caller of
3228 * this function is unable to know. Use the thread-safe
3229 * gst_pad_iterate_internal_links_default() instead.
3231 #ifndef GST_REMOVE_DEPRECATED
3233 gst_pad_get_internal_links_default (GstPad * pad)
3238 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
3240 GST_WARNING_OBJECT (pad, "Unsafe internal links used");
3242 /* when we get here, the default handler for get_internal_links is called,
3243 * which means that the user has not installed a custom one. We first check if
3244 * there is maybe a custom iterate function we can call. */
3245 if (GST_PAD_ITERINTLINKFUNC (pad) &&
3246 GST_PAD_ITERINTLINKFUNC (pad) != gst_pad_iterate_internal_links_default) {
3248 GstIteratorResult ires;
3249 gboolean done = FALSE;
3251 it = gst_pad_iterate_internal_links (pad);
3252 /* loop over the iterator and put all elements into a list, we also
3253 * immediatly unref them, which is bad. */
3255 ires = gst_iterator_foreach (it, (GFunc) add_unref_pad_to_list, res);
3257 case GST_ITERATOR_OK:
3258 case GST_ITERATOR_DONE:
3259 case GST_ITERATOR_ERROR:
3262 case GST_ITERATOR_RESYNC:
3263 /* restart, discard previous list */
3264 gst_iterator_resync (it);
3271 gst_iterator_free (it);
3273 /* lock pad, check and ref parent */
3274 GST_OBJECT_LOCK (pad);
3275 parent = GST_PAD_PARENT (pad);
3276 if (!parent || !GST_IS_ELEMENT (parent))
3279 parent = gst_object_ref (parent);
3280 GST_OBJECT_UNLOCK (pad);
3282 /* now lock the parent while we copy the pads */
3283 GST_OBJECT_LOCK (parent);
3284 if (pad->direction == GST_PAD_SRC)
3285 res = g_list_copy (parent->sinkpads);
3287 res = g_list_copy (parent->srcpads);
3288 GST_OBJECT_UNLOCK (parent);
3290 gst_object_unref (parent);
3293 /* At this point pads can be changed and unreffed. Nothing we can do about it
3294 * because for compatibility reasons this function cannot ref the pads or
3295 * notify the app that the list changed. */
3301 GST_DEBUG_OBJECT (pad, "no parent");
3302 GST_OBJECT_UNLOCK (pad);
3306 #endif /* GST_REMOVE_DEPRECATED */
3309 * gst_pad_get_internal_links:
3310 * @pad: the #GstPad to get the internal links of.
3312 * Gets a list of pads to which the given pad is linked to
3313 * inside of the parent element.
3314 * The caller must free this list after use.
3318 * Returns: a newly allocated #GList of pads, free with g_list_free().
3320 * Deprecated: This function does not ref the pads in the list so that they
3321 * could become invalid by the time the application accesses them. It's also
3322 * possible that the list changes while handling the pads, which the caller of
3323 * this function is unable to know. Use the thread-safe
3324 * gst_pad_iterate_internal_links() instead.
3326 #ifndef GST_REMOVE_DEPRECATED
3328 gst_pad_get_internal_links (GstPad * pad)
3332 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
3334 GST_WARNING_OBJECT (pad, "Calling unsafe internal links");
3336 if (GST_PAD_INTLINKFUNC (pad))
3337 res = GST_PAD_INTLINKFUNC (pad) (pad);
3341 #endif /* GST_REMOVE_DEPRECATED */
3344 gst_pad_event_default_dispatch (GstPad * pad, GstEvent * event)
3346 gboolean result = FALSE;
3348 gboolean done = FALSE;
3351 GList *pushed_pads = NULL;
3353 GST_INFO_OBJECT (pad, "Sending event %p (%s) to all internally linked pads",
3354 event, GST_EVENT_TYPE_NAME (event));
3356 iter = gst_pad_iterate_internal_links (pad);
3362 switch (gst_iterator_next (iter, &item)) {
3363 case GST_ITERATOR_OK:
3364 eventpad = GST_PAD (item);
3366 /* if already pushed, skip */
3367 if (g_list_find (pushed_pads, eventpad)) {
3368 gst_object_unref (item);
3372 if (GST_PAD_IS_SRC (eventpad)) {
3373 /* for each pad we send to, we should ref the event; it's up
3374 * to downstream to unref again when handled. */
3375 GST_LOG_OBJECT (pad, "Reffing and sending event %p (%s) to %s:%s",
3376 event, GST_EVENT_TYPE_NAME (event),
3377 GST_DEBUG_PAD_NAME (eventpad));
3378 gst_event_ref (event);
3379 result |= gst_pad_push_event (eventpad, event);
3381 /* we only send the event on one pad, multi-sinkpad elements
3382 * should implement a handler */
3383 GST_LOG_OBJECT (pad, "sending event %p (%s) to one sink pad %s:%s",
3384 event, GST_EVENT_TYPE_NAME (event),
3385 GST_DEBUG_PAD_NAME (eventpad));
3386 result = gst_pad_push_event (eventpad, event);
3391 pushed_pads = g_list_prepend (pushed_pads, eventpad);
3393 gst_object_unref (item);
3395 case GST_ITERATOR_RESYNC:
3396 /* FIXME, if we want to reset the result value we need to remember which
3397 * pads pushed with which result */
3398 gst_iterator_resync (iter);
3400 case GST_ITERATOR_ERROR:
3401 GST_ERROR_OBJECT (pad, "Could not iterate over internally linked pads");
3404 case GST_ITERATOR_DONE:
3409 gst_iterator_free (iter);
3413 /* If this is a sinkpad and we don't have pads to send the event to, we
3414 * return TRUE. This is so that when using the default handler on a sink
3415 * element, we don't fail to push it. */
3417 result = GST_PAD_IS_SINK (pad);
3419 g_list_free (pushed_pads);
3421 /* we handled the incoming event so we unref once */
3423 GST_LOG_OBJECT (pad, "handled event %p, unreffing", event);
3424 gst_event_unref (event);
3431 * gst_pad_event_default:
3432 * @pad: a #GstPad to call the default event handler on.
3433 * @event: the #GstEvent to handle.
3435 * Invokes the default event handler for the given pad. End-of-stream and
3436 * discontinuity events are handled specially, and then the event is sent to all
3437 * pads internally linked to @pad. Note that if there are many possible sink
3438 * pads that are internally linked to @pad, only one will be sent an event.
3439 * Multi-sinkpad elements should implement custom event handlers.
3441 * Returns: TRUE if the event was sent succesfully.
3444 gst_pad_event_default (GstPad * pad, GstEvent * event)
3446 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3447 g_return_val_if_fail (event != NULL, FALSE);
3449 GST_LOG_OBJECT (pad, "default event handler");
3451 switch (GST_EVENT_TYPE (event)) {
3454 GST_DEBUG_OBJECT (pad, "pausing task because of eos");
3455 gst_pad_pause_task (pad);
3462 return gst_pad_event_default_dispatch (pad, event);
3466 * gst_pad_dispatcher:
3467 * @pad: a #GstPad to dispatch.
3468 * @dispatch: the #GstDispatcherFunction to call.
3469 * @data: gpointer user data passed to the dispatcher function.
3471 * Invokes the given dispatcher function on each respective peer of
3472 * all pads that are internally linked to the given pad.
3473 * The GstPadDispatcherFunction should return TRUE when no further pads
3474 * need to be processed.
3476 * Returns: TRUE if one of the dispatcher functions returned TRUE.
3479 gst_pad_dispatcher (GstPad * pad, GstPadDispatcherFunction dispatch,
3482 gboolean res = FALSE;
3483 GstIterator *iter = NULL;
3484 gboolean done = FALSE;
3487 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3488 g_return_val_if_fail (dispatch != NULL, FALSE);
3490 iter = gst_pad_iterate_internal_links (pad);
3496 switch (gst_iterator_next (iter, &item)) {
3497 case GST_ITERATOR_OK:
3499 GstPad *int_pad = GST_PAD_CAST (item);
3500 GstPad *int_peer = gst_pad_get_peer (int_pad);
3503 GST_DEBUG_OBJECT (int_pad, "dispatching to peer %s:%s",
3504 GST_DEBUG_PAD_NAME (int_peer));
3505 done = res = dispatch (int_peer, data);
3506 gst_object_unref (int_peer);
3508 GST_DEBUG_OBJECT (int_pad, "no peer");
3511 gst_object_unref (item);
3513 case GST_ITERATOR_RESYNC:
3514 gst_iterator_resync (iter);
3516 case GST_ITERATOR_ERROR:
3518 GST_ERROR_OBJECT (pad, "Could not iterate internally linked pads");
3520 case GST_ITERATOR_DONE:
3525 gst_iterator_free (iter);
3527 GST_DEBUG_OBJECT (pad, "done, result %d", res);
3536 * @pad: a #GstPad to invoke the default query on.
3537 * @query: the #GstQuery to perform.
3539 * Dispatches a query to a pad. The query should have been allocated by the
3540 * caller via one of the type-specific allocation functions in gstquery.h. The
3541 * element is responsible for filling the query with an appropriate response,
3542 * which should then be parsed with a type-specific query parsing function.
3544 * Again, the caller is responsible for both the allocation and deallocation of
3545 * the query structure.
3547 * Returns: TRUE if the query could be performed.
3550 gst_pad_query (GstPad * pad, GstQuery * query)
3552 GstPadQueryFunction func;
3554 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3555 g_return_val_if_fail (GST_IS_QUERY (query), FALSE);
3557 GST_DEBUG_OBJECT (pad, "sending query %p", query);
3559 if ((func = GST_PAD_QUERYFUNC (pad)) == NULL)
3562 return func (pad, query);
3566 GST_DEBUG_OBJECT (pad, "had no query function");
3572 * gst_pad_peer_query:
3573 * @pad: a #GstPad to invoke the peer query on.
3574 * @query: the #GstQuery to perform.
3576 * Performs gst_pad_query() on the peer of @pad.
3578 * The caller is responsible for both the allocation and deallocation of
3579 * the query structure.
3581 * Returns: TRUE if the query could be performed. This function returns %FALSE
3582 * if @pad has no peer.
3587 gst_pad_peer_query (GstPad * pad, GstQuery * query)
3592 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3593 g_return_val_if_fail (GST_IS_QUERY (query), FALSE);
3595 GST_OBJECT_LOCK (pad);
3597 GST_DEBUG_OBJECT (pad, "peer query");
3599 peerpad = GST_PAD_PEER (pad);
3600 if (G_UNLIKELY (peerpad == NULL))
3603 gst_object_ref (peerpad);
3604 GST_OBJECT_UNLOCK (pad);
3606 result = gst_pad_query (peerpad, query);
3608 gst_object_unref (peerpad);
3615 GST_WARNING_OBJECT (pad, "pad has no peer");
3616 GST_OBJECT_UNLOCK (pad);
3622 * gst_pad_query_default:
3623 * @pad: a #GstPad to call the default query handler on.
3624 * @query: the #GstQuery to handle.
3626 * Invokes the default query handler for the given pad.
3627 * The query is sent to all pads internally linked to @pad. Note that
3628 * if there are many possible sink pads that are internally linked to
3629 * @pad, only one will be sent the query.
3630 * Multi-sinkpad elements should implement custom query handlers.
3632 * Returns: TRUE if the query was performed succesfully.
3635 gst_pad_query_default (GstPad * pad, GstQuery * query)
3637 switch (GST_QUERY_TYPE (query)) {
3638 case GST_QUERY_POSITION:
3639 case GST_QUERY_SEEKING:
3640 case GST_QUERY_FORMATS:
3641 case GST_QUERY_LATENCY:
3642 case GST_QUERY_JITTER:
3643 case GST_QUERY_RATE:
3644 case GST_QUERY_CONVERT:
3646 return gst_pad_dispatcher
3647 (pad, (GstPadDispatcherFunction) gst_pad_query, query);
3651 #ifndef GST_DISABLE_LOADSAVE
3652 /* FIXME: why isn't this on a GstElement ? */
3654 * gst_pad_load_and_link:
3655 * @self: an #xmlNodePtr to read the description from.
3656 * @parent: the #GstObject element that owns the pad.
3658 * Reads the pad definition from the XML node and links the given pad
3659 * in the element to a pad of an element up in the hierarchy.
3662 gst_pad_load_and_link (xmlNodePtr self, GstObject * parent)
3664 xmlNodePtr field = self->xmlChildrenNode;
3665 GstPad *pad = NULL, *targetpad;
3666 GstPadTemplate *tmpl;
3670 GstObject *grandparent;
3674 if (!strcmp ((char *) field->name, "name")) {
3675 name = (gchar *) xmlNodeGetContent (field);
3676 pad = gst_element_get_static_pad (GST_ELEMENT (parent), name);
3677 if ((!pad) || ((tmpl = gst_pad_get_pad_template (pad))
3678 && (GST_PAD_REQUEST == GST_PAD_TEMPLATE_PRESENCE (tmpl))))
3679 pad = gst_element_get_request_pad (GST_ELEMENT (parent), name);
3681 } else if (!strcmp ((char *) field->name, "peer")) {
3682 peer = (gchar *) xmlNodeGetContent (field);
3684 field = field->next;
3686 g_return_if_fail (pad != NULL);
3691 split = g_strsplit (peer, ".", 2);
3693 if (split[0] == NULL || split[1] == NULL) {
3694 GST_CAT_DEBUG_OBJECT (GST_CAT_XML, pad,
3695 "Could not parse peer '%s', leaving unlinked", peer);
3702 g_return_if_fail (split[0] != NULL);
3703 g_return_if_fail (split[1] != NULL);
3705 grandparent = gst_object_get_parent (parent);
3707 if (grandparent && GST_IS_BIN (grandparent)) {
3708 target = gst_bin_get_by_name_recurse_up (GST_BIN (grandparent), split[0]);
3715 targetpad = gst_element_get_static_pad (target, split[1]);
3717 targetpad = gst_element_get_request_pad (target, split[1]);
3719 if (targetpad == NULL)
3722 if (gst_pad_get_direction (pad) == GST_PAD_SRC)
3723 gst_pad_link (pad, targetpad);
3725 gst_pad_link (targetpad, pad);
3732 * gst_pad_save_thyself:
3733 * @pad: a #GstPad to save.
3734 * @parent: the parent #xmlNodePtr to save the description in.
3736 * Saves the pad into an xml representation.
3738 * Returns: the #xmlNodePtr representation of the pad.
3741 gst_pad_save_thyself (GstObject * object, xmlNodePtr parent)
3746 g_return_val_if_fail (GST_IS_PAD (object), NULL);
3748 pad = GST_PAD (object);
3750 xmlNewChild (parent, NULL, (xmlChar *) "name",
3751 (xmlChar *) GST_PAD_NAME (pad));
3753 if (GST_PAD_IS_SRC (pad)) {
3754 xmlNewChild (parent, NULL, (xmlChar *) "direction", (xmlChar *) "source");
3755 } else if (GST_PAD_IS_SINK (pad)) {
3756 xmlNewChild (parent, NULL, (xmlChar *) "direction", (xmlChar *) "sink");
3758 xmlNewChild (parent, NULL, (xmlChar *) "direction", (xmlChar *) "unknown");
3761 if (GST_PAD_PEER (pad) != NULL) {
3764 peer = GST_PAD_PEER (pad);
3765 /* first check to see if the peer's parent's parent is the same */
3766 /* we just save it off */
3767 content = g_strdup_printf ("%s.%s",
3768 GST_OBJECT_NAME (GST_PAD_PARENT (peer)), GST_PAD_NAME (peer));
3769 xmlNewChild (parent, NULL, (xmlChar *) "peer", (xmlChar *) content);
3772 xmlNewChild (parent, NULL, (xmlChar *) "peer", NULL);
3779 * gst_ghost_pad_save_thyself:
3780 * @pad: a ghost #GstPad to save.
3781 * @parent: the parent #xmlNodePtr to save the description in.
3783 * Saves the ghost pad into an xml representation.
3785 * Returns: the #xmlNodePtr representation of the pad.
3788 gst_ghost_pad_save_thyself (GstPad * pad, xmlNodePtr parent)
3792 g_return_val_if_fail (GST_IS_GHOST_PAD (pad), NULL);
3794 self = xmlNewChild (parent, NULL, (xmlChar *) "ghostpad", NULL);
3795 xmlNewChild (self, NULL, (xmlChar *) "name", (xmlChar *) GST_PAD_NAME (pad));
3796 xmlNewChild (self, NULL, (xmlChar *) "parent",
3797 (xmlChar *) GST_OBJECT_NAME (GST_PAD_PARENT (pad)));
3799 /* FIXME FIXME FIXME! */
3804 #endif /* GST_DISABLE_LOADSAVE */
3807 * should be called with pad OBJECT_LOCK and STREAM_LOCK held.
3808 * GST_PAD_IS_BLOCKED (pad) == TRUE when this function is
3811 * This function performs the pad blocking when an event, buffer push
3812 * or buffer_alloc is performed on a _SRC_ pad. It blocks the
3813 * streaming thread after informing the pad has been blocked.
3815 * An application can with this method wait and block any streaming
3816 * thread and perform operations such as seeking or linking.
3818 * Two methods are available for notifying the application of the
3820 * - the callback method, which happens in the STREAMING thread with
3821 * the STREAM_LOCK held. With this method, the most useful way of
3822 * dealing with the callback is to post a message to the main thread
3823 * where the pad block can then be handled outside of the streaming
3824 * thread. With the last method one can perform all operations such
3825 * as doing a state change, linking, unblocking, seeking etc on the
3827 * - the GCond signal method, which makes any thread unblock when
3828 * the pad block happens.
3830 * During the actual blocking state, the GST_PAD_BLOCKING flag is set.
3831 * The GST_PAD_BLOCKING flag is unset when the pad was unblocked.
3835 static GstFlowReturn
3836 handle_pad_block (GstPad * pad)
3838 GstPadBlockCallback callback;
3840 GstFlowReturn ret = GST_FLOW_OK;
3842 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "signal block taken");
3844 /* flushing, don't bother trying to block and return WRONG_STATE
3846 if (GST_PAD_IS_FLUSHING (pad))
3847 goto flushingnonref;
3849 /* we grab an extra ref for the callbacks, this is probably not
3850 * needed (callback code does not have a ref and cannot unref). I
3851 * think this was done to make it possible to unref the element in
3852 * the callback, which is in the end totally impossible as it
3853 * requires grabbing the STREAM_LOCK and OBJECT_LOCK which are
3854 * all taken when calling this function. */
3855 gst_object_ref (pad);
3857 while (GST_PAD_IS_BLOCKED (pad)) {
3859 /* we either have a callback installed to notify the block or
3860 * some other thread is doing a GCond wait. */
3861 callback = pad->block_callback;
3862 pad->abidata.ABI.block_callback_called = TRUE;
3864 /* there is a callback installed, call it. We release the
3865 * lock so that the callback can do something usefull with the
3867 user_data = pad->block_data;
3868 GST_OBJECT_UNLOCK (pad);
3869 callback (pad, TRUE, user_data);
3870 GST_OBJECT_LOCK (pad);
3872 /* we released the lock, recheck flushing */
3873 if (GST_PAD_IS_FLUSHING (pad))
3876 /* no callback, signal the thread that is doing a GCond wait
3878 GST_PAD_BLOCK_BROADCAST (pad);
3880 } while (pad->abidata.ABI.block_callback_called == FALSE
3881 && GST_PAD_IS_BLOCKED (pad));
3883 /* OBJECT_LOCK could have been released when we did the callback, which
3884 * then could have made the pad unblock so we need to check the blocking
3885 * condition again. */
3886 if (!GST_PAD_IS_BLOCKED (pad))
3889 /* now we block the streaming thread. It can be unlocked when we
3890 * deactivate the pad (which will also set the FLUSHING flag) or
3891 * when the pad is unblocked. A flushing event will also unblock
3892 * the pad after setting the FLUSHING flag. */
3893 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
3894 "Waiting to be unblocked or set flushing");
3895 GST_OBJECT_FLAG_SET (pad, GST_PAD_BLOCKING);
3896 GST_PAD_BLOCK_WAIT (pad);
3897 GST_OBJECT_FLAG_UNSET (pad, GST_PAD_BLOCKING);
3899 /* see if we got unblocked by a flush or not */
3900 if (GST_PAD_IS_FLUSHING (pad))
3904 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "got unblocked");
3906 /* when we get here, the pad is unblocked again and we perform
3907 * the needed unblock code. */
3908 callback = pad->block_callback;
3910 /* we need to call the callback */
3911 user_data = pad->block_data;
3912 GST_OBJECT_UNLOCK (pad);
3913 callback (pad, FALSE, user_data);
3914 GST_OBJECT_LOCK (pad);
3916 /* we need to signal the thread waiting on the GCond */
3917 GST_PAD_BLOCK_BROADCAST (pad);
3920 gst_object_unref (pad);
3926 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "pad was flushing");
3927 return GST_FLOW_WRONG_STATE;
3931 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad, "pad became flushing");
3932 gst_object_unref (pad);
3933 return GST_FLOW_WRONG_STATE;
3937 /**********************************************************************
3938 * Data passing functions
3942 gst_pad_emit_have_data_signal (GstPad * pad, GstMiniObject * obj)
3945 GValue args[2] = { {0}, {0} };
3950 g_value_init (&ret, G_TYPE_BOOLEAN);
3951 g_value_set_boolean (&ret, TRUE);
3952 g_value_init (&args[0], GST_TYPE_PAD);
3953 g_value_set_object (&args[0], pad);
3954 g_value_init (&args[1], GST_TYPE_MINI_OBJECT);
3955 gst_value_set_mini_object (&args[1], obj);
3957 if (GST_IS_EVENT (obj))
3958 detail = event_quark;
3960 detail = buffer_quark;
3963 g_signal_emitv (args, gst_pad_signals[PAD_HAVE_DATA], detail, &ret);
3964 res = g_value_get_boolean (&ret);
3967 g_value_unset (&ret);
3968 g_value_unset (&args[0]);
3969 g_value_unset (&args[1]);
3975 gst_pad_data_unref (gboolean is_buffer, void *data)
3977 if (G_LIKELY (is_buffer)) {
3978 gst_buffer_unref (data);
3980 gst_buffer_list_unref (data);
3985 gst_pad_data_get_caps (gboolean is_buffer, void *data)
3989 if (G_LIKELY (is_buffer)) {
3990 caps = GST_BUFFER_CAPS (data);
3994 if ((buf = gst_buffer_list_get (GST_BUFFER_LIST_CAST (data), 0, 0)))
3995 caps = GST_BUFFER_CAPS (buf);
4002 /* this is the chain function that does not perform the additional argument
4003 * checking for that little extra speed.
4005 static inline GstFlowReturn
4006 gst_pad_chain_data_unchecked (GstPad * pad, gboolean is_buffer, void *data)
4009 gboolean caps_changed;
4011 gboolean emit_signal;
4013 GST_PAD_STREAM_LOCK (pad);
4015 GST_OBJECT_LOCK (pad);
4016 if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4019 caps = gst_pad_data_get_caps (is_buffer, data);
4020 caps_changed = caps && caps != GST_PAD_CAPS (pad);
4022 emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
4023 GST_OBJECT_UNLOCK (pad);
4025 /* see if the signal should be emited, we emit before caps nego as
4026 * we might drop the buffer and do capsnego for nothing. */
4027 if (G_UNLIKELY (emit_signal)) {
4028 if (G_LIKELY (is_buffer)) {
4029 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (data)))
4032 /* chain all groups in the buffer list one by one to avoid problems with
4033 * buffer probes that push buffers or events */
4038 /* we got a new datatype on the pad, see if it can handle it */
4039 if (G_UNLIKELY (caps_changed)) {
4040 GST_DEBUG_OBJECT (pad, "caps changed to %p %" GST_PTR_FORMAT, caps, caps);
4041 if (G_UNLIKELY (!gst_pad_configure_sink (pad, caps)))
4042 goto not_negotiated;
4045 /* NOTE: we read the chainfunc unlocked.
4046 * we cannot hold the lock for the pad so we might send
4047 * the data to the wrong function. This is not really a
4048 * problem since functions are assigned at creation time
4049 * and don't change that often... */
4050 if (G_LIKELY (is_buffer)) {
4051 GstPadChainFunction chainfunc;
4053 if (G_UNLIKELY ((chainfunc = GST_PAD_CHAINFUNC (pad)) == NULL))
4056 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4057 "calling chainfunction &%s", GST_DEBUG_FUNCPTR_NAME (chainfunc));
4059 ret = chainfunc (pad, GST_BUFFER_CAST (data));
4061 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4062 "called chainfunction &%s, returned %s",
4063 GST_DEBUG_FUNCPTR_NAME (chainfunc), gst_flow_get_name (ret));
4065 GstPadChainListFunction chainlistfunc;
4067 if (G_UNLIKELY ((chainlistfunc = GST_PAD_CHAINLISTFUNC (pad)) == NULL))
4070 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4071 "calling chainlistfunction &%s",
4072 GST_DEBUG_FUNCPTR_NAME (chainlistfunc));
4074 ret = chainlistfunc (pad, GST_BUFFER_LIST_CAST (data));
4076 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4077 "called chainlistfunction &%s, returned %s",
4078 GST_DEBUG_FUNCPTR_NAME (chainlistfunc), gst_flow_get_name (ret));
4081 GST_PAD_STREAM_UNLOCK (pad);
4087 GstBufferList *list;
4088 GstBufferListIterator *it;
4091 GST_PAD_STREAM_UNLOCK (pad);
4093 GST_INFO_OBJECT (pad, "chaining each group in list as a merged buffer");
4095 list = GST_BUFFER_LIST_CAST (data);
4096 it = gst_buffer_list_iterate (list);
4099 if (gst_buffer_list_iterator_next_group (it)) {
4101 group = gst_buffer_list_iterator_merge_group (it);
4102 if (group == NULL) {
4103 group = gst_buffer_new ();
4104 GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "chaining empty group");
4106 GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "chaining group");
4108 ret = gst_pad_chain_data_unchecked (pad, TRUE, group);
4109 } while (ret == GST_FLOW_OK && gst_buffer_list_iterator_next_group (it));
4111 GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "chaining empty group");
4112 ret = gst_pad_chain_data_unchecked (pad, TRUE, gst_buffer_new ());
4115 gst_buffer_list_iterator_free (it);
4116 gst_buffer_list_unref (list);
4124 gst_pad_data_unref (is_buffer, data);
4125 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4126 "pushing, but pad was flushing");
4127 GST_OBJECT_UNLOCK (pad);
4128 GST_PAD_STREAM_UNLOCK (pad);
4129 return GST_FLOW_WRONG_STATE;
4133 gst_pad_data_unref (is_buffer, data);
4134 GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
4135 GST_PAD_STREAM_UNLOCK (pad);
4140 gst_pad_data_unref (is_buffer, data);
4141 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4142 "pushing data but pad did not accept");
4143 GST_PAD_STREAM_UNLOCK (pad);
4144 return GST_FLOW_NOT_NEGOTIATED;
4148 gst_pad_data_unref (is_buffer, data);
4149 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4150 "pushing, but not chainhandler");
4151 GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
4152 ("push on pad %s:%s but it has no chainfunction",
4153 GST_DEBUG_PAD_NAME (pad)));
4154 GST_PAD_STREAM_UNLOCK (pad);
4155 return GST_FLOW_NOT_SUPPORTED;
4161 * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
4162 * @buffer: the #GstBuffer to send, return GST_FLOW_ERROR if not.
4164 * Chain a buffer to @pad.
4166 * The function returns #GST_FLOW_WRONG_STATE if the pad was flushing.
4168 * If the caps on @buffer are different from the current caps on @pad, this
4169 * function will call any setcaps function (see gst_pad_set_setcaps_function())
4170 * installed on @pad. If the new caps are not acceptable for @pad, this
4171 * function returns #GST_FLOW_NOT_NEGOTIATED.
4173 * The function proceeds calling the chain function installed on @pad (see
4174 * gst_pad_set_chain_function()) and the return value of that function is
4175 * returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no
4178 * In all cases, success or failure, the caller loses its reference to @buffer
4179 * after calling this function.
4181 * Returns: a #GstFlowReturn from the pad.
4186 gst_pad_chain (GstPad * pad, GstBuffer * buffer)
4188 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4189 g_return_val_if_fail (GST_PAD_IS_SINK (pad), GST_FLOW_ERROR);
4190 g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
4192 return gst_pad_chain_data_unchecked (pad, TRUE, buffer);
4196 * gst_pad_chain_list:
4197 * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
4198 * @list: the #GstBufferList to send, return GST_FLOW_ERROR if not.
4200 * Chain a bufferlist to @pad.
4202 * The function returns #GST_FLOW_WRONG_STATE if the pad was flushing.
4204 * If the caps on the first buffer of @list are different from the current
4205 * caps on @pad, this function will call any setcaps function
4206 * (see gst_pad_set_setcaps_function()) installed on @pad. If the new caps
4207 * are not acceptable for @pad, this function returns #GST_FLOW_NOT_NEGOTIATED.
4209 * The function proceeds calling the chainlist function installed on @pad (see
4210 * gst_pad_set_chain_list_function()) and the return value of that function is
4211 * returned to the caller. #GST_FLOW_NOT_SUPPORTED is returned if @pad has no
4212 * chainlist function.
4214 * In all cases, success or failure, the caller loses its reference to @list
4215 * after calling this function.
4219 * Returns: a #GstFlowReturn from the pad.
4224 gst_pad_chain_list (GstPad * pad, GstBufferList * list)
4226 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4227 g_return_val_if_fail (GST_PAD_IS_SINK (pad), GST_FLOW_ERROR);
4228 g_return_val_if_fail (GST_IS_BUFFER_LIST (list), GST_FLOW_ERROR);
4230 return gst_pad_chain_data_unchecked (pad, FALSE, list);
4233 static GstFlowReturn
4234 gst_pad_push_data (GstPad * pad, gboolean is_buffer, void *data)
4239 gboolean caps_changed;
4241 GST_OBJECT_LOCK (pad);
4243 /* FIXME: this check can go away; pad_set_blocked could be implemented with
4244 * probes completely or probes with an extended pad block. */
4245 while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
4246 if ((ret = handle_pad_block (pad)) != GST_FLOW_OK)
4249 /* we emit signals on the pad arg, the peer will have a chance to
4250 * emit in the _chain() function */
4251 if (G_UNLIKELY (GST_PAD_DO_BUFFER_SIGNALS (pad) > 0)) {
4252 /* unlock before emitting */
4253 GST_OBJECT_UNLOCK (pad);
4255 if (G_LIKELY (is_buffer)) {
4256 /* if the signal handler returned FALSE, it means we should just drop the
4258 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (data)))
4261 /* push all buffers in the list */
4264 GST_OBJECT_LOCK (pad);
4267 if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
4270 /* Before pushing the buffer to the peer pad, ensure that caps
4271 * are set on this pad */
4272 caps = gst_pad_data_get_caps (is_buffer, data);
4273 caps_changed = caps && caps != GST_PAD_CAPS (pad);
4275 /* take ref to peer pad before releasing the lock */
4276 gst_object_ref (peer);
4278 GST_OBJECT_UNLOCK (pad);
4280 /* we got a new datatype from the pad, it had better handle it */
4281 if (G_UNLIKELY (caps_changed)) {
4282 GST_DEBUG_OBJECT (pad,
4283 "caps changed from %" GST_PTR_FORMAT " to %p %" GST_PTR_FORMAT,
4284 GST_PAD_CAPS (pad), caps, caps);
4285 if (G_UNLIKELY (!gst_pad_configure_src (pad, caps, TRUE)))
4286 goto not_negotiated;
4289 ret = gst_pad_chain_data_unchecked (peer, is_buffer, data);
4291 gst_object_unref (peer);
4297 GstBufferList *list;
4298 GstBufferListIterator *it;
4301 GST_INFO_OBJECT (pad, "pushing each group in list as a merged buffer");
4303 list = GST_BUFFER_LIST_CAST (data);
4304 it = gst_buffer_list_iterate (list);
4307 if (gst_buffer_list_iterator_next_group (it)) {
4309 group = gst_buffer_list_iterator_merge_group (it);
4310 if (group == NULL) {
4311 group = gst_buffer_new ();
4312 GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "pushing empty group");
4314 GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "pushing group");
4316 ret = gst_pad_push_data (pad, TRUE, group);
4317 } while (ret == GST_FLOW_OK && gst_buffer_list_iterator_next_group (it));
4319 GST_CAT_INFO_OBJECT (GST_CAT_SCHEDULING, pad, "pushing empty group");
4320 ret = gst_pad_push_data (pad, TRUE, gst_buffer_new ());
4323 gst_buffer_list_iterator_free (it);
4324 gst_buffer_list_unref (list);
4329 /* ERROR recovery here */
4332 gst_pad_data_unref (is_buffer, data);
4333 GST_DEBUG_OBJECT (pad, "pad block stopped by flush");
4334 GST_OBJECT_UNLOCK (pad);
4339 gst_pad_data_unref (is_buffer, data);
4340 GST_DEBUG_OBJECT (pad, "Dropping buffer due to FALSE probe return");
4345 gst_pad_data_unref (is_buffer, data);
4346 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4347 "pushing, but it was not linked");
4348 GST_OBJECT_UNLOCK (pad);
4349 return GST_FLOW_NOT_LINKED;
4353 gst_pad_data_unref (is_buffer, data);
4354 gst_object_unref (peer);
4355 GST_CAT_DEBUG_OBJECT (GST_CAT_SCHEDULING, pad,
4356 "element pushed data then refused to accept the caps");
4357 return GST_FLOW_NOT_NEGOTIATED;
4363 * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not.
4364 * @buffer: the #GstBuffer to push returns GST_FLOW_ERROR if not.
4366 * Pushes a buffer to the peer of @pad.
4368 * This function will call an installed pad block before triggering any
4369 * installed pad probes.
4371 * If the caps on @buffer are different from the currently configured caps on
4372 * @pad, this function will call any installed setcaps function on @pad (see
4373 * gst_pad_set_setcaps_function()). In case of failure to renegotiate the new
4374 * format, this function returns #GST_FLOW_NOT_NEGOTIATED.
4376 * The function proceeds calling gst_pad_chain() on the peer pad and returns
4377 * the value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will
4380 * In all cases, success or failure, the caller loses its reference to @buffer
4381 * after calling this function.
4383 * Returns: a #GstFlowReturn from the peer pad.
4388 gst_pad_push (GstPad * pad, GstBuffer * buffer)
4390 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4391 g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
4392 g_return_val_if_fail (GST_IS_BUFFER (buffer), GST_FLOW_ERROR);
4394 return gst_pad_push_data (pad, TRUE, buffer);
4398 * gst_pad_push_list:
4399 * @pad: a source #GstPad, returns #GST_FLOW_ERROR if not.
4400 * @list: the #GstBufferList to push returns GST_FLOW_ERROR if not.
4402 * Pushes a buffer list to the peer of @pad.
4404 * This function will call an installed pad block before triggering any
4405 * installed pad probes.
4407 * If the caps on the first buffer in the first group of @list are different
4408 * from the currently configured caps on @pad, this function will call any
4409 * installed setcaps function on @pad (see gst_pad_set_setcaps_function()). In
4410 * case of failure to renegotiate the new format, this function returns
4411 * #GST_FLOW_NOT_NEGOTIATED.
4413 * If there are any probes installed on @pad every group of the buffer list
4414 * will be merged into a normal #GstBuffer and pushed via gst_pad_push and the
4415 * buffer list will be unreffed.
4417 * The function proceeds calling the chain function on the peer pad and returns
4418 * the value from that function. If @pad has no peer, #GST_FLOW_NOT_LINKED will
4419 * be returned. If the peer pad does not have any installed chainlist function
4420 * every group buffer of the list will be merged into a normal #GstBuffer and
4421 * chained via gst_pad_chain().
4423 * In all cases, success or failure, the caller loses its reference to @list
4424 * after calling this function.
4426 * Returns: a #GstFlowReturn from the peer pad.
4433 gst_pad_push_list (GstPad * pad, GstBufferList * list)
4435 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4436 g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
4437 g_return_val_if_fail (GST_IS_BUFFER_LIST (list), GST_FLOW_ERROR);
4439 return gst_pad_push_data (pad, FALSE, list);
4443 * gst_pad_check_pull_range:
4444 * @pad: a sink #GstPad.
4446 * Checks if a gst_pad_pull_range() can be performed on the peer
4447 * source pad. This function is used by plugins that want to check
4448 * if they can use random access on the peer source pad.
4450 * The peer sourcepad can implement a custom #GstPadCheckGetRangeFunction
4451 * if it needs to perform some logic to determine if pull_range is
4454 * Returns: a gboolean with the result.
4459 gst_pad_check_pull_range (GstPad * pad)
4463 GstPadCheckGetRangeFunction checkgetrangefunc;
4465 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4467 GST_OBJECT_LOCK (pad);
4468 if (!GST_PAD_IS_SINK (pad))
4469 goto wrong_direction;
4471 if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
4474 gst_object_ref (peer);
4475 GST_OBJECT_UNLOCK (pad);
4477 /* see note in above function */
4478 if (G_LIKELY ((checkgetrangefunc = peer->checkgetrangefunc) == NULL)) {
4479 /* FIXME, kindoff ghetto */
4480 ret = GST_PAD_GETRANGEFUNC (peer) != NULL;
4481 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4482 "no checkgetrangefunc, assuming %d", ret);
4484 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4485 "calling checkgetrangefunc %s of peer pad %s:%s",
4486 GST_DEBUG_FUNCPTR_NAME (checkgetrangefunc), GST_DEBUG_PAD_NAME (peer));
4488 ret = checkgetrangefunc (peer);
4491 gst_object_unref (peer);
4495 /* ERROR recovery here */
4498 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4499 "checking pull range, but pad must be a sinkpad");
4500 GST_OBJECT_UNLOCK (pad);
4505 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4506 "checking pull range, but it was not linked");
4507 GST_OBJECT_UNLOCK (pad);
4513 * gst_pad_get_range:
4514 * @pad: a src #GstPad, returns #GST_FLOW_ERROR if not.
4515 * @offset: The start offset of the buffer
4516 * @size: The length of the buffer
4517 * @buffer: a pointer to hold the #GstBuffer, returns #GST_FLOW_ERROR if %NULL.
4519 * When @pad is flushing this function returns #GST_FLOW_WRONG_STATE
4522 * Calls the getrange function of @pad, see #GstPadGetRangeFunction for a
4523 * description of a getrange function. If @pad has no getrange function
4524 * installed (see gst_pad_set_getrange_function()) this function returns
4525 * #GST_FLOW_NOT_SUPPORTED.
4527 * This is a lowlevel function. Usualy gst_pad_pull_range() is used.
4529 * Returns: a #GstFlowReturn from the pad.
4534 gst_pad_get_range (GstPad * pad, guint64 offset, guint size,
4535 GstBuffer ** buffer)
4538 GstPadGetRangeFunction getrangefunc;
4539 gboolean emit_signal;
4541 gboolean caps_changed;
4543 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4544 g_return_val_if_fail (GST_PAD_IS_SRC (pad), GST_FLOW_ERROR);
4545 g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
4547 GST_PAD_STREAM_LOCK (pad);
4549 GST_OBJECT_LOCK (pad);
4550 if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4553 emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
4554 GST_OBJECT_UNLOCK (pad);
4556 if (G_UNLIKELY ((getrangefunc = GST_PAD_GETRANGEFUNC (pad)) == NULL))
4559 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4560 "calling getrangefunc %s, offset %"
4561 G_GUINT64_FORMAT ", size %u",
4562 GST_DEBUG_FUNCPTR_NAME (getrangefunc), offset, size);
4564 ret = getrangefunc (pad, offset, size, buffer);
4566 /* can only fire the signal if we have a valid buffer */
4567 if (G_UNLIKELY (emit_signal) && (ret == GST_FLOW_OK)) {
4568 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (*buffer)))
4572 GST_PAD_STREAM_UNLOCK (pad);
4574 if (G_UNLIKELY (ret != GST_FLOW_OK))
4575 goto get_range_failed;
4577 GST_OBJECT_LOCK (pad);
4578 /* Before pushing the buffer to the peer pad, ensure that caps
4579 * are set on this pad */
4580 caps = GST_BUFFER_CAPS (*buffer);
4581 caps_changed = caps && caps != GST_PAD_CAPS (pad);
4582 GST_OBJECT_UNLOCK (pad);
4584 if (G_UNLIKELY (caps_changed)) {
4585 GST_DEBUG_OBJECT (pad, "caps changed to %p %" GST_PTR_FORMAT, caps, caps);
4586 /* this should usually work because the element produced the buffer */
4587 if (G_UNLIKELY (!gst_pad_configure_src (pad, caps, TRUE)))
4588 goto not_negotiated;
4595 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4596 "pulling range, but pad was flushing");
4597 GST_OBJECT_UNLOCK (pad);
4598 GST_PAD_STREAM_UNLOCK (pad);
4599 return GST_FLOW_WRONG_STATE;
4603 GST_ELEMENT_ERROR (GST_PAD_PARENT (pad), CORE, PAD, (NULL),
4604 ("pullrange on pad %s:%s but it has no getrangefunction",
4605 GST_DEBUG_PAD_NAME (pad)));
4606 GST_PAD_STREAM_UNLOCK (pad);
4607 return GST_FLOW_NOT_SUPPORTED;
4611 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4612 "Dropping data after FALSE probe return");
4613 GST_PAD_STREAM_UNLOCK (pad);
4614 gst_buffer_unref (*buffer);
4616 return GST_FLOW_UNEXPECTED;
4621 GST_CAT_WARNING_OBJECT (GST_CAT_SCHEDULING, pad,
4622 "getrange failed %s", gst_flow_get_name (ret));
4627 gst_buffer_unref (*buffer);
4629 GST_CAT_WARNING_OBJECT (GST_CAT_SCHEDULING, pad,
4630 "getrange returned buffer of unaccaptable caps");
4631 return GST_FLOW_NOT_NEGOTIATED;
4637 * gst_pad_pull_range:
4638 * @pad: a sink #GstPad, returns GST_FLOW_ERROR if not.
4639 * @offset: The start offset of the buffer
4640 * @size: The length of the buffer
4641 * @buffer: a pointer to hold the #GstBuffer, returns GST_FLOW_ERROR if %NULL.
4643 * Pulls a @buffer from the peer pad.
4645 * This function will first trigger the pad block signal if it was
4648 * When @pad is not linked #GST_FLOW_NOT_LINKED is returned else this
4649 * function returns the result of gst_pad_get_range() on the peer pad.
4650 * See gst_pad_get_range() for a list of return values and for the
4651 * semantics of the arguments of this function.
4653 * @buffer's caps must either be unset or the same as what is already
4654 * configured on @pad. Renegotiation within a running pull-mode pipeline is not
4657 * Returns: a #GstFlowReturn from the peer pad.
4658 * When this function returns #GST_FLOW_OK, @buffer will contain a valid
4659 * #GstBuffer that should be freed with gst_buffer_unref() after usage.
4660 * @buffer may not be used or freed when any other return value than
4661 * #GST_FLOW_OK is returned.
4666 gst_pad_pull_range (GstPad * pad, guint64 offset, guint size,
4667 GstBuffer ** buffer)
4671 gboolean emit_signal;
4673 gboolean caps_changed;
4675 g_return_val_if_fail (GST_IS_PAD (pad), GST_FLOW_ERROR);
4676 g_return_val_if_fail (GST_PAD_IS_SINK (pad), GST_FLOW_ERROR);
4677 g_return_val_if_fail (buffer != NULL, GST_FLOW_ERROR);
4679 GST_OBJECT_LOCK (pad);
4681 while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad)))
4682 handle_pad_block (pad);
4684 if (G_UNLIKELY ((peer = GST_PAD_PEER (pad)) == NULL))
4687 /* signal emision for the pad, peer has chance to emit when
4688 * we call _get_range() */
4689 emit_signal = GST_PAD_DO_BUFFER_SIGNALS (pad) > 0;
4691 gst_object_ref (peer);
4692 GST_OBJECT_UNLOCK (pad);
4694 ret = gst_pad_get_range (peer, offset, size, buffer);
4696 gst_object_unref (peer);
4698 if (G_UNLIKELY (ret != GST_FLOW_OK))
4699 goto pull_range_failed;
4701 /* can only fire the signal if we have a valid buffer */
4702 if (G_UNLIKELY (emit_signal)) {
4703 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (*buffer)))
4707 GST_OBJECT_LOCK (pad);
4708 /* Before pushing the buffer to the peer pad, ensure that caps
4709 * are set on this pad */
4710 caps = GST_BUFFER_CAPS (*buffer);
4711 caps_changed = caps && caps != GST_PAD_CAPS (pad);
4712 GST_OBJECT_UNLOCK (pad);
4714 /* we got a new datatype on the pad, see if it can handle it */
4715 if (G_UNLIKELY (caps_changed)) {
4716 GST_DEBUG_OBJECT (pad, "caps changed to %p %" GST_PTR_FORMAT, caps, caps);
4717 if (G_UNLIKELY (!gst_pad_configure_sink (pad, caps)))
4718 goto not_negotiated;
4722 /* ERROR recovery here */
4725 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4726 "pulling range, but it was not linked");
4727 GST_OBJECT_UNLOCK (pad);
4728 return GST_FLOW_NOT_LINKED;
4733 GST_CAT_WARNING_OBJECT (GST_CAT_SCHEDULING, pad,
4734 "pullrange failed %s", gst_flow_get_name (ret));
4739 GST_CAT_LOG_OBJECT (GST_CAT_SCHEDULING, pad,
4740 "Dropping data after FALSE probe return");
4741 gst_buffer_unref (*buffer);
4743 return GST_FLOW_UNEXPECTED;
4747 gst_buffer_unref (*buffer);
4749 GST_CAT_WARNING_OBJECT (GST_CAT_SCHEDULING, pad,
4750 "pullrange returned buffer of different caps");
4751 return GST_FLOW_NOT_NEGOTIATED;
4756 * gst_pad_push_event:
4757 * @pad: a #GstPad to push the event to.
4758 * @event: the #GstEvent to send to the pad.
4760 * Sends the event to the peer of the given pad. This function is
4761 * mainly used by elements to send events to their peer
4764 * This function takes owership of the provided event so you should
4765 * gst_event_ref() it if you want to reuse the event after this call.
4767 * Returns: TRUE if the event was handled.
4772 gst_pad_push_event (GstPad * pad, GstEvent * event)
4777 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4778 g_return_val_if_fail (event != NULL, FALSE);
4779 g_return_val_if_fail (GST_IS_EVENT (event), FALSE);
4781 GST_LOG_OBJECT (pad, "event: %s", GST_EVENT_TYPE_NAME (event));
4783 GST_OBJECT_LOCK (pad);
4785 /* Two checks to be made:
4786 * . (un)set the FLUSHING flag for flushing events,
4787 * . handle pad blocking */
4788 switch (GST_EVENT_TYPE (event)) {
4789 case GST_EVENT_FLUSH_START:
4790 GST_PAD_SET_FLUSHING (pad);
4792 if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
4793 /* flush start will have set the FLUSHING flag and will then
4794 * unlock all threads doing a GCond wait on the blocking pad. This
4795 * will typically unblock the STREAMING thread blocked on a pad. */
4796 GST_LOG_OBJECT (pad, "Pad is blocked, not forwarding flush-start, "
4797 "doing block signal.");
4798 GST_PAD_BLOCK_BROADCAST (pad);
4802 case GST_EVENT_FLUSH_STOP:
4803 GST_PAD_UNSET_FLUSHING (pad);
4805 /* if we are blocked, flush away the FLUSH_STOP event */
4806 if (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
4807 GST_LOG_OBJECT (pad, "Pad is blocked, not forwarding flush-stop");
4812 while (G_UNLIKELY (GST_PAD_IS_BLOCKED (pad))) {
4813 /* block the event as long as the pad is blocked */
4814 if (handle_pad_block (pad) != GST_FLOW_OK)
4820 if (G_UNLIKELY (GST_PAD_DO_EVENT_SIGNALS (pad) > 0)) {
4821 GST_OBJECT_UNLOCK (pad);
4823 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT (event)))
4826 GST_OBJECT_LOCK (pad);
4828 peerpad = GST_PAD_PEER (pad);
4829 if (peerpad == NULL)
4832 GST_LOG_OBJECT (pad, "sending event %s to peerpad %" GST_PTR_FORMAT,
4833 GST_EVENT_TYPE_NAME (event), peerpad);
4834 gst_object_ref (peerpad);
4835 GST_OBJECT_UNLOCK (pad);
4837 result = gst_pad_send_event (peerpad, event);
4839 /* Note: we gave away ownership of the event at this point */
4840 GST_LOG_OBJECT (pad, "sent event to peerpad %" GST_PTR_FORMAT ", result %d",
4842 gst_object_unref (peerpad);
4846 /* ERROR handling */
4849 GST_DEBUG_OBJECT (pad, "Dropping event after FALSE probe return");
4850 gst_event_unref (event);
4855 GST_DEBUG_OBJECT (pad, "Dropping event because pad is not linked");
4856 gst_event_unref (event);
4857 GST_OBJECT_UNLOCK (pad);
4862 GST_DEBUG_OBJECT (pad,
4863 "Not forwarding event since we're flushing and blocking");
4864 gst_event_unref (event);
4865 GST_OBJECT_UNLOCK (pad);
4871 * gst_pad_send_event:
4872 * @pad: a #GstPad to send the event to.
4873 * @event: the #GstEvent to send to the pad.
4875 * Sends the event to the pad. This function can be used
4876 * by applications to send events in the pipeline.
4878 * If @pad is a source pad, @event should be an upstream event. If @pad is a
4879 * sink pad, @event should be a downstream event. For example, you would not
4880 * send a #GST_EVENT_EOS on a src pad; EOS events only propagate downstream.
4881 * Furthermore, some downstream events have to be serialized with data flow,
4882 * like EOS, while some can travel out-of-band, like #GST_EVENT_FLUSH_START. If
4883 * the event needs to be serialized with data flow, this function will take the
4884 * pad's stream lock while calling its event function.
4886 * To find out whether an event type is upstream, downstream, or downstream and
4887 * serialized, see #GstEventTypeFlags, gst_event_type_get_flags(),
4888 * #GST_EVENT_IS_UPSTREAM, #GST_EVENT_IS_DOWNSTREAM, and
4889 * #GST_EVENT_IS_SERIALIZED. Note that in practice that an application or
4890 * plugin doesn't need to bother itself with this information; the core handles
4891 * all necessary locks and checks.
4893 * This function takes owership of the provided event so you should
4894 * gst_event_ref() it if you want to reuse the event after this call.
4896 * Returns: TRUE if the event was handled.
4899 gst_pad_send_event (GstPad * pad, GstEvent * event)
4901 gboolean result = FALSE;
4902 GstPadEventFunction eventfunc;
4903 gboolean serialized, need_unlock = FALSE;
4905 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
4906 g_return_val_if_fail (event != NULL, FALSE);
4908 GST_OBJECT_LOCK (pad);
4909 if (GST_PAD_IS_SINK (pad)) {
4910 if (G_UNLIKELY (!GST_EVENT_IS_DOWNSTREAM (event)))
4911 goto wrong_direction;
4912 serialized = GST_EVENT_IS_SERIALIZED (event);
4913 } else if (GST_PAD_IS_SRC (pad)) {
4914 if (G_UNLIKELY (!GST_EVENT_IS_UPSTREAM (event)))
4915 goto wrong_direction;
4916 /* events on srcpad never are serialized */
4919 goto unknown_direction;
4921 if (G_UNLIKELY (GST_EVENT_SRC (event) == NULL)) {
4922 GST_LOG_OBJECT (pad, "event had no source, setting pad as event source");
4923 GST_EVENT_SRC (event) = gst_object_ref (pad);
4927 if (G_UNLIKELY (GST_PAD_DO_EVENT_SIGNALS (pad) > 0)) {
4928 GST_OBJECT_UNLOCK (pad);
4930 if (!gst_pad_emit_have_data_signal (pad, GST_MINI_OBJECT_CAST (event)))
4933 GST_OBJECT_LOCK (pad);
4936 switch (GST_EVENT_TYPE (event)) {
4937 case GST_EVENT_FLUSH_START:
4938 GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad,
4939 "have event type %d (FLUSH_START)", GST_EVENT_TYPE (event));
4941 /* can't even accept a flush begin event when flushing */
4942 if (GST_PAD_IS_FLUSHING (pad))
4944 GST_PAD_SET_FLUSHING (pad);
4945 GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "set flush flag");
4947 case GST_EVENT_FLUSH_STOP:
4948 GST_PAD_UNSET_FLUSHING (pad);
4949 GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "cleared flush flag");
4950 GST_OBJECT_UNLOCK (pad);
4951 /* grab stream lock */
4952 GST_PAD_STREAM_LOCK (pad);
4954 GST_OBJECT_LOCK (pad);
4957 GST_CAT_DEBUG_OBJECT (GST_CAT_EVENT, pad, "have event type %s",
4958 GST_EVENT_TYPE_NAME (event));
4960 /* make this a little faster, no point in grabbing the lock
4961 * if the pad is allready flushing. */
4962 if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4966 /* lock order: STREAM_LOCK, LOCK, recheck flushing. */
4967 GST_OBJECT_UNLOCK (pad);
4968 GST_PAD_STREAM_LOCK (pad);
4970 GST_OBJECT_LOCK (pad);
4971 if (G_UNLIKELY (GST_PAD_IS_FLUSHING (pad)))
4976 if (G_UNLIKELY ((eventfunc = GST_PAD_EVENTFUNC (pad)) == NULL))
4979 GST_OBJECT_UNLOCK (pad);
4981 result = eventfunc (pad, event);
4984 GST_PAD_STREAM_UNLOCK (pad);
4986 GST_DEBUG_OBJECT (pad, "sent event, result %d", result);
4990 /* ERROR handling */
4993 g_warning ("pad %s:%s sending %s event in wrong direction",
4994 GST_DEBUG_PAD_NAME (pad), GST_EVENT_TYPE_NAME (event));
4995 GST_OBJECT_UNLOCK (pad);
4996 gst_event_unref (event);
5001 g_warning ("pad %s:%s has invalid direction", GST_DEBUG_PAD_NAME (pad));
5002 GST_OBJECT_UNLOCK (pad);
5003 gst_event_unref (event);
5008 g_warning ("pad %s:%s has no event handler, file a bug.",
5009 GST_DEBUG_PAD_NAME (pad));
5010 GST_OBJECT_UNLOCK (pad);
5012 GST_PAD_STREAM_UNLOCK (pad);
5013 gst_event_unref (event);
5018 GST_OBJECT_UNLOCK (pad);
5020 GST_PAD_STREAM_UNLOCK (pad);
5021 GST_CAT_INFO_OBJECT (GST_CAT_EVENT, pad,
5022 "Received event on flushing pad. Discarding");
5023 gst_event_unref (event);
5028 GST_DEBUG_OBJECT (pad, "Dropping event after FALSE probe return");
5029 gst_event_unref (event);
5035 * gst_pad_set_element_private:
5036 * @pad: the #GstPad to set the private data of.
5037 * @priv: The private data to attach to the pad.
5039 * Set the given private data gpointer on the pad.
5040 * This function can only be used by the element that owns the pad.
5041 * No locking is performed in this function.
5044 gst_pad_set_element_private (GstPad * pad, gpointer priv)
5046 pad->element_private = priv;
5050 * gst_pad_get_element_private:
5051 * @pad: the #GstPad to get the private data of.
5053 * Gets the private data of a pad.
5054 * No locking is performed in this function.
5056 * Returns: a #gpointer to the private data.
5059 gst_pad_get_element_private (GstPad * pad)
5061 return pad->element_private;
5065 do_stream_status (GstPad * pad, GstStreamStatusType type,
5066 GThread * thread, GstTask * task)
5070 GST_DEBUG_OBJECT (pad, "doing stream-status %d", type);
5072 if ((parent = GST_ELEMENT_CAST (gst_pad_get_parent (pad)))) {
5073 if (GST_IS_ELEMENT (parent)) {
5074 GstMessage *message;
5075 GValue value = { 0 };
5077 message = gst_message_new_stream_status (GST_OBJECT_CAST (pad),
5080 g_value_init (&value, GST_TYPE_TASK);
5081 g_value_set_object (&value, task);
5082 gst_message_set_stream_status_object (message, &value);
5083 g_value_unset (&value);
5085 GST_DEBUG_OBJECT (pad, "posting stream-status %d", type);
5086 gst_element_post_message (parent, message);
5088 gst_object_unref (parent);
5093 pad_enter_thread (GstTask * task, GThread * thread, gpointer user_data)
5095 do_stream_status (GST_PAD_CAST (user_data), GST_STREAM_STATUS_TYPE_ENTER,
5100 pad_leave_thread (GstTask * task, GThread * thread, gpointer user_data)
5102 do_stream_status (GST_PAD_CAST (user_data), GST_STREAM_STATUS_TYPE_LEAVE,
5106 static GstTaskThreadCallbacks thr_callbacks = {
5112 * gst_pad_start_task:
5113 * @pad: the #GstPad to start the task of
5114 * @func: the task function to call
5115 * @data: data passed to the task function
5117 * Starts a task that repeatedly calls @func with @data. This function
5118 * is mostly used in pad activation functions to start the dataflow.
5119 * The #GST_PAD_STREAM_LOCK of @pad will automatically be acquired
5120 * before @func is called.
5122 * Returns: a %TRUE if the task could be started.
5125 gst_pad_start_task (GstPad * pad, GstTaskFunction func, gpointer data)
5130 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
5131 g_return_val_if_fail (func != NULL, FALSE);
5133 GST_DEBUG_OBJECT (pad, "start task");
5135 GST_OBJECT_LOCK (pad);
5136 task = GST_PAD_TASK (pad);
5138 task = gst_task_create (func, data);
5139 gst_task_set_lock (task, GST_PAD_GET_STREAM_LOCK (pad));
5140 gst_task_set_thread_callbacks (task, &thr_callbacks, pad, NULL);
5141 GST_DEBUG_OBJECT (pad, "created task");
5142 GST_PAD_TASK (pad) = task;
5143 gst_object_ref (task);
5144 /* release lock to post the message */
5145 GST_OBJECT_UNLOCK (pad);
5147 do_stream_status (pad, GST_STREAM_STATUS_TYPE_CREATE, NULL, task);
5149 gst_object_unref (task);
5151 GST_OBJECT_LOCK (pad);
5152 /* nobody else is supposed to have changed the pad now */
5153 if (GST_PAD_TASK (pad) != task)
5154 goto concurrent_stop;
5156 res = gst_task_set_state (task, GST_TASK_STARTED);
5157 GST_OBJECT_UNLOCK (pad);
5164 GST_OBJECT_UNLOCK (pad);
5170 * gst_pad_pause_task:
5171 * @pad: the #GstPad to pause the task of
5173 * Pause the task of @pad. This function will also wait until the
5174 * function executed by the task is finished if this function is not
5175 * called from the task function.
5177 * Returns: a TRUE if the task could be paused or FALSE when the pad
5181 gst_pad_pause_task (GstPad * pad)
5186 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
5188 GST_DEBUG_OBJECT (pad, "pause task");
5190 GST_OBJECT_LOCK (pad);
5191 task = GST_PAD_TASK (pad);
5194 res = gst_task_set_state (task, GST_TASK_PAUSED);
5195 GST_OBJECT_UNLOCK (pad);
5197 /* wait for task function to finish, this lock is recursive so it does nothing
5198 * when the pause is called from the task itself */
5199 GST_PAD_STREAM_LOCK (pad);
5200 GST_PAD_STREAM_UNLOCK (pad);
5206 GST_DEBUG_OBJECT (pad, "pad has no task");
5207 GST_OBJECT_UNLOCK (pad);
5213 * gst_pad_stop_task:
5214 * @pad: the #GstPad to stop the task of
5216 * Stop the task of @pad. This function will also make sure that the
5217 * function executed by the task will effectively stop if not called
5218 * from the GstTaskFunction.
5220 * This function will deadlock if called from the GstTaskFunction of
5221 * the task. Use gst_task_pause() instead.
5223 * Regardless of whether the pad has a task, the stream lock is acquired and
5224 * released so as to ensure that streaming through this pad has finished.
5226 * Returns: a TRUE if the task could be stopped or FALSE on error.
5229 gst_pad_stop_task (GstPad * pad)
5234 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
5236 GST_DEBUG_OBJECT (pad, "stop task");
5238 GST_OBJECT_LOCK (pad);
5239 task = GST_PAD_TASK (pad);
5242 GST_PAD_TASK (pad) = NULL;
5243 res = gst_task_set_state (task, GST_TASK_STOPPED);
5244 GST_OBJECT_UNLOCK (pad);
5246 GST_PAD_STREAM_LOCK (pad);
5247 GST_PAD_STREAM_UNLOCK (pad);
5249 if (!gst_task_join (task))
5252 gst_object_unref (task);
5258 GST_DEBUG_OBJECT (pad, "no task");
5259 GST_OBJECT_UNLOCK (pad);
5261 GST_PAD_STREAM_LOCK (pad);
5262 GST_PAD_STREAM_UNLOCK (pad);
5264 /* this is not an error */
5269 /* this is bad, possibly the application tried to join the task from
5270 * the task's thread. We install the task again so that it will be stopped
5271 * again from the right thread next time hopefully. */
5272 GST_OBJECT_LOCK (pad);
5273 GST_DEBUG_OBJECT (pad, "join failed");
5274 /* we can only install this task if there was no other task */
5275 if (GST_PAD_TASK (pad) == NULL)
5276 GST_PAD_TASK (pad) = task;
5277 GST_OBJECT_UNLOCK (pad);