2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2000 Wim Taymans <wtay@chello.be>
5 * gstpadtemplate.c: Templates for pad creation
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.
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.
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.
24 * SECTION:gstpadtemplate
25 * @short_description: Describe the media type of a pad.
26 * @see_also: #GstPad, #GstElementFactory
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).
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.
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().
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.
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.
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 ()).
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
65 * "channels = (int) [ 1, 6 ]"
72 * pad = gst_pad_new_from_static_template (&my_template, "sink");
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" -->
81 * my_element_class_init (GstMyElementClass *klass)
83 * GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);
85 * gst_element_class_add_static_pad_template (gstelement_class, &my_template);
90 #include "gst_private.h"
93 #include "gstpadtemplate.h"
94 #include "gstenumtypes.h"
100 #define GST_CAT_DEFAULT GST_CAT_PADS
104 PROP_NAME_TEMPLATE = 1,
117 static guint gst_pad_template_signals[LAST_SIGNAL] = { 0 };
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);
125 #define gst_pad_template_parent_class parent_class
126 G_DEFINE_TYPE (GstPadTemplate, gst_pad_template, GST_TYPE_OBJECT);
129 gst_pad_template_class_init (GstPadTemplateClass * klass)
131 GObjectClass *gobject_class;
132 GstObjectClass *gstobject_class;
134 gobject_class = (GObjectClass *) klass;
135 gstobject_class = (GstObjectClass *) klass;
138 * GstPadTemplate::pad-created:
139 * @pad_template: the object which received the signal.
140 * @pad: the pad that was created.
142 * This signal is fired when an element creates a pad from this template.
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);
149 gobject_class->dispose = gst_pad_template_dispose;
151 gobject_class->get_property = gst_pad_template_get_property;
152 gobject_class->set_property = gst_pad_template_set_property;
155 * GstPadTemplate:name-template:
157 * The name template of the pad template.
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));
165 * GstPadTemplate:direction:
167 * The direction of the pad described by the pad template.
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));
176 * GstPadTemplate:presence:
178 * When the pad described by the pad template will become available.
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));
187 * GstPadTemplate:caps:
189 * The capabilities of the pad described by the pad template.
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",
195 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
197 gstobject_class->path_string_separator = "*";
201 gst_pad_template_init (GstPadTemplate * templ)
203 /* GstPadTemplate objects are usually leaked */
204 GST_OBJECT_FLAG_SET (templ, GST_OBJECT_FLAG_MAY_BE_LEAKED);
208 gst_pad_template_dispose (GObject * object)
210 GstPadTemplate *templ = GST_PAD_TEMPLATE (object);
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));
217 G_OBJECT_CLASS (parent_class)->dispose (object);
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
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.
228 name_is_valid (const gchar * name, GstPadPresence presence)
230 const gchar *str, *underscore = NULL;
231 gboolean has_s = FALSE;
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);
239 } else if (presence == GST_PAD_REQUEST) {
240 str = strchr (name, '%');
243 if (*(str + 1) != 's' && *(str + 1) != 'd' && *(str + 1) != 'u') {
245 ("invalid name template %s: conversion specification must be of"
246 " type '%%d', '%%u' or '%%s' for GST_PAD_REQUEST padtemplate",
251 if (*(str + 1) == 's' && (*(str + 2) != '\0' || has_s)) {
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);
259 if (*(str + 1) == 's') {
263 underscore = strchr (str, '_');
264 str = strchr (str + 1, '%');
266 if (str && (!underscore || (underscore && str < underscore))) {
268 ("invalid name template %s: each of conversion specifications "
269 "must be separated by an underscore", name);
278 G_DEFINE_POINTER_TYPE (GstStaticPadTemplate, gst_static_pad_template);
281 * gst_static_pad_template_get:
282 * @pad_template: the static pad template
284 * Converts a #GstStaticPadTemplate into a #GstPadTemplate.
286 * Returns: (transfer full): a new #GstPadTemplate.
288 /* FIXME0.11: rename to gst_pad_template_new_from_static_pad_template() */
290 gst_static_pad_template_get (GstStaticPadTemplate * pad_template)
295 if (!name_is_valid (pad_template->name_template, pad_template->presence))
298 caps = gst_static_caps_get (&pad_template->static_caps);
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);
306 gst_caps_unref (caps);
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.
318 * Creates a new pad template with a name according to the given template
319 * and with the given arguments.
321 * Returns: (transfer floating): a new #GstPadTemplate.
324 gst_pad_template_new (const gchar * name_template,
325 GstPadDirection direction, GstPadPresence presence, GstCaps * caps)
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);
336 if (!name_is_valid (name_template, presence)) {
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);
348 * gst_static_pad_template_get_caps:
349 * @templ: a #GstStaticPadTemplate to get capabilities of.
351 * Gets the capabilities of the static pad template.
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.
359 gst_static_pad_template_get_caps (GstStaticPadTemplate * templ)
361 g_return_val_if_fail (templ, NULL);
363 return gst_static_caps_get (&templ->static_caps);
367 * gst_pad_template_get_caps:
368 * @templ: a #GstPadTemplate to get capabilities of.
370 * Gets the capabilities of the pad template.
372 * Returns: (transfer full): the #GstCaps of the pad template.
376 gst_pad_template_get_caps (GstPadTemplate * templ)
379 g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
381 caps = GST_PAD_TEMPLATE_CAPS (templ);
383 return (caps ? gst_caps_ref (caps) : NULL);
387 * gst_pad_template_pad_created:
388 * @templ: a #GstPadTemplate that has been created
389 * @pad: the #GstPad that created it
391 * Emit the pad-created signal for this template when created by this pad.
394 gst_pad_template_pad_created (GstPadTemplate * templ, GstPad * pad)
396 g_signal_emit (templ, gst_pad_template_signals[TEMPL_PAD_CREATED], 0, pad);
400 gst_pad_template_set_property (GObject * object, guint prop_id,
401 const GValue * value, GParamSpec * pspec)
403 /* these properties are all construct-only */
405 case PROP_NAME_TEMPLATE:
406 GST_PAD_TEMPLATE_NAME_TEMPLATE (object) = g_value_dup_string (value);
409 GST_PAD_TEMPLATE_DIRECTION (object) =
410 (GstPadDirection) g_value_get_enum (value);
413 GST_PAD_TEMPLATE_PRESENCE (object) =
414 (GstPadPresence) g_value_get_enum (value);
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);
425 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
431 gst_pad_template_get_property (GObject * object, guint prop_id, GValue * value,
434 /* these properties are all construct-only */
436 case PROP_NAME_TEMPLATE:
437 g_value_set_string (value, GST_PAD_TEMPLATE_NAME_TEMPLATE (object));
440 g_value_set_enum (value, GST_PAD_TEMPLATE_DIRECTION (object));
443 g_value_set_enum (value, GST_PAD_TEMPLATE_PRESENCE (object));
446 g_value_set_boxed (value, GST_PAD_TEMPLATE_CAPS (object));
449 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);