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  * SECTION:gstpadtemplate
  24  * @short_description: Describe the media type of a pad.
  25  * @see_also: #GstPad, #GstElementFactory
  26  *
  27  * Padtemplates describe the possible media types a pad or an elementfactory can
  28  * handle.
  29  *
  30  * Pad and PadTemplates have #GstCaps attached to it to describe the media type they
  31  * are capable of dealing with. gst_pad_template_get_caps() is used to get the
  32  * caps of a padtemplate. It's not possible to modify the caps of a padtemplate after
  33  * creation.
  34  *
  35  * Padtemplates can be created with gst_pad_template_new() or with the convenient
  36  * GST_PAD_TEMPLATE_FACTORY() macro. A padtemplate can be used to create a pad or
  37  * to add to an elementfactory.
  38  *
  39  * The following code example shows the code to create a pad from a padtemplate.
  40  * <example>
  41  * <title>Create a pad from a padtemplate</title>
  42  *   <programlisting>
  43  *   GstStaticPadTemplate my_template =
  44  *   GST_STATIC_PAD_TEMPLATE (
  45  *     "sink",          // the name of the pad
  46  *     GST_PAD_SINK,    // the direction of the pad
  47  *     GST_PAD_ALWAYS,  // when this pad will be present
  48  *     GST_STATIC_CAPS (        // the capabilities of the padtemplate
  49  *       "audio/x-raw-int, "
  50  *         "channels = (int) [ 1, 6 ]"
  51  *     )
  52  *   )
  53  *
  54  *   void
  55  *   my_method (void)
  56  *   {
  57  *     GstPad *pad;
  58  *
  59  *     pad = gst_pad_new_from_template (GST_PAD_TEMPLATE_GET (my_template_factory), "sink");
  60  *     ...
  61  *   }
  62  *   </programlisting>
  63  * </example>
  64  *
  65  * The following example shows you how to add the padtemplate to an elementfactory:
  66  * <informalexample>
  67  *   <programlisting>
  68  *   gboolean
  69  *   my_factory_init (GstPlugin *plugin)
  70  *   {
  71  *     GstElementFactory *factory;
  72  *
  73  *     factory = gst_element_factory_new ("my_factory", GST_TYPE_MYFACTORY, &amp;gst_myfactory_details);
  74  *     g_return_val_if_fail (factory != NULL, FALSE);
  75  *
  76  *     gst_element_factory_add_pad_template (factory, GST_PAD_TEMPLATE_GET (my_template_factory));
  77  *
  78  *     gst_plugin_add_feature (plugin, GST_PLUGIN_FEATURE (factory));
  79  *
  80  *     return TRUE;
  81  *   }
  82  *   </programlisting>
  83  * </informalexample>
  84  */
  85
  86 #include "gst_private.h"
  87
  88 #include "gstpad.h"
  89 #include "gstpadtemplate.h"
  90 #include "gstenumtypes.h"
  91 #include "gstmarshal.h"
  92 #include "gstutils.h"
  93 #include "gstinfo.h"
  94 #include "gsterror.h"
  95 #include "gstvalue.h"
  96
  97 #define GST_CAT_DEFAULT GST_CAT_PADS
  98
  99 enum
 100 {
 101   TEMPL_PAD_CREATED,
 102   /* FILL ME */
 103   LAST_SIGNAL
 104 };
 105
 106 static GstObject *parent_class = NULL;
 107 static guint gst_pad_template_signals[LAST_SIGNAL] = { 0 };
 108
 109 static void gst_pad_template_class_init (GstPadTemplateClass * klass);
 110 static void gst_pad_template_init (GstPadTemplate * templ);
 111 static void gst_pad_template_dispose (GObject * object);
 112
 113 GType
 114 gst_pad_template_get_type (void)
 115 {
 116   static GType padtemplate_type = 0;
 117
 118   if (!padtemplate_type) {
 119     static const GTypeInfo padtemplate_info = {
 120       sizeof (GstPadTemplateClass), NULL, NULL,
 121       (GClassInitFunc) gst_pad_template_class_init, NULL, NULL,
 122       sizeof (GstPadTemplate),
 123       0,
 124       (GInstanceInitFunc) gst_pad_template_init, NULL
 125     };
 126
 127     padtemplate_type =
 128         g_type_register_static (GST_TYPE_OBJECT, "GstPadTemplate",
 129         &padtemplate_info, 0);
 130   }
 131   return padtemplate_type;
 132 }
 133
 134 static void
 135 gst_pad_template_class_init (GstPadTemplateClass * klass)
 136 {
 137   GObjectClass *gobject_class;
 138   GstObjectClass *gstobject_class;
 139
 140   gobject_class = (GObjectClass *) klass;
 141   gstobject_class = (GstObjectClass *) klass;
 142
 143   parent_class = g_type_class_ref (GST_TYPE_OBJECT);
 144
 145   /**
 146    * GstPadTemplate::pad-created:
 147    * @pad_template: the object which received the signal.
 148    * @pad: the pad that was created.
 149    *
 150    * This signal is fired when an element creates a pad from this template.
 151    */
 152   gst_pad_template_signals[TEMPL_PAD_CREATED] =
 153       g_signal_new ("pad-created", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
 154       G_STRUCT_OFFSET (GstPadTemplateClass, pad_created),
 155       NULL, NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
 156
 157   gobject_class->dispose = gst_pad_template_dispose;
 158
 159   gstobject_class->path_string_separator = "*";
 160 }
 161
 162 static void
 163 gst_pad_template_init (GstPadTemplate * templ)
 164 {
 165 }
 166
 167 static void
 168 gst_pad_template_dispose (GObject * object)
 169 {
 170   GstPadTemplate *templ = GST_PAD_TEMPLATE (object);
 171
 172   g_free (GST_PAD_TEMPLATE_NAME_TEMPLATE (templ));
 173   if (GST_PAD_TEMPLATE_CAPS (templ)) {
 174     gst_caps_unref (GST_PAD_TEMPLATE_CAPS (templ));
 175   }
 176
 177   G_OBJECT_CLASS (parent_class)->dispose (object);
 178 }
 179
 180 /* ALWAYS padtemplates cannot have conversion specifications (like src_%d),
 181  * since it doesn't make sense.
 182  * SOMETIMES padtemplates can do whatever they want, they are provided by the
 183  * element.
 184  * REQUEST padtemplates can be reverse-parsed (the user asks for 'sink1', the
 185  * 'sink%d' template is automatically selected), so we need to restrict their
 186  * naming.
 187  */
 188 static gboolean
 189 name_is_valid (const gchar * name, GstPadPresence presence)
 190 {
 191   const gchar *str;
 192
 193   if (presence == GST_PAD_ALWAYS) {
 194     if (strchr (name, '%')) {
 195       g_warning ("invalid name template %s: conversion specifications are not"
 196           " allowed for GST_PAD_ALWAYS padtemplates", name);
 197       return FALSE;
 198     }
 199   } else if (presence == GST_PAD_REQUEST) {
 200     if ((str = strchr (name, '%')) && strchr (str + 1, '%')) {
 201       g_warning ("invalid name template %s: only one conversion specification"
 202           " allowed in GST_PAD_REQUEST padtemplate", name);
 203       return FALSE;
 204     }
 205     if (str && (*(str + 1) != 's' && *(str + 1) != 'd')) {
 206       g_warning ("invalid name template %s: conversion specification must be of"
 207           " type '%%d' or '%%s' for GST_PAD_REQUEST padtemplate", name);
 208       return FALSE;
 209     }
 210     if (str && (*(str + 2) != '\0')) {
 211       g_warning ("invalid name template %s: conversion specification must"
 212           " appear at the end of the GST_PAD_REQUEST padtemplate name", name);
 213       return FALSE;
 214     }
 215   }
 216
 217   return TRUE;
 218 }
 219
 220 /**
 221  * gst_static_pad_template_get:
 222  * @pad_template: the static pad template
 223  *
 224  * Converts a #GstStaticPadTemplate into a #GstPadTemplate.
 225  *
 226  * Returns: a new #GstPadTemplate.
 227  */
 228 GstPadTemplate *
 229 gst_static_pad_template_get (GstStaticPadTemplate * pad_template)
 230 {
 231   GstPadTemplate *new;
 232
 233   if (!name_is_valid (pad_template->name_template, pad_template->presence))
 234     return NULL;
 235
 236   new = g_object_new (gst_pad_template_get_type (),
 237       "name", pad_template->name_template, NULL);
 238
 239   GST_PAD_TEMPLATE_NAME_TEMPLATE (new) = g_strdup (pad_template->name_template);
 240   GST_PAD_TEMPLATE_DIRECTION (new) = pad_template->direction;
 241   GST_PAD_TEMPLATE_PRESENCE (new) = pad_template->presence;
 242
 243   GST_PAD_TEMPLATE_CAPS (new) =
 244       gst_caps_copy (gst_static_caps_get (&pad_template->static_caps));
 245
 246   return new;
 247 }
 248
 249 /**
 250  * gst_pad_template_new:
 251  * @name_template: the name template.
 252  * @direction: the #GstPadDirection of the template.
 253  * @presence: the #GstPadPresence of the pad.
 254  * @caps: a #GstCaps set for the template. The caps are taken ownership of.
 255  *
 256  * Creates a new pad template with a name according to the given template
 257  * and with the given arguments. This functions takes ownership of the provided
 258  * caps, so be sure to not use them afterwards.
 259  *
 260  * Returns: a new #GstPadTemplate.
 261  */
 262 GstPadTemplate *
 263 gst_pad_template_new (const gchar * name_template,
 264     GstPadDirection direction, GstPadPresence presence, GstCaps * caps)
 265 {
 266   GstPadTemplate *new;
 267
 268   g_return_val_if_fail (name_template != NULL, NULL);
 269   g_return_val_if_fail (caps != NULL, NULL);
 270   g_return_val_if_fail (direction == GST_PAD_SRC
 271       || direction == GST_PAD_SINK, NULL);
 272   g_return_val_if_fail (presence == GST_PAD_ALWAYS
 273       || presence == GST_PAD_SOMETIMES || presence == GST_PAD_REQUEST, NULL);
 274
 275   if (!name_is_valid (name_template, presence)) {
 276     gst_caps_unref (caps);
 277     return NULL;
 278   }
 279
 280   new = g_object_new (gst_pad_template_get_type (),
 281       "name", name_template, NULL);
 282
 283   GST_PAD_TEMPLATE_NAME_TEMPLATE (new) = g_strdup (name_template);
 284   GST_PAD_TEMPLATE_DIRECTION (new) = direction;
 285   GST_PAD_TEMPLATE_PRESENCE (new) = presence;
 286   GST_PAD_TEMPLATE_CAPS (new) = caps;
 287
 288   return new;
 289 }
 290
 291 /**
 292  * gst_static_pad_template_get_caps:
 293  * @templ: a #GstStaticPadTemplate to get capabilities of.
 294  *
 295  * Gets the capabilities of the static pad template.
 296  *
 297  * Returns: the #GstCaps of the static pad template. If you need to keep a
 298  * reference to the caps, take a ref (see gst_caps_ref ()).
 299  */
 300 GstCaps *
 301 gst_static_pad_template_get_caps (GstStaticPadTemplate * templ)
 302 {
 303   g_return_val_if_fail (templ, NULL);
 304
 305   return (GstCaps *) gst_static_caps_get (&templ->static_caps);
 306 }
 307
 308 /**
 309  * gst_pad_template_get_caps:
 310  * @templ: a #GstPadTemplate to get capabilities of.
 311  *
 312  * Gets the capabilities of the pad template.
 313  *
 314  * Returns: the #GstCaps of the pad template. If you need to keep a reference to
 315  * the caps, take a ref (see gst_caps_ref ()).
 316  */
 317 GstCaps *
 318 gst_pad_template_get_caps (GstPadTemplate * templ)
 319 {
 320   g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
 321
 322   return GST_PAD_TEMPLATE_CAPS (templ);
 323 }
 324
 325 void
 326 gst_pad_template_pad_created (GstPadTemplate * templ, GstPad * pad)
 327 {
 328   gst_object_sink (GST_OBJECT (templ));
 329   g_signal_emit (G_OBJECT (templ),
 330       gst_pad_template_signals[TEMPL_PAD_CREATED], 0, pad);
 331 }