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., 59 Temple Place - Suite 330,
20 * Boston, MA 02111-1307, 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_request_pad_by_name()
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_pad_template ()).
56 * The following code example shows the code to create a pad from a padtemplate.
58 * <title>Create a pad from a padtemplate</title>
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
67 * "channels = (int) [ 1, 6 ]"
74 * pad = gst_pad_new_from_static_template (&my_template, "sink");
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:
85 * my_element_base_init (gpointer g_class)
87 * GstElementClass *gstelement_class = GST_ELEMENT_CLASS (g_class);
89 * gst_element_class_add_pad_template (gstelement_class,
90 * gst_static_pad_template_get (&my_template));
95 * Last reviewed on 2006-02-14 (0.10.3)
98 #include "gst_private.h"
101 #include "gstpadtemplate.h"
102 #include "gstenumtypes.h"
103 #include "gstmarshal.h"
104 #include "gstutils.h"
106 #include "gsterror.h"
107 #include "gstvalue.h"
109 #define GST_CAT_DEFAULT GST_CAT_PADS
113 PROP_NAME_TEMPLATE = 1,
126 static GstObject *parent_class = NULL;
127 static guint gst_pad_template_signals[LAST_SIGNAL] = { 0 };
129 static void gst_pad_template_class_init (GstPadTemplateClass * klass);
130 static void gst_pad_template_init (GstPadTemplate * templ,
131 GstPadTemplateClass * klass);
132 static void gst_pad_template_dispose (GObject * object);
133 static void gst_pad_template_set_property (GObject * object, guint prop_id,
134 const GValue * value, GParamSpec * pspec);
135 static void gst_pad_template_get_property (GObject * object, guint prop_id,
136 GValue * value, GParamSpec * pspec);
139 gst_pad_template_get_type (void)
141 static GType padtemplate_type = 0;
143 if (G_UNLIKELY (padtemplate_type == 0)) {
144 static const GTypeInfo padtemplate_info = {
145 sizeof (GstPadTemplateClass), NULL, NULL,
146 (GClassInitFunc) gst_pad_template_class_init, NULL, NULL,
147 sizeof (GstPadTemplate),
149 (GInstanceInitFunc) gst_pad_template_init, NULL
153 g_type_register_static (GST_TYPE_OBJECT, "GstPadTemplate",
154 &padtemplate_info, 0);
156 return padtemplate_type;
160 gst_pad_template_class_init (GstPadTemplateClass * klass)
162 GObjectClass *gobject_class;
163 GstObjectClass *gstobject_class;
165 gobject_class = (GObjectClass *) klass;
166 gstobject_class = (GstObjectClass *) klass;
168 parent_class = g_type_class_peek_parent (klass);
171 * GstPadTemplate::pad-created:
172 * @pad_template: the object which received the signal.
173 * @pad: the pad that was created.
175 * This signal is fired when an element creates a pad from this template.
177 gst_pad_template_signals[TEMPL_PAD_CREATED] =
178 g_signal_new ("pad-created", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
179 G_STRUCT_OFFSET (GstPadTemplateClass, pad_created),
180 NULL, NULL, gst_marshal_VOID__OBJECT, G_TYPE_NONE, 1, GST_TYPE_PAD);
182 gobject_class->dispose = gst_pad_template_dispose;
184 gobject_class->get_property = gst_pad_template_get_property;
185 gobject_class->set_property = gst_pad_template_set_property;
188 * GstPadTemplate:name-template
190 * The name template of the pad template.
194 g_object_class_install_property (gobject_class, PROP_NAME_TEMPLATE,
195 g_param_spec_string ("name-template", "Name template",
196 "The name template of the pad template", NULL,
197 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
200 * GstPadTemplate:direction
202 * The direction of the pad described by the pad template.
206 g_object_class_install_property (gobject_class, PROP_DIRECTION,
207 g_param_spec_enum ("direction", "Direction",
208 "The direction of the pad described by the pad template",
209 GST_TYPE_PAD_DIRECTION, GST_PAD_UNKNOWN,
210 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
213 * GstPadTemplate:presence
215 * When the pad described by the pad template will become available.
219 g_object_class_install_property (gobject_class, PROP_PRESENCE,
220 g_param_spec_enum ("presence", "Presence",
221 "When the pad described by the pad template will become available",
222 GST_TYPE_PAD_PRESENCE, GST_PAD_ALWAYS,
223 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
226 * GstPadTemplate:caps
228 * The capabilities of the pad described by the pad template.
232 g_object_class_install_property (gobject_class, PROP_CAPS,
233 g_param_spec_boxed ("caps", "Caps",
234 "The capabilities of the pad described by the pad template",
236 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
238 gstobject_class->path_string_separator = "*";
242 gst_pad_template_init (GstPadTemplate * templ, GstPadTemplateClass * klass)
244 /* FIXME 0.11: Does anybody remember why this is here? If not, let's
245 * change it for 0.11 and let gst_element_class_add_pad_template() for
246 * example ref/sink the pad templates.
248 /* We ensure that the pad template we're creating has a sunken reference.
249 * Inconsistencies in pad templates being floating or sunken has caused
250 * problems in the past with leaks, etc.
252 * For consistency, then, we only produce them with sunken references
253 * owned by the creator of the object
255 if (GST_OBJECT_IS_FLOATING (templ)) {
256 gst_object_ref (templ);
257 gst_object_sink (templ);
262 gst_pad_template_dispose (GObject * object)
264 GstPadTemplate *templ = GST_PAD_TEMPLATE (object);
266 g_free (GST_PAD_TEMPLATE_NAME_TEMPLATE (templ));
267 if (GST_PAD_TEMPLATE_CAPS (templ)) {
268 gst_caps_unref (GST_PAD_TEMPLATE_CAPS (templ));
271 G_OBJECT_CLASS (parent_class)->dispose (object);
274 /* ALWAYS padtemplates cannot have conversion specifications (like src_%d),
275 * since it doesn't make sense.
276 * SOMETIMES padtemplates can do whatever they want, they are provided by the
278 * REQUEST padtemplates can be reverse-parsed (the user asks for 'sink1', the
279 * 'sink%d' template is automatically selected), so we need to restrict their
283 name_is_valid (const gchar * name, GstPadPresence presence)
287 if (presence == GST_PAD_ALWAYS) {
288 if (strchr (name, '%')) {
289 g_warning ("invalid name template %s: conversion specifications are not"
290 " allowed for GST_PAD_ALWAYS padtemplates", name);
293 } else if (presence == GST_PAD_REQUEST) {
294 if ((str = strchr (name, '%')) && strchr (str + 1, '%')) {
295 g_warning ("invalid name template %s: only one conversion specification"
296 " allowed in GST_PAD_REQUEST padtemplate", name);
299 if (str && (*(str + 1) != 's' && *(str + 1) != 'd')) {
300 g_warning ("invalid name template %s: conversion specification must be of"
301 " type '%%d' or '%%s' for GST_PAD_REQUEST padtemplate", name);
304 if (str && (*(str + 2) != '\0')) {
305 g_warning ("invalid name template %s: conversion specification must"
306 " appear at the end of the GST_PAD_REQUEST padtemplate name", name);
315 gst_static_pad_template_get_type (void)
317 static GType staticpadtemplate_type = 0;
319 if (G_UNLIKELY (staticpadtemplate_type == 0)) {
320 staticpadtemplate_type =
321 g_pointer_type_register_static ("GstStaticPadTemplate");
323 return staticpadtemplate_type;
327 * gst_static_pad_template_get:
328 * @pad_template: the static pad template
330 * Converts a #GstStaticPadTemplate into a #GstPadTemplate.
332 * Returns: a new #GstPadTemplate.
335 gst_static_pad_template_get (GstStaticPadTemplate * pad_template)
340 if (!name_is_valid (pad_template->name_template, pad_template->presence))
343 caps = gst_static_caps_get (&pad_template->static_caps);
345 new = g_object_new (gst_pad_template_get_type (),
346 "name", pad_template->name_template,
347 "name-template", pad_template->name_template,
348 "direction", pad_template->direction,
349 "presence", pad_template->presence, "caps", caps, NULL);
351 gst_caps_unref (caps);
357 * gst_pad_template_new:
358 * @name_template: the name template.
359 * @direction: the #GstPadDirection of the template.
360 * @presence: the #GstPadPresence of the pad.
361 * @caps: a #GstCaps set for the template. The caps are taken ownership of.
363 * Creates a new pad template with a name according to the given template
364 * and with the given arguments. This functions takes ownership of the provided
365 * caps, so be sure to not use them afterwards.
367 * Returns: a new #GstPadTemplate.
370 gst_pad_template_new (const gchar * name_template,
371 GstPadDirection direction, GstPadPresence presence, GstCaps * caps)
375 g_return_val_if_fail (name_template != NULL, NULL);
376 g_return_val_if_fail (caps != NULL, NULL);
377 g_return_val_if_fail (direction == GST_PAD_SRC
378 || direction == GST_PAD_SINK, NULL);
379 g_return_val_if_fail (presence == GST_PAD_ALWAYS
380 || presence == GST_PAD_SOMETIMES || presence == GST_PAD_REQUEST, NULL);
382 if (!name_is_valid (name_template, presence)) {
383 gst_caps_unref (caps);
387 new = g_object_new (gst_pad_template_get_type (),
388 "name", name_template, "name-template", name_template,
389 "direction", direction, "presence", presence, "caps", caps, NULL);
392 /* FIXME: enable this after gst-ffmpeg-0.10.6 and
393 * gst-plugins-good-0.10.11 have been released. Previous versions
394 * depend on broken core behavior. */
396 gst_caps_unref (caps);
403 * gst_static_pad_template_get_caps:
404 * @templ: a #GstStaticPadTemplate to get capabilities of.
406 * Gets the capabilities of the static pad template.
408 * Returns: the #GstCaps of the static pad template. If you need to keep a
409 * reference to the caps, take a ref (see gst_caps_ref ()).
412 gst_static_pad_template_get_caps (GstStaticPadTemplate * templ)
414 g_return_val_if_fail (templ, NULL);
416 return (GstCaps *) gst_static_caps_get (&templ->static_caps);
420 * gst_pad_template_get_caps:
421 * @templ: a #GstPadTemplate to get capabilities of.
423 * Gets the capabilities of the pad template.
425 * Returns: the #GstCaps of the pad template. If you need to keep a reference to
426 * the caps, take a ref (see gst_caps_ref ()).
429 gst_pad_template_get_caps (GstPadTemplate * templ)
431 g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
433 return GST_PAD_TEMPLATE_CAPS (templ);
437 * gst_pad_template_pad_created:
438 * @templ: a #GstPadTemplate that has been created
439 * @pad: the #GstPad that created it
441 * Emit the pad-created signal for this template when created by this pad.
444 gst_pad_template_pad_created (GstPadTemplate * templ, GstPad * pad)
446 g_signal_emit (G_OBJECT (templ),
447 gst_pad_template_signals[TEMPL_PAD_CREATED], 0, pad);
451 gst_pad_template_set_property (GObject * object, guint prop_id,
452 const GValue * value, GParamSpec * pspec)
454 /* these properties are all construct-only */
456 case PROP_NAME_TEMPLATE:
457 GST_PAD_TEMPLATE_NAME_TEMPLATE (object) = g_value_dup_string (value);
460 GST_PAD_TEMPLATE_DIRECTION (object) = g_value_get_enum (value);
463 GST_PAD_TEMPLATE_PRESENCE (object) = g_value_get_enum (value);
466 /* allow caps == NULL for backwards compatibility (ie. g_object_new()
467 * called without any of the new properties) (FIXME 0.11) */
468 if (g_value_get_boxed (value) != NULL) {
469 GST_PAD_TEMPLATE_CAPS (object) =
470 gst_caps_copy (g_value_get_boxed (value));
474 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
480 gst_pad_template_get_property (GObject * object, guint prop_id, GValue * value,
483 /* these properties are all construct-only */
485 case PROP_NAME_TEMPLATE:
486 g_value_set_string (value, GST_PAD_TEMPLATE_NAME_TEMPLATE (object));
489 g_value_set_enum (value, GST_PAD_TEMPLATE_DIRECTION (object));
492 g_value_set_enum (value, GST_PAD_TEMPLATE_PRESENCE (object));
495 g_value_set_boxed (value, GST_PAD_TEMPLATE_CAPS (object));
498 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);