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  * @short_description: Describe the media type of a pad.
  26  * @see_also: #GstPad, #GstElementFactory
  27  *
  28  * Padtemplates describe the possible media types a pad or an elementfactory can
  29  * handle. This allows for both inspection of handled types before loading the
  30  * element plugin as well as identifying pads on elements that are not yet
  31  * created (request or sometimes pads).
  32  *
  33  * Pad and PadTemplates have #GstCaps attached to it to describe the media type
  34  * they are capable of dealing with. gst_pad_template_get_caps() or
  35  * GST_PAD_TEMPLATE_CAPS() are used to get the caps of a padtemplate. It's not
  36  * possible to modify the caps of a padtemplate after creation.
  37  *
  38  * PadTemplates have a #GstPadPresence property which identifies the lifetime
  39  * of the pad and that can be retrieved with GST_PAD_TEMPLATE_PRESENCE(). Also
  40  * the direction of the pad can be retrieved from the #GstPadTemplate with
  41  * GST_PAD_TEMPLATE_DIRECTION().
  42  *
  43  * The GST_PAD_TEMPLATE_NAME_TEMPLATE () is important for GST_PAD_REQUEST pads
  44  * because it has to be used as the name in the gst_element_get_request_pad()
  45  * call to instantiate a pad from this template.
  46  *
  47  * Padtemplates can be created with gst_pad_template_new() or with
  48  * gst_static_pad_template_get (), which creates a #GstPadTemplate from a
  49  * #GstStaticPadTemplate that can be filled with the
  50  * convenient GST_STATIC_PAD_TEMPLATE() macro.
  51  *
  52  * A padtemplate can be used to create a pad (see gst_pad_new_from_template()
  53  * or gst_pad_new_from_static_template ()) or to add to an element class
  54  * (see gst_element_class_add_static_pad_template ()).
  55  *
  56  * The following code example shows the code to create a pad from a padtemplate.
  57  * |[<!-- language="C" -->
  58  *   GstStaticPadTemplate my_template =
  59  *   GST_STATIC_PAD_TEMPLATE (
  60  *     "sink",          // the name of the pad
  61  *     GST_PAD_SINK,    // the direction of the pad
  62  *     GST_PAD_ALWAYS,  // when this pad will be present
  63  *     GST_STATIC_CAPS (        // the capabilities of the padtemplate
  64  *       "audio/x-raw, "
  65  *         "channels = (int) [ 1, 6 ]"
  66  *     )
  67  *   );
  68  *   void
  69  *   my_method (void)
  70  *   {
  71  *     GstPad *pad;
  72  *     pad = gst_pad_new_from_static_template (&amp;my_template, "sink");
  73  *     ...
  74  *   }
  75  * ]|
  76  *
  77  * The following example shows you how to add the padtemplate to an
  78  * element class, this is usually done in the class_init of the class:
  79  * |[<!-- language="C" -->
  80  *   static void
  81  *   my_element_class_init (GstMyElementClass *klass)
  82  *   {
  83  *     GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);
  84  *
  85  *     gst_element_class_add_static_pad_template (gstelement_class, &amp;my_template);
  86  *   }
  87  * ]|
  88  */
  89
  90 #include "gst_private.h"
  91
  92 #include "gstpad.h"
  93 #include "gstpadtemplate.h"
  94 #include "gstenumtypes.h"
  95 #include "gstutils.h"
  96 #include "gstinfo.h"
  97 #include "gsterror.h"
  98 #include "gstvalue.h"
  99
 100 #define GST_CAT_DEFAULT GST_CAT_PADS
 101
 102 enum
 103 {
 104   PROP_NAME_TEMPLATE = 1,
 105   PROP_DIRECTION,
 106   PROP_PRESENCE,
 107   PROP_CAPS
 108 };
 109
 110 enum
 111 {
 112   TEMPL_PAD_CREATED,
 113   /* FILL ME */
 114   LAST_SIGNAL
 115 };
 116
 117 static guint gst_pad_template_signals[LAST_SIGNAL] = { 0 };
 118
 119 static void gst_pad_template_dispose (GObject * object);
 120 static void gst_pad_template_set_property (GObject * object, guint prop_id,
 121     const GValue * value, GParamSpec * pspec);
 122 static void gst_pad_template_get_property (GObject * object, guint prop_id,
 123     GValue * value, GParamSpec * pspec);
 124
 125 #define gst_pad_template_parent_class parent_class
 126 G_DEFINE_TYPE (GstPadTemplate, gst_pad_template, GST_TYPE_OBJECT);
 127
 128 static void
 129 gst_pad_template_class_init (GstPadTemplateClass * klass)
 130 {
 131   GObjectClass *gobject_class;
 132   GstObjectClass *gstobject_class;
 133
 134   gobject_class = (GObjectClass *) klass;
 135   gstobject_class = (GstObjectClass *) klass;
 136
 137   /**
 138    * GstPadTemplate::pad-created:
 139    * @pad_template: the object which received the signal.
 140    * @pad: the pad that was created.
 141    *
 142    * This signal is fired when an element creates a pad from this template.
 143    */
 144   gst_pad_template_signals[TEMPL_PAD_CREATED] =
 145       g_signal_new ("pad-created", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 146       G_STRUCT_OFFSET (GstPadTemplateClass, pad_created),
 147       NULL, NULL, g_cclosure_marshal_generic, G_TYPE_NONE, 1, GST_TYPE_PAD);
 148
 149   gobject_class->dispose = gst_pad_template_dispose;
 150
 151   gobject_class->get_property = gst_pad_template_get_property;
 152   gobject_class->set_property = gst_pad_template_set_property;
 153
 154   /**
 155    * GstPadTemplate:name-template:
 156    *
 157    * The name template of the pad template.
 158    */
 159   g_object_class_install_property (gobject_class, PROP_NAME_TEMPLATE,
 160       g_param_spec_string ("name-template", "Name template",
 161           "The name template of the pad template", NULL,
 162           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 163
 164   /**
 165    * GstPadTemplate:direction:
 166    *
 167    * The direction of the pad described by the pad template.
 168    */
 169   g_object_class_install_property (gobject_class, PROP_DIRECTION,
 170       g_param_spec_enum ("direction", "Direction",
 171           "The direction of the pad described by the pad template",
 172           GST_TYPE_PAD_DIRECTION, GST_PAD_UNKNOWN,
 173           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 174
 175   /**
 176    * GstPadTemplate:presence:
 177    *
 178    * When the pad described by the pad template will become available.
 179    */
 180   g_object_class_install_property (gobject_class, PROP_PRESENCE,
 181       g_param_spec_enum ("presence", "Presence",
 182           "When the pad described by the pad template will become available",
 183           GST_TYPE_PAD_PRESENCE, GST_PAD_ALWAYS,
 184           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 185
 186   /**
 187    * GstPadTemplate:caps:
 188    *
 189    * The capabilities of the pad described by the pad template.
 190    */
 191   g_object_class_install_property (gobject_class, PROP_CAPS,
 192       g_param_spec_boxed ("caps", "Caps",
 193           "The capabilities of the pad described by the pad template",
 194           GST_TYPE_CAPS,
 195           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 196
 197   gstobject_class->path_string_separator = "*";
 198 }
 199
 200 static void
 201 gst_pad_template_init (GstPadTemplate * templ)
 202 {
 203   /* GstPadTemplate objects are usually leaked */
 204   GST_OBJECT_FLAG_SET (templ, GST_OBJECT_FLAG_MAY_BE_LEAKED);
 205 }
 206
 207 static void
 208 gst_pad_template_dispose (GObject * object)
 209 {
 210   GstPadTemplate *templ = GST_PAD_TEMPLATE (object);
 211
 212   g_free (GST_PAD_TEMPLATE_NAME_TEMPLATE (templ));
 213   if (GST_PAD_TEMPLATE_CAPS (templ)) {
 214     gst_caps_unref (GST_PAD_TEMPLATE_CAPS (templ));
 215   }
 216
 217   G_OBJECT_CLASS (parent_class)->dispose (object);
 218 }
 219
 220 /* ALWAYS padtemplates cannot have conversion specifications (like src_%d),
 221  * since it doesn't make sense.
 222  * SOMETIMES padtemplates can do whatever they want, they are provided by the
 223  * element.
 224  * REQUEST padtemplates can have multiple specifiers in case of %d and %u, like
 225  * src_%u_%u, but %s only can be used once in the template.
 226  */
 227 static gboolean
 228 name_is_valid (const gchar * name, GstPadPresence presence)
 229 {
 230   const gchar *str, *underscore = NULL;
 231   gboolean has_s = FALSE;
 232
 233   if (presence == GST_PAD_ALWAYS) {
 234     if (strchr (name, '%')) {
 235       g_warning ("invalid name template %s: conversion specifications are not"
 236           " allowed for GST_PAD_ALWAYS padtemplates", name);
 237       return FALSE;
 238     }
 239   } else if (presence == GST_PAD_REQUEST) {
 240     str = strchr (name, '%');
 241
 242     while (str) {
 243       if (*(str + 1) != 's' && *(str + 1) != 'd' && *(str + 1) != 'u') {
 244         g_warning
 245             ("invalid name template %s: conversion specification must be of"
 246             " type '%%d', '%%u' or '%%s' for GST_PAD_REQUEST padtemplate",
 247             name);
 248         return FALSE;
 249       }
 250
 251       if (*(str + 1) == 's' && (*(str + 2) != '\0' || has_s)) {
 252         g_warning
 253             ("invalid name template %s: conversion specification of type '%%s'"
 254             "only can be used once in the GST_PAD_REQUEST padtemplate at the "
 255             "very end and not allowed any other characters with '%%s'", name);
 256         return FALSE;
 257       }
 258
 259       if (*(str + 1) == 's') {
 260         has_s = TRUE;
 261       }
 262
 263       underscore = strchr (str, '_');
 264       str = strchr (str + 1, '%');
 265
 266       if (str && (!underscore || (underscore && str < underscore))) {
 267         g_warning
 268             ("invalid name template %s: each of conversion specifications "
 269             "must be separated by an underscore", name);
 270         return FALSE;
 271       }
 272     }
 273   }
 274
 275   return TRUE;
 276 }
 277
 278 G_DEFINE_POINTER_TYPE (GstStaticPadTemplate, gst_static_pad_template);
 279
 280 /**
 281  * gst_static_pad_template_get:
 282  * @pad_template: the static pad template
 283  *
 284  * Converts a #GstStaticPadTemplate into a #GstPadTemplate.
 285  *
 286  * Returns: (transfer full): a new #GstPadTemplate.
 287  */
 288 /* FIXME0.11: rename to gst_pad_template_new_from_static_pad_template() */
 289 GstPadTemplate *
 290 gst_static_pad_template_get (GstStaticPadTemplate * pad_template)
 291 {
 292   GstPadTemplate *new;
 293   GstCaps *caps;
 294
 295   if (!name_is_valid (pad_template->name_template, pad_template->presence))
 296     return NULL;
 297
 298   caps = gst_static_caps_get (&pad_template->static_caps);
 299
 300   new = g_object_new (gst_pad_template_get_type (),
 301       "name", pad_template->name_template,
 302       "name-template", pad_template->name_template,
 303       "direction", pad_template->direction,
 304       "presence", pad_template->presence, "caps", caps, NULL);
 305
 306   gst_caps_unref (caps);
 307
 308   return new;
 309 }
 310
 311 /**
 312  * gst_pad_template_new:
 313  * @name_template: the name template.
 314  * @direction: the #GstPadDirection of the template.
 315  * @presence: the #GstPadPresence of the pad.
 316  * @caps: (transfer none): a #GstCaps set for the template.
 317  *
 318  * Creates a new pad template with a name according to the given template
 319  * and with the given arguments.
 320  *
 321  * Returns: (transfer floating): a new #GstPadTemplate.
 322  */
 323 GstPadTemplate *
 324 gst_pad_template_new (const gchar * name_template,
 325     GstPadDirection direction, GstPadPresence presence, GstCaps * caps)
 326 {
 327   GstPadTemplate *new;
 328
 329   g_return_val_if_fail (name_template != NULL, NULL);
 330   g_return_val_if_fail (caps != NULL, NULL);
 331   g_return_val_if_fail (direction == GST_PAD_SRC
 332       || direction == GST_PAD_SINK, NULL);
 333   g_return_val_if_fail (presence == GST_PAD_ALWAYS
 334       || presence == GST_PAD_SOMETIMES || presence == GST_PAD_REQUEST, NULL);
 335
 336   if (!name_is_valid (name_template, presence)) {
 337     return NULL;
 338   }
 339
 340   new = g_object_new (gst_pad_template_get_type (),
 341       "name", name_template, "name-template", name_template,
 342       "direction", direction, "presence", presence, "caps", caps, NULL);
 343
 344   return new;
 345 }
 346
 347 /**
 348  * gst_static_pad_template_get_caps:
 349  * @templ: a #GstStaticPadTemplate to get capabilities of.
 350  *
 351  * Gets the capabilities of the static pad template.
 352  *
 353  * Returns: (transfer full): the #GstCaps of the static pad template.
 354  * Unref after usage. Since the core holds an additional
 355  * ref to the returned caps, use gst_caps_make_writable()
 356  * on the returned caps to modify it.
 357  */
 358 GstCaps *
 359 gst_static_pad_template_get_caps (GstStaticPadTemplate * templ)
 360 {
 361   g_return_val_if_fail (templ, NULL);
 362
 363   return gst_static_caps_get (&templ->static_caps);
 364 }
 365
 366 /**
 367  * gst_pad_template_get_caps:
 368  * @templ: a #GstPadTemplate to get capabilities of.
 369  *
 370  * Gets the capabilities of the pad template.
 371  *
 372  * Returns: (transfer full): the #GstCaps of the pad template.
 373  * Unref after usage.
 374  */
 375 GstCaps *
 376 gst_pad_template_get_caps (GstPadTemplate * templ)
 377 {
 378   GstCaps *caps;
 379   g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
 380
 381   caps = GST_PAD_TEMPLATE_CAPS (templ);
 382
 383   return (caps ? gst_caps_ref (caps) : NULL);
 384 }
 385
 386 /**
 387  * gst_pad_template_pad_created:
 388  * @templ: a #GstPadTemplate that has been created
 389  * @pad:   the #GstPad that created it
 390  *
 391  * Emit the pad-created signal for this template when created by this pad.
 392  */
 393 void
 394 gst_pad_template_pad_created (GstPadTemplate * templ, GstPad * pad)
 395 {
 396   g_signal_emit (templ, gst_pad_template_signals[TEMPL_PAD_CREATED], 0, pad);
 397 }
 398
 399 static void
 400 gst_pad_template_set_property (GObject * object, guint prop_id,
 401     const GValue * value, GParamSpec * pspec)
 402 {
 403   /* these properties are all construct-only */
 404   switch (prop_id) {
 405     case PROP_NAME_TEMPLATE:
 406       GST_PAD_TEMPLATE_NAME_TEMPLATE (object) = g_value_dup_string (value);
 407       break;
 408     case PROP_DIRECTION:
 409       GST_PAD_TEMPLATE_DIRECTION (object) =
 410           (GstPadDirection) g_value_get_enum (value);
 411       break;
 412     case PROP_PRESENCE:
 413       GST_PAD_TEMPLATE_PRESENCE (object) =
 414           (GstPadPresence) g_value_get_enum (value);
 415       break;
 416     case PROP_CAPS:
 417       GST_PAD_TEMPLATE_CAPS (object) = g_value_dup_boxed (value);
 418       if (GST_PAD_TEMPLATE_CAPS (object) != NULL) {
 419         /* GstPadTemplate are usually leaked so are their caps */
 420         GST_MINI_OBJECT_FLAG_SET (GST_PAD_TEMPLATE_CAPS (object),
 421             GST_MINI_OBJECT_FLAG_MAY_BE_LEAKED);
 422       }
 423       break;
 424     default:
 425       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 426       break;
 427   }
 428 }
 429
 430 static void
 431 gst_pad_template_get_property (GObject * object, guint prop_id, GValue * value,
 432     GParamSpec * pspec)
 433 {
 434   /* these properties are all construct-only */
 435   switch (prop_id) {
 436     case PROP_NAME_TEMPLATE:
 437       g_value_set_string (value, GST_PAD_TEMPLATE_NAME_TEMPLATE (object));
 438       break;
 439     case PROP_DIRECTION:
 440       g_value_set_enum (value, GST_PAD_TEMPLATE_DIRECTION (object));
 441       break;
 442     case PROP_PRESENCE:
 443       g_value_set_enum (value, GST_PAD_TEMPLATE_PRESENCE (object));
 444       break;
 445     case PROP_CAPS:
 446       g_value_set_boxed (value, GST_PAD_TEMPLATE_CAPS (object));
 447       break;
 448     default:
 449       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 450       break;
 451   }
 452 }