subprojects/gstreamer/gst/gstpadtemplate.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *
   5  * gstpadtemplate.c: Templates for pad creation
   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., 51 Franklin St, Fifth Floor,
  20  * Boston, MA 02110-1301, USA.
  21  */
  22
  23 /**
  24  * SECTION:gstpadtemplate
  25  * @title: GstPadTemplate
  26  * @short_description: Describe the media type of a pad.
  27  * @see_also: #GstPad, #GstElementFactory
  28  *
  29  * Padtemplates describe the possible media types a pad or an elementfactory can
  30  * handle. This allows for both inspection of handled types before loading the
  31  * element plugin as well as identifying pads on elements that are not yet
  32  * created (request or sometimes pads).
  33  *
  34  * Pad and PadTemplates have #GstCaps attached to it to describe the media type
  35  * they are capable of dealing with. gst_pad_template_get_caps() or
  36  * GST_PAD_TEMPLATE_CAPS() are used to get the caps of a padtemplate. It's not
  37  * possible to modify the caps of a padtemplate after creation.
  38  *
  39  * PadTemplates have a #GstPadPresence property which identifies the lifetime
  40  * of the pad and that can be retrieved with GST_PAD_TEMPLATE_PRESENCE(). Also
  41  * the direction of the pad can be retrieved from the #GstPadTemplate with
  42  * GST_PAD_TEMPLATE_DIRECTION().
  43  *
  44  * The GST_PAD_TEMPLATE_NAME_TEMPLATE () is important for GST_PAD_REQUEST pads
  45  * because it has to be used as the name in the gst_element_request_pad_simple()
  46  * call to instantiate a pad from this template.
  47  *
  48  * Padtemplates can be created with gst_pad_template_new() or with
  49  * gst_static_pad_template_get (), which creates a #GstPadTemplate from a
  50  * #GstStaticPadTemplate that can be filled with the
  51  * convenient GST_STATIC_PAD_TEMPLATE() macro.
  52  *
  53  * A padtemplate can be used to create a pad (see gst_pad_new_from_template()
  54  * or gst_pad_new_from_static_template ()) or to add to an element class
  55  * (see gst_element_class_add_static_pad_template ()).
  56  *
  57  * The following code example shows the code to create a pad from a padtemplate.
  58  * |[<!-- language="C" -->
  59  *   GstStaticPadTemplate my_template =
  60  *   GST_STATIC_PAD_TEMPLATE (
  61  *     "sink",          // the name of the pad
  62  *     GST_PAD_SINK,    // the direction of the pad
  63  *     GST_PAD_ALWAYS,  // when this pad will be present
  64  *     GST_STATIC_CAPS (        // the capabilities of the padtemplate
  65  *       "audio/x-raw, "
  66  *         "channels = (int) [ 1, 6 ]"
  67  *     )
  68  *   );
  69  *   void
  70  *   my_method (void)
  71  *   {
  72  *     GstPad *pad;
  73  *     pad = gst_pad_new_from_static_template (&my_template, "sink");
  74  *     ...
  75  *   }
  76  * ]|
  77  *
  78  * The following example shows you how to add the padtemplate to an
  79  * element class, this is usually done in the class_init of the class:
  80  * |[<!-- language="C" -->
  81  *   static void
  82  *   my_element_class_init (GstMyElementClass *klass)
  83  *   {
  84  *     GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);
  85  *
  86  *     gst_element_class_add_static_pad_template (gstelement_class, &my_template);
  87  *   }
  88  * ]|
  89  */
  90
  91 #include "gst_private.h"
  92
  93 #include "gstpad.h"
  94 #include "gstpadtemplate.h"
  95 #include "gstenumtypes.h"
  96 #include "gstutils.h"
  97 #include "gstinfo.h"
  98 #include "gsterror.h"
  99 #include "gstvalue.h"
 100
 101 #define GST_CAT_DEFAULT GST_CAT_PADS
 102
 103 enum
 104 {
 105   PROP_NAME_TEMPLATE = 1,
 106   PROP_DIRECTION,
 107   PROP_PRESENCE,
 108   PROP_CAPS,
 109   PROP_GTYPE,
 110 };
 111
 112 enum
 113 {
 114   TEMPL_PAD_CREATED,
 115   /* FILL ME */
 116   LAST_SIGNAL
 117 };
 118
 119 static guint gst_pad_template_signals[LAST_SIGNAL] = { 0 };
 120
 121 static void gst_pad_template_dispose (GObject * object);
 122 static void gst_pad_template_set_property (GObject * object, guint prop_id,
 123     const GValue * value, GParamSpec * pspec);
 124 static void gst_pad_template_get_property (GObject * object, guint prop_id,
 125     GValue * value, GParamSpec * pspec);
 126
 127 #define gst_pad_template_parent_class parent_class
 128 G_DEFINE_TYPE (GstPadTemplate, gst_pad_template, GST_TYPE_OBJECT);
 129
 130 static void
 131 gst_pad_template_class_init (GstPadTemplateClass * klass)
 132 {
 133   GObjectClass *gobject_class;
 134   GstObjectClass *gstobject_class;
 135
 136   gobject_class = (GObjectClass *) klass;
 137   gstobject_class = (GstObjectClass *) klass;
 138
 139   /**
 140    * GstPadTemplate::pad-created:
 141    * @pad_template: the object which received the signal.
 142    * @pad: the pad that was created.
 143    *
 144    * This signal is fired when an element creates a pad from this template.
 145    */
 146   gst_pad_template_signals[TEMPL_PAD_CREATED] =
 147       g_signal_new ("pad-created", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 148       G_STRUCT_OFFSET (GstPadTemplateClass, pad_created),
 149       NULL, NULL, NULL, G_TYPE_NONE, 1, GST_TYPE_PAD);
 150
 151   gobject_class->dispose = gst_pad_template_dispose;
 152
 153   gobject_class->get_property = gst_pad_template_get_property;
 154   gobject_class->set_property = gst_pad_template_set_property;
 155
 156   /**
 157    * GstPadTemplate:name-template:
 158    *
 159    * The name template of the pad template.
 160    */
 161   g_object_class_install_property (gobject_class, PROP_NAME_TEMPLATE,
 162       g_param_spec_string ("name-template", "Name template",
 163           "The name template of the pad template", NULL,
 164           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 165
 166   /**
 167    * GstPadTemplate:direction:
 168    *
 169    * The direction of the pad described by the pad template.
 170    */
 171   g_object_class_install_property (gobject_class, PROP_DIRECTION,
 172       g_param_spec_enum ("direction", "Direction",
 173           "The direction of the pad described by the pad template",
 174           GST_TYPE_PAD_DIRECTION, GST_PAD_UNKNOWN,
 175           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 176
 177   /**
 178    * GstPadTemplate:presence:
 179    *
 180    * When the pad described by the pad template will become available.
 181    */
 182   g_object_class_install_property (gobject_class, PROP_PRESENCE,
 183       g_param_spec_enum ("presence", "Presence",
 184           "When the pad described by the pad template will become available",
 185           GST_TYPE_PAD_PRESENCE, GST_PAD_ALWAYS,
 186           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 187
 188   /**
 189    * GstPadTemplate:caps:
 190    *
 191    * The capabilities of the pad described by the pad template.
 192    */
 193   g_object_class_install_property (gobject_class, PROP_CAPS,
 194       g_param_spec_boxed ("caps", "Caps",
 195           "The capabilities of the pad described by the pad template",
 196           GST_TYPE_CAPS,
 197           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 198
 199   /**
 200    * GstPadTemplate:gtype:
 201    *
 202    * The type of the pad described by the pad template.
 203    *
 204    * Since: 1.14
 205    */
 206   g_object_class_install_property (gobject_class, PROP_GTYPE,
 207       g_param_spec_gtype ("gtype", "GType",
 208           "The GType of the pad described by the pad template",
 209           G_TYPE_NONE,
 210           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 211
 212   gstobject_class->path_string_separator = "*";
 213 }
 214
 215 static void
 216 gst_pad_template_init (GstPadTemplate * templ)
 217 {
 218   /* GstPadTemplate objects are usually leaked */
 219   GST_OBJECT_FLAG_SET (templ, GST_OBJECT_FLAG_MAY_BE_LEAKED);
 220   GST_PAD_TEMPLATE_GTYPE (templ) = G_TYPE_NONE;
 221 }
 222
 223 static void
 224 gst_pad_template_dispose (GObject * object)
 225 {
 226   GstPadTemplate *templ = GST_PAD_TEMPLATE (object);
 227
 228   g_free (GST_PAD_TEMPLATE_NAME_TEMPLATE (templ));
 229   if (GST_PAD_TEMPLATE_CAPS (templ)) {
 230     gst_caps_unref (GST_PAD_TEMPLATE_CAPS (templ));
 231   }
 232
 233   gst_caps_replace (&templ->ABI.abi.documentation_caps, NULL);
 234
 235   G_OBJECT_CLASS (parent_class)->dispose (object);
 236 }
 237
 238 /* ALWAYS padtemplates cannot have conversion specifications (like src_%d),
 239  * since it doesn't make sense.
 240  * SOMETIMES padtemplates can do whatever they want, they are provided by the
 241  * element.
 242  * REQUEST padtemplates can have multiple specifiers in case of %d and %u, like
 243  * src_%u_%u, but %s only can be used once in the template.
 244  */
 245 static gboolean
 246 name_is_valid (const gchar * name, GstPadPresence presence)
 247 {
 248   const gchar *str, *underscore = NULL;
 249   gboolean has_s = FALSE;
 250
 251   if (presence == GST_PAD_ALWAYS) {
 252     if (strchr (name, '%')) {
 253       g_warning ("invalid name template %s: conversion specifications are not"
 254           " allowed for GST_PAD_ALWAYS padtemplates", name);
 255       return FALSE;
 256     }
 257   } else if (presence == GST_PAD_REQUEST) {
 258     str = strchr (name, '%');
 259
 260     while (str) {
 261       if (*(str + 1) != 's' && *(str + 1) != 'd' && *(str + 1) != 'u') {
 262         g_warning
 263             ("invalid name template %s: conversion specification must be of"
 264             " type '%%d', '%%u' or '%%s' for GST_PAD_REQUEST padtemplate",
 265             name);
 266         return FALSE;
 267       }
 268
 269       if (*(str + 1) == 's' && (*(str + 2) != '\0' || has_s)) {
 270         g_warning
 271             ("invalid name template %s: conversion specification of type '%%s'"
 272             "only can be used once in the GST_PAD_REQUEST padtemplate at the "
 273             "very end and not allowed any other characters with '%%s'", name);
 274         return FALSE;
 275       }
 276
 277       if (*(str + 1) == 's') {
 278         has_s = TRUE;
 279       }
 280
 281       underscore = strchr (str, '_');
 282       str = strchr (str + 1, '%');
 283
 284       if (str && (!underscore || str < underscore)) {
 285         g_warning
 286             ("invalid name template %s: each of conversion specifications "
 287             "must be separated by an underscore", name);
 288         return FALSE;
 289       }
 290     }
 291   }
 292
 293   return TRUE;
 294 }
 295
 296 G_DEFINE_POINTER_TYPE (GstStaticPadTemplate, gst_static_pad_template);
 297
 298 /**
 299  * gst_static_pad_template_get:
 300  * @pad_template: the static pad template
 301  *
 302  * Converts a #GstStaticPadTemplate into a #GstPadTemplate.
 303  *
 304  * Returns: (transfer floating) (nullable): a new #GstPadTemplate.
 305  */
 306 /* FIXME0.11: rename to gst_pad_template_new_from_static_pad_template() */
 307 GstPadTemplate *
 308 gst_static_pad_template_get (GstStaticPadTemplate * pad_template)
 309 {
 310   GstPadTemplate *new;
 311   GstCaps *caps;
 312
 313   if (!name_is_valid (pad_template->name_template, pad_template->presence))
 314     return NULL;
 315
 316   caps = gst_static_caps_get (&pad_template->static_caps);
 317
 318   new = g_object_new (gst_pad_template_get_type (),
 319       "name", pad_template->name_template,
 320       "name-template", pad_template->name_template,
 321       "direction", pad_template->direction,
 322       "presence", pad_template->presence, "caps", caps, NULL);
 323
 324   gst_caps_unref (caps);
 325
 326   return new;
 327 }
 328
 329 /**
 330  * gst_pad_template_new_from_static_pad_template_with_gtype:
 331  * @pad_template: the static pad template
 332  * @pad_type: The #GType of the pad to create
 333  *
 334  * Converts a #GstStaticPadTemplate into a #GstPadTemplate with a type.
 335  *
 336  * Returns: (transfer floating) (nullable): a new #GstPadTemplate.
 337  *
 338  * Since: 1.14
 339  */
 340 GstPadTemplate *
 341 gst_pad_template_new_from_static_pad_template_with_gtype (GstStaticPadTemplate *
 342     pad_template, GType pad_type)
 343 {
 344   GstPadTemplate *new;
 345   GstCaps *caps;
 346
 347   g_return_val_if_fail (g_type_is_a (pad_type, GST_TYPE_PAD), NULL);
 348
 349   if (!name_is_valid (pad_template->name_template, pad_template->presence))
 350     return NULL;
 351
 352   caps = gst_static_caps_get (&pad_template->static_caps);
 353
 354   new = g_object_new (gst_pad_template_get_type (),
 355       "name", pad_template->name_template,
 356       "name-template", pad_template->name_template,
 357       "direction", pad_template->direction,
 358       "presence", pad_template->presence, "caps", caps, "gtype", pad_type,
 359       NULL);
 360
 361   gst_caps_unref (caps);
 362
 363   return new;
 364 }
 365
 366 /**
 367  * gst_pad_template_new:
 368  * @name_template: the name template.
 369  * @direction: the #GstPadDirection of the template.
 370  * @presence: the #GstPadPresence of the pad.
 371  * @caps: (transfer none): a #GstCaps set for the template.
 372  *
 373  * Creates a new pad template with a name according to the given template
 374  * and with the given arguments.
 375  *
 376  * Returns: (transfer floating) (nullable): a new #GstPadTemplate.
 377  */
 378 GstPadTemplate *
 379 gst_pad_template_new (const gchar * name_template,
 380     GstPadDirection direction, GstPadPresence presence, GstCaps * caps)
 381 {
 382   GstPadTemplate *new;
 383
 384   g_return_val_if_fail (name_template != NULL, NULL);
 385   g_return_val_if_fail (caps != NULL, NULL);
 386   g_return_val_if_fail (direction == GST_PAD_SRC
 387       || direction == GST_PAD_SINK, NULL);
 388   g_return_val_if_fail (presence == GST_PAD_ALWAYS
 389       || presence == GST_PAD_SOMETIMES || presence == GST_PAD_REQUEST, NULL);
 390
 391   if (!name_is_valid (name_template, presence)) {
 392     return NULL;
 393   }
 394
 395   new = g_object_new (gst_pad_template_get_type (),
 396       "name", name_template, "name-template", name_template,
 397       "direction", direction, "presence", presence, "caps", caps, NULL);
 398
 399   return new;
 400 }
 401
 402 /**
 403  * gst_pad_template_new_with_gtype:
 404  * @name_template: the name template.
 405  * @direction: the #GstPadDirection of the template.
 406  * @presence: the #GstPadPresence of the pad.
 407  * @caps: (transfer none): a #GstCaps set for the template.
 408  * @pad_type: The #GType of the pad to create
 409  *
 410  * Creates a new pad template with a name according to the given template
 411  * and with the given arguments.
 412  *
 413  * Returns: (transfer floating) (nullable): a new #GstPadTemplate.
 414  *
 415  * Since: 1.14
 416  */
 417 GstPadTemplate *
 418 gst_pad_template_new_with_gtype (const gchar * name_template,
 419     GstPadDirection direction, GstPadPresence presence, GstCaps * caps,
 420     GType pad_type)
 421 {
 422   GstPadTemplate *new;
 423
 424   g_return_val_if_fail (name_template != NULL, NULL);
 425   g_return_val_if_fail (caps != NULL, NULL);
 426   g_return_val_if_fail (direction == GST_PAD_SRC
 427       || direction == GST_PAD_SINK, NULL);
 428   g_return_val_if_fail (presence == GST_PAD_ALWAYS
 429       || presence == GST_PAD_SOMETIMES || presence == GST_PAD_REQUEST, NULL);
 430   g_return_val_if_fail (g_type_is_a (pad_type, GST_TYPE_PAD), NULL);
 431
 432   if (!name_is_valid (name_template, presence)) {
 433     return NULL;
 434   }
 435
 436   new = g_object_new (gst_pad_template_get_type (),
 437       "name", name_template, "name-template", name_template,
 438       "direction", direction, "presence", presence, "caps", caps,
 439       "gtype", pad_type, NULL);
 440
 441   return new;
 442 }
 443
 444 /**
 445  * gst_static_pad_template_get_caps:
 446  * @templ: a #GstStaticPadTemplate to get capabilities of.
 447  *
 448  * Gets the capabilities of the static pad template.
 449  *
 450  * Returns: (transfer full): the #GstCaps of the static pad template.
 451  * Unref after usage. Since the core holds an additional
 452  * ref to the returned caps, use gst_caps_make_writable()
 453  * on the returned caps to modify it.
 454  */
 455 GstCaps *
 456 gst_static_pad_template_get_caps (GstStaticPadTemplate * templ)
 457 {
 458   g_return_val_if_fail (templ, NULL);
 459
 460   return gst_static_caps_get (&templ->static_caps);
 461 }
 462
 463 /**
 464  * gst_pad_template_get_caps:
 465  * @templ: a #GstPadTemplate to get capabilities of.
 466  *
 467  * Gets the capabilities of the pad template.
 468  *
 469  * Returns: (transfer full): the #GstCaps of the pad template.
 470  * Unref after usage.
 471  */
 472 GstCaps *
 473 gst_pad_template_get_caps (GstPadTemplate * templ)
 474 {
 475   GstCaps *caps;
 476   g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
 477
 478   caps = GST_PAD_TEMPLATE_CAPS (templ);
 479
 480   return (caps ? gst_caps_ref (caps) : NULL);
 481 }
 482
 483 /**
 484  * gst_pad_template_set_documentation_caps:
 485  * @templ: the pad template to set documented capabilities on
 486  * @caps: (transfer full): the documented capabilities
 487  *
 488  * Certain elements will dynamically construct the caps of their
 489  * pad templates. In order not to let environment-specific information
 490  * into the documentation, element authors should use this method to
 491  * expose "stable" caps to the reader.
 492  *
 493  * Since: 1.18
 494  */
 495 void
 496 gst_pad_template_set_documentation_caps (GstPadTemplate * templ, GstCaps * caps)
 497 {
 498   g_return_if_fail (GST_IS_PAD_TEMPLATE (templ));
 499   g_return_if_fail (GST_IS_CAPS (caps));
 500
 501   if (caps)
 502     GST_MINI_OBJECT_FLAG_SET (caps, GST_MINI_OBJECT_FLAG_MAY_BE_LEAKED);
 503   gst_caps_replace (&(((GstPadTemplate *) (templ))->ABI.abi.documentation_caps),
 504       caps);
 505 }
 506
 507 /**
 508  * gst_pad_template_get_documentation_caps:
 509  * @templ: the pad template to get documented capabilities on
 510  *
 511  * See gst_pad_template_set_documentation_caps().
 512  *
 513  * Returns: The caps to document. For convenience, this will return
 514  *   gst_pad_template_get_caps() when no documentation caps were set.
 515  * Since: 1.18
 516  */
 517 GstCaps *
 518 gst_pad_template_get_documentation_caps (GstPadTemplate * templ)
 519 {
 520   g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
 521
 522   if (((GstPadTemplate *) (templ))->ABI.abi.documentation_caps)
 523     return gst_caps_ref (((GstPadTemplate *) (templ))->ABI.abi.
 524         documentation_caps);
 525   else
 526     return gst_pad_template_get_caps (templ);
 527 }
 528
 529 /**
 530  * gst_pad_template_pad_created:
 531  * @templ: a #GstPadTemplate that has been created
 532  * @pad:   the #GstPad that created it
 533  *
 534  * Emit the pad-created signal for this template when created by this pad.
 535  */
 536 void
 537 gst_pad_template_pad_created (GstPadTemplate * templ, GstPad * pad)
 538 {
 539   g_signal_emit (templ, gst_pad_template_signals[TEMPL_PAD_CREATED], 0, pad);
 540 }
 541
 542 static void
 543 gst_pad_template_set_property (GObject * object, guint prop_id,
 544     const GValue * value, GParamSpec * pspec)
 545 {
 546   /* these properties are all construct-only */
 547   switch (prop_id) {
 548     case PROP_NAME_TEMPLATE:
 549       GST_PAD_TEMPLATE_NAME_TEMPLATE (object) = g_value_dup_string (value);
 550       break;
 551     case PROP_DIRECTION:
 552       GST_PAD_TEMPLATE_DIRECTION (object) =
 553           (GstPadDirection) g_value_get_enum (value);
 554       break;
 555     case PROP_PRESENCE:
 556       GST_PAD_TEMPLATE_PRESENCE (object) =
 557           (GstPadPresence) g_value_get_enum (value);
 558       break;
 559     case PROP_CAPS:
 560       GST_PAD_TEMPLATE_CAPS (object) = g_value_dup_boxed (value);
 561       if (GST_PAD_TEMPLATE_CAPS (object) != NULL) {
 562         /* GstPadTemplate are usually leaked so are their caps */
 563         GST_MINI_OBJECT_FLAG_SET (GST_PAD_TEMPLATE_CAPS (object),
 564             GST_MINI_OBJECT_FLAG_MAY_BE_LEAKED);
 565       }
 566       break;
 567     case PROP_GTYPE:
 568       GST_PAD_TEMPLATE_GTYPE (object) = g_value_get_gtype (value);
 569       break;
 570     default:
 571       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 572       break;
 573   }
 574 }
 575
 576 static void
 577 gst_pad_template_get_property (GObject * object, guint prop_id, GValue * value,
 578     GParamSpec * pspec)
 579 {
 580   /* these properties are all construct-only */
 581   switch (prop_id) {
 582     case PROP_NAME_TEMPLATE:
 583       g_value_set_string (value, GST_PAD_TEMPLATE_NAME_TEMPLATE (object));
 584       break;
 585     case PROP_DIRECTION:
 586       g_value_set_enum (value, GST_PAD_TEMPLATE_DIRECTION (object));
 587       break;
 588     case PROP_PRESENCE:
 589       g_value_set_enum (value, GST_PAD_TEMPLATE_PRESENCE (object));
 590       break;
 591     case PROP_CAPS:
 592       g_value_set_boxed (value, GST_PAD_TEMPLATE_CAPS (object));
 593       break;
 594     case PROP_GTYPE:
 595       g_value_set_gtype (value, GST_PAD_TEMPLATE_GTYPE (object));
 596       break;
 597     default:
 598       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 599       break;
 600   }
 601 }