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., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, 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_request_pad_by_name()
  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_pad_template ()).
  55  *
  56  * The following code example shows the code to create a pad from a padtemplate.
  57  * <example>
  58  * <title>Create a pad from a padtemplate</title>
  59  *   <programlisting>
  60  *   GstStaticPadTemplate my_template =
  61  *   GST_STATIC_PAD_TEMPLATE (
  62  *     "sink",          // the name of the pad
  63  *     GST_PAD_SINK,    // the direction of the pad
  64  *     GST_PAD_ALWAYS,  // when this pad will be present
  65  *     GST_STATIC_CAPS (        // the capabilities of the padtemplate
  66  *       "audio/x-raw-int, "
  67  *         "channels = (int) [ 1, 6 ]"
  68  *     )
  69  *   )
  70  *   void
  71  *   my_method (void)
  72  *   {
  73  *     GstPad *pad;
  74  *     pad = gst_pad_new_from_static_template (&amp;my_template, "sink");
  75  *     ...
  76  *   }
  77  *   </programlisting>
  78  * </example>
  79  *
  80  * The following example shows you how to add the padtemplate to an
  81  * element class, this is usually done in the base_init of the class:
  82  * <informalexample>
  83  *   <programlisting>
  84  *   static void
  85  *   my_element_base_init (gpointer g_class)
  86  *   {
  87  *     GstElementClass *gstelement_class = GST_ELEMENT_CLASS (g_class);
  88  *
  89  *     gst_element_class_add_pad_template (gstelement_class,
  90  *         gst_static_pad_template_get (&amp;my_template));
  91  *   }
  92  *   </programlisting>
  93  * </informalexample>
  94  *
  95  * Last reviewed on 2006-02-14 (0.10.3)
  96  */
  97
  98 #include "gst_private.h"
  99
 100 #include "gstpad.h"
 101 #include "gstpadtemplate.h"
 102 #include "gstenumtypes.h"
 103 #include "gstmarshal.h"
 104 #include "gstutils.h"
 105 #include "gstinfo.h"
 106 #include "gsterror.h"
 107 #include "gstvalue.h"
 108
 109 #define GST_CAT_DEFAULT GST_CAT_PADS
 110
 111 enum
 112 {
 113   PROP_NAME_TEMPLATE = 1,
 114   PROP_DIRECTION,
 115   PROP_PRESENCE,
 116   PROP_CAPS
 117 };
 118
 119 enum
 120 {
 121   TEMPL_PAD_CREATED,
 122   /* FILL ME */
 123   LAST_SIGNAL
 124 };
 125
 126 static GstObject *parent_class = NULL;
 127 static guint gst_pad_template_signals[LAST_SIGNAL] = { 0 };
 128
 129 static void gst_pad_template_dispose (GObject * object);
 130 static void gst_pad_template_set_property (GObject * object, guint prop_id,
 131     const GValue * value, GParamSpec * pspec);
 132 static void gst_pad_template_get_property (GObject * object, guint prop_id,
 133     GValue * value, GParamSpec * pspec);
 134
 135 G_DEFINE_TYPE (GstPadTemplate, gst_pad_template, GST_TYPE_OBJECT);
 136
 137 static void
 138 gst_pad_template_class_init (GstPadTemplateClass * klass)
 139 {
 140   GObjectClass *gobject_class;
 141   GstObjectClass *gstobject_class;
 142
 143   gobject_class = (GObjectClass *) klass;
 144   gstobject_class = (GstObjectClass *) klass;
 145
 146   parent_class = g_type_class_peek_parent (klass);
 147
 148   /**
 149    * GstPadTemplate::pad-created:
 150    * @pad_template: the object which received the signal.
 151    * @pad: the pad that was created.
 152    *
 153    * This signal is fired when an element creates a pad from this template.
 154    */
 155   gst_pad_template_signals[TEMPL_PAD_CREATED] =
 156       g_signal_new ("pad-created", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 157       G_STRUCT_OFFSET (GstPadTemplateClass, pad_created),
 158       NULL, NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
 159
 160   gobject_class->dispose = gst_pad_template_dispose;
 161
 162   gobject_class->get_property = gst_pad_template_get_property;
 163   gobject_class->set_property = gst_pad_template_set_property;
 164
 165   /**
 166    * GstPadTemplate:name-template
 167    *
 168    * The name template of the pad template.
 169    *
 170    * Since: 0.10.21
 171    */
 172   g_object_class_install_property (gobject_class, PROP_NAME_TEMPLATE,
 173       g_param_spec_string ("name-template", "Name template",
 174           "The name template of the pad template", NULL,
 175           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 176
 177   /**
 178    * GstPadTemplate:direction
 179    *
 180    * The direction of the pad described by the pad template.
 181    *
 182    * Since: 0.10.21
 183    */
 184   g_object_class_install_property (gobject_class, PROP_DIRECTION,
 185       g_param_spec_enum ("direction", "Direction",
 186           "The direction of the pad described by the pad template",
 187           GST_TYPE_PAD_DIRECTION, GST_PAD_UNKNOWN,
 188           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 189
 190   /**
 191    * GstPadTemplate:presence
 192    *
 193    * When the pad described by the pad template will become available.
 194    *
 195    * Since: 0.10.21
 196    */
 197   g_object_class_install_property (gobject_class, PROP_PRESENCE,
 198       g_param_spec_enum ("presence", "Presence",
 199           "When the pad described by the pad template will become available",
 200           GST_TYPE_PAD_PRESENCE, GST_PAD_ALWAYS,
 201           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 202
 203   /**
 204    * GstPadTemplate:caps
 205    *
 206    * The capabilities of the pad described by the pad template.
 207    *
 208    * Since: 0.10.21
 209    */
 210   g_object_class_install_property (gobject_class, PROP_CAPS,
 211       g_param_spec_boxed ("caps", "Caps",
 212           "The capabilities of the pad described by the pad template",
 213           GST_TYPE_CAPS,
 214           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 215
 216   gstobject_class->path_string_separator = "*";
 217 }
 218
 219 static void
 220 gst_pad_template_init (GstPadTemplate * templ)
 221 {
 222   /* FIXME 0.11: Does anybody remember why this is here? If not, let's
 223    * change it for 0.11 and let gst_element_class_add_pad_template() for
 224    * example ref/sink the pad templates.
 225    */
 226   /* We ensure that the pad template we're creating has a sunken reference.
 227    * Inconsistencies in pad templates being floating or sunken has caused
 228    * problems in the past with leaks, etc.
 229    *
 230    * For consistency, then, we only produce them  with sunken references
 231    * owned by the creator of the object
 232    */
 233   if (GST_OBJECT_IS_FLOATING (templ)) {
 234     gst_object_ref_sink (templ);
 235   }
 236 }
 237
 238 static void
 239 gst_pad_template_dispose (GObject * object)
 240 {
 241   GstPadTemplate *templ = GST_PAD_TEMPLATE (object);
 242
 243   g_free (GST_PAD_TEMPLATE_NAME_TEMPLATE (templ));
 244   if (GST_PAD_TEMPLATE_CAPS (templ)) {
 245     gst_caps_unref (GST_PAD_TEMPLATE_CAPS (templ));
 246   }
 247
 248   G_OBJECT_CLASS (parent_class)->dispose (object);
 249 }
 250
 251 /* ALWAYS padtemplates cannot have conversion specifications (like src_%d),
 252  * since it doesn't make sense.
 253  * SOMETIMES padtemplates can do whatever they want, they are provided by the
 254  * element.
 255  * REQUEST padtemplates can be reverse-parsed (the user asks for 'sink1', the
 256  * 'sink%d' template is automatically selected), so we need to restrict their
 257  * naming.
 258  */
 259 static gboolean
 260 name_is_valid (const gchar * name, GstPadPresence presence)
 261 {
 262   const gchar *str;
 263
 264   if (presence == GST_PAD_ALWAYS) {
 265     if (strchr (name, '%')) {
 266       g_warning ("invalid name template %s: conversion specifications are not"
 267           " allowed for GST_PAD_ALWAYS padtemplates", name);
 268       return FALSE;
 269     }
 270   } else if (presence == GST_PAD_REQUEST) {
 271     if ((str = strchr (name, '%')) && strchr (str + 1, '%')) {
 272       g_warning ("invalid name template %s: only one conversion specification"
 273           " allowed in GST_PAD_REQUEST padtemplate", name);
 274       return FALSE;
 275     }
 276     if (str && (*(str + 1) != 's' && *(str + 1) != 'd' && *(str + 1) != 'u')) {
 277       g_warning ("invalid name template %s: conversion specification must be of"
 278           " type '%%d', '%%u' or '%%s' for GST_PAD_REQUEST padtemplate", name);
 279       return FALSE;
 280     }
 281     if (str && (*(str + 2) != '\0')) {
 282       g_warning ("invalid name template %s: conversion specification must"
 283           " appear at the end of the GST_PAD_REQUEST padtemplate name", name);
 284       return FALSE;
 285     }
 286   }
 287
 288   return TRUE;
 289 }
 290
 291 GType
 292 gst_static_pad_template_get_type (void)
 293 {
 294   static GType staticpadtemplate_type = 0;
 295
 296   if (G_UNLIKELY (staticpadtemplate_type == 0)) {
 297     staticpadtemplate_type =
 298         g_pointer_type_register_static ("GstStaticPadTemplate");
 299   }
 300   return staticpadtemplate_type;
 301 }
 302
 303 /**
 304  * gst_static_pad_template_get:
 305  * @pad_template: the static pad template
 306  *
 307  * Converts a #GstStaticPadTemplate into a #GstPadTemplate.
 308  *
 309  * Returns: a new #GstPadTemplate.
 310  */
 311 GstPadTemplate *
 312 gst_static_pad_template_get (GstStaticPadTemplate * pad_template)
 313 {
 314   GstPadTemplate *new;
 315   GstCaps *caps;
 316
 317   if (!name_is_valid (pad_template->name_template, pad_template->presence))
 318     return NULL;
 319
 320   caps = gst_static_caps_get (&pad_template->static_caps);
 321
 322   new = g_object_new (gst_pad_template_get_type (),
 323       "name", pad_template->name_template,
 324       "name-template", pad_template->name_template,
 325       "direction", pad_template->direction,
 326       "presence", pad_template->presence, "caps", caps, NULL);
 327
 328   gst_caps_unref (caps);
 329
 330   return new;
 331 }
 332
 333 /**
 334  * gst_pad_template_new:
 335  * @name_template: the name template.
 336  * @direction: the #GstPadDirection of the template.
 337  * @presence: the #GstPadPresence of the pad.
 338  * @caps: a #GstCaps set for the template. The caps are taken ownership of.
 339  *
 340  * Creates a new pad template with a name according to the given template
 341  * and with the given arguments. This functions takes ownership of the provided
 342  * caps, so be sure to not use them afterwards.
 343  *
 344  * Returns: a new #GstPadTemplate.
 345  */
 346 GstPadTemplate *
 347 gst_pad_template_new (const gchar * name_template,
 348     GstPadDirection direction, GstPadPresence presence, GstCaps * caps)
 349 {
 350   GstPadTemplate *new;
 351
 352   g_return_val_if_fail (name_template != NULL, NULL);
 353   g_return_val_if_fail (caps != NULL, NULL);
 354   g_return_val_if_fail (direction == GST_PAD_SRC
 355       || direction == GST_PAD_SINK, NULL);
 356   g_return_val_if_fail (presence == GST_PAD_ALWAYS
 357       || presence == GST_PAD_SOMETIMES || presence == GST_PAD_REQUEST, NULL);
 358
 359   if (!name_is_valid (name_template, presence)) {
 360     gst_caps_unref (caps);
 361     return NULL;
 362   }
 363
 364   new = g_object_new (gst_pad_template_get_type (),
 365       "name", name_template, "name-template", name_template,
 366       "direction", direction, "presence", presence, "caps", caps, NULL);
 367
 368   if (caps)
 369     gst_caps_unref (caps);
 370
 371   return new;
 372 }
 373
 374 /**
 375  * gst_static_pad_template_get_caps:
 376  * @templ: a #GstStaticPadTemplate to get capabilities of.
 377  *
 378  * Gets the capabilities of the static pad template.
 379  *
 380  * Returns: the #GstCaps of the static pad template.
 381  * Unref after usage. Since the core holds an additional
 382  * ref to the returned caps, use gst_caps_make_writable()
 383  * on the returned caps to modify it.
 384  */
 385 GstCaps *
 386 gst_static_pad_template_get_caps (GstStaticPadTemplate * templ)
 387 {
 388   g_return_val_if_fail (templ, NULL);
 389
 390   return (GstCaps *) gst_static_caps_get (&templ->static_caps);
 391 }
 392
 393 /**
 394  * gst_pad_template_get_caps:
 395  * @templ: a #GstPadTemplate to get capabilities of.
 396  *
 397  * Gets the capabilities of the pad template.
 398  *
 399  * Returns: the #GstCaps of the pad template. If you need to keep a reference to
 400  * the caps, take a ref (see gst_caps_ref ()).
 401  */
 402 GstCaps *
 403 gst_pad_template_get_caps (GstPadTemplate * templ)
 404 {
 405   g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
 406
 407   return GST_PAD_TEMPLATE_CAPS (templ);
 408 }
 409
 410 /**
 411  * gst_pad_template_pad_created:
 412  * @templ: a #GstPadTemplate that has been created
 413  * @pad:   the #GstPad that created it
 414  *
 415  * Emit the pad-created signal for this template when created by this pad.
 416  */
 417 void
 418 gst_pad_template_pad_created (GstPadTemplate * templ, GstPad * pad)
 419 {
 420   g_signal_emit (G_OBJECT (templ),
 421       gst_pad_template_signals[TEMPL_PAD_CREATED], 0, pad);
 422 }
 423
 424 static void
 425 gst_pad_template_set_property (GObject * object, guint prop_id,
 426     const GValue * value, GParamSpec * pspec)
 427 {
 428   /* these properties are all construct-only */
 429   switch (prop_id) {
 430     case PROP_NAME_TEMPLATE:
 431       GST_PAD_TEMPLATE_NAME_TEMPLATE (object) = g_value_dup_string (value);
 432       break;
 433     case PROP_DIRECTION:
 434       GST_PAD_TEMPLATE_DIRECTION (object) = g_value_get_enum (value);
 435       break;
 436     case PROP_PRESENCE:
 437       GST_PAD_TEMPLATE_PRESENCE (object) = g_value_get_enum (value);
 438       break;
 439     case PROP_CAPS:
 440       /* allow caps == NULL for backwards compatibility (ie. g_object_new()
 441        * called without any of the new properties) (FIXME 0.11) */
 442       if (g_value_get_boxed (value) != NULL) {
 443         GST_PAD_TEMPLATE_CAPS (object) =
 444             gst_caps_copy (g_value_get_boxed (value));
 445       }
 446       break;
 447     default:
 448       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 449       break;
 450   }
 451 }
 452
 453 static void
 454 gst_pad_template_get_property (GObject * object, guint prop_id, GValue * value,
 455     GParamSpec * pspec)
 456 {
 457   /* these properties are all construct-only */
 458   switch (prop_id) {
 459     case PROP_NAME_TEMPLATE:
 460       g_value_set_string (value, GST_PAD_TEMPLATE_NAME_TEMPLATE (object));
 461       break;
 462     case PROP_DIRECTION:
 463       g_value_set_enum (value, GST_PAD_TEMPLATE_DIRECTION (object));
 464       break;
 465     case PROP_PRESENCE:
 466       g_value_set_enum (value, GST_PAD_TEMPLATE_PRESENCE (object));
 467       break;
 468     case PROP_CAPS:
 469       g_value_set_boxed (value, GST_PAD_TEMPLATE_CAPS (object));
 470       break;
 471     default:
 472       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 473       break;
 474   }
 475 }