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 class_init of the class:
  82  * <informalexample>
  83  *   <programlisting>
  84  *   static void
  85  *   my_element_class_init (GstMyElementClass *klass)
  86  *   {
  87  *     GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);
  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   TEMPL_PAD_CREATED,
 114   /* FILL ME */
 115   LAST_SIGNAL
 116 };
 117
 118 static GstObject *parent_class = NULL;
 119 static guint gst_pad_template_signals[LAST_SIGNAL] = { 0 };
 120
 121 static void gst_pad_template_class_init (GstPadTemplateClass * klass);
 122 static void gst_pad_template_init (GstPadTemplate * templ,
 123     GstPadTemplateClass * klass);
 124 static void gst_pad_template_dispose (GObject * object);
 125
 126 GType
 127 gst_pad_template_get_type (void)
 128 {
 129   static GType padtemplate_type = 0;
 130
 131   if (G_UNLIKELY (padtemplate_type == 0)) {
 132     static const GTypeInfo padtemplate_info = {
 133       sizeof (GstPadTemplateClass), NULL, NULL,
 134       (GClassInitFunc) gst_pad_template_class_init, NULL, NULL,
 135       sizeof (GstPadTemplate),
 136       0,
 137       (GInstanceInitFunc) gst_pad_template_init, NULL
 138     };
 139
 140     padtemplate_type =
 141         g_type_register_static (GST_TYPE_OBJECT, "GstPadTemplate",
 142         &padtemplate_info, 0);
 143   }
 144   return padtemplate_type;
 145 }
 146
 147 static void
 148 gst_pad_template_class_init (GstPadTemplateClass * klass)
 149 {
 150   GObjectClass *gobject_class;
 151   GstObjectClass *gstobject_class;
 152
 153   gobject_class = (GObjectClass *) klass;
 154   gstobject_class = (GstObjectClass *) klass;
 155
 156   parent_class = g_type_class_peek_parent (klass);
 157
 158   /**
 159    * GstPadTemplate::pad-created:
 160    * @pad_template: the object which received the signal.
 161    * @pad: the pad that was created.
 162    *
 163    * This signal is fired when an element creates a pad from this template.
 164    */
 165   gst_pad_template_signals[TEMPL_PAD_CREATED] =
 166       g_signal_new ("pad-created", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 167       G_STRUCT_OFFSET (GstPadTemplateClass, pad_created),
 168       NULL, NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
 169
 170   gobject_class->dispose = gst_pad_template_dispose;
 171
 172   gstobject_class->path_string_separator = "*";
 173 }
 174
 175 static void
 176 gst_pad_template_init (GstPadTemplate * templ, GstPadTemplateClass * klass)
 177 {
 178   /* We ensure that the pad template we're creating has a sunken reference.
 179    * Inconsistencies in pad templates being floating or sunken has caused
 180    * problems in the past with leaks, etc.
 181    *
 182    * For consistency, then, we only produce them  with sunken references
 183    * owned by the creator of the object
 184    */
 185   if (GST_OBJECT_IS_FLOATING (templ)) {
 186     gst_object_ref (templ);
 187     gst_object_sink (templ);
 188   }
 189 }
 190
 191 static void
 192 gst_pad_template_dispose (GObject * object)
 193 {
 194   GstPadTemplate *templ = GST_PAD_TEMPLATE (object);
 195
 196   g_free (GST_PAD_TEMPLATE_NAME_TEMPLATE (templ));
 197   if (GST_PAD_TEMPLATE_CAPS (templ)) {
 198     gst_caps_unref (GST_PAD_TEMPLATE_CAPS (templ));
 199   }
 200
 201   G_OBJECT_CLASS (parent_class)->dispose (object);
 202 }
 203
 204 /* ALWAYS padtemplates cannot have conversion specifications (like src_%d),
 205  * since it doesn't make sense.
 206  * SOMETIMES padtemplates can do whatever they want, they are provided by the
 207  * element.
 208  * REQUEST padtemplates can be reverse-parsed (the user asks for 'sink1', the
 209  * 'sink%d' template is automatically selected), so we need to restrict their
 210  * naming.
 211  */
 212 static gboolean
 213 name_is_valid (const gchar * name, GstPadPresence presence)
 214 {
 215   const gchar *str;
 216
 217   if (presence == GST_PAD_ALWAYS) {
 218     if (strchr (name, '%')) {
 219       g_warning ("invalid name template %s: conversion specifications are not"
 220           " allowed for GST_PAD_ALWAYS padtemplates", name);
 221       return FALSE;
 222     }
 223   } else if (presence == GST_PAD_REQUEST) {
 224     if ((str = strchr (name, '%')) && strchr (str + 1, '%')) {
 225       g_warning ("invalid name template %s: only one conversion specification"
 226           " allowed in GST_PAD_REQUEST padtemplate", name);
 227       return FALSE;
 228     }
 229     if (str && (*(str + 1) != 's' && *(str + 1) != 'd')) {
 230       g_warning ("invalid name template %s: conversion specification must be of"
 231           " type '%%d' or '%%s' for GST_PAD_REQUEST padtemplate", name);
 232       return FALSE;
 233     }
 234     if (str && (*(str + 2) != '\0')) {
 235       g_warning ("invalid name template %s: conversion specification must"
 236           " appear at the end of the GST_PAD_REQUEST padtemplate name", name);
 237       return FALSE;
 238     }
 239   }
 240
 241   return TRUE;
 242 }
 243
 244 GType
 245 gst_static_pad_template_get_type (void)
 246 {
 247   static GType staticpadtemplate_type = 0;
 248
 249   if (G_UNLIKELY (staticpadtemplate_type == 0)) {
 250     staticpadtemplate_type =
 251         g_pointer_type_register_static ("GstStaticPadTemplate");
 252   }
 253   return staticpadtemplate_type;
 254 }
 255
 256 /**
 257  * gst_static_pad_template_get:
 258  * @pad_template: the static pad template
 259  *
 260  * Converts a #GstStaticPadTemplate into a #GstPadTemplate.
 261  *
 262  * Returns: a new #GstPadTemplate.
 263  */
 264 GstPadTemplate *
 265 gst_static_pad_template_get (GstStaticPadTemplate * pad_template)
 266 {
 267   GstPadTemplate *new;
 268
 269   if (!name_is_valid (pad_template->name_template, pad_template->presence))
 270     return NULL;
 271
 272   new = g_object_new (gst_pad_template_get_type (),
 273       "name", pad_template->name_template, NULL);
 274
 275   GST_PAD_TEMPLATE_NAME_TEMPLATE (new) = g_strdup (pad_template->name_template);
 276   GST_PAD_TEMPLATE_DIRECTION (new) = pad_template->direction;
 277   GST_PAD_TEMPLATE_PRESENCE (new) = pad_template->presence;
 278
 279   GST_PAD_TEMPLATE_CAPS (new) =
 280       gst_caps_make_writable (gst_static_caps_get (&pad_template->static_caps));
 281
 282   return new;
 283 }
 284
 285 /**
 286  * gst_pad_template_new:
 287  * @name_template: the name template.
 288  * @direction: the #GstPadDirection of the template.
 289  * @presence: the #GstPadPresence of the pad.
 290  * @caps: a #GstCaps set for the template. The caps are taken ownership of.
 291  *
 292  * Creates a new pad template with a name according to the given template
 293  * and with the given arguments. This functions takes ownership of the provided
 294  * caps, so be sure to not use them afterwards.
 295  *
 296  * Returns: a new #GstPadTemplate.
 297  */
 298 GstPadTemplate *
 299 gst_pad_template_new (const gchar * name_template,
 300     GstPadDirection direction, GstPadPresence presence, GstCaps * caps)
 301 {
 302   GstPadTemplate *new;
 303
 304   g_return_val_if_fail (name_template != NULL, NULL);
 305   g_return_val_if_fail (caps != NULL, NULL);
 306   g_return_val_if_fail (direction == GST_PAD_SRC
 307       || direction == GST_PAD_SINK, NULL);
 308   g_return_val_if_fail (presence == GST_PAD_ALWAYS
 309       || presence == GST_PAD_SOMETIMES || presence == GST_PAD_REQUEST, NULL);
 310
 311   if (!name_is_valid (name_template, presence)) {
 312     gst_caps_unref (caps);
 313     return NULL;
 314   }
 315
 316   new = g_object_new (gst_pad_template_get_type (),
 317       "name", name_template, NULL);
 318
 319   GST_PAD_TEMPLATE_NAME_TEMPLATE (new) = g_strdup (name_template);
 320   GST_PAD_TEMPLATE_DIRECTION (new) = direction;
 321   GST_PAD_TEMPLATE_PRESENCE (new) = presence;
 322   GST_PAD_TEMPLATE_CAPS (new) = caps;
 323
 324   return new;
 325 }
 326
 327 /**
 328  * gst_static_pad_template_get_caps:
 329  * @templ: a #GstStaticPadTemplate to get capabilities of.
 330  *
 331  * Gets the capabilities of the static pad template.
 332  *
 333  * Returns: the #GstCaps of the static pad template. If you need to keep a
 334  * reference to the caps, take a ref (see gst_caps_ref ()).
 335  */
 336 GstCaps *
 337 gst_static_pad_template_get_caps (GstStaticPadTemplate * templ)
 338 {
 339   g_return_val_if_fail (templ, NULL);
 340
 341   return (GstCaps *) gst_static_caps_get (&templ->static_caps);
 342 }
 343
 344 /**
 345  * gst_pad_template_get_caps:
 346  * @templ: a #GstPadTemplate to get capabilities of.
 347  *
 348  * Gets the capabilities of the pad template.
 349  *
 350  * Returns: the #GstCaps of the pad template. If you need to keep a reference to
 351  * the caps, take a ref (see gst_caps_ref ()).
 352  */
 353 GstCaps *
 354 gst_pad_template_get_caps (GstPadTemplate * templ)
 355 {
 356   g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
 357
 358   return GST_PAD_TEMPLATE_CAPS (templ);
 359 }
 360
 361 /**
 362  * gst_pad_template_pad_created:
 363  * @templ: a #GstPadTemplate that has been created
 364  * @pad:   the #GstPad that created it
 365  *
 366  * Emit the pad-created signal for this template when created by this pad.
 367  */
 368 void
 369 gst_pad_template_pad_created (GstPadTemplate * templ, GstPad * pad)
 370 {
 371   g_signal_emit (G_OBJECT (templ),
 372       gst_pad_template_signals[TEMPL_PAD_CREATED], 0, pad);
 373 }