gst/gstpad.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *
   5  * gstpad.c: Pads for linking elements together
   6  *
   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.
  11  *
  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.
  16  *
  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.
  21  */
  22
  23 /* #define GST_DEBUG_ENABLED */
  24 #include "gst_private.h"
  25
  26 #include "gstpad.h"
  27 #include "gstutils.h"
  28 #include "gstelement.h"
  29 #include "gsttype.h"
  30 #include "gstbin.h"
  31 #include "gstscheduler.h"
  32 #include "gstevent.h"
  33 #include "gstlog.h"
  34
  35 enum {
  36   TEMPL_PAD_CREATED,
  37   /* FILL ME */
  38   TEMPL_LAST_SIGNAL
  39 };
  40
  41 static GstObject *padtemplate_parent_class = NULL;
  42 static guint gst_pad_template_signals[TEMPL_LAST_SIGNAL] = { 0 };
  43
  44 GType _gst_pad_type = 0;
  45
  46 /***** Start with the base GstPad class *****/
  47 static void             gst_pad_class_init              (GstPadClass *klass);
  48 static void             gst_pad_init                    (GstPad *pad);
  49
  50 static gboolean         gst_pad_try_relink_filtered_func (GstRealPad *srcpad, GstRealPad *sinkpad,
  51                                                          GstCaps *caps, gboolean clear);
  52
  53 #ifndef GST_DISABLE_LOADSAVE
  54 static xmlNodePtr       gst_pad_save_thyself            (GstObject *object, xmlNodePtr parent);
  55 #endif
  56
  57 static GstObject *pad_parent_class = NULL;
  58
  59 GType
  60 gst_pad_get_type (void)
  61 {
  62   if (!_gst_pad_type) {
  63     static const GTypeInfo pad_info = {
  64       sizeof (GstPadClass), NULL, NULL,
  65       (GClassInitFunc) gst_pad_class_init, NULL, NULL,
  66       sizeof (GstPad),
  67       32,
  68       (GInstanceInitFunc) gst_pad_init, NULL
  69     };
  70     _gst_pad_type = g_type_register_static (GST_TYPE_OBJECT, "GstPad",
  71                                             &pad_info, 0);
  72   }
  73   return _gst_pad_type;
  74 }
  75
  76 static void
  77 gst_pad_class_init (GstPadClass *klass)
  78 {
  79   pad_parent_class = g_type_class_ref (GST_TYPE_OBJECT);
  80 }
  81
  82 static void
  83 gst_pad_init (GstPad *pad)
  84 {
  85   pad->element_private = NULL;
  86
  87   pad->padtemplate = NULL;
  88 }
  89
  90
  91
  92 /***** Then do the Real Pad *****/
  93 /* Pad signals and args */
  94 enum {
  95   REAL_CAPS_NEGO_FAILED,
  96   REAL_LINKED,
  97   REAL_UNLINKED,
  98   /* FILL ME */
  99   REAL_LAST_SIGNAL
 100 };
 101
 102 enum {
 103   REAL_ARG_0,
 104   REAL_ARG_CAPS,
 105   REAL_ARG_ACTIVE,
 106   /* FILL ME */
 107 };
 108
 109 static void     gst_real_pad_class_init         (GstRealPadClass *klass);
 110 static void     gst_real_pad_init               (GstRealPad *pad);
 111
 112 static void     gst_real_pad_set_property       (GObject *object, guint prop_id,
 113                                                  const GValue *value,
 114                                                  GParamSpec *pspec);
 115 static void     gst_real_pad_get_property       (GObject *object, guint prop_id,
 116                                                  GValue *value,
 117                                                  GParamSpec *pspec);
 118
 119 static void     gst_real_pad_dispose            (GObject *object);
 120
 121 GType _gst_real_pad_type = 0;
 122
 123 static GstPad *real_pad_parent_class = NULL;
 124 static guint gst_real_pad_signals[REAL_LAST_SIGNAL] = { 0 };
 125
 126 GType
 127 gst_real_pad_get_type (void) {
 128   if (!_gst_real_pad_type) {
 129     static const GTypeInfo pad_info = {
 130       sizeof (GstRealPadClass), NULL, NULL,
 131       (GClassInitFunc) gst_real_pad_class_init, NULL, NULL,
 132       sizeof (GstRealPad),
 133       32,
 134       (GInstanceInitFunc) gst_real_pad_init, NULL
 135     };
 136     _gst_real_pad_type = g_type_register_static (GST_TYPE_PAD, "GstRealPad",
 137                                                  &pad_info, 0);
 138   }
 139   return _gst_real_pad_type;
 140 }
 141
 142 static void
 143 gst_real_pad_class_init (GstRealPadClass *klass)
 144 {
 145   GObjectClass *gobject_class;
 146   GstObjectClass *gstobject_class;
 147
 148   gobject_class = (GObjectClass*) klass;
 149   gstobject_class = (GstObjectClass*) klass;
 150
 151   real_pad_parent_class = g_type_class_ref (GST_TYPE_PAD);
 152
 153   gobject_class->dispose  = GST_DEBUG_FUNCPTR (gst_real_pad_dispose);
 154   gobject_class->set_property  = GST_DEBUG_FUNCPTR (gst_real_pad_set_property);
 155   gobject_class->get_property  = GST_DEBUG_FUNCPTR (gst_real_pad_get_property);
 156
 157   gst_real_pad_signals[REAL_CAPS_NEGO_FAILED] =
 158     g_signal_new ("caps_nego_failed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 159                   G_STRUCT_OFFSET (GstRealPadClass, caps_nego_failed), NULL, NULL,
 160                   gst_marshal_VOID__POINTER, G_TYPE_NONE, 1,
 161                   G_TYPE_POINTER);
 162   gst_real_pad_signals[REAL_LINKED] =
 163     g_signal_new ("linked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 164                   G_STRUCT_OFFSET (GstRealPadClass, linked), NULL, NULL,
 165                   gst_marshal_VOID__POINTER, G_TYPE_NONE, 1,
 166                   G_TYPE_POINTER);
 167   gst_real_pad_signals[REAL_UNLINKED] =
 168     g_signal_new ("unlinked", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 169                   G_STRUCT_OFFSET (GstRealPadClass, unlinked), NULL, NULL,
 170                   gst_marshal_VOID__POINTER, G_TYPE_NONE, 1,
 171                   G_TYPE_POINTER);
 172
 173 /*  gtk_object_add_arg_type ("GstRealPad::active", G_TYPE_BOOLEAN, */
 174 /*                           GTK_ARG_READWRITE, REAL_ARG_ACTIVE); */
 175   g_object_class_install_property (G_OBJECT_CLASS (klass), REAL_ARG_ACTIVE,
 176     g_param_spec_boolean ("active", "Active", "Whether the pad is active.",
 177                           TRUE, G_PARAM_READWRITE));
 178   g_object_class_install_property (G_OBJECT_CLASS (klass), REAL_ARG_CAPS,
 179     g_param_spec_boxed ("caps", "Caps", "The capabilities of the pad",
 180                         GST_TYPE_CAPS, G_PARAM_READABLE));
 181
 182 #ifndef GST_DISABLE_LOADSAVE
 183   gstobject_class->save_thyself = GST_DEBUG_FUNCPTR (gst_pad_save_thyself);
 184 #endif
 185   gstobject_class->path_string_separator = ".";
 186 }
 187
 188 static void
 189 gst_real_pad_init (GstRealPad *pad)
 190 {
 191   pad->direction = GST_PAD_UNKNOWN;
 192   pad->peer = NULL;
 193
 194   pad->chainfunc = NULL;
 195   pad->getfunc = NULL;
 196
 197   pad->chainhandler = NULL;
 198   pad->gethandler = NULL;
 199
 200   pad->bufferpoolfunc = NULL;
 201   pad->ghostpads = NULL;
 202   pad->caps = NULL;
 203
 204   pad->linkfunc = NULL;
 205   pad->getcapsfunc = NULL;
 206
 207   pad->convertfunc      = gst_pad_convert_default;
 208   pad->eventfunc        = gst_pad_event_default;
 209   pad->convertfunc      = gst_pad_convert_default;
 210   pad->queryfunc        = gst_pad_query_default;
 211   pad->intlinkfunc      = gst_pad_get_internal_links_default;
 212
 213   pad->eventmaskfunc    = gst_pad_get_event_masks_default;
 214   pad->formatsfunc      = gst_pad_get_formats_default;
 215   pad->querytypefunc    = gst_pad_get_query_types_default;
 216
 217   GST_FLAG_SET (pad, GST_PAD_DISABLED);
 218   GST_FLAG_UNSET (pad, GST_PAD_NEGOTIATING);
 219
 220   gst_probe_dispatcher_init (&pad->probedisp);
 221 }
 222
 223 static void
 224 gst_real_pad_set_property (GObject *object, guint prop_id,
 225                            const GValue *value, GParamSpec *pspec)
 226 {
 227   g_return_if_fail (GST_IS_PAD (object));
 228
 229   switch (prop_id) {
 230     case REAL_ARG_ACTIVE:
 231       gst_pad_set_active (GST_PAD (object), g_value_get_boolean (value));
 232       break;
 233     default:
 234       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 235       break;
 236   }
 237 }
 238
 239 static void
 240 gst_real_pad_get_property (GObject *object, guint prop_id,
 241                            GValue *value, GParamSpec *pspec)
 242 {
 243   g_return_if_fail (GST_IS_PAD (object));
 244
 245   switch (prop_id) {
 246     case REAL_ARG_ACTIVE:
 247       g_value_set_boolean (value, !GST_FLAG_IS_SET (object, GST_PAD_DISABLED));
 248       break;
 249     case REAL_ARG_CAPS:
 250       g_value_set_boxed (value, GST_PAD_CAPS (GST_REAL_PAD (object)));
 251       break;
 252     default:
 253       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 254       break;
 255   }
 256 }
 257
 258
 259 /**
 260  * gst_pad_custom_new:
 261  * @type: the #Gtype of the pad.
 262  * @name: the name of the new pad.
 263  * @direction: the #GstPadDirection of the pad.
 264  *
 265  * Creates a new pad with the given name and type in the given direction.
 266  * If name is NULL, a guaranteed unique name (across all pads)
 267  * will be assigned.
 268  *
 269  * Returns: a new #GstPad, or NULL in case of an error.
 270  */
 271 GstPad*
 272 gst_pad_custom_new (GType type, const gchar *name,
 273                     GstPadDirection direction)
 274 {
 275   GstRealPad *pad;
 276
 277   g_return_val_if_fail (direction != GST_PAD_UNKNOWN, NULL);
 278
 279   pad = g_object_new (type, NULL);
 280   gst_object_set_name (GST_OBJECT (pad), name);
 281   GST_RPAD_DIRECTION (pad) = direction;
 282
 283   return GST_PAD (pad);
 284 }
 285
 286 /**
 287  * gst_pad_new:
 288  * @name: the name of the new pad.
 289  * @direction: the #GstPadDirection of the pad.
 290  *
 291  * Creates a new real pad with the given name in the given direction.
 292  * If name is NULL, a guaranteed unique name (across all pads)
 293  * will be assigned.
 294  *
 295  * Returns: a new #GstPad, or NULL in case of an error.
 296  */
 297 GstPad*
 298 gst_pad_new (const gchar *name,
 299              GstPadDirection direction)
 300 {
 301   return gst_pad_custom_new (gst_real_pad_get_type (), name, direction);
 302 }
 303
 304 /**
 305  * gst_pad_custom_new_from_template:
 306  * @type: the custom #GType of the pad.
 307  * @templ: the #GstPadTemplate to instantiate from.
 308  * @name: the name of the new pad.
 309  *
 310  * Creates a new custom pad with the given name from the given template.
 311  * If name is NULL, a guaranteed unique name (across all pads)
 312  * will be assigned.
 313  *
 314  * Returns: a new #GstPad, or NULL in case of an error.
 315  */
 316 GstPad*
 317 gst_pad_custom_new_from_template (GType type, GstPadTemplate *templ,
 318                                   const gchar *name)
 319 {
 320   GstPad *pad;
 321
 322   g_return_val_if_fail (templ != NULL, NULL);
 323
 324   pad = gst_pad_new (name, templ->direction);
 325
 326   gst_object_ref (GST_OBJECT (templ));
 327   GST_PAD_PAD_TEMPLATE (pad) = templ;
 328
 329   g_signal_emit (G_OBJECT (templ), gst_pad_template_signals[TEMPL_PAD_CREATED], 0, pad);
 330
 331   return pad;
 332 }
 333
 334 /**
 335  * gst_pad_new_from_template:
 336  * @templ: the pad template to use
 337  * @name: the name of the element
 338  *
 339  * Creates a new real pad with the given name from the given template.
 340  * If name is NULL, a guaranteed unique name (across all pads)
 341  * will be assigned.
 342  *
 343  * Returns: a new #GstPad, or NULL in case of an error.
 344  */
 345 GstPad*
 346 gst_pad_new_from_template (GstPadTemplate *templ, const gchar *name)
 347 {
 348   return gst_pad_custom_new_from_template (gst_real_pad_get_type (),
 349                                            templ, name);
 350 }
 351
 352 /**
 353  * gst_pad_get_direction:
 354  * @pad: a #GstPad to get the direction of.
 355  *
 356  * Gets the direction of the pad.
 357  *
 358  * Returns: the #GstPadDirection of the pad.
 359  */
 360 GstPadDirection
 361 gst_pad_get_direction (GstPad *pad)
 362 {
 363   g_return_val_if_fail (GST_IS_PAD (pad), GST_PAD_UNKNOWN);
 364
 365   return GST_PAD_DIRECTION (pad);
 366 }
 367
 368 /**
 369  * gst_pad_set_active:
 370  * @pad: the #GstPad to activate or deactivate.
 371  * @active: TRUE to activate the pad.
 372  *
 373  * Activates or deactivates the given pad.
 374  */
 375 void
 376 gst_pad_set_active (GstPad *pad, gboolean active)
 377 {
 378   GstRealPad *realpad;
 379   gboolean old;
 380
 381   g_return_if_fail (GST_IS_PAD (pad));
 382
 383   old = GST_PAD_IS_ACTIVE (pad);
 384
 385   if (old == active)
 386     return;
 387
 388   realpad = GST_PAD_REALIZE (pad);
 389
 390   if (active) {
 391     GST_DEBUG (GST_CAT_PADS, "activating pad %s:%s",
 392                GST_DEBUG_PAD_NAME (realpad));
 393     GST_FLAG_UNSET (realpad, GST_PAD_DISABLED);
 394   } else {
 395     GST_DEBUG (GST_CAT_PADS, "de-activating pad %s:%s",
 396                GST_DEBUG_PAD_NAME (realpad));
 397     GST_FLAG_SET (realpad, GST_PAD_DISABLED);
 398   }
 399   if (old != active)
 400     g_object_notify (G_OBJECT (realpad), "active");
 401 }
 402
 403 /**
 404  * gst_pad_is_active:
 405  * @pad: the #GstPad to query
 406  *
 407  * Query if a pad is active
 408  *
 409  * Returns: TRUE if the pad is active.
 410  */
 411 gboolean
 412 gst_pad_is_active (GstPad *pad)
 413 {
 414   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
 415
 416   return !GST_FLAG_IS_SET (pad, GST_PAD_DISABLED);
 417 }
 418
 419 /**
 420  * gst_pad_set_name:
 421  * @pad: a #GstPad to set the name of.
 422  * @name: the name of the pad.
 423  *
 424  * Sets the name of a pad.  If name is NULL, then a guaranteed unique
 425  * name will be assigned.
 426  */
 427 void
 428 gst_pad_set_name (GstPad *pad, const gchar *name)
 429 {
 430   g_return_if_fail (GST_IS_PAD (pad));
 431
 432   gst_object_set_name (GST_OBJECT (pad), name);
 433 }
 434
 435 /**
 436  * gst_pad_get_name:
 437  * @pad: a #GstPad to get the name of.
 438  *
 439  * Gets the name of a pad.
 440  *
 441  * Returns: the name of the pad.  This is not a newly allocated pointer
 442  * so you must not free it.
 443  */
 444 const gchar*
 445 gst_pad_get_name (GstPad *pad)
 446 {
 447   g_return_val_if_fail (pad != NULL, NULL);
 448   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
 449
 450   return GST_OBJECT_NAME (pad);
 451 }
 452
 453 /**
 454  * gst_pad_set_chain_function:
 455  * @pad: a #GstPad to set the chain function for.
 456  * @chain: the #GstPadChainFunction to set.
 457  *
 458  * Sets the given chain function for the pad.
 459  */
 460 void
 461 gst_pad_set_chain_function (GstPad *pad, GstPadChainFunction chain)
 462 {
 463   g_return_if_fail (pad != NULL);
 464   g_return_if_fail (GST_IS_REAL_PAD (pad));
 465
 466   GST_RPAD_CHAINFUNC (pad) = chain;
 467   GST_DEBUG (GST_CAT_PADS, "chainfunc for %s:%s set to %s",
 468              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (chain));
 469 }
 470
 471 /**
 472  * gst_pad_set_get_function:
 473  * @pad: a #GstPad to set the get function for.
 474  * @get: the #GstPadGetFunction to set.
 475  *
 476  * Sets the given get function for the pad.
 477  */
 478 void
 479 gst_pad_set_get_function (GstPad *pad,
 480                           GstPadGetFunction get)
 481 {
 482   g_return_if_fail (pad != NULL);
 483   g_return_if_fail (GST_IS_REAL_PAD (pad));
 484
 485   GST_RPAD_GETFUNC (pad) = get;
 486
 487   GST_DEBUG (GST_CAT_PADS, "getfunc for %s:%s  set to %s",
 488              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (get));
 489 }
 490
 491 /**
 492  * gst_pad_set_event_function:
 493  * @pad: a #GstPad to set the event handler for.
 494  * @event: the #GstPadEventFunction to set.
 495  *
 496  * Sets the given event handler for the pad.
 497  */
 498 void
 499 gst_pad_set_event_function (GstPad *pad,
 500                             GstPadEventFunction event)
 501 {
 502   g_return_if_fail (GST_IS_REAL_PAD (pad));
 503
 504   GST_RPAD_EVENTFUNC (pad) = event;
 505
 506   GST_DEBUG (GST_CAT_PADS, "eventfunc for %s:%s  set to %s",
 507              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (event));
 508 }
 509
 510 /**
 511  * gst_pad_set_event_mask_function:
 512  * @pad: a #GstPad to set the event mask function for.
 513  * @mask_func: the #GstPadEventMaskFunction to set.
 514  *
 515  * Sets the given event mask function for the pad.
 516  */
 517 void
 518 gst_pad_set_event_mask_function (GstPad *pad,
 519                                  GstPadEventMaskFunction mask_func)
 520 {
 521   g_return_if_fail (GST_IS_REAL_PAD (pad));
 522
 523   GST_RPAD_EVENTMASKFUNC (pad) = mask_func;
 524
 525   GST_DEBUG (GST_CAT_PADS, "eventmaskfunc for %s:%s  set to %s",
 526              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (mask_func));
 527 }
 528
 529 /**
 530  * gst_pad_get_event_masks:
 531  * @pad: a #GstPad to get the event mask for.
 532  *
 533  * Gets the array of eventmasks from the given pad.
 534  *
 535  * Returns: an array with eventmasks, the list is ended
 536  * with 0
 537  */
 538 const GstEventMask*
 539 gst_pad_get_event_masks (GstPad *pad)
 540 {
 541   GstRealPad *rpad;
 542
 543   if (pad == NULL)
 544     return FALSE;
 545
 546   rpad = GST_PAD_REALIZE (pad);
 547
 548   g_return_val_if_fail (rpad, FALSE);
 549
 550   if (GST_RPAD_EVENTMASKFUNC (rpad))
 551     return GST_RPAD_EVENTMASKFUNC (rpad) (GST_PAD_CAST (pad));
 552
 553   return NULL;
 554 }
 555
 556 static gboolean
 557 gst_pad_get_event_masks_dispatcher (GstPad *pad, const GstEventMask **data)
 558 {
 559   *data = gst_pad_get_event_masks (pad);
 560
 561   return TRUE;
 562 }
 563
 564 /**
 565  * gst_pad_get_event_masks_default:
 566  * @pad: a #GstPad to get the event mask for.
 567  *
 568  * Invokes the default event masks dispatcher on the pad.
 569  *
 570  * Returns: an array with eventmasks, the list is ended
 571  * with 0
 572  */
 573 const GstEventMask*
 574 gst_pad_get_event_masks_default (GstPad *pad)
 575 {
 576   GstEventMask *result = NULL;
 577
 578   gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
 579                            gst_pad_get_event_masks_dispatcher, &result);
 580
 581   return result;
 582 }
 583
 584 /**
 585  * gst_pad_set_convert_function:
 586  * @pad: a #GstPad to set the convert function for.
 587  * @convert: the #GstPadConvertFunction to set.
 588  *
 589  * Sets the given convert function for the pad.
 590  */
 591 void
 592 gst_pad_set_convert_function (GstPad *pad,
 593                               GstPadConvertFunction convert)
 594 {
 595   g_return_if_fail (pad != NULL);
 596   g_return_if_fail (GST_IS_REAL_PAD (pad));
 597
 598   GST_RPAD_CONVERTFUNC (pad) = convert;
 599
 600   GST_DEBUG (GST_CAT_PADS, "convertfunc for %s:%s  set to %s",
 601              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (convert));
 602 }
 603
 604 /**
 605  * gst_pad_set_query_function:
 606  * @pad: the #GstPad to set the query function for.
 607  * @query: the #GstPadQueryFunction to set.
 608  *
 609  * Set the given query function for the pad.
 610  */
 611 void
 612 gst_pad_set_query_function (GstPad *pad, GstPadQueryFunction query)
 613 {
 614   g_return_if_fail (pad != NULL);
 615   g_return_if_fail (GST_IS_REAL_PAD (pad));
 616
 617   GST_RPAD_QUERYFUNC (pad) = query;
 618
 619   GST_DEBUG (GST_CAT_PADS, "queryfunc for %s:%s  set to %s",
 620              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (query));
 621 }
 622
 623 /**
 624  * gst_pad_set_query_type_function:
 625  * @pad: the #GstPad to set the query type function for.
 626  * @type_func: the #GstPadQueryTypeFunction to set.
 627  *
 628  * Set the given query type function for the pad.
 629  */
 630 void
 631 gst_pad_set_query_type_function (GstPad *pad, GstPadQueryTypeFunction type_func)
 632 {
 633   g_return_if_fail (pad != NULL);
 634   g_return_if_fail (GST_IS_REAL_PAD (pad));
 635
 636   GST_RPAD_QUERYTYPEFUNC (pad) = type_func;
 637
 638   GST_DEBUG (GST_CAT_PADS, "querytypefunc for %s:%s  set to %s",
 639              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (type_func));
 640 }
 641
 642 /**
 643  * gst_pad_get_query_types:
 644  * @pad: the #GstPad to query
 645  *
 646  * Get an array of supported queries that can be performed
 647  * on this pad.
 648  *
 649  * Returns: an array of querytypes anded with 0.
 650  */
 651 const GstQueryType*
 652 gst_pad_get_query_types (GstPad *pad)
 653 {
 654   GstRealPad *rpad;
 655
 656   if (pad == NULL)
 657     return FALSE;
 658
 659   rpad = GST_PAD_REALIZE (pad);
 660
 661   g_return_val_if_fail (rpad, FALSE);
 662
 663   if (GST_RPAD_QUERYTYPEFUNC (rpad))
 664     return GST_RPAD_QUERYTYPEFUNC (rpad) (GST_PAD_CAST (pad));
 665
 666   return NULL;
 667 }
 668
 669 static gboolean
 670 gst_pad_get_query_types_dispatcher (GstPad *pad, const GstQueryType **data)
 671 {
 672   *data = gst_pad_get_query_types (pad);
 673
 674   return TRUE;
 675 }
 676
 677 /**
 678  * gst_pad_get_query_types_default:
 679  * @pad: the #GstPad to query
 680  *
 681  * Invoke the default dispatcher for the query types on
 682  * the pad.
 683  *
 684  * Returns: an array of querytypes anded with 0.
 685  */
 686 const GstQueryType*
 687 gst_pad_get_query_types_default (GstPad *pad)
 688 {
 689   GstQueryType *result = NULL;
 690
 691   gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
 692                            gst_pad_get_query_types_dispatcher, &result);
 693
 694   return result;
 695 }
 696
 697 /**
 698  * gst_pad_set_internal_link_function:
 699  * @pad: a #GstPad to set the internal link function for.
 700  * @intlink: the #GstPadIntLinkFunction to set.
 701  *
 702  * Sets the given internal link function for the pad.
 703  */
 704 void
 705 gst_pad_set_internal_link_function (GstPad *pad,
 706                                           GstPadIntLinkFunction intlink)
 707 {
 708   g_return_if_fail (pad != NULL);
 709   g_return_if_fail (GST_IS_REAL_PAD (pad));
 710
 711   GST_RPAD_INTLINKFUNC (pad) = intlink;
 712   GST_DEBUG (GST_CAT_PADS, "internal link for %s:%s  set to %s",
 713              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (intlink));
 714 }
 715
 716 /**
 717  * gst_pad_set_formats_function:
 718  * @pad: the #GstPad to set the formats function for.
 719  * @formats: the #GstPadFormatsFunction to set.
 720  *
 721  * Sets the given formats function for the pad.
 722  */
 723 void
 724 gst_pad_set_formats_function (GstPad *pad, GstPadFormatsFunction formats)
 725 {
 726   g_return_if_fail (pad != NULL);
 727   g_return_if_fail (GST_IS_REAL_PAD (pad));
 728
 729   GST_RPAD_FORMATSFUNC (pad) = formats;
 730   GST_DEBUG (GST_CAT_PADS, "formats function for %s:%s  set to %s",
 731              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (formats));
 732 }
 733
 734 /**
 735  * gst_pad_set_link_function:
 736  * @pad: a #GstPad to set the link function for.
 737  * @link: the #GstPadLinkFunction to set.
 738  *
 739  * Sets the given link function for the pad. It will be called
 740  * when the pad is linked or relinked with caps.
 741  */
 742 void
 743 gst_pad_set_link_function (GstPad *pad,
 744                               GstPadLinkFunction link)
 745 {
 746   g_return_if_fail (pad != NULL);
 747   g_return_if_fail (GST_IS_REAL_PAD (pad));
 748
 749   GST_RPAD_LINKFUNC (pad) = link;
 750   GST_DEBUG (GST_CAT_PADS, "linkfunc for %s:%s set to %s",
 751              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (link));
 752 }
 753
 754 /**
 755  * gst_pad_set_getcaps_function:
 756  * @pad: a #GstPad to set the getcaps function for.
 757  * @getcaps: the #GstPadGetCapsFunction to set.
 758  *
 759  * Sets the given getcaps function for the pad.
 760  */
 761 void
 762 gst_pad_set_getcaps_function (GstPad *pad,
 763                               GstPadGetCapsFunction getcaps)
 764 {
 765   g_return_if_fail (pad != NULL);
 766   g_return_if_fail (GST_IS_REAL_PAD (pad));
 767
 768   GST_RPAD_GETCAPSFUNC (pad) = getcaps;
 769   GST_DEBUG (GST_CAT_PADS, "getcapsfunc for %s:%s set to %s",
 770              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (getcaps));
 771 }
 772 /**
 773  * gst_pad_set_bufferpool_function:
 774  * @pad: a #GstPad to set the bufferpool function for.
 775  * @bufpool: the #GstPadBufferPoolFunction to set.
 776  *
 777  * Sets the given bufferpool function for the pad. Note that the
 778  * bufferpool function can only be set on sinkpads.
 779  */
 780 void
 781 gst_pad_set_bufferpool_function (GstPad *pad,
 782                                  GstPadBufferPoolFunction bufpool)
 783 {
 784   g_return_if_fail (pad != NULL);
 785   g_return_if_fail (GST_IS_REAL_PAD (pad));
 786   g_return_if_fail (GST_PAD_IS_SINK (pad));
 787
 788   GST_RPAD_BUFFERPOOLFUNC (pad) = bufpool;
 789   GST_DEBUG (GST_CAT_PADS, "bufferpoolfunc for %s:%s set to %s",
 790              GST_DEBUG_PAD_NAME (pad), GST_DEBUG_FUNCPTR_NAME (bufpool));
 791 }
 792
 793 /**
 794  * gst_pad_unlink:
 795  * @srcpad: the source #GstPad to unlink.
 796  * @sinkpad: the sink #GstPad to unlink.
 797  *
 798  * Unlinks the source pad from the sink pad.
 799  */
 800 void
 801 gst_pad_unlink (GstPad *srcpad,
 802                     GstPad *sinkpad)
 803 {
 804   GstRealPad *realsrc, *realsink;
 805   GstScheduler *src_sched, *sink_sched;
 806
 807   /* generic checks */
 808   g_return_if_fail (srcpad != NULL);
 809   g_return_if_fail (GST_IS_PAD (srcpad));
 810   g_return_if_fail (sinkpad != NULL);
 811   g_return_if_fail (GST_IS_PAD (sinkpad));
 812
 813   GST_INFO (GST_CAT_ELEMENT_PADS, "unlinking %s:%s(%p) and %s:%s(%p)",
 814             GST_DEBUG_PAD_NAME (srcpad), srcpad,
 815             GST_DEBUG_PAD_NAME (sinkpad), sinkpad);
 816
 817   /* now we need to deal with the real/ghost stuff */
 818   realsrc = GST_PAD_REALIZE (srcpad);
 819   realsink = GST_PAD_REALIZE (sinkpad);
 820
 821   g_return_if_fail (GST_RPAD_PEER (realsrc) != NULL);
 822   g_return_if_fail (GST_RPAD_PEER (realsink) == realsrc);
 823
 824   if ((GST_RPAD_DIRECTION (realsrc) == GST_PAD_SINK) &&
 825       (GST_RPAD_DIRECTION (realsink) == GST_PAD_SRC)) {
 826     GstRealPad *temppad;
 827
 828     temppad = realsrc;
 829     realsrc = realsink;
 830     realsink = temppad;
 831   }
 832   g_return_if_fail ((GST_RPAD_DIRECTION (realsrc) == GST_PAD_SRC) &&
 833                     (GST_RPAD_DIRECTION (realsink) == GST_PAD_SINK));
 834
 835   /* get the schedulers before we unlink */
 836   src_sched = gst_pad_get_scheduler (GST_PAD_CAST (realsrc));
 837   sink_sched = gst_pad_get_scheduler (GST_PAD_CAST (realsink));
 838
 839   /* first clear peers */
 840   GST_RPAD_PEER (realsrc) = NULL;
 841   GST_RPAD_PEER (realsink) = NULL;
 842
 843   /* reset the filters, both filters are refcounted once */
 844   if (GST_RPAD_FILTER (realsrc)) {
 845     gst_caps_replace (&GST_RPAD_FILTER (realsink), NULL);
 846     gst_caps_replace (&GST_RPAD_FILTER (realsrc), NULL);
 847   }
 848
 849   /* now tell the scheduler */
 850   if (src_sched && src_sched == sink_sched) {
 851     gst_scheduler_pad_unlink (src_sched,
 852                               GST_PAD_CAST (realsrc),
 853                               GST_PAD_CAST (realsink));
 854   }
 855
 856   /* hold a reference, as they can go away in the signal handlers */
 857   gst_object_ref (GST_OBJECT (realsrc));
 858   gst_object_ref (GST_OBJECT (realsink));
 859
 860   /* fire off a signal to each of the pads telling them
 861    * that they've been unlinked */
 862   g_signal_emit (G_OBJECT (realsrc), gst_real_pad_signals[REAL_UNLINKED],
 863                  0, realsink);
 864   g_signal_emit (G_OBJECT (realsink), gst_real_pad_signals[REAL_UNLINKED],
 865                  0, realsrc);
 866
 867   GST_INFO (GST_CAT_ELEMENT_PADS, "unlinked %s:%s and %s:%s",
 868             GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
 869
 870   gst_object_unref (GST_OBJECT (realsrc));
 871   gst_object_unref (GST_OBJECT (realsink));
 872 }
 873
 874 static gboolean
 875 gst_pad_check_schedulers (GstRealPad *realsrc, GstRealPad *realsink)
 876 {
 877   GstScheduler *src_sched, *sink_sched;
 878   gint num_decoupled = 0;
 879
 880   src_sched = gst_pad_get_scheduler (GST_PAD_CAST (realsrc));
 881   sink_sched = gst_pad_get_scheduler (GST_PAD_CAST (realsink));
 882
 883   if (src_sched && sink_sched) {
 884     if (GST_FLAG_IS_SET (GST_PAD_PARENT (realsrc), GST_ELEMENT_DECOUPLED))
 885       num_decoupled++;
 886     if (GST_FLAG_IS_SET (GST_PAD_PARENT (realsink), GST_ELEMENT_DECOUPLED))
 887       num_decoupled++;
 888
 889     if (src_sched != sink_sched && num_decoupled != 1) {
 890       return FALSE;
 891     }
 892   }
 893   return TRUE;
 894 }
 895
 896 /**
 897  * gst_pad_can_link_filtered:
 898  * @srcpad: the source #GstPad to link.
 899  * @sinkpad: the sink #GstPad to link.
 900  * @filtercaps: the filter #GstCaps.
 901  *
 902  * Checks if the source pad and the sink pad can be linked when constrained
 903  * by the given filter caps.
 904  *
 905  * Returns: TRUE if the pads can be linked, FALSE otherwise.
 906  */
 907 gboolean
 908 gst_pad_can_link_filtered (GstPad *srcpad, GstPad *sinkpad,
 909                            GstCaps *filtercaps)
 910 {
 911   GstRealPad *realsrc, *realsink;
 912
 913   /* generic checks */
 914   g_return_val_if_fail (srcpad != NULL, FALSE);
 915   g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
 916   g_return_val_if_fail (sinkpad != NULL, FALSE);
 917   g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
 918
 919   /* now we need to deal with the real/ghost stuff */
 920   realsrc = GST_PAD_REALIZE (srcpad);
 921   realsink = GST_PAD_REALIZE (sinkpad);
 922
 923   g_return_val_if_fail (GST_RPAD_PEER (realsrc) == NULL, FALSE);
 924   g_return_val_if_fail (GST_RPAD_PEER (realsink) == NULL, FALSE);
 925   g_return_val_if_fail (GST_PAD_PARENT (realsrc) != NULL, FALSE);
 926   g_return_val_if_fail (GST_PAD_PARENT (realsink) != NULL, FALSE);
 927
 928   if (!gst_pad_check_schedulers (realsrc, realsink)) {
 929     g_warning ("linking pads with different scheds requires "
 930                "exactly one decoupled element (queue)");
 931     return FALSE;
 932   }
 933
 934   /* check if the directions are compatible */
 935   if (!(((GST_RPAD_DIRECTION (realsrc) == GST_PAD_SINK) &&
 936          (GST_RPAD_DIRECTION (realsink) == GST_PAD_SRC)) ||
 937         ((GST_RPAD_DIRECTION (realsrc) == GST_PAD_SRC) &&
 938          (GST_RPAD_DIRECTION (realsink) == GST_PAD_SINK))))
 939     return FALSE;
 940
 941   return TRUE;
 942 }
 943 /**
 944  * gst_pad_can_link:
 945  * @srcpad: the source #GstPad to link.
 946  * @sinkpad: the sink #GstPad to link.
 947  *
 948  * Checks if the source pad and the sink pad can be link.
 949  *
 950  * Returns: TRUE if the pads can be linked, FALSE otherwise.
 951  */
 952 gboolean
 953 gst_pad_can_link (GstPad *srcpad, GstPad *sinkpad)
 954 {
 955   return gst_pad_can_link_filtered (srcpad, sinkpad, NULL);
 956 }
 957
 958 /**
 959  * gst_pad_link_filtered:
 960  * @srcpad: the source #GstPad to link.
 961  * @sinkpad: the sink #GstPad to link.
 962  * @filtercaps: the filter #GstCaps.
 963  *
 964  * Links the source pad and the sink pad, constrained
 965  * by the given filter caps.
 966  *
 967  * Returns: TRUE if the pads have been linked, FALSE otherwise.
 968  */
 969 gboolean
 970 gst_pad_link_filtered (GstPad *srcpad, GstPad *sinkpad, GstCaps *filtercaps)
 971 {
 972   GstRealPad *realsrc, *realsink;
 973   GstScheduler *src_sched, *sink_sched;
 974
 975   /* generic checks */
 976   g_return_val_if_fail (srcpad != NULL, FALSE);
 977   g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
 978   g_return_val_if_fail (sinkpad != NULL, FALSE);
 979   g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
 980
 981   GST_INFO (GST_CAT_PADS, "trying to link %s:%s and %s:%s",
 982             GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
 983
 984   /* now we need to deal with the real/ghost stuff */
 985   realsrc = GST_PAD_REALIZE (srcpad);
 986   realsink = GST_PAD_REALIZE (sinkpad);
 987
 988   if ((GST_PAD (realsrc) != srcpad) || (GST_PAD (realsink) != sinkpad)) {
 989     GST_INFO (GST_CAT_PADS, "*actually* linking %s:%s and %s:%s",
 990               GST_DEBUG_PAD_NAME (realsrc), GST_DEBUG_PAD_NAME (realsink));
 991   }
 992   if (GST_RPAD_PEER (realsrc) != NULL) {
 993     GST_INFO (GST_CAT_PADS, "Real source pad %s:%s has a peer, failed",
 994               GST_DEBUG_PAD_NAME (realsrc));
 995     return FALSE;
 996   }
 997   if (GST_RPAD_PEER (realsink) != NULL) {
 998     GST_INFO (GST_CAT_PADS, "Real sink pad %s:%s has a peer, failed",
 999               GST_DEBUG_PAD_NAME (realsink));
1000     return FALSE;
1001   }
1002   if (GST_PAD_PARENT (realsrc) == NULL) {
1003     GST_INFO (GST_CAT_PADS, "Real src pad %s:%s has no parent, failed",
1004               GST_DEBUG_PAD_NAME (realsrc));
1005     return FALSE;
1006   }
1007   if (GST_PAD_PARENT (realsink) == NULL) {
1008     GST_INFO (GST_CAT_PADS, "Real src pad %s:%s has no parent, failed",
1009               GST_DEBUG_PAD_NAME (realsrc));
1010     return FALSE;
1011   }
1012
1013   if (!gst_pad_check_schedulers (realsrc, realsink)) {
1014     g_warning ("linking pads with different scheds requires "
1015                "exactly one decoupled element (such as queue)");
1016     return FALSE;
1017   }
1018
1019   /* check for reversed directions and swap if necessary */
1020   if ((GST_RPAD_DIRECTION (realsrc) == GST_PAD_SINK) &&
1021       (GST_RPAD_DIRECTION (realsink) == GST_PAD_SRC)) {
1022     GstRealPad *temppad;
1023
1024     temppad = realsrc;
1025     realsrc = realsink;
1026     realsink = temppad;
1027   }
1028   if (GST_RPAD_DIRECTION (realsrc) != GST_PAD_SRC) {
1029     GST_INFO (GST_CAT_PADS, "Real src pad %s:%s is not a source pad, failed",
1030               GST_DEBUG_PAD_NAME (realsrc));
1031     return FALSE;
1032   }
1033   if (GST_RPAD_DIRECTION (realsink) != GST_PAD_SINK) {
1034     GST_INFO (GST_CAT_PADS, "Real sink pad %s:%s is not a sink pad, failed",
1035               GST_DEBUG_PAD_NAME (realsink));
1036     return FALSE;
1037   }
1038   /* first set peers */
1039   GST_RPAD_PEER (realsrc) = realsink;
1040   GST_RPAD_PEER (realsink) = realsrc;
1041
1042   /* try to negotiate the pads, we don't need to clear the caps here */
1043   if (!gst_pad_try_relink_filtered_func (realsrc, realsink,
1044                                          filtercaps, FALSE)) {
1045     GST_DEBUG (GST_CAT_CAPS, "relink_filtered_func failed, can't link");
1046
1047     GST_RPAD_PEER (realsrc) = NULL;
1048     GST_RPAD_PEER (realsink) = NULL;
1049
1050     return FALSE;
1051   }
1052
1053   /* fire off a signal to each of the pads telling them
1054    * that they've been linked */
1055   g_signal_emit (G_OBJECT (realsrc), gst_real_pad_signals[REAL_LINKED],
1056                  0, realsink);
1057   g_signal_emit (G_OBJECT (realsink), gst_real_pad_signals[REAL_LINKED],
1058                  0, realsrc);
1059
1060   src_sched = gst_pad_get_scheduler (GST_PAD_CAST (realsrc));
1061   sink_sched = gst_pad_get_scheduler (GST_PAD_CAST (realsink));
1062
1063   /* now tell the scheduler */
1064   if (src_sched && src_sched == sink_sched) {
1065     gst_scheduler_pad_link (src_sched,
1066                             GST_PAD_CAST (realsrc), GST_PAD_CAST (realsink));
1067   }
1068
1069   GST_INFO (GST_CAT_PADS, "linked %s:%s and %s:%s, successful",
1070             GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1071
1072   return TRUE;
1073 }
1074
1075 /**
1076  * gst_pad_link:
1077  * @srcpad: the source #GstPad to link.
1078  * @sinkpad: the sink #GstPad to link.
1079  *
1080  * Links the source pad to the sink pad.
1081  *
1082  * Returns: TRUE if the pad could be linked, FALSE otherwise.
1083  */
1084 gboolean
1085 gst_pad_link (GstPad *srcpad, GstPad *sinkpad)
1086 {
1087   return gst_pad_link_filtered (srcpad, sinkpad, NULL);
1088 }
1089
1090 /**
1091  * gst_pad_set_parent:
1092  * @pad: a #GstPad to set the parent of.
1093  * @parent: the new parent #GstElement.
1094  *
1095  * Sets the parent object of a pad.
1096  */
1097 void
1098 gst_pad_set_parent (GstPad *pad, GstElement *parent)
1099 {
1100   g_return_if_fail (pad != NULL);
1101   g_return_if_fail (GST_IS_PAD (pad));
1102   g_return_if_fail (GST_PAD_PARENT (pad) == NULL);
1103   g_return_if_fail (parent != NULL);
1104   g_return_if_fail (GST_IS_OBJECT (parent));
1105   g_return_if_fail ((gpointer) pad != (gpointer) parent);
1106
1107   gst_object_set_parent (GST_OBJECT (pad), GST_OBJECT (parent));
1108 }
1109
1110 /**
1111  * gst_pad_get_parent:
1112  * @pad: the #GstPad to get the parent of.
1113  *
1114  * Gets the parent object of this pad.
1115  *
1116  * Returns: the parent #GstElement.
1117  */
1118 GstElement*
1119 gst_pad_get_parent (GstPad *pad)
1120 {
1121   g_return_val_if_fail (pad != NULL, NULL);
1122   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1123
1124   return GST_PAD_PARENT (pad);
1125 }
1126
1127 /**
1128  * gst_pad_get_pad_template:
1129  * @pad: a #GstPad to get the pad template of.
1130  *
1131  * Gets the pad template object of this pad.
1132  *
1133  * Returns: the #GstPadTemplate from which this pad was instantiated.
1134  */
1135 GstPadTemplate*
1136 gst_pad_get_pad_template (GstPad *pad)
1137 {
1138   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1139
1140   return GST_PAD_PAD_TEMPLATE (pad);
1141 }
1142
1143
1144 /**
1145  * gst_pad_get_scheduler:
1146  * @pad: a #GstPad to get the scheduler of.
1147  *
1148  * Gets the scheduler of the pad. Since the pad does not
1149  * have a scheduler of its own, the scheduler of the parent
1150  * is taken. For decoupled pads, the scheduler of the peer
1151  * parent is taken.
1152  *
1153  * Returns: the #GstScheduler of the pad.
1154  */
1155 GstScheduler*
1156 gst_pad_get_scheduler (GstPad *pad)
1157 {
1158   GstScheduler *scheduler = NULL;
1159   GstElement *parent;
1160
1161   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1162
1163   parent = gst_pad_get_parent (pad);
1164   if (parent) {
1165     if (GST_FLAG_IS_SET (parent, GST_ELEMENT_DECOUPLED)) {
1166       GstRealPad *peer = GST_RPAD_PEER (pad);
1167
1168       if (peer) {
1169         scheduler = gst_element_get_scheduler (gst_pad_get_parent (GST_PAD_CAST (peer)));
1170       }
1171     }
1172     else {
1173       scheduler = gst_element_get_scheduler (parent);
1174     }
1175   }
1176
1177   return scheduler;
1178 }
1179
1180 /**
1181  * gst_pad_get_real_parent:
1182  * @pad: a #GstPad to get the real parent of.
1183  *
1184  * Gets the real parent object of this pad. If the pad
1185  * is a ghost pad, the actual owner of the real pad is
1186  * returned, as opposed to #gst_pad_get_parent().
1187  *
1188  * Returns: the parent #GstElement.
1189  */
1190 GstElement*
1191 gst_pad_get_real_parent (GstPad *pad)
1192 {
1193   g_return_val_if_fail (pad != NULL, NULL);
1194   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1195
1196   return GST_PAD_PARENT (GST_PAD (GST_PAD_REALIZE (pad)));
1197 }
1198
1199 /**
1200  * gst_pad_add_ghost_pad:
1201  * @pad: a #GstPad to attach the ghost pad to.
1202  * @ghostpad: the ghost #GstPad to to the pad.
1203  *
1204  * Adds a ghost pad to a pad.
1205  */
1206 void
1207 gst_pad_add_ghost_pad (GstPad *pad,
1208                        GstPad *ghostpad)
1209 {
1210   GstRealPad *realpad;
1211
1212   g_return_if_fail (pad != NULL);
1213   g_return_if_fail (GST_IS_PAD (pad));
1214   g_return_if_fail (ghostpad != NULL);
1215   g_return_if_fail (GST_IS_GHOST_PAD (ghostpad));
1216
1217   realpad = GST_PAD_REALIZE (pad);
1218
1219   realpad->ghostpads = g_list_prepend (realpad->ghostpads, ghostpad);
1220 }
1221
1222
1223 /**
1224  * gst_pad_remove_ghost_pad:
1225  * @pad: a #GstPad to remove the ghost pad from.
1226  * @ghostpad: the ghost #GstPad to remove from the pad.
1227  *
1228  * Removes a ghost pad from a pad.
1229  */
1230 void
1231 gst_pad_remove_ghost_pad (GstPad *pad,
1232                           GstPad *ghostpad)
1233 {
1234   GstRealPad *realpad;
1235
1236   g_return_if_fail (pad != NULL);
1237   g_return_if_fail (GST_IS_PAD (pad));
1238   g_return_if_fail (ghostpad != NULL);
1239   g_return_if_fail (GST_IS_GHOST_PAD (ghostpad));
1240
1241   realpad = GST_PAD_REALIZE (pad);
1242
1243   realpad->ghostpads = g_list_remove (realpad->ghostpads, ghostpad);
1244 }
1245
1246 /**
1247  * gst_pad_get_ghost_pad_list:
1248  * @pad: a #GstPad to get the ghost pads of.
1249  *
1250  * Gets the ghost pads of this pad.
1251  *
1252  * Returns: a #GList of ghost pads.
1253  */
1254 GList*
1255 gst_pad_get_ghost_pad_list (GstPad *pad)
1256 {
1257   g_return_val_if_fail (pad != NULL, NULL);
1258   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1259
1260   return GST_PAD_REALIZE(pad)->ghostpads;
1261 }
1262
1263 /* an internal caps negotiation helper function:
1264  *
1265  * 1. optionally calls the pad link function with the provided caps
1266  * 2. deals with the result code of the link function
1267  * 3. sets fixed caps on the pad.
1268  */
1269 static GstPadLinkReturn
1270 gst_pad_try_set_caps_func (GstRealPad *pad, GstCaps *caps, gboolean notify)
1271 {
1272   GstCaps *allowed = NULL;
1273   GstPadTemplate *template;
1274   GstElement *parent = GST_PAD_PARENT (pad);
1275
1276   g_return_val_if_fail (pad != NULL, GST_PAD_LINK_REFUSED);
1277   g_return_val_if_fail (GST_IS_PAD (pad), GST_PAD_LINK_REFUSED);
1278
1279   /* if this pad has a parent and the parent is not READY, delay the
1280    * negotiation */
1281   if (parent && GST_STATE (parent) < GST_STATE_READY)
1282   {
1283     GST_DEBUG (GST_CAT_CAPS, "parent %s of pad %s:%s is not READY",
1284                GST_ELEMENT_NAME (parent), GST_DEBUG_PAD_NAME (pad));
1285     return GST_PAD_LINK_DELAYED;
1286   }
1287
1288   GST_INFO (GST_CAT_CAPS, "trying to set caps %p on pad %s:%s",
1289             caps, GST_DEBUG_PAD_NAME (pad));
1290
1291   /* first see if we have to check against a filter, we ref the caps here as we're
1292    * going to unref it later on */
1293   if (!(allowed = gst_caps_ref (GST_RPAD_FILTER (pad)))) {
1294     /* no filter, make sure we check against the padtemplate then */
1295     if ((template = gst_pad_get_pad_template (GST_PAD_CAST (pad)))) {
1296       allowed = gst_pad_template_get_caps (template);
1297     }
1298   }
1299
1300   /* do we have to check the caps against something? */
1301   if (allowed) {
1302     GstCaps *intersection;
1303
1304     /* check against calculated caps */
1305     intersection = gst_caps_intersect (caps, allowed);
1306
1307     /* oops, empty intersection, caps don"t have anything in common */
1308     if (!intersection) {
1309       GST_INFO (GST_CAT_CAPS, "caps did not intersect with %s:%s's allowed caps",
1310                 GST_DEBUG_PAD_NAME (pad));
1311       gst_caps_debug (caps, "caps themselves (attemped to set)");
1312       gst_caps_debug (allowed,
1313                       "allowed caps that did not agree with caps");
1314       gst_caps_unref (allowed);
1315       return GST_PAD_LINK_REFUSED;
1316     }
1317     /* caps checks out fine, we can unref the intersection now */
1318     gst_caps_unref (intersection);
1319     gst_caps_unref (allowed);
1320     /* given that the caps are fixed, we know that their intersection with the
1321      * padtemplate caps is the same as caps itself */
1322   }
1323
1324   /* we need to notify the link function */
1325   if (notify && GST_RPAD_LINKFUNC (pad)) {
1326     GstPadLinkReturn res;
1327     gchar *debug_string;
1328     gboolean negotiating;
1329
1330     GST_INFO (GST_CAT_CAPS, "calling link function on pad %s:%s",
1331             GST_DEBUG_PAD_NAME (pad));
1332
1333     negotiating = GST_FLAG_IS_SET (pad, GST_PAD_NEGOTIATING);
1334
1335     /* set the NEGOTIATING flag if not already done */
1336     if (!negotiating)
1337       GST_FLAG_SET (pad, GST_PAD_NEGOTIATING);
1338
1339     /* call the link function */
1340     res = GST_RPAD_LINKFUNC (pad) (GST_PAD (pad), caps);
1341
1342     /* unset again after negotiating only if we set it  */
1343     if (!negotiating)
1344       GST_FLAG_UNSET (pad, GST_PAD_NEGOTIATING);
1345
1346     switch (res) {
1347       case GST_PAD_LINK_REFUSED:
1348         debug_string = "REFUSED";
1349         break;
1350       case GST_PAD_LINK_OK:
1351         debug_string = "OK";
1352         break;
1353       case GST_PAD_LINK_DONE:
1354         debug_string = "DONE";
1355         break;
1356       case GST_PAD_LINK_DELAYED:
1357         debug_string = "DELAYED";
1358         break;
1359       default:
1360         g_warning ("unknown return code from link function of pad %s:%s %d",
1361                    GST_DEBUG_PAD_NAME (pad), res);
1362         return GST_PAD_LINK_REFUSED;
1363     }
1364
1365     GST_INFO (GST_CAT_CAPS,
1366               "got reply %s (%d) from link function on pad %s:%s",
1367               debug_string, res, GST_DEBUG_PAD_NAME (pad));
1368
1369     /* done means the link function called another caps negotiate function
1370      * on this pad that succeeded, we dont need to continue */
1371     if (res == GST_PAD_LINK_DONE) {
1372       GST_INFO (GST_CAT_CAPS, "pad %s:%s is done", GST_DEBUG_PAD_NAME (pad));
1373       return GST_PAD_LINK_DONE;
1374     }
1375     if (res == GST_PAD_LINK_REFUSED) {
1376       GST_INFO (GST_CAT_CAPS, "pad %s:%s doesn't accept caps",
1377                 GST_DEBUG_PAD_NAME (pad));
1378       return GST_PAD_LINK_REFUSED;
1379     }
1380   }
1381   /* we can only set caps on the pad if they are fixed */
1382   if (GST_CAPS_IS_FIXED (caps)) {
1383
1384     GST_INFO (GST_CAT_CAPS, "setting caps on pad %s:%s",
1385               GST_DEBUG_PAD_NAME (pad));
1386     /* if we got this far all is ok, remove the old caps, set the new one */
1387     gst_caps_replace_sink (&GST_PAD_CAPS (pad), caps);
1388
1389     g_object_notify (G_OBJECT (pad), "caps");
1390   }
1391   else {
1392     GST_INFO (GST_CAT_CAPS,
1393               "caps are not fixed on pad %s:%s, not setting them yet",
1394               GST_DEBUG_PAD_NAME (pad));
1395
1396     return GST_PAD_LINK_DELAYED;
1397   }
1398   return GST_PAD_LINK_OK;
1399 }
1400
1401 /**
1402  * gst_pad_try_set_caps:
1403  * @pad: a #GstPad to try to set the caps on.
1404  * @caps: the #GstCaps to set.
1405  *
1406  * Tries to set the caps on the given pad. Ownership is always taken
1407  * of the caps, so you will need to unref non-floating caps.
1408  *
1409  * Returns: A #GstPadLinkReturn value indicating whether the caps
1410  *              could be set.
1411  */
1412 GstPadLinkReturn
1413 gst_pad_try_set_caps (GstPad *pad, GstCaps *caps)
1414 {
1415   GstRealPad *peer, *realpad;
1416   GstPadLinkReturn set_retval;
1417
1418   realpad = GST_PAD_REALIZE (pad);
1419   peer = GST_RPAD_PEER (realpad);
1420
1421   GST_INFO (GST_CAT_CAPS, "trying to set caps %p on pad %s:%s",
1422             caps, GST_DEBUG_PAD_NAME (realpad));
1423
1424   gst_caps_debug (caps, "caps that we are trying to set");
1425
1426   /* try to take ownership */
1427   gst_caps_ref (caps);
1428   gst_caps_sink (caps);
1429
1430   /* setting non fixed caps on a pad is not allowed */
1431   if (!GST_CAPS_IS_FIXED (caps)) {
1432     GST_INFO (GST_CAT_CAPS,
1433               "trying to set unfixed caps on pad %s:%s, not allowed",
1434               GST_DEBUG_PAD_NAME (realpad));
1435     g_warning ("trying to set non fixed caps on pad %s:%s, not allowed",
1436                GST_DEBUG_PAD_NAME (realpad));
1437
1438     gst_caps_debug (caps, "unfixed caps");
1439     set_retval = GST_PAD_LINK_DELAYED;
1440     goto done;
1441   }
1442
1443   /* if we have a peer try to set the caps, notifying the peerpad
1444    * if it has a link function */
1445   if (peer && ((set_retval = gst_pad_try_set_caps_func (peer, caps, TRUE)) <= 0))
1446   {
1447     GST_INFO (GST_CAT_CAPS, "tried to set caps on peerpad %s:%s but couldn't, return value %d",
1448               GST_DEBUG_PAD_NAME (peer), set_retval);
1449     goto done;
1450   }
1451
1452   /* then try to set our own caps, we don't need to be notified */
1453   if ((set_retval = gst_pad_try_set_caps_func (realpad, caps, FALSE)) <= 0)
1454   {
1455     GST_INFO (GST_CAT_CAPS, "tried to set own caps on pad %s:%s but couldn't, return value %d",
1456               GST_DEBUG_PAD_NAME (realpad), set_retval);
1457     goto done;
1458   }
1459   GST_INFO (GST_CAT_CAPS, "succeeded setting caps %p on pad %s:%s, return value %d",
1460             caps, GST_DEBUG_PAD_NAME (realpad), set_retval);
1461   g_assert (GST_PAD_CAPS (pad));
1462
1463 done:
1464   /* if we took ownership, the caps will be freed */
1465   gst_caps_unref (caps);
1466
1467   return set_retval;
1468 }
1469
1470 /* this is a caps negotiation convenience routine, it:
1471  *
1472  * 1. optionally clears any pad caps.
1473  * 2. calculates the intersection between the two pad tamplate/getcaps caps.
1474  * 3. calculates the intersection with the (optional) filtercaps.
1475  * 4. stores the intersection in the pad filter.
1476  * 5. stores the app filtercaps in the pad appfilter.
1477  * 6. starts the caps negotiation.
1478  */
1479 static gboolean
1480 gst_pad_try_relink_filtered_func (GstRealPad *srcpad, GstRealPad *sinkpad,
1481                                   GstCaps *filtercaps, gboolean clear)
1482 {
1483   GstCaps *srccaps, *sinkcaps;
1484   GstCaps *intersection = NULL;
1485   GstRealPad *realsrc, *realsink;
1486
1487   realsrc = GST_PAD_REALIZE (srcpad);
1488   realsink = GST_PAD_REALIZE (sinkpad);
1489
1490   g_return_val_if_fail (GST_RPAD_PEER (realsrc) != NULL, FALSE);
1491   g_return_val_if_fail (GST_RPAD_PEER (realsink) == realsrc, FALSE);
1492
1493   /* optinally clear the caps */
1494   if (clear) {
1495     GST_INFO (GST_CAT_PADS,
1496               "start relink filtered %s:%s and %s:%s, clearing caps",
1497               GST_DEBUG_PAD_NAME (realsrc), GST_DEBUG_PAD_NAME (realsink));
1498
1499     /* FIXME does this leak? */
1500     gst_caps_replace (&GST_PAD_CAPS (GST_PAD (realsrc)), NULL);
1501     gst_caps_replace (&GST_PAD_CAPS (GST_PAD (realsink)), NULL);
1502     gst_caps_replace (&GST_RPAD_FILTER (realsrc), NULL);
1503     gst_caps_replace (&GST_RPAD_FILTER (realsink), NULL);
1504   }
1505   else {
1506     GST_INFO (GST_CAT_PADS, "start relink filtered %s:%s and %s:%s",
1507         GST_DEBUG_PAD_NAME (realsrc), GST_DEBUG_PAD_NAME (realsink));
1508   }
1509
1510   srccaps = gst_pad_get_caps (GST_PAD (realsrc));
1511   GST_DEBUG (GST_CAT_PADS, "dumping caps of pad %s:%s",
1512              GST_DEBUG_PAD_NAME (realsrc));
1513   gst_caps_debug (srccaps, "caps of src pad (pre-relink)");
1514   sinkcaps = gst_pad_get_caps (GST_PAD (realsink));
1515   GST_DEBUG (GST_CAT_PADS, "dumping caps of pad %s:%s",
1516              GST_DEBUG_PAD_NAME (realsink));
1517   gst_caps_debug (sinkcaps, "caps of sink pad (pre-relink)");
1518
1519   /* first take the intersection of the pad caps */
1520   intersection = gst_caps_intersect (srccaps, sinkcaps);
1521   gst_caps_debug (intersection, "caps of intersection");
1522
1523   /* if we have no intersection but one of the caps was not NULL.. */
1524   if (!intersection && (srccaps || sinkcaps)) {
1525     /* the intersection is NULL but the pad caps were not both NULL,
1526      * this means they have no common format */
1527     GST_INFO (GST_CAT_PADS, "pads %s:%s and %s:%s have no common type",
1528               GST_DEBUG_PAD_NAME (realsrc), GST_DEBUG_PAD_NAME (realsink));
1529     /* make sure any floating caps from gst_pad_get_caps are freed here */
1530     gst_caps_sink (srccaps);
1531     gst_caps_sink (sinkcaps);
1532     return FALSE;
1533   } else  {
1534     GST_INFO (GST_CAT_PADS, "pads %s:%s and %s:%s intersected to %s caps",
1535        GST_DEBUG_PAD_NAME (realsrc), GST_DEBUG_PAD_NAME (realsink),
1536        (intersection ?
1537            (GST_CAPS_IS_FIXED (intersection) ? "fixed" : "variable") :
1538            "NULL"));
1539
1540     /* we don't need those anymore, as the caps can be floating */
1541     gst_caps_sink (srccaps);
1542     gst_caps_sink (sinkcaps);
1543
1544     /* then filter this against the app filter */
1545     if (filtercaps) {
1546       GstCaps *filtered_intersection;
1547
1548       filtered_intersection = gst_caps_intersect (intersection,
1549                                                   filtercaps);
1550
1551       gst_caps_unref (intersection);
1552
1553       if (!filtered_intersection) {
1554         GST_INFO (GST_CAT_PADS,
1555                   "filtered link between pads %s:%s and %s:%s is empty",
1556                   GST_DEBUG_PAD_NAME (realsrc), GST_DEBUG_PAD_NAME (realsink));
1557         return FALSE;
1558       }
1559       intersection = filtered_intersection;
1560
1561       /* keep a reference to the app caps */
1562       gst_caps_replace_sink (&GST_RPAD_APPFILTER (realsink), filtercaps);
1563       gst_caps_replace_sink (&GST_RPAD_APPFILTER (realsrc), filtercaps);
1564     }
1565   }
1566   GST_DEBUG (GST_CAT_CAPS, "setting filter for link to:");
1567   gst_caps_debug (intersection, "filter for link");
1568
1569   /* both the app filter and the filter, while stored on both peer pads,
1570    * are equal to the same thing on both */
1571   gst_caps_replace_sink (&GST_RPAD_FILTER (realsrc), intersection);
1572   gst_caps_replace_sink (&GST_RPAD_FILTER (realsink), intersection);
1573   gst_caps_unref (intersection);
1574
1575   return gst_pad_perform_negotiate (GST_PAD (realsrc), GST_PAD (realsink));
1576 }
1577
1578 /**
1579  * gst_pad_perform_negotiate:
1580  * @srcpad: the source #GstPad.
1581  * @sinkpad: the sink #GstPad.
1582  *
1583  * Tries to negotiate the pads.
1584  *
1585  * Returns: TRUE if the pads were succesfully negotiated, FALSE otherwise.
1586  */
1587 gboolean
1588 gst_pad_perform_negotiate (GstPad *srcpad, GstPad *sinkpad)
1589 {
1590   GstCaps *intersection, *filtered_intersection;
1591   GstRealPad *realsrc, *realsink;
1592   GstCaps *srccaps, *sinkcaps, *filter;
1593   gboolean res = TRUE;
1594   GstElement *parent;
1595
1596
1597   g_return_val_if_fail (srcpad != NULL, FALSE);
1598   g_return_val_if_fail (sinkpad != NULL, FALSE);
1599
1600   realsrc = GST_PAD_REALIZE (srcpad);
1601   realsink = GST_PAD_REALIZE (sinkpad);
1602
1603   g_return_val_if_fail (GST_RPAD_PEER (realsrc) != NULL, FALSE);
1604   g_return_val_if_fail (GST_RPAD_PEER (realsink) == realsrc, FALSE);
1605
1606   /* shortcut negotiation */
1607   parent = GST_PAD_PARENT (realsrc);
1608   if (parent && GST_STATE (parent) < GST_STATE_READY) {
1609     GST_DEBUG (GST_CAT_CAPS, "parent %s of pad %s:%s is not READY",
1610                GST_ELEMENT_NAME (parent), GST_DEBUG_PAD_NAME (realsrc));
1611     return TRUE;
1612   }
1613   parent = GST_PAD_PARENT (realsink);
1614   if (parent && GST_STATE (parent) < GST_STATE_READY) {
1615     GST_DEBUG (GST_CAT_CAPS, "parent %s of pad %s:%s is not READY",
1616                GST_ELEMENT_NAME (parent), GST_DEBUG_PAD_NAME (realsink));
1617     return TRUE;
1618   }
1619
1620   GST_INFO (GST_CAT_PADS, "perform negotiate for link %s:%s-%s:%s",
1621               GST_DEBUG_PAD_NAME (realsrc), GST_DEBUG_PAD_NAME (realsink));
1622
1623   filter = GST_RPAD_APPFILTER (realsrc);
1624   if (filter) {
1625     GST_INFO (GST_CAT_PADS, "dumping filter for link %s:%s-%s:%s",
1626               GST_DEBUG_PAD_NAME (realsrc), GST_DEBUG_PAD_NAME (realsink));
1627     gst_caps_debug (filter, "link filter caps");
1628   }
1629
1630   /* calculate the new caps here */
1631   srccaps = gst_pad_get_caps (GST_PAD (realsrc));
1632   GST_DEBUG (GST_CAT_PADS, "dumping caps of pad %s:%s",
1633              GST_DEBUG_PAD_NAME (realsrc));
1634   gst_caps_debug (srccaps,
1635                   "src caps, awaiting negotiation, after applying filter");
1636   sinkcaps = gst_pad_get_caps (GST_PAD (realsink));
1637   GST_DEBUG (GST_CAT_PADS, "dumping caps of pad %s:%s",
1638              GST_DEBUG_PAD_NAME (realsink));
1639   gst_caps_debug (sinkcaps,
1640                   "sink caps, awaiting negotiation, after applying filter");
1641   intersection = gst_caps_intersect (srccaps, sinkcaps);
1642   filtered_intersection = gst_caps_intersect (intersection, filter);
1643   gst_caps_unref (intersection);
1644
1645   /* no negotiation is performed if the pads have filtercaps */
1646   if (filtered_intersection) {
1647     GstPadLinkReturn link_res;
1648
1649     link_res = gst_pad_try_set_caps_func (realsrc, filtered_intersection, TRUE);
1650     if (link_res == GST_PAD_LINK_REFUSED)
1651       goto error;
1652     if (link_res == GST_PAD_LINK_DONE)
1653       goto success;
1654
1655     link_res = gst_pad_try_set_caps_func (realsink, filtered_intersection, TRUE);
1656     if (link_res == GST_PAD_LINK_REFUSED)
1657       goto error;
1658     if (link_res == GST_PAD_LINK_DONE)
1659       goto success;
1660   }
1661   /* no filtered_intersection, some pads had caps and ther was a filter */
1662   else if ((srccaps || sinkcaps) && filter) {
1663     goto error;
1664   }
1665
1666 success:
1667 cleanup:
1668   gst_caps_sink (srccaps);
1669   gst_caps_sink (sinkcaps);
1670   gst_caps_unref (filtered_intersection);
1671   return res;
1672
1673 error:
1674   res = FALSE;
1675   goto cleanup;
1676 }
1677
1678 /**
1679  * gst_pad_try_relink_filtered:
1680  * @srcpad: the source #GstPad to relink.
1681  * @sinkpad: the sink #GstPad to relink.
1682  * @filtercaps: the #GstPad to use as a filter in the relink.
1683  *
1684  * Tries to relink the given source and sink pad, constrained by the given
1685  * capabilities.
1686  *
1687  * Returns: TRUE if the pads were succesfully renegotiated, FALSE otherwise.
1688  */
1689 gboolean
1690 gst_pad_try_relink_filtered (GstPad *srcpad, GstPad *sinkpad,
1691                                 GstCaps *filtercaps)
1692 {
1693   GstRealPad *realsrc, *realsink;
1694
1695   g_return_val_if_fail (srcpad != NULL, FALSE);
1696   g_return_val_if_fail (sinkpad != NULL, FALSE);
1697
1698   realsrc = GST_PAD_REALIZE (srcpad);
1699   realsink = GST_PAD_REALIZE (sinkpad);
1700
1701   g_return_val_if_fail (GST_RPAD_PEER (realsrc) != NULL, FALSE);
1702   g_return_val_if_fail (GST_RPAD_PEER (realsink) == realsrc, FALSE);
1703
1704   return gst_pad_try_relink_filtered_func (realsrc, realsink,
1705                                            filtercaps, TRUE);
1706 }
1707
1708 /**
1709  * gst_pad_relink_filtered:
1710  * @srcpad: the source #GstPad to relink.
1711  * @sinkpad: the sink #GstPad to relink.
1712  * @filtercaps: the #GstPad to use as a filter in the relink.
1713  *
1714  * Relinks the given source and sink pad, constrained by the given
1715  * capabilities.  If the relink fails, the pads are unlinked
1716  * and FALSE is returned.
1717  *
1718  * Returns: TRUE if the pads were succesfully relinked, FALSE otherwise.
1719  */
1720 gboolean
1721 gst_pad_relink_filtered (GstPad *srcpad, GstPad *sinkpad,
1722                             GstCaps *filtercaps)
1723 {
1724   GstRealPad *realsrc, *realsink;
1725
1726   g_return_val_if_fail (srcpad != NULL, FALSE);
1727   g_return_val_if_fail (sinkpad != NULL, FALSE);
1728
1729   realsrc = GST_PAD_REALIZE (srcpad);
1730   realsink = GST_PAD_REALIZE (sinkpad);
1731
1732   g_return_val_if_fail (GST_RPAD_PEER (realsrc) != NULL, FALSE);
1733   g_return_val_if_fail (GST_RPAD_PEER (realsink) == realsrc, FALSE);
1734
1735   if (!gst_pad_try_relink_filtered_func (realsrc, realsink,
1736                                          filtercaps, TRUE))
1737   {
1738     gst_pad_unlink (srcpad, GST_PAD (GST_PAD_PEER (srcpad)));
1739     return FALSE;
1740   }
1741   return TRUE;
1742 }
1743
1744 /**
1745  * gst_pad_proxy_link:
1746  * @pad: a #GstPad to proxy to.
1747  * @caps: the #GstCaps to use in proxying.
1748  *
1749  * Proxies the link function to the specified pad.
1750  *
1751  * Returns: TRUE if the peer pad accepted the caps, FALSE otherwise.
1752  */
1753 GstPadLinkReturn
1754 gst_pad_proxy_link (GstPad *pad, GstCaps *caps)
1755 {
1756   GstRealPad *peer, *realpad;
1757
1758   realpad = GST_PAD_REALIZE (pad);
1759
1760   peer = GST_RPAD_PEER (realpad);
1761
1762   GST_INFO (GST_CAT_CAPS, "proxy link to pad %s:%s",
1763             GST_DEBUG_PAD_NAME (realpad));
1764
1765   if (peer && gst_pad_try_set_caps_func (peer, caps, TRUE) < 0)
1766     return GST_PAD_LINK_REFUSED;
1767   if (gst_pad_try_set_caps_func (realpad, caps, FALSE) < 0)
1768     return GST_PAD_LINK_REFUSED;
1769
1770   return GST_PAD_LINK_OK;
1771 }
1772
1773 /**
1774  * gst_pad_get_caps:
1775  * @pad: a  #GstPad to get the capabilities of.
1776  *
1777  * Gets the capabilities of this pad.
1778  *
1779  * Returns: the #GstCaps of this pad. This function potentially
1780  * returns a floating caps, so use gst_caps_sink to get rid of
1781  * it.
1782  */
1783 GstCaps*
1784 gst_pad_get_caps (GstPad *pad)
1785 {
1786   GstRealPad *realpad;
1787
1788   g_return_val_if_fail (pad != NULL, NULL);
1789   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1790
1791   realpad = GST_PAD_REALIZE (pad);
1792
1793   GST_DEBUG (GST_CAT_CAPS, "get pad caps of %s:%s (%p)",
1794             GST_DEBUG_PAD_NAME (realpad), realpad);
1795
1796   /* note that we will not _ref the caps here as this function might be
1797    * called recursively */
1798   if (GST_PAD_CAPS (realpad)) {
1799     GST_DEBUG (GST_CAT_CAPS, "using pad real caps %p", GST_PAD_CAPS (realpad));
1800     return GST_PAD_CAPS (realpad);
1801   }
1802   else if GST_RPAD_GETCAPSFUNC (realpad) {
1803     GST_DEBUG (GST_CAT_CAPS, "using pad get function");
1804     return GST_RPAD_GETCAPSFUNC (realpad) (GST_PAD_CAST (realpad), NULL);
1805   }
1806   else if (GST_PAD_PAD_TEMPLATE (realpad)) {
1807     GstPadTemplate *templ = GST_PAD_PAD_TEMPLATE (realpad);
1808     GST_DEBUG (GST_CAT_CAPS, "using pad template %p with caps %p",
1809                templ, GST_PAD_TEMPLATE_CAPS (templ));
1810     return GST_PAD_TEMPLATE_CAPS (templ);
1811   }
1812   GST_DEBUG (GST_CAT_CAPS, "pad has no caps");
1813
1814   return NULL;
1815 }
1816
1817 /**
1818  * gst_pad_get_pad_template_caps:
1819  * @pad: a #GstPad to get the template capabilities from.
1820  *
1821  * Gets the template capabilities of this pad.
1822  *
1823  * Returns: the template #GstCaps of this pad, unref the caps
1824  * if you no longer need it.
1825  */
1826 GstCaps*
1827 gst_pad_get_pad_template_caps (GstPad *pad)
1828 {
1829   g_return_val_if_fail (pad != NULL, NULL);
1830   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1831
1832   if (GST_PAD_PAD_TEMPLATE (pad))
1833     return gst_caps_ref (GST_PAD_TEMPLATE_CAPS (GST_PAD_PAD_TEMPLATE (pad)));
1834
1835   return NULL;
1836 }
1837
1838 /**
1839  * gst_pad_template_get_caps_by_name:
1840  * @templ: a #GstPadTemplate to get the capabilities of.
1841  * @name: the name of the capability to get.
1842  *
1843  * Gets the capability with the given name from this pad template.
1844  *
1845  * Returns: the #GstCaps, or NULL if not found or in case of an error. unref
1846  * the caps if you no longer need it.
1847  */
1848 GstCaps*
1849 gst_pad_template_get_caps_by_name (GstPadTemplate *templ, const gchar *name)
1850 {
1851   GstCaps *caps;
1852
1853   g_return_val_if_fail (templ != NULL, NULL);
1854
1855   caps = GST_PAD_TEMPLATE_CAPS (templ);
1856   if (!caps)
1857     return NULL;
1858
1859   return gst_caps_ref (gst_caps_get_by_name (caps, name));
1860 }
1861
1862 /**
1863  * gst_pad_check_compatibility:
1864  * @srcpad: the source #GstPad to check.
1865  * @sinkpad: the sink #GstPad to check against.
1866  *
1867  * Checks if two pads have compatible capabilities.
1868  *
1869  * Returns: TRUE if they are compatible or if the capabilities
1870  * could not be checked
1871  */
1872 gboolean
1873 gst_pad_check_compatibility (GstPad *srcpad, GstPad *sinkpad)
1874 {
1875   g_return_val_if_fail (srcpad != NULL, FALSE);
1876   g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
1877   g_return_val_if_fail (sinkpad != NULL, FALSE);
1878   g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
1879
1880   if (GST_PAD_CAPS (srcpad) && GST_PAD_CAPS (sinkpad)) {
1881     if (!gst_caps_is_always_compatible (GST_PAD_CAPS (srcpad),
1882                                         GST_PAD_CAPS (sinkpad))) {
1883       return FALSE;
1884     }
1885     else {
1886       return TRUE;
1887     }
1888   }
1889   else {
1890     GST_DEBUG (GST_CAT_PADS,
1891                "could not check capabilities of pads (%s:%s) and (%s:%s) %p %p",
1892                GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad),
1893                GST_PAD_CAPS (srcpad), GST_PAD_CAPS (sinkpad));
1894     return TRUE;
1895   }
1896 }
1897
1898 /**
1899  * gst_pad_get_peer:
1900  * @pad: a #GstPad to get the peer of.
1901  *
1902  * Gets the peer pad of this pad.
1903  *
1904  * Returns: the peer #GstPad.
1905  */
1906 GstPad*
1907 gst_pad_get_peer (GstPad *pad)
1908 {
1909   g_return_val_if_fail (pad != NULL, NULL);
1910   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1911
1912   return GST_PAD (GST_PAD_PEER (pad));
1913 }
1914
1915 /**
1916  * gst_pad_get_allowed_caps:
1917  * @pad: a #GstPad to get the allowed caps of.
1918  *
1919  * Gets the capabilities of the allowed media types that can
1920  * flow through this pad.  The caller must free the resulting caps.
1921  *
1922  * Returns: the allowed #GstCaps of the pad link. unref the caps if
1923  * you no longer need it.
1924  */
1925 GstCaps*
1926 gst_pad_get_allowed_caps (GstPad *pad)
1927 {
1928   GstCaps *caps;
1929
1930   g_return_val_if_fail (pad != NULL, NULL);
1931   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1932
1933   GST_DEBUG (GST_CAT_PROPERTIES, "get allowed caps of %s:%s",
1934              GST_DEBUG_PAD_NAME (pad));
1935
1936   caps = gst_caps_ref (GST_RPAD_FILTER (pad));
1937
1938   return caps;
1939 }
1940
1941 /**
1942  * gst_pad_recalc_allowed_caps:
1943  * @pad: a #GstPad to recalculate the capablities of.
1944  *
1945  * Attempts to relink the pad to its peer through its filter,
1946  * set with gst_pad_[re]link_filtered. This function is useful when a
1947  * plug-in has new capabilities on a pad and wants to notify the peer.
1948  *
1949  * Returns: TRUE on success, FALSE otherwise.
1950  */
1951 gboolean
1952 gst_pad_recalc_allowed_caps (GstPad *pad)
1953 {
1954   GstRealPad *peer;
1955
1956   g_return_val_if_fail (pad != NULL, FALSE);
1957   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
1958
1959   GST_DEBUG (GST_CAT_PROPERTIES, "set allowed caps of %s:%s",
1960              GST_DEBUG_PAD_NAME (pad));
1961
1962
1963   peer = GST_RPAD_PEER (pad);
1964   if (peer)
1965     return gst_pad_try_relink_filtered (pad, GST_PAD (peer),
1966                                         GST_RPAD_APPFILTER (pad));
1967
1968   return TRUE;
1969 }
1970
1971 /**
1972  * gst_pad_get_bufferpool:
1973  * @pad: a #GstPad to get the bufferpool from.
1974  *
1975  * Gets the bufferpool of the peer pad of the given pad.Note that
1976  * a bufferpool can only be obtained from a srcpad.
1977  *
1978  * Returns: the #GstBufferPool, or NULL in case of an error.
1979  */
1980 GstBufferPool*
1981 gst_pad_get_bufferpool (GstPad *pad)
1982 {
1983   GstRealPad *peer;
1984
1985   g_return_val_if_fail (pad != NULL, NULL);
1986   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1987   g_return_val_if_fail (GST_PAD_IS_SRC (pad), NULL);
1988
1989   peer = GST_RPAD_PEER (pad);
1990
1991   if (!peer)
1992     return NULL;
1993
1994   GST_DEBUG_ENTER ("(%s:%s)", GST_DEBUG_PAD_NAME (pad));
1995
1996   if (peer->bufferpoolfunc) {
1997     GST_DEBUG (GST_CAT_PADS,
1998                "calling bufferpoolfunc &%s (@%p) of peer pad %s:%s",
1999                GST_DEBUG_FUNCPTR_NAME (peer->bufferpoolfunc),
2000                &peer->bufferpoolfunc, GST_DEBUG_PAD_NAME (((GstPad*) peer)));
2001     return (peer->bufferpoolfunc) (((GstPad*) peer));
2002   } else {
2003     GST_DEBUG (GST_CAT_PADS, "no bufferpoolfunc for peer pad %s:%s at %p",
2004                GST_DEBUG_PAD_NAME (((GstPad*) peer)), &peer->bufferpoolfunc);
2005     return NULL;
2006   }
2007 }
2008
2009 static void
2010 gst_real_pad_dispose (GObject *object)
2011 {
2012   GstPad *pad = GST_PAD (object);
2013
2014   /* No linked pad can ever be disposed.
2015    * It has to have a parent to be linked
2016    * and a parent would hold a reference */
2017   g_assert (GST_PAD_PEER (pad) == NULL);
2018
2019   GST_DEBUG (GST_CAT_REFCOUNTING, "dispose %s:%s", GST_DEBUG_PAD_NAME(pad));
2020
2021   if (GST_PAD_PAD_TEMPLATE (pad)){
2022     GST_DEBUG (GST_CAT_REFCOUNTING, "unreffing padtemplate'%s'",
2023                GST_OBJECT_NAME (GST_PAD_PAD_TEMPLATE (pad)));
2024     gst_object_unref (GST_OBJECT (GST_PAD_PAD_TEMPLATE (pad)));
2025     GST_PAD_PAD_TEMPLATE (pad) = NULL;
2026   }
2027
2028   /* we destroy the ghostpads, because they are nothing without the real pad */
2029   if (GST_REAL_PAD (pad)->ghostpads) {
2030     GList *orig, *ghostpads;
2031
2032     orig = ghostpads = g_list_copy (GST_REAL_PAD (pad)->ghostpads);
2033
2034     while (ghostpads) {
2035       GstPad *ghostpad = GST_PAD (ghostpads->data);
2036
2037       if (GST_IS_ELEMENT (GST_OBJECT_PARENT (ghostpad))){
2038         GST_DEBUG (GST_CAT_REFCOUNTING, "removing ghost pad from element '%s'",
2039                    GST_OBJECT_NAME (GST_OBJECT_PARENT (ghostpad)));
2040
2041         gst_element_remove_ghost_pad (GST_ELEMENT (GST_OBJECT_PARENT (ghostpad)), GST_PAD (ghostpad));
2042       }
2043       ghostpads = g_list_next (ghostpads);
2044     }
2045     g_list_free (orig);
2046     g_list_free (GST_REAL_PAD(pad)->ghostpads);
2047   }
2048
2049   gst_caps_replace (&GST_PAD_CAPS (pad), NULL);
2050   gst_caps_replace (&GST_RPAD_APPFILTER (pad), NULL);
2051
2052   if (GST_IS_ELEMENT (GST_OBJECT_PARENT (pad))) {
2053     GST_DEBUG (GST_CAT_REFCOUNTING, "removing pad from element '%s'",
2054                GST_OBJECT_NAME (GST_OBJECT (GST_ELEMENT (GST_OBJECT_PARENT (pad)))));
2055
2056     gst_element_remove_pad (GST_ELEMENT (GST_OBJECT_PARENT (pad)), pad);
2057   }
2058
2059   G_OBJECT_CLASS (real_pad_parent_class)->dispose (object);
2060 }
2061
2062
2063 #ifndef GST_DISABLE_LOADSAVE
2064 /* FIXME: why isn't this on a GstElement ? */
2065 /**
2066  * gst_pad_load_and_link:
2067  * @self: an #xmlNodePtr to read the description from.
2068  * @parent: the #GstObject element that owns the pad.
2069  *
2070  * Reads the pad definition from the XML node and links the given pad
2071  * in the element to a pad of an element up in the hierarchy.
2072  */
2073 void
2074 gst_pad_load_and_link (xmlNodePtr self, GstObject *parent)
2075 {
2076   xmlNodePtr field = self->xmlChildrenNode;
2077   GstPad *pad = NULL, *targetpad;
2078   gchar *peer = NULL;
2079   gchar **split;
2080   GstElement *target;
2081   GstObject *grandparent;
2082
2083   while (field) {
2084     if (!strcmp (field->name, "name")) {
2085       pad = gst_element_get_pad (GST_ELEMENT (parent),
2086                                  xmlNodeGetContent (field));
2087     }
2088     else if (!strcmp(field->name, "peer")) {
2089       peer = xmlNodeGetContent (field);
2090     }
2091     field = field->next;
2092   }
2093   g_return_if_fail (pad != NULL);
2094
2095   if (peer == NULL) return;
2096
2097   split = g_strsplit (peer, ".", 2);
2098
2099   if (split[0] == NULL || split[1] == NULL) {
2100     GST_DEBUG (GST_CAT_XML,
2101                "Could not parse peer '%s' for pad %s:%s, leaving unlinked",
2102                peer, GST_DEBUG_PAD_NAME (pad));
2103     return;
2104   }
2105
2106   g_return_if_fail (split[0] != NULL);
2107   g_return_if_fail (split[1] != NULL);
2108
2109   grandparent = gst_object_get_parent (parent);
2110
2111   if (grandparent && GST_IS_BIN (grandparent)) {
2112     target = gst_bin_get_by_name_recurse_up (GST_BIN (grandparent), split[0]);
2113   }
2114   else
2115     goto cleanup;
2116
2117   if (target == NULL) goto cleanup;
2118
2119   targetpad = gst_element_get_pad (target, split[1]);
2120
2121   if (targetpad == NULL) goto cleanup;
2122
2123   gst_pad_link (pad, targetpad);
2124
2125 cleanup:
2126   g_strfreev (split);
2127 }
2128
2129 /**
2130  * gst_pad_save_thyself:
2131  * @pad: a #GstPad to save.
2132  * @parent: the parent #xmlNodePtr to save the description in.
2133  *
2134  * Saves the pad into an xml representation.
2135  *
2136  * Returns: the #xmlNodePtr representation of the pad.
2137  */
2138 static xmlNodePtr
2139 gst_pad_save_thyself (GstObject *object, xmlNodePtr parent)
2140 {
2141   GstRealPad *realpad;
2142   GstPad *peer;
2143
2144   g_return_val_if_fail (GST_IS_REAL_PAD (object), NULL);
2145
2146   realpad = GST_REAL_PAD (object);
2147
2148   xmlNewChild (parent, NULL, "name", GST_PAD_NAME (realpad));
2149   if (GST_RPAD_PEER (realpad) != NULL) {
2150     gchar *content;
2151
2152     peer = GST_PAD (GST_RPAD_PEER (realpad));
2153     /* first check to see if the peer's parent's parent is the same */
2154     /* we just save it off */
2155     content = g_strdup_printf ("%s.%s",
2156                                GST_OBJECT_NAME (GST_PAD_PARENT (peer)),
2157                                GST_PAD_NAME (peer));
2158     xmlNewChild (parent, NULL, "peer", content);
2159     g_free (content);
2160   } else
2161     xmlNewChild (parent, NULL, "peer", "");
2162
2163   return parent;
2164 }
2165
2166 /* FIXME: shouldn't pad and ghost be switched ?
2167  */
2168 /**
2169  * gst_ghost_pad_save_thyself:
2170  * @pad: a ghost #GstPad to save.
2171  * @parent: the parent #xmlNodePtr to save the description in.
2172  *
2173  * Saves the ghost pad into an xml representation.
2174  *
2175  * Returns: the #xmlNodePtr representation of the pad.
2176  */
2177 xmlNodePtr
2178 gst_ghost_pad_save_thyself (GstPad *pad, xmlNodePtr parent)
2179 {
2180   xmlNodePtr self;
2181
2182   g_return_val_if_fail (GST_IS_GHOST_PAD (pad), NULL);
2183
2184   self = xmlNewChild (parent, NULL, "ghostpad", NULL);
2185   xmlNewChild (self, NULL, "name", GST_PAD_NAME (pad));
2186   xmlNewChild (self, NULL, "parent", GST_OBJECT_NAME (GST_PAD_PARENT (pad)));
2187
2188   /* FIXME FIXME FIXME! */
2189
2190   return self;
2191 }
2192 #endif /* GST_DISABLE_LOADSAVE */
2193
2194 /**
2195  * gst_pad_push:
2196  * @pad: a #GstPad to push the buffer out of.
2197  * @buf: the #GstBuffer to push.
2198  *
2199  * Pushes a buffer to the peer of the pad.
2200  */
2201 void
2202 gst_pad_push (GstPad *pad, GstBuffer *buf)
2203 {
2204   GstRealPad *peer;
2205
2206   GST_DEBUG_ENTER ("(%s:%s)", GST_DEBUG_PAD_NAME (pad));
2207
2208   g_return_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SRC);
2209
2210   if (!gst_probe_dispatcher_dispatch (&(GST_REAL_PAD (pad)->probedisp), GST_DATA (buf)))
2211     return;
2212
2213   peer = GST_RPAD_PEER (pad);
2214
2215   if (!peer) {
2216     g_warning ("push on pad %s:%s but it is unlinked",
2217                GST_DEBUG_PAD_NAME (pad));
2218   }
2219   else {
2220     if (!GST_IS_EVENT (buf) && !GST_PAD_IS_ACTIVE (pad)) {
2221       g_warning ("push on pad %s:%s but it is not active",
2222                  GST_DEBUG_PAD_NAME (pad));
2223       return;
2224     }
2225
2226     if (peer->chainhandler) {
2227       if (buf) {
2228         GST_DEBUG (GST_CAT_DATAFLOW,
2229                    "calling chainhandler &%s of peer pad %s:%s",
2230                    GST_DEBUG_FUNCPTR_NAME (peer->chainhandler),
2231                    GST_DEBUG_PAD_NAME (GST_PAD (peer)));
2232         if (!gst_probe_dispatcher_dispatch (&peer->probedisp, GST_DATA (buf)))
2233           return;
2234
2235         (peer->chainhandler) (GST_PAD_CAST (peer), buf);
2236         return;
2237       }
2238       else {
2239         g_warning ("trying to push a NULL buffer on pad %s:%s",
2240                    GST_DEBUG_PAD_NAME (peer));
2241         return;
2242       }
2243     }
2244     else {
2245       g_warning ("internal error: push on pad %s:%s but it has no chainhandler",
2246                  GST_DEBUG_PAD_NAME (peer));
2247     }
2248   }
2249   /* clean up the mess here */
2250   if (buf != NULL) gst_data_unref (GST_DATA (buf));
2251 }
2252
2253 /**
2254  * gst_pad_pull:
2255  * @pad: a #GstPad to pull a buffer from.
2256  *
2257  * Pulls a buffer from the peer pad.
2258  *
2259  * Returns: a new #GstBuffer from the peer pad.
2260  */
2261 GstBuffer*
2262 gst_pad_pull (GstPad *pad)
2263 {
2264   GstRealPad *peer;
2265
2266   GST_DEBUG_ENTER("(%s:%s)",GST_DEBUG_PAD_NAME(pad));
2267
2268   g_return_val_if_fail (GST_PAD_DIRECTION (pad) == GST_PAD_SINK,
2269                         GST_BUFFER (gst_event_new (GST_EVENT_INTERRUPT)));
2270
2271   peer = GST_RPAD_PEER (pad);
2272
2273   if (!peer) {
2274     gst_element_error (GST_PAD_PARENT (pad),
2275                        "pull on pad %s:%s but it was unlinked",
2276                        GST_ELEMENT_NAME (GST_PAD_PARENT (pad)),
2277                        GST_PAD_NAME (pad), NULL);
2278   }
2279   else {
2280 restart:
2281     if (peer->gethandler) {
2282       GstBuffer *buf;
2283       gboolean active = GST_PAD_IS_ACTIVE (peer);
2284
2285       GST_DEBUG (GST_CAT_DATAFLOW, "calling gethandler %s of peer pad %s:%s",
2286                  GST_DEBUG_FUNCPTR_NAME (peer->gethandler),
2287                  GST_DEBUG_PAD_NAME (peer));
2288
2289       buf = (peer->gethandler) (GST_PAD_CAST (peer));
2290
2291       if (buf) {
2292         if (!gst_probe_dispatcher_dispatch (&peer->probedisp, GST_DATA (buf)))
2293           goto restart;
2294
2295         if (!GST_IS_EVENT (buf) && !active) {
2296           g_warning ("pull on pad %s:%s but it is not active",
2297                  GST_DEBUG_PAD_NAME (peer));
2298           return GST_BUFFER (gst_event_new (GST_EVENT_INTERRUPT));
2299         }
2300         return buf;
2301       }
2302
2303       /* no null buffers allowed */
2304       gst_element_error (GST_PAD_PARENT (pad),
2305                          "NULL buffer during pull on %s:%s",
2306                          GST_DEBUG_PAD_NAME (pad), NULL);
2307
2308     } else {
2309       gst_element_error (GST_PAD_PARENT (pad),
2310                          "internal error: pull on pad %s:%s "
2311                          "but the peer pad %s:%s has no gethandler",
2312                          GST_DEBUG_PAD_NAME (pad), GST_DEBUG_PAD_NAME (peer),
2313                          NULL);
2314     }
2315   }
2316   return GST_BUFFER (gst_event_new (GST_EVENT_INTERRUPT));
2317 }
2318
2319 /**
2320  * gst_pad_select:
2321  * @padlist: a #GList of pads.
2322  *
2323  * Waits for a buffer on any of the list of pads.
2324  *
2325  * Returns: the #GstPad that has a buffer available.
2326  * Use #gst_pad_pull() to get the buffer.
2327  */
2328 GstPad*
2329 gst_pad_select (GList *padlist)
2330 {
2331   GstPad *pad;
2332
2333   pad = gst_scheduler_pad_select (GST_PAD_PARENT (padlist->data)->sched,
2334                                   padlist);
2335   return pad;
2336 }
2337
2338 /**
2339  * gst_pad_selectv:
2340  * @pad: a first #GstPad to perform the select on.
2341  * @...: A NULL-terminated list of more pads to select on.
2342  *
2343  * Waits for a buffer on the given set of pads.
2344  *
2345  * Returns: the #GstPad that has a buffer available.
2346  * Use #gst_pad_pull() to get the buffer.
2347  */
2348 GstPad*
2349 gst_pad_selectv (GstPad *pad, ...)
2350 {
2351   GstPad *result;
2352   GList *padlist = NULL;
2353   va_list var_args;
2354
2355   if (pad == NULL)
2356     return NULL;
2357
2358   va_start (var_args, pad);
2359
2360   while (pad) {
2361     padlist = g_list_prepend (padlist, pad);
2362     pad = va_arg (var_args, GstPad *);
2363   }
2364   result = gst_pad_select (padlist);
2365   g_list_free (padlist);
2366
2367   va_end (var_args);
2368
2369   return result;
2370 }
2371
2372 /************************************************************************
2373  *
2374  * templates
2375  *
2376  */
2377 static void             gst_pad_template_class_init     (GstPadTemplateClass *klass);
2378 static void             gst_pad_template_init           (GstPadTemplate *templ);
2379 static void             gst_pad_template_dispose        (GObject *object);
2380
2381 GType
2382 gst_pad_template_get_type (void)
2383 {
2384   static GType padtemplate_type = 0;
2385
2386   if (!padtemplate_type) {
2387     static const GTypeInfo padtemplate_info = {
2388       sizeof (GstPadTemplateClass), NULL, NULL,
2389       (GClassInitFunc) gst_pad_template_class_init, NULL, NULL,
2390       sizeof (GstPadTemplate),
2391       32,
2392       (GInstanceInitFunc) gst_pad_template_init, NULL
2393     };
2394     padtemplate_type = g_type_register_static(GST_TYPE_OBJECT, "GstPadTemplate",
2395                                               &padtemplate_info, 0);
2396   }
2397   return padtemplate_type;
2398 }
2399
2400 static void
2401 gst_pad_template_class_init (GstPadTemplateClass *klass)
2402 {
2403   GObjectClass *gobject_class;
2404   GstObjectClass *gstobject_class;
2405
2406   gobject_class = (GObjectClass*) klass;
2407   gstobject_class = (GstObjectClass*) klass;
2408
2409   padtemplate_parent_class = g_type_class_ref (GST_TYPE_OBJECT);
2410
2411   gst_pad_template_signals[TEMPL_PAD_CREATED] =
2412     g_signal_new ("pad_created", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
2413                   G_STRUCT_OFFSET (GstPadTemplateClass, pad_created),
2414                   NULL, NULL, gst_marshal_VOID__POINTER, G_TYPE_NONE, 1,
2415                   G_TYPE_POINTER);
2416
2417   gobject_class->dispose = gst_pad_template_dispose;
2418
2419   gstobject_class->path_string_separator = "*";
2420 }
2421
2422 static void
2423 gst_pad_template_init (GstPadTemplate *templ)
2424 {
2425 }
2426
2427 static void
2428 gst_pad_template_dispose (GObject *object)
2429 {
2430   GstPadTemplate *templ = GST_PAD_TEMPLATE (object);
2431
2432   g_free (GST_PAD_TEMPLATE_NAME_TEMPLATE (templ));
2433   gst_caps_unref (GST_PAD_TEMPLATE_CAPS (templ));
2434
2435   G_OBJECT_CLASS (padtemplate_parent_class)->dispose (object);
2436 }
2437
2438 /* ALWAYS padtemplates cannot have conversion specifications, it doesn't make
2439  * sense.
2440  * SOMETIMES padtemplates can do whatever they want, they are provided by the
2441  * element.
2442  * REQUEST padtemplates can be reverse-parsed (the user asks for 'sink1', the
2443  * 'sink%d' template is automatically selected), so we need to restrict their
2444  * naming.
2445  */
2446 static gboolean
2447 name_is_valid (const gchar *name, GstPadPresence presence)
2448 {
2449   const gchar *str;
2450
2451   if (presence == GST_PAD_ALWAYS) {
2452     if (strchr (name, '%')) {
2453       g_warning ("invalid name template %s: conversion specifications are not"
2454                  " allowed for GST_PAD_ALWAYS padtemplates", name);
2455       return FALSE;
2456     }
2457   } else if (presence == GST_PAD_REQUEST) {
2458     if ((str = strchr (name, '%')) && strchr (str + 1, '%')) {
2459       g_warning ("invalid name template %s: only one conversion specification"
2460                  " allowed in GST_PAD_REQUEST padtemplate", name);
2461       return FALSE;
2462     }
2463     if (str && (*(str+1) != 's' && *(str+1) != 'd')) {
2464       g_warning ("invalid name template %s: conversion specification must be of"
2465                  " type '%%d' or '%%s' for GST_PAD_REQUEST padtemplate", name);
2466       return FALSE;
2467     }
2468     if (str && (*(str+2) != '\0')) {
2469       g_warning ("invalid name template %s: conversion specification must"
2470                  " appear at the end of the GST_PAD_REQUEST padtemplate name",
2471                  name);
2472       return FALSE;
2473     }
2474   }
2475
2476   return TRUE;
2477 }
2478
2479 /**
2480  * gst_pad_template_new:
2481  * @name_template: the name template.
2482  * @direction: the #GstPadDirection of the template.
2483  * @presence: the #GstPadPresence of the pad.
2484  * @caps: a #GstCaps set for the template.
2485  * @...: a NULL-terminated list of #GstCaps.
2486  *
2487  * Creates a new pad template with a name according to the given template
2488  * and with the given arguments.
2489  *
2490  * Returns: a new #GstPadTemplate.
2491  */
2492 GstPadTemplate*
2493 gst_pad_template_new (const gchar *name_template,
2494                      GstPadDirection direction, GstPadPresence presence,
2495                      GstCaps *caps, ...)
2496 {
2497   GstPadTemplate *new;
2498   va_list var_args;
2499   GstCaps *thecaps = NULL;
2500
2501   g_return_val_if_fail (name_template != NULL, NULL);
2502
2503   if (!name_is_valid (name_template, presence))
2504     return NULL;
2505
2506   new = g_object_new (gst_pad_template_get_type (),
2507                       "name", name_template,
2508                       NULL);
2509
2510   GST_PAD_TEMPLATE_NAME_TEMPLATE (new) = g_strdup (name_template);
2511   GST_PAD_TEMPLATE_DIRECTION (new) = direction;
2512   GST_PAD_TEMPLATE_PRESENCE (new) = presence;
2513
2514   va_start (var_args, caps);
2515
2516   GST_FLAG_SET (GST_OBJECT (new), GST_PAD_TEMPLATE_FIXED);
2517   while (caps) {
2518     if (!GST_CAPS_IS_FIXED (caps)) {
2519       GST_FLAG_UNSET (GST_OBJECT (new), GST_PAD_TEMPLATE_FIXED);
2520     }
2521     thecaps = gst_caps_append (thecaps, caps);
2522     caps = va_arg (var_args, GstCaps*);
2523   }
2524   va_end (var_args);
2525
2526   GST_PAD_TEMPLATE_CAPS (new) = thecaps;
2527   gst_caps_ref (thecaps);
2528   gst_caps_sink (thecaps);
2529
2530   return new;
2531 }
2532
2533 /**
2534  * gst_pad_template_get_caps:
2535  * @templ: a #GstPadTemplate to get capabilities of.
2536  *
2537  * Gets the capabilities of the pad template.
2538  *
2539  * Returns: the #GstCaps of the pad template. unref the caps
2540  * after use.
2541  */
2542 GstCaps*
2543 gst_pad_template_get_caps (GstPadTemplate *templ)
2544 {
2545   g_return_val_if_fail (templ != NULL, NULL);
2546
2547   return gst_caps_ref (GST_PAD_TEMPLATE_CAPS (templ));
2548 }
2549
2550 /**
2551  * gst_pad_set_element_private:
2552  * @pad: the #GstPad to set the private data of.
2553  * @priv: The private data to attach to the pad.
2554  *
2555  * Set the given private data gpointer on the pad.
2556  * This function can only be used by the element that owns the pad.
2557  */
2558 void
2559 gst_pad_set_element_private (GstPad *pad, gpointer priv)
2560 {
2561   pad->element_private = priv;
2562 }
2563
2564 /**
2565  * gst_pad_get_element_private:
2566  * @pad: the #GstPad to get the private data of.
2567  *
2568  * Gets the private data of a pad.
2569  *
2570  * Returns: a #gpointer to the private data.
2571  */
2572 gpointer
2573 gst_pad_get_element_private (GstPad *pad)
2574 {
2575   return pad->element_private;
2576 }
2577
2578
2579 /***** ghost pads *****/
2580 GType _gst_ghost_pad_type = 0;
2581
2582 static void     gst_ghost_pad_class_init         (GstGhostPadClass *klass);
2583 static void     gst_ghost_pad_init               (GstGhostPad *pad);
2584
2585 static GstPad *ghost_pad_parent_class = NULL;
2586 /* static guint gst_ghost_pad_signals[LAST_SIGNAL] = { 0 }; */
2587
2588 GType
2589 gst_ghost_pad_get_type (void)
2590 {
2591   if (!_gst_ghost_pad_type) {
2592     static const GTypeInfo pad_info = {
2593       sizeof (GstGhostPadClass), NULL, NULL,
2594       (GClassInitFunc) gst_ghost_pad_class_init, NULL, NULL,
2595       sizeof (GstGhostPad),
2596       8,
2597       (GInstanceInitFunc) gst_ghost_pad_init,
2598       NULL
2599     };
2600     _gst_ghost_pad_type = g_type_register_static (GST_TYPE_PAD, "GstGhostPad",
2601                                                   &pad_info, 0);
2602   }
2603   return _gst_ghost_pad_type;
2604 }
2605
2606 static void
2607 gst_ghost_pad_class_init (GstGhostPadClass *klass)
2608 {
2609   GObjectClass *gobject_class;
2610
2611   gobject_class = (GObjectClass*) klass;
2612
2613   ghost_pad_parent_class = g_type_class_ref (GST_TYPE_PAD);
2614 }
2615
2616 static void
2617 gst_ghost_pad_init (GstGhostPad *pad)
2618 {
2619   pad->realpad = NULL;
2620 }
2621
2622 /**
2623  * gst_ghost_pad_new:
2624  * @name: the name of the new ghost pad.
2625  * @pad: the #GstPad to create a ghost pad for.
2626  *
2627  * Creates a new ghost pad associated with the given pad, and names it with
2628  * the given name.  If name is NULL, a guaranteed unique name (across all
2629  * ghost pads) will be assigned (most likely of the form ghostpad&perc;d).
2630  *
2631  * Returns: a new ghost #GstPad, or NULL in case of an error.
2632  */
2633
2634 GstPad*
2635 gst_ghost_pad_new (const gchar *name,
2636                    GstPad *pad)
2637 {
2638   GstGhostPad *ghostpad;
2639   GstRealPad *realpad;
2640
2641   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2642
2643   ghostpad = g_object_new (gst_ghost_pad_get_type () ,NULL);
2644   gst_pad_set_name (GST_PAD (ghostpad), name);
2645
2646   realpad = (GstRealPad *) pad;
2647
2648   while (!GST_IS_REAL_PAD (realpad)) {
2649     realpad = GST_PAD_REALIZE (realpad);
2650   }
2651   GST_GPAD_REALPAD (ghostpad) = realpad;
2652   GST_PAD_PAD_TEMPLATE (ghostpad) = GST_PAD_PAD_TEMPLATE (pad);
2653
2654   /* add ourselves to the real pad's list of ghostpads */
2655   gst_pad_add_ghost_pad (pad, GST_PAD (ghostpad));
2656
2657   /* FIXME need to ref the real pad here... ? */
2658
2659   GST_DEBUG (GST_CAT_PADS, "created ghost pad \"%s\"",
2660              gst_pad_get_name (GST_PAD (ghostpad)));
2661
2662   return GST_PAD (ghostpad);
2663 }
2664
2665 /**
2666  * gst_pad_get_internal_links_default:
2667  * @pad: the #GstPad to get the internal links of.
2668  *
2669  * Gets a list of pads to which the given pad is linked to
2670  * inside of the parent element.
2671  * This is the default handler, and thus returns a list of all of the
2672  * pads inside the parent element with opposite direction.
2673  * The caller must free this list after use.
2674  *
2675  * Returns: a newly allocated #GList of pads.
2676  */
2677 GList*
2678 gst_pad_get_internal_links_default (GstPad *pad)
2679 {
2680   GList *res = NULL;
2681   GstElement *parent;
2682   GList *parent_pads;
2683   GstPadDirection direction;
2684   GstRealPad *rpad;
2685
2686   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2687
2688   rpad = GST_PAD_REALIZE (pad);
2689   direction = rpad->direction;
2690
2691   parent = GST_PAD_PARENT (rpad);
2692   parent_pads = parent->pads;
2693
2694   while (parent_pads) {
2695     GstRealPad *parent_pad = GST_PAD_REALIZE (parent_pads->data);
2696
2697     if (parent_pad->direction != direction) {
2698       res = g_list_prepend (res, parent_pad);
2699     }
2700
2701     parent_pads = g_list_next (parent_pads);
2702   }
2703
2704   return res;
2705 }
2706
2707 /**
2708  * gst_pad_get_internal_links:
2709  * @pad: the #GstPad to get the internal links of.
2710  *
2711  * Gets a list of pads to which the given pad is linked to
2712  * inside of the parent element.
2713  * The caller must free this list after use.
2714  *
2715  * Returns: a newly allocated #GList of pads.
2716  */
2717 GList*
2718 gst_pad_get_internal_links (GstPad *pad)
2719 {
2720   GList *res = NULL;
2721   GstRealPad *rpad;
2722
2723   g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2724
2725   rpad = GST_PAD_REALIZE (pad);
2726
2727   if (GST_RPAD_INTLINKFUNC (rpad))
2728     res = GST_RPAD_INTLINKFUNC (rpad) (GST_PAD_CAST (rpad));
2729
2730   return res;
2731 }
2732
2733
2734 static gboolean
2735 gst_pad_event_default_dispatch (GstPad *pad, GstElement *element,
2736                                 GstEvent *event)
2737 {
2738   GList *pads = element->pads;
2739
2740   while (pads) {
2741     GstPad *eventpad = GST_PAD (pads->data);
2742     pads = g_list_next (pads);
2743
2744     /* for all pads in the opposite direction that are linked */
2745     if (GST_PAD_DIRECTION (eventpad) != GST_PAD_DIRECTION (pad)
2746      && GST_PAD_IS_LINKED (eventpad)) {
2747       if (GST_PAD_DIRECTION (eventpad) == GST_PAD_SRC) {
2748         /* increase the refcount */
2749         gst_event_ref (event);
2750         gst_pad_push (eventpad, GST_BUFFER (event));
2751       }
2752       else {
2753         GstPad *peerpad = GST_PAD_CAST (GST_RPAD_PEER (eventpad));
2754
2755         /* we only send the event on one pad, multi-sinkpad elements
2756          * should implement a handler */
2757         return gst_pad_send_event (peerpad, event);
2758       }
2759     }
2760   }
2761   gst_event_unref (event);
2762   return TRUE;
2763 }
2764
2765 /**
2766  * gst_pad_event_default:
2767  * @pad: a #GstPad to call the default event handler on.
2768  * @event: the #GstEvent to handle.
2769  *
2770  * Invokes the default event handler for the given pad.
2771  *
2772  * Returns: TRUE if the event was sent succesfully.
2773  */
2774 gboolean
2775 gst_pad_event_default (GstPad *pad, GstEvent *event)
2776 {
2777   GstElement *element;
2778
2779   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2780   g_return_val_if_fail (event, FALSE);
2781
2782   element = GST_PAD_PARENT (pad);
2783
2784   switch (GST_EVENT_TYPE (event)) {
2785     case GST_EVENT_EOS:
2786       gst_pad_event_default_dispatch (pad, element, event);
2787       gst_element_set_eos (element);
2788       break;
2789     case GST_EVENT_DISCONTINUOUS:
2790     {
2791       guint64 time;
2792
2793       if (gst_event_discont_get_value (event, GST_FORMAT_TIME, &time)) {
2794         if (gst_element_requires_clock (element) && element->clock) {
2795           gst_clock_handle_discont (element->clock, time);
2796         }
2797       }
2798     }
2799     case GST_EVENT_FLUSH:
2800     default:
2801       return gst_pad_event_default_dispatch (pad, element, event);
2802   }
2803   return TRUE;
2804 }
2805
2806 /**
2807  * gst_pad_dispatcher:
2808  * @pad: a #GstPad to dispatch.
2809  * @dispatch: the #GstDispatcherFunction to call.
2810  * @data: gpointer user data passed to the dispatcher function.
2811  *
2812  * Invokes the given dispatcher function on all pads that are
2813  * internally linked to the given pad.
2814  * The GstPadDispatcherFunction should return TRUE when no further pads
2815  * need to be processed.
2816  *
2817  * Returns: TRUE if one of the dispatcher functions returned TRUE.
2818  */
2819 gboolean
2820 gst_pad_dispatcher (GstPad *pad, GstPadDispatcherFunction dispatch,
2821                     gpointer data)
2822 {
2823   gboolean res = FALSE;
2824   GList *int_pads, *orig;
2825
2826   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2827   g_return_val_if_fail (data, FALSE);
2828
2829   orig = int_pads = gst_pad_get_internal_links (pad);
2830
2831   while (int_pads) {
2832     GstRealPad *int_rpad = GST_PAD_REALIZE (int_pads->data);
2833     GstRealPad *int_peer = GST_RPAD_PEER (int_rpad);
2834
2835     if (int_peer) {
2836       res = dispatch (GST_PAD_CAST (int_peer), data);
2837       if (res)
2838         break;
2839     }
2840     int_pads = g_list_next (int_pads);
2841   }
2842
2843   g_list_free (orig);
2844
2845   return res;
2846 }
2847
2848 /**
2849  * gst_pad_send_event:
2850  * @pad: a #GstPad to send the event to.
2851  * @event: the #GstEvent to send to the pad.
2852  *
2853  * Sends the event to the pad.
2854  *
2855  * Returns: TRUE if the event was handled.
2856  */
2857 gboolean
2858 gst_pad_send_event (GstPad *pad, GstEvent *event)
2859 {
2860   gboolean success = FALSE;
2861   GstRealPad *rpad;
2862
2863   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2864   g_return_val_if_fail (event, FALSE);
2865
2866   rpad = GST_PAD_REALIZE (pad);
2867
2868   if (GST_EVENT_SRC (event) == NULL)
2869     GST_EVENT_SRC (event) = gst_object_ref (GST_OBJECT (rpad));
2870
2871   GST_DEBUG (GST_CAT_EVENT, "have event %d on pad %s:%s",
2872                   GST_EVENT_TYPE (event), GST_DEBUG_PAD_NAME (rpad));
2873
2874   if (GST_RPAD_EVENTFUNC (rpad))
2875     success = GST_RPAD_EVENTFUNC (rpad) (GST_PAD_CAST (rpad), event);
2876   else {
2877     GST_DEBUG (GST_CAT_EVENT, "there's no event function for pad %s:%s",
2878                GST_DEBUG_PAD_NAME (rpad));
2879     gst_event_unref (event);
2880   }
2881
2882   return success;
2883 }
2884
2885 typedef struct
2886 {
2887   GstFormat      src_format;
2888   gint64         src_value;
2889   GstFormat      *dest_format;
2890   gint64         *dest_value;
2891 } GstPadConvertData;
2892
2893 static gboolean
2894 gst_pad_convert_dispatcher (GstPad *pad, GstPadConvertData *data)
2895 {
2896   return gst_pad_convert (pad, data->src_format, data->src_value,
2897                                data->dest_format, data->dest_value);
2898 }
2899
2900 /**
2901  * gst_pad_convert_default:
2902  * @pad: a #GstPad to invoke the default converter on.
2903  * @src_format: the source #GstFormat.
2904  * @src_value: the source value.
2905  * @dest_format: a pointer to the destination #GstFormat.
2906  * @dest_value: a pointer to the destination value.
2907  *
2908  * Invokes the default converter on a pad.
2909  * This will forward the call to the pad obtained
2910  * using the internal link of
2911  * the element.
2912  *
2913  * Returns: TRUE if the conversion could be performed.
2914  */
2915 gboolean
2916 gst_pad_convert_default (GstPad *pad,
2917                          GstFormat src_format,  gint64  src_value,
2918                          GstFormat *dest_format, gint64 *dest_value)
2919 {
2920   GstPadConvertData data;
2921
2922   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2923   g_return_val_if_fail (dest_format, FALSE);
2924   g_return_val_if_fail (dest_value, FALSE);
2925
2926   data.src_format = src_format;
2927   data.src_value = src_value;
2928   data.dest_format = dest_format;
2929   data.dest_value = dest_value;
2930
2931   return gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
2932                                     gst_pad_convert_dispatcher, &data);
2933 }
2934
2935 /**
2936  * gst_pad_convert:
2937  * @pad: a #GstPad to invoke the default converter on.
2938  * @src_format: the source #GstFormat.
2939  * @src_value: the source value.
2940  * @dest_format: a pointer to the destination #GstFormat.
2941  * @dest_value: a pointer to the destination value.
2942  *
2943  * Invokes a conversion on the pad.
2944  *
2945  * Returns: TRUE if the conversion could be performed.
2946  */
2947 gboolean
2948 gst_pad_convert (GstPad *pad,
2949                  GstFormat src_format,  gint64  src_value,
2950                  GstFormat *dest_format, gint64 *dest_value)
2951 {
2952   GstRealPad *rpad;
2953
2954   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2955   g_return_val_if_fail (dest_format, FALSE);
2956   g_return_val_if_fail (dest_value, FALSE);
2957
2958   if (src_format == *dest_format) {
2959     *dest_value = src_value;
2960     return TRUE;
2961   }
2962
2963   rpad = GST_PAD_REALIZE (pad);
2964
2965   if (GST_RPAD_CONVERTFUNC (rpad)) {
2966     return GST_RPAD_CONVERTFUNC (rpad) (GST_PAD_CAST (rpad), src_format,
2967                                         src_value, dest_format, dest_value);
2968   }
2969
2970   return FALSE;
2971 }
2972
2973 typedef struct
2974 {
2975   GstQueryType    type;
2976   GstFormat      *format;
2977   gint64         *value;
2978 } GstPadQueryData;
2979
2980 static gboolean
2981 gst_pad_query_dispatcher (GstPad *pad, GstPadQueryData *data)
2982 {
2983   return gst_pad_query (pad, data->type, data->format, data->value);
2984 }
2985
2986 /**
2987  * gst_pad_query_default:
2988  * @pad: a #GstPad to invoke the default query on.
2989  * @type: the #GstQueryType of the query to perform.
2990  * @format: a pointer to the #GstFormat of the result.
2991  * @value: a pointer to the result.
2992  *
2993  * Invokes the default query function on a pad.
2994  *
2995  * Returns: TRUE if the query could be performed.
2996  */
2997 gboolean
2998 gst_pad_query_default (GstPad *pad, GstQueryType type,
2999                        GstFormat *format,  gint64 *value)
3000 {
3001   GstPadQueryData data;
3002
3003   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3004   g_return_val_if_fail (format, FALSE);
3005   g_return_val_if_fail (value, FALSE);
3006
3007   data.type = type;
3008   data.format = format;
3009   data.value = value;
3010
3011   return gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
3012                                    gst_pad_query_dispatcher, &data);
3013 }
3014
3015 /**
3016  * gst_pad_query:
3017  * @pad: a #GstPad to invoke the default query on.
3018  * @type: the #GstQueryType of the query to perform.
3019  * @format: a pointer to the #GstFormat of the result.
3020  * @value: a pointer to the result.
3021  *
3022  * Queries a pad for one of the available properties.
3023  *
3024  * Returns: TRUE if the query could be performed.
3025  */
3026 gboolean
3027 gst_pad_query (GstPad *pad, GstQueryType type,
3028                GstFormat *format, gint64 *value)
3029 {
3030   GstRealPad *rpad;
3031
3032   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3033   g_return_val_if_fail (format, FALSE);
3034   g_return_val_if_fail (value, FALSE);
3035
3036   rpad = GST_PAD_REALIZE (pad);
3037
3038   g_return_val_if_fail (rpad, FALSE);
3039
3040   if (GST_RPAD_QUERYFUNC (rpad))
3041     return GST_RPAD_QUERYFUNC (rpad) (GST_PAD_CAST (pad), type, format, value);
3042
3043   return FALSE;
3044 }
3045
3046 static gboolean
3047 gst_pad_get_formats_dispatcher (GstPad *pad, const GstFormat **data)
3048 {
3049   *data = gst_pad_get_formats (pad);
3050
3051   return TRUE;
3052 }
3053
3054 /**
3055  * gst_pad_get_formats_default:
3056  * @pad: a #GstPad to query
3057  *
3058  * Invoke the default format dispatcher for the pad.
3059  *
3060  * Returns: An array of GstFormats ended with a 0 value.
3061  */
3062 const GstFormat*
3063 gst_pad_get_formats_default (GstPad *pad)
3064 {
3065   GstFormat *result = NULL;
3066
3067   gst_pad_dispatcher (pad, (GstPadDispatcherFunction)
3068                       gst_pad_get_formats_dispatcher, &result);
3069
3070   return result;
3071 }
3072
3073 /**
3074  * gst_pad_get_formats:
3075  * @pad: a #GstPad to query
3076  *
3077  * Gets the list of supported formats from the pad.
3078  *
3079  * Returns: An array of GstFormats ended with a 0 value.
3080  */
3081 const GstFormat*
3082 gst_pad_get_formats (GstPad *pad)
3083 {
3084   GstRealPad *rpad;
3085
3086   g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
3087
3088   rpad = GST_PAD_REALIZE (pad);
3089
3090   if (GST_RPAD_FORMATSFUNC (rpad))
3091     return GST_RPAD_FORMATSFUNC (rpad) (GST_PAD_CAST (pad));
3092
3093   return NULL;
3094 }
3095