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., 51 Franklin St, Fifth Floor,
20 * Boston, MA 02110-1301, USA.
21 */
22
23 /**
24 * SECTION:gstpadtemplate
25 * @title: GstPadTemplate
26 * @short_description: Describe the media type of a pad.
27 * @see_also: #GstPad, #GstElementFactory
28 *
29 * Padtemplates describe the possible media types a pad or an elementfactory can
30 * handle. This allows for both inspection of handled types before loading the
31 * element plugin as well as identifying pads on elements that are not yet
32 * created (request or sometimes pads).
33 *
34 * Pad and PadTemplates have #GstCaps attached to it to describe the media type
35 * they are capable of dealing with. gst_pad_template_get_caps() or
36 * GST_PAD_TEMPLATE_CAPS() are used to get the caps of a padtemplate. It's not
37 * possible to modify the caps of a padtemplate after creation.
38 *
39 * PadTemplates have a #GstPadPresence property which identifies the lifetime
40 * of the pad and that can be retrieved with GST_PAD_TEMPLATE_PRESENCE(). Also
41 * the direction of the pad can be retrieved from the #GstPadTemplate with
42 * GST_PAD_TEMPLATE_DIRECTION().
43 *
44 * The GST_PAD_TEMPLATE_NAME_TEMPLATE () is important for GST_PAD_REQUEST pads
45 * because it has to be used as the name in the gst_element_get_request_pad()
46 * call to instantiate a pad from this template.
47 *
48 * Padtemplates can be created with gst_pad_template_new() or with
49 * gst_static_pad_template_get (), which creates a #GstPadTemplate from a
50 * #GstStaticPadTemplate that can be filled with the
51 * convenient GST_STATIC_PAD_TEMPLATE() macro.
52 *
53 * A padtemplate can be used to create a pad (see gst_pad_new_from_template()
54 * or gst_pad_new_from_static_template ()) or to add to an element class
55 * (see gst_element_class_add_static_pad_template ()).
56 *
57 * The following code example shows the code to create a pad from a padtemplate.
58 * |[<!-- language="C" -->
59 * GstStaticPadTemplate my_template =
60 * GST_STATIC_PAD_TEMPLATE (
61 * "sink", // the name of the pad
62 * GST_PAD_SINK, // the direction of the pad
63 * GST_PAD_ALWAYS, // when this pad will be present
64 * GST_STATIC_CAPS ( // the capabilities of the padtemplate
65 * "audio/x-raw, "
66 * "channels = (int) [ 1, 6 ]"
67 * )
68 * );
69 * void
70 * my_method (void)
71 * {
72 * GstPad *pad;
73 * pad = gst_pad_new_from_static_template (&my_template, "sink");
74 * ...
75 * }
76 * ]|
77 *
78 * The following example shows you how to add the padtemplate to an
79 * element class, this is usually done in the class_init of the class:
80 * |[<!-- language="C" -->
81 * static void
82 * my_element_class_init (GstMyElementClass *klass)
83 * {
84 * GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);
85 *
86 * gst_element_class_add_static_pad_template (gstelement_class, &my_template);
87 * }
88 * ]|
89 */
90
91 #include "gst_private.h"
92
93 #include "gstpad.h"
94 #include "gstpadtemplate.h"
95 #include "gstenumtypes.h"
96 #include "gstutils.h"
97 #include "gstinfo.h"
98 #include "gsterror.h"
99 #include "gstvalue.h"
100
101 #define GST_CAT_DEFAULT GST_CAT_PADS
102
103 enum
104 {
105 PROP_NAME_TEMPLATE = 1,
106 PROP_DIRECTION,
107 PROP_PRESENCE,
108 PROP_CAPS,
109 PROP_GTYPE,
110 };
111
112 enum
113 {
114 TEMPL_PAD_CREATED,
115 /* FILL ME */
116 LAST_SIGNAL
117 };
118
119 static guint gst_pad_template_signals[LAST_SIGNAL] = { 0 };
120
121 static void gst_pad_template_dispose (GObject * object);
122 static void gst_pad_template_set_property (GObject * object, guint prop_id,
123 const GValue * value, GParamSpec * pspec);
124 static void gst_pad_template_get_property (GObject * object, guint prop_id,
125 GValue * value, GParamSpec * pspec);
126
127 #define gst_pad_template_parent_class parent_class
128 G_DEFINE_TYPE (GstPadTemplate, gst_pad_template, GST_TYPE_OBJECT);
129
130 static void
gst_pad_template_class_init(GstPadTemplateClass * klass)131 gst_pad_template_class_init (GstPadTemplateClass * klass)
132 {
133 GObjectClass *gobject_class;
134 GstObjectClass *gstobject_class;
135
136 gobject_class = (GObjectClass *) klass;
137 gstobject_class = (GstObjectClass *) klass;
138
139 /**
140 * GstPadTemplate::pad-created:
141 * @pad_template: the object which received the signal.
142 * @pad: the pad that was created.
143 *
144 * This signal is fired when an element creates a pad from this template.
145 */
146 gst_pad_template_signals[TEMPL_PAD_CREATED] =
147 g_signal_new ("pad-created", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST,
148 G_STRUCT_OFFSET (GstPadTemplateClass, pad_created),
149 NULL, NULL, g_cclosure_marshal_generic, G_TYPE_NONE, 1, GST_TYPE_PAD);
150
151 gobject_class->dispose = gst_pad_template_dispose;
152
153 gobject_class->get_property = gst_pad_template_get_property;
154 gobject_class->set_property = gst_pad_template_set_property;
155
156 /**
157 * GstPadTemplate:name-template:
158 *
159 * The name template of the pad template.
160 */
161 g_object_class_install_property (gobject_class, PROP_NAME_TEMPLATE,
162 g_param_spec_string ("name-template", "Name template",
163 "The name template of the pad template", NULL,
164 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
165
166 /**
167 * GstPadTemplate:direction:
168 *
169 * The direction of the pad described by the pad template.
170 */
171 g_object_class_install_property (gobject_class, PROP_DIRECTION,
172 g_param_spec_enum ("direction", "Direction",
173 "The direction of the pad described by the pad template",
174 GST_TYPE_PAD_DIRECTION, GST_PAD_UNKNOWN,
175 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
176
177 /**
178 * GstPadTemplate:presence:
179 *
180 * When the pad described by the pad template will become available.
181 */
182 g_object_class_install_property (gobject_class, PROP_PRESENCE,
183 g_param_spec_enum ("presence", "Presence",
184 "When the pad described by the pad template will become available",
185 GST_TYPE_PAD_PRESENCE, GST_PAD_ALWAYS,
186 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
187
188 /**
189 * GstPadTemplate:caps:
190 *
191 * The capabilities of the pad described by the pad template.
192 */
193 g_object_class_install_property (gobject_class, PROP_CAPS,
194 g_param_spec_boxed ("caps", "Caps",
195 "The capabilities of the pad described by the pad template",
196 GST_TYPE_CAPS,
197 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
198
199 /**
200 * GstPadTemplate:gtype:
201 *
202 * The type of the pad described by the pad template.
203 *
204 * Since: 1.14
205 */
206 g_object_class_install_property (gobject_class, PROP_GTYPE,
207 g_param_spec_gtype ("gtype", "GType",
208 "The GType of the pad described by the pad template",
209 G_TYPE_NONE,
210 G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
211
212 gstobject_class->path_string_separator = "*";
213 }
214
215 static void
gst_pad_template_init(GstPadTemplate * templ)216 gst_pad_template_init (GstPadTemplate * templ)
217 {
218 /* GstPadTemplate objects are usually leaked */
219 GST_OBJECT_FLAG_SET (templ, GST_OBJECT_FLAG_MAY_BE_LEAKED);
220 GST_PAD_TEMPLATE_GTYPE (templ) = G_TYPE_NONE;
221 }
222
223 static void
gst_pad_template_dispose(GObject * object)224 gst_pad_template_dispose (GObject * object)
225 {
226 GstPadTemplate *templ = GST_PAD_TEMPLATE (object);
227
228 g_free (GST_PAD_TEMPLATE_NAME_TEMPLATE (templ));
229 if (GST_PAD_TEMPLATE_CAPS (templ)) {
230 gst_caps_unref (GST_PAD_TEMPLATE_CAPS (templ));
231 }
232
233 G_OBJECT_CLASS (parent_class)->dispose (object);
234 }
235
236 /* ALWAYS padtemplates cannot have conversion specifications (like src_%d),
237 * since it doesn't make sense.
238 * SOMETIMES padtemplates can do whatever they want, they are provided by the
239 * element.
240 * REQUEST padtemplates can have multiple specifiers in case of %d and %u, like
241 * src_%u_%u, but %s only can be used once in the template.
242 */
243 static gboolean
name_is_valid(const gchar * name,GstPadPresence presence)244 name_is_valid (const gchar * name, GstPadPresence presence)
245 {
246 const gchar *str, *underscore = NULL;
247 gboolean has_s = FALSE;
248
249 if (presence == GST_PAD_ALWAYS) {
250 if (strchr (name, '%')) {
251 g_warning ("invalid name template %s: conversion specifications are not"
252 " allowed for GST_PAD_ALWAYS padtemplates", name);
253 return FALSE;
254 }
255 } else if (presence == GST_PAD_REQUEST) {
256 str = strchr (name, '%');
257
258 while (str) {
259 if (*(str + 1) != 's' && *(str + 1) != 'd' && *(str + 1) != 'u') {
260 g_warning
261 ("invalid name template %s: conversion specification must be of"
262 " type '%%d', '%%u' or '%%s' for GST_PAD_REQUEST padtemplate",
263 name);
264 return FALSE;
265 }
266
267 if (*(str + 1) == 's' && (*(str + 2) != '\0' || has_s)) {
268 g_warning
269 ("invalid name template %s: conversion specification of type '%%s'"
270 "only can be used once in the GST_PAD_REQUEST padtemplate at the "
271 "very end and not allowed any other characters with '%%s'", name);
272 return FALSE;
273 }
274
275 if (*(str + 1) == 's') {
276 has_s = TRUE;
277 }
278
279 underscore = strchr (str, '_');
280 str = strchr (str + 1, '%');
281
282 if (str && (!underscore || str < underscore)) {
283 g_warning
284 ("invalid name template %s: each of conversion specifications "
285 "must be separated by an underscore", name);
286 return FALSE;
287 }
288 }
289 }
290
291 return TRUE;
292 }
293
294 G_DEFINE_POINTER_TYPE (GstStaticPadTemplate, gst_static_pad_template);
295
296 /**
297 * gst_static_pad_template_get:
298 * @pad_template: the static pad template
299 *
300 * Converts a #GstStaticPadTemplate into a #GstPadTemplate.
301 *
302 * Returns: (transfer floating) (nullable): a new #GstPadTemplate.
303 */
304 /* FIXME0.11: rename to gst_pad_template_new_from_static_pad_template() */
305 GstPadTemplate *
gst_static_pad_template_get(GstStaticPadTemplate * pad_template)306 gst_static_pad_template_get (GstStaticPadTemplate * pad_template)
307 {
308 GstPadTemplate *new;
309 GstCaps *caps;
310
311 if (!name_is_valid (pad_template->name_template, pad_template->presence))
312 return NULL;
313
314 caps = gst_static_caps_get (&pad_template->static_caps);
315
316 new = g_object_new (gst_pad_template_get_type (),
317 "name", pad_template->name_template,
318 "name-template", pad_template->name_template,
319 "direction", pad_template->direction,
320 "presence", pad_template->presence, "caps", caps, NULL);
321
322 gst_caps_unref (caps);
323
324 return new;
325 }
326
327 /**
328 * gst_pad_template_new_from_static_pad_template_with_gtype:
329 * @pad_template: the static pad template
330 * @pad_type: The #GType of the pad to create
331 *
332 * Converts a #GstStaticPadTemplate into a #GstPadTemplate with a type.
333 *
334 * Returns: (transfer floating) (nullable): a new #GstPadTemplate.
335 *
336 * Since: 1.14
337 */
338 GstPadTemplate *
gst_pad_template_new_from_static_pad_template_with_gtype(GstStaticPadTemplate * pad_template,GType pad_type)339 gst_pad_template_new_from_static_pad_template_with_gtype (GstStaticPadTemplate *
340 pad_template, GType pad_type)
341 {
342 GstPadTemplate *new;
343 GstCaps *caps;
344
345 g_return_val_if_fail (g_type_is_a (pad_type, GST_TYPE_PAD), NULL);
346
347 if (!name_is_valid (pad_template->name_template, pad_template->presence))
348 return NULL;
349
350 caps = gst_static_caps_get (&pad_template->static_caps);
351
352 new = g_object_new (gst_pad_template_get_type (),
353 "name", pad_template->name_template,
354 "name-template", pad_template->name_template,
355 "direction", pad_template->direction,
356 "presence", pad_template->presence, "caps", caps, "gtype", pad_type,
357 NULL);
358
359 gst_caps_unref (caps);
360
361 return new;
362 }
363
364 /**
365 * gst_pad_template_new:
366 * @name_template: the name template.
367 * @direction: the #GstPadDirection of the template.
368 * @presence: the #GstPadPresence of the pad.
369 * @caps: (transfer none): a #GstCaps set for the template.
370 *
371 * Creates a new pad template with a name according to the given template
372 * and with the given arguments.
373 *
374 * Returns: (transfer floating) (nullable): a new #GstPadTemplate.
375 */
376 GstPadTemplate *
gst_pad_template_new(const gchar * name_template,GstPadDirection direction,GstPadPresence presence,GstCaps * caps)377 gst_pad_template_new (const gchar * name_template,
378 GstPadDirection direction, GstPadPresence presence, GstCaps * caps)
379 {
380 GstPadTemplate *new;
381
382 g_return_val_if_fail (name_template != NULL, NULL);
383 g_return_val_if_fail (caps != NULL, NULL);
384 g_return_val_if_fail (direction == GST_PAD_SRC
385 || direction == GST_PAD_SINK, NULL);
386 g_return_val_if_fail (presence == GST_PAD_ALWAYS
387 || presence == GST_PAD_SOMETIMES || presence == GST_PAD_REQUEST, NULL);
388
389 if (!name_is_valid (name_template, presence)) {
390 return NULL;
391 }
392
393 new = g_object_new (gst_pad_template_get_type (),
394 "name", name_template, "name-template", name_template,
395 "direction", direction, "presence", presence, "caps", caps, NULL);
396
397 return new;
398 }
399
400 /**
401 * gst_pad_template_new_with_gtype:
402 * @name_template: the name template.
403 * @direction: the #GstPadDirection of the template.
404 * @presence: the #GstPadPresence of the pad.
405 * @caps: (transfer none): a #GstCaps set for the template.
406 * @pad_type: The #GType of the pad to create
407 *
408 * Creates a new pad template with a name according to the given template
409 * and with the given arguments.
410 *
411 * Returns: (transfer floating) (nullable): a new #GstPadTemplate.
412 *
413 * Since: 1.14
414 */
415 GstPadTemplate *
gst_pad_template_new_with_gtype(const gchar * name_template,GstPadDirection direction,GstPadPresence presence,GstCaps * caps,GType pad_type)416 gst_pad_template_new_with_gtype (const gchar * name_template,
417 GstPadDirection direction, GstPadPresence presence, GstCaps * caps,
418 GType pad_type)
419 {
420 GstPadTemplate *new;
421
422 g_return_val_if_fail (name_template != NULL, NULL);
423 g_return_val_if_fail (caps != NULL, NULL);
424 g_return_val_if_fail (direction == GST_PAD_SRC
425 || direction == GST_PAD_SINK, NULL);
426 g_return_val_if_fail (presence == GST_PAD_ALWAYS
427 || presence == GST_PAD_SOMETIMES || presence == GST_PAD_REQUEST, NULL);
428 g_return_val_if_fail (g_type_is_a (pad_type, GST_TYPE_PAD), NULL);
429
430 if (!name_is_valid (name_template, presence)) {
431 return NULL;
432 }
433
434 new = g_object_new (gst_pad_template_get_type (),
435 "name", name_template, "name-template", name_template,
436 "direction", direction, "presence", presence, "caps", caps,
437 "gtype", pad_type, NULL);
438
439 return new;
440 }
441
442 /**
443 * gst_static_pad_template_get_caps:
444 * @templ: a #GstStaticPadTemplate to get capabilities of.
445 *
446 * Gets the capabilities of the static pad template.
447 *
448 * Returns: (transfer full): the #GstCaps of the static pad template.
449 * Unref after usage. Since the core holds an additional
450 * ref to the returned caps, use gst_caps_make_writable()
451 * on the returned caps to modify it.
452 */
453 GstCaps *
gst_static_pad_template_get_caps(GstStaticPadTemplate * templ)454 gst_static_pad_template_get_caps (GstStaticPadTemplate * templ)
455 {
456 g_return_val_if_fail (templ, NULL);
457
458 return gst_static_caps_get (&templ->static_caps);
459 }
460
461 /**
462 * gst_pad_template_get_caps:
463 * @templ: a #GstPadTemplate to get capabilities of.
464 *
465 * Gets the capabilities of the pad template.
466 *
467 * Returns: (transfer full): the #GstCaps of the pad template.
468 * Unref after usage.
469 */
470 GstCaps *
gst_pad_template_get_caps(GstPadTemplate * templ)471 gst_pad_template_get_caps (GstPadTemplate * templ)
472 {
473 GstCaps *caps;
474 g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
475
476 caps = GST_PAD_TEMPLATE_CAPS (templ);
477
478 return (caps ? gst_caps_ref (caps) : NULL);
479 }
480
481 /**
482 * gst_pad_template_pad_created:
483 * @templ: a #GstPadTemplate that has been created
484 * @pad: the #GstPad that created it
485 *
486 * Emit the pad-created signal for this template when created by this pad.
487 */
488 void
gst_pad_template_pad_created(GstPadTemplate * templ,GstPad * pad)489 gst_pad_template_pad_created (GstPadTemplate * templ, GstPad * pad)
490 {
491 g_signal_emit (templ, gst_pad_template_signals[TEMPL_PAD_CREATED], 0, pad);
492 }
493
494 static void
gst_pad_template_set_property(GObject * object,guint prop_id,const GValue * value,GParamSpec * pspec)495 gst_pad_template_set_property (GObject * object, guint prop_id,
496 const GValue * value, GParamSpec * pspec)
497 {
498 /* these properties are all construct-only */
499 switch (prop_id) {
500 case PROP_NAME_TEMPLATE:
501 GST_PAD_TEMPLATE_NAME_TEMPLATE (object) = g_value_dup_string (value);
502 break;
503 case PROP_DIRECTION:
504 GST_PAD_TEMPLATE_DIRECTION (object) =
505 (GstPadDirection) g_value_get_enum (value);
506 break;
507 case PROP_PRESENCE:
508 GST_PAD_TEMPLATE_PRESENCE (object) =
509 (GstPadPresence) g_value_get_enum (value);
510 break;
511 case PROP_CAPS:
512 GST_PAD_TEMPLATE_CAPS (object) = g_value_dup_boxed (value);
513 if (GST_PAD_TEMPLATE_CAPS (object) != NULL) {
514 /* GstPadTemplate are usually leaked so are their caps */
515 GST_MINI_OBJECT_FLAG_SET (GST_PAD_TEMPLATE_CAPS (object),
516 GST_MINI_OBJECT_FLAG_MAY_BE_LEAKED);
517 }
518 break;
519 case PROP_GTYPE:
520 GST_PAD_TEMPLATE_GTYPE (object) = g_value_get_gtype (value);
521 break;
522 default:
523 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
524 break;
525 }
526 }
527
528 static void
gst_pad_template_get_property(GObject * object,guint prop_id,GValue * value,GParamSpec * pspec)529 gst_pad_template_get_property (GObject * object, guint prop_id, GValue * value,
530 GParamSpec * pspec)
531 {
532 /* these properties are all construct-only */
533 switch (prop_id) {
534 case PROP_NAME_TEMPLATE:
535 g_value_set_string (value, GST_PAD_TEMPLATE_NAME_TEMPLATE (object));
536 break;
537 case PROP_DIRECTION:
538 g_value_set_enum (value, GST_PAD_TEMPLATE_DIRECTION (object));
539 break;
540 case PROP_PRESENCE:
541 g_value_set_enum (value, GST_PAD_TEMPLATE_PRESENCE (object));
542 break;
543 case PROP_CAPS:
544 g_value_set_boxed (value, GST_PAD_TEMPLATE_CAPS (object));
545 break;
546 case PROP_GTYPE:
547 g_value_set_gtype (value, GST_PAD_TEMPLATE_GTYPE (object));
548 break;
549 default:
550 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
551 break;
552 }
553 }
554