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_request_pad_simple()
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, NULL, 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 gst_caps_replace (&templ->ABI.abi.documentation_caps, NULL);
234
235 G_OBJECT_CLASS (parent_class)->dispose (object);
236 }
237
238 /* ALWAYS padtemplates cannot have conversion specifications (like src_%d),
239 * since it doesn't make sense.
240 * SOMETIMES padtemplates can do whatever they want, they are provided by the
241 * element.
242 * REQUEST padtemplates can have multiple specifiers in case of %d and %u, like
243 * src_%u_%u, but %s only can be used once in the template.
244 */
245 static gboolean
name_is_valid(const gchar * name,GstPadPresence presence)246 name_is_valid (const gchar * name, GstPadPresence presence)
247 {
248 const gchar *str, *underscore = NULL;
249 gboolean has_s = FALSE;
250
251 if (presence == GST_PAD_ALWAYS) {
252 if (strchr (name, '%')) {
253 g_warning ("invalid name template %s: conversion specifications are not"
254 " allowed for GST_PAD_ALWAYS padtemplates", name);
255 return FALSE;
256 }
257 } else if (presence == GST_PAD_REQUEST) {
258 str = strchr (name, '%');
259
260 while (str) {
261 if (*(str + 1) != 's' && *(str + 1) != 'd' && *(str + 1) != 'u') {
262 g_warning
263 ("invalid name template %s: conversion specification must be of"
264 " type '%%d', '%%u' or '%%s' for GST_PAD_REQUEST padtemplate",
265 name);
266 return FALSE;
267 }
268
269 if (*(str + 1) == 's' && (*(str + 2) != '\0' || has_s)) {
270 g_warning
271 ("invalid name template %s: conversion specification of type '%%s'"
272 "only can be used once in the GST_PAD_REQUEST padtemplate at the "
273 "very end and not allowed any other characters with '%%s'", name);
274 return FALSE;
275 }
276
277 if (*(str + 1) == 's') {
278 has_s = TRUE;
279 }
280
281 underscore = strchr (str, '_');
282 str = strchr (str + 1, '%');
283
284 if (str && (!underscore || str < underscore)) {
285 g_warning
286 ("invalid name template %s: each of conversion specifications "
287 "must be separated by an underscore", name);
288 return FALSE;
289 }
290 }
291 }
292
293 return TRUE;
294 }
295
296 G_DEFINE_POINTER_TYPE (GstStaticPadTemplate, gst_static_pad_template);
297
298 /**
299 * gst_static_pad_template_get:
300 * @pad_template: the static pad template
301 *
302 * Converts a #GstStaticPadTemplate into a #GstPadTemplate.
303 *
304 * Returns: (transfer floating) (nullable): a new #GstPadTemplate.
305 */
306 /* FIXME0.11: rename to gst_pad_template_new_from_static_pad_template() */
307 GstPadTemplate *
gst_static_pad_template_get(GstStaticPadTemplate * pad_template)308 gst_static_pad_template_get (GstStaticPadTemplate * pad_template)
309 {
310 GstPadTemplate *new;
311 GstCaps *caps;
312
313 if (!name_is_valid (pad_template->name_template, pad_template->presence))
314 return NULL;
315
316 caps = gst_static_caps_get (&pad_template->static_caps);
317
318 new = g_object_new (gst_pad_template_get_type (),
319 "name", pad_template->name_template,
320 "name-template", pad_template->name_template,
321 "direction", pad_template->direction,
322 "presence", pad_template->presence, "caps", caps, NULL);
323
324 gst_caps_unref (caps);
325
326 return new;
327 }
328
329 /**
330 * gst_pad_template_new_from_static_pad_template_with_gtype:
331 * @pad_template: the static pad template
332 * @pad_type: The #GType of the pad to create
333 *
334 * Converts a #GstStaticPadTemplate into a #GstPadTemplate with a type.
335 *
336 * Returns: (transfer floating) (nullable): a new #GstPadTemplate.
337 *
338 * Since: 1.14
339 */
340 GstPadTemplate *
gst_pad_template_new_from_static_pad_template_with_gtype(GstStaticPadTemplate * pad_template,GType pad_type)341 gst_pad_template_new_from_static_pad_template_with_gtype (GstStaticPadTemplate *
342 pad_template, GType pad_type)
343 {
344 GstPadTemplate *new;
345 GstCaps *caps;
346
347 g_return_val_if_fail (g_type_is_a (pad_type, GST_TYPE_PAD), NULL);
348
349 if (!name_is_valid (pad_template->name_template, pad_template->presence))
350 return NULL;
351
352 caps = gst_static_caps_get (&pad_template->static_caps);
353
354 new = g_object_new (gst_pad_template_get_type (),
355 "name", pad_template->name_template,
356 "name-template", pad_template->name_template,
357 "direction", pad_template->direction,
358 "presence", pad_template->presence, "caps", caps, "gtype", pad_type,
359 NULL);
360
361 gst_caps_unref (caps);
362
363 return new;
364 }
365
366 /**
367 * gst_pad_template_new:
368 * @name_template: the name template.
369 * @direction: the #GstPadDirection of the template.
370 * @presence: the #GstPadPresence of the pad.
371 * @caps: (transfer none): a #GstCaps set for the template.
372 *
373 * Creates a new pad template with a name according to the given template
374 * and with the given arguments.
375 *
376 * Returns: (transfer floating) (nullable): a new #GstPadTemplate.
377 */
378 GstPadTemplate *
gst_pad_template_new(const gchar * name_template,GstPadDirection direction,GstPadPresence presence,GstCaps * caps)379 gst_pad_template_new (const gchar * name_template,
380 GstPadDirection direction, GstPadPresence presence, GstCaps * caps)
381 {
382 GstPadTemplate *new;
383
384 g_return_val_if_fail (name_template != NULL, NULL);
385 g_return_val_if_fail (caps != NULL, NULL);
386 g_return_val_if_fail (direction == GST_PAD_SRC
387 || direction == GST_PAD_SINK, NULL);
388 g_return_val_if_fail (presence == GST_PAD_ALWAYS
389 || presence == GST_PAD_SOMETIMES || presence == GST_PAD_REQUEST, NULL);
390
391 if (!name_is_valid (name_template, presence)) {
392 return NULL;
393 }
394
395 new = g_object_new (gst_pad_template_get_type (),
396 "name", name_template, "name-template", name_template,
397 "direction", direction, "presence", presence, "caps", caps, NULL);
398
399 return new;
400 }
401
402 /**
403 * gst_pad_template_new_with_gtype:
404 * @name_template: the name template.
405 * @direction: the #GstPadDirection of the template.
406 * @presence: the #GstPadPresence of the pad.
407 * @caps: (transfer none): a #GstCaps set for the template.
408 * @pad_type: The #GType of the pad to create
409 *
410 * Creates a new pad template with a name according to the given template
411 * and with the given arguments.
412 *
413 * Returns: (transfer floating) (nullable): a new #GstPadTemplate.
414 *
415 * Since: 1.14
416 */
417 GstPadTemplate *
gst_pad_template_new_with_gtype(const gchar * name_template,GstPadDirection direction,GstPadPresence presence,GstCaps * caps,GType pad_type)418 gst_pad_template_new_with_gtype (const gchar * name_template,
419 GstPadDirection direction, GstPadPresence presence, GstCaps * caps,
420 GType pad_type)
421 {
422 GstPadTemplate *new;
423
424 g_return_val_if_fail (name_template != NULL, NULL);
425 g_return_val_if_fail (caps != NULL, NULL);
426 g_return_val_if_fail (direction == GST_PAD_SRC
427 || direction == GST_PAD_SINK, NULL);
428 g_return_val_if_fail (presence == GST_PAD_ALWAYS
429 || presence == GST_PAD_SOMETIMES || presence == GST_PAD_REQUEST, NULL);
430 g_return_val_if_fail (g_type_is_a (pad_type, GST_TYPE_PAD), NULL);
431
432 if (!name_is_valid (name_template, presence)) {
433 return NULL;
434 }
435
436 new = g_object_new (gst_pad_template_get_type (),
437 "name", name_template, "name-template", name_template,
438 "direction", direction, "presence", presence, "caps", caps,
439 "gtype", pad_type, NULL);
440
441 return new;
442 }
443
444 /**
445 * gst_static_pad_template_get_caps:
446 * @templ: a #GstStaticPadTemplate to get capabilities of.
447 *
448 * Gets the capabilities of the static pad template.
449 *
450 * Returns: (transfer full): the #GstCaps of the static pad template.
451 * Unref after usage. Since the core holds an additional
452 * ref to the returned caps, use gst_caps_make_writable()
453 * on the returned caps to modify it.
454 */
455 GstCaps *
gst_static_pad_template_get_caps(GstStaticPadTemplate * templ)456 gst_static_pad_template_get_caps (GstStaticPadTemplate * templ)
457 {
458 g_return_val_if_fail (templ, NULL);
459
460 return gst_static_caps_get (&templ->static_caps);
461 }
462
463 /**
464 * gst_pad_template_get_caps:
465 * @templ: a #GstPadTemplate to get capabilities of.
466 *
467 * Gets the capabilities of the pad template.
468 *
469 * Returns: (transfer full): the #GstCaps of the pad template.
470 * Unref after usage.
471 */
472 GstCaps *
gst_pad_template_get_caps(GstPadTemplate * templ)473 gst_pad_template_get_caps (GstPadTemplate * templ)
474 {
475 GstCaps *caps;
476 g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
477
478 caps = GST_PAD_TEMPLATE_CAPS (templ);
479
480 return (caps ? gst_caps_ref (caps) : NULL);
481 }
482
483 /**
484 * gst_pad_template_set_documentation_caps:
485 * @templ: the pad template to set documented capabilities on
486 * @caps: (transfer full): the documented capabilities
487 *
488 * Certain elements will dynamically construct the caps of their
489 * pad templates. In order not to let environment-specific information
490 * into the documentation, element authors should use this method to
491 * expose "stable" caps to the reader.
492 *
493 * Since: 1.18
494 */
495 void
gst_pad_template_set_documentation_caps(GstPadTemplate * templ,GstCaps * caps)496 gst_pad_template_set_documentation_caps (GstPadTemplate * templ, GstCaps * caps)
497 {
498 g_return_if_fail (GST_IS_PAD_TEMPLATE (templ));
499 g_return_if_fail (GST_IS_CAPS (caps));
500
501 if (caps)
502 GST_MINI_OBJECT_FLAG_SET (caps, GST_MINI_OBJECT_FLAG_MAY_BE_LEAKED);
503 gst_caps_replace (&(((GstPadTemplate *) (templ))->ABI.abi.documentation_caps),
504 caps);
505 }
506
507 /**
508 * gst_pad_template_get_documentation_caps:
509 * @templ: the pad template to get documented capabilities on
510 *
511 * See gst_pad_template_set_documentation_caps().
512 *
513 * Returns: The caps to document. For convenience, this will return
514 * gst_pad_template_get_caps() when no documentation caps were set.
515 * Since: 1.18
516 */
517 GstCaps *
gst_pad_template_get_documentation_caps(GstPadTemplate * templ)518 gst_pad_template_get_documentation_caps (GstPadTemplate * templ)
519 {
520 g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
521
522 if (((GstPadTemplate *) (templ))->ABI.abi.documentation_caps)
523 return gst_caps_ref (((GstPadTemplate *) (templ))->ABI.abi.
524 documentation_caps);
525 else
526 return gst_pad_template_get_caps (templ);
527 }
528
529 /**
530 * gst_pad_template_pad_created:
531 * @templ: a #GstPadTemplate that has been created
532 * @pad: the #GstPad that created it
533 *
534 * Emit the pad-created signal for this template when created by this pad.
535 */
536 void
gst_pad_template_pad_created(GstPadTemplate * templ,GstPad * pad)537 gst_pad_template_pad_created (GstPadTemplate * templ, GstPad * pad)
538 {
539 g_signal_emit (templ, gst_pad_template_signals[TEMPL_PAD_CREATED], 0, pad);
540 }
541
542 static void
gst_pad_template_set_property(GObject * object,guint prop_id,const GValue * value,GParamSpec * pspec)543 gst_pad_template_set_property (GObject * object, guint prop_id,
544 const GValue * value, GParamSpec * pspec)
545 {
546 /* these properties are all construct-only */
547 switch (prop_id) {
548 case PROP_NAME_TEMPLATE:
549 GST_PAD_TEMPLATE_NAME_TEMPLATE (object) = g_value_dup_string (value);
550 break;
551 case PROP_DIRECTION:
552 GST_PAD_TEMPLATE_DIRECTION (object) =
553 (GstPadDirection) g_value_get_enum (value);
554 break;
555 case PROP_PRESENCE:
556 GST_PAD_TEMPLATE_PRESENCE (object) =
557 (GstPadPresence) g_value_get_enum (value);
558 break;
559 case PROP_CAPS:
560 GST_PAD_TEMPLATE_CAPS (object) = g_value_dup_boxed (value);
561 if (GST_PAD_TEMPLATE_CAPS (object) != NULL) {
562 /* GstPadTemplate are usually leaked so are their caps */
563 GST_MINI_OBJECT_FLAG_SET (GST_PAD_TEMPLATE_CAPS (object),
564 GST_MINI_OBJECT_FLAG_MAY_BE_LEAKED);
565 }
566 break;
567 case PROP_GTYPE:
568 GST_PAD_TEMPLATE_GTYPE (object) = g_value_get_gtype (value);
569 break;
570 default:
571 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
572 break;
573 }
574 }
575
576 static void
gst_pad_template_get_property(GObject * object,guint prop_id,GValue * value,GParamSpec * pspec)577 gst_pad_template_get_property (GObject * object, guint prop_id, GValue * value,
578 GParamSpec * pspec)
579 {
580 /* these properties are all construct-only */
581 switch (prop_id) {
582 case PROP_NAME_TEMPLATE:
583 g_value_set_string (value, GST_PAD_TEMPLATE_NAME_TEMPLATE (object));
584 break;
585 case PROP_DIRECTION:
586 g_value_set_enum (value, GST_PAD_TEMPLATE_DIRECTION (object));
587 break;
588 case PROP_PRESENCE:
589 g_value_set_enum (value, GST_PAD_TEMPLATE_PRESENCE (object));
590 break;
591 case PROP_CAPS:
592 g_value_set_boxed (value, GST_PAD_TEMPLATE_CAPS (object));
593 break;
594 case PROP_GTYPE:
595 g_value_set_gtype (value, GST_PAD_TEMPLATE_GTYPE (object));
596 break;
597 default:
598 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
599 break;
600 }
601 }
602