2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2000 Wim Taymans <wtay@chello.be>
4 * 2002 Thomas Vander Stichele <thomas@apestaart.org>
6 * gstutils.c: Utility functions
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
18 * You should have received a copy of the GNU Library General Public
19 * License along with this library; if not, write to the
20 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21 * Boston, MA 02111-1307, USA.
26 * @short_description: Various utility functions
28 * When defining own plugins, use the GST_BOILERPLATE ease gobject creation.
31 #include "gst_private.h"
35 #include "gstghostpad.h"
41 #include "gst-i18n-lib.h"
45 * @mem: a pointer to the memory to dump
46 * @size: the size of the memory block to dump
48 * Dumps the memory block into a hex representation. Useful for debugging.
51 gst_util_dump_mem (const guchar * mem, guint size)
54 GString *string = g_string_sized_new (50);
55 GString *chars = g_string_sized_new (18);
59 if (g_ascii_isprint (mem[i]))
60 g_string_append_c (chars, mem[i]);
62 g_string_append_c (chars, '.');
64 g_string_append_printf (string, "%02x ", mem[i]);
69 if (j == 16 || i == size) {
70 g_print ("%08x (%p): %-48.48s %-16.16s\n", i - j, mem + i - j,
71 string->str, chars->str);
72 g_string_set_size (string, 0);
73 g_string_set_size (chars, 0);
77 g_string_free (string, TRUE);
78 g_string_free (chars, TRUE);
83 * gst_util_set_value_from_string:
84 * @value: the value to set
85 * @value_str: the string to get the value from
87 * Converts the string to the type of the value and
88 * sets the value with it.
90 * Note that this function is dangerous as it does not return any indication
91 * if the conversion worked or not.
94 gst_util_set_value_from_string (GValue * value, const gchar * value_str)
98 g_return_if_fail (value != NULL);
99 g_return_if_fail (value_str != NULL);
101 GST_CAT_DEBUG (GST_CAT_PARAMS, "parsing '%s' to type %s", value_str,
102 g_type_name (G_VALUE_TYPE (value)));
104 res = gst_value_deserialize (value, value_str);
105 if (!res && G_VALUE_TYPE (value) == G_TYPE_BOOLEAN) {
106 /* backwards compat, all booleans that fail to parse are false */
107 g_value_set_boolean (value, FALSE);
110 g_return_if_fail (res);
114 * gst_util_set_object_arg:
115 * @object: the object to set the argument of
116 * @name: the name of the argument to set
117 * @value: the string value to set
119 * Convertes the string value to the type of the objects argument and
120 * sets the argument with it.
122 * Note that this function silently returns if @object has no property named
123 * @name or when @value cannot be converted to the type of the property.
126 gst_util_set_object_arg (GObject * object, const gchar * name,
133 g_return_if_fail (G_IS_OBJECT (object));
134 g_return_if_fail (name != NULL);
135 g_return_if_fail (value != NULL);
137 pspec = g_object_class_find_property (G_OBJECT_GET_CLASS (object), name);
141 value_type = G_PARAM_SPEC_VALUE_TYPE (pspec);
143 GST_DEBUG ("pspec->flags is %d, pspec->value_type is %s",
144 pspec->flags, g_type_name (value_type));
146 if (!(pspec->flags & G_PARAM_WRITABLE))
149 g_value_init (&v, value_type);
151 /* special case for element <-> xml (de)serialisation */
152 if (GST_VALUE_HOLDS_STRUCTURE (&v) && strcmp (value, "NULL") == 0) {
153 g_value_set_boxed (&v, NULL);
157 if (!gst_value_deserialize (&v, value))
162 g_object_set_property (object, pspec->name, &v);
166 /* work around error C2520: conversion from unsigned __int64 to double
167 * not implemented, use signed __int64
169 * These are implemented as functions because on some platforms a 64bit int to
170 * double conversion is not defined/implemented.
174 gst_util_guint64_to_gdouble (guint64 value)
176 if (value & G_GINT64_CONSTANT (0x8000000000000000))
177 return (gdouble) ((gint64) value) + (gdouble) 18446744073709551616.;
179 return (gdouble) ((gint64) value);
183 gst_util_gdouble_to_guint64 (gdouble value)
185 if (value < (gdouble) 9223372036854775808.) /* 1 << 63 */
186 return ((guint64) ((gint64) value));
188 value -= (gdouble) 18446744073709551616.;
189 return ((guint64) ((gint64) value));
192 /* convenience struct for getting high and low uint32 parts of
199 #if G_BYTE_ORDER == G_BIG_ENDIAN
207 /* used internally by muldiv functions to control rounding mode */
215 /* multiply two 64-bit unsigned ints into a 128-bit unsigned int. the high
216 * and low 64 bits of the product are placed in c1 and c0 respectively.
217 * this operation cannot overflow. */
219 gst_util_uint64_mul_uint64 (GstUInt64 * c1, GstUInt64 * c0, guint64 arg1,
229 /* do 128 bits multiply
237 * -------------------
240 * "a0" is optimized away, result is stored directly in c0. "b1" is
241 * optimized away, result is stored directly in c1.
243 c0->ll = (guint64) v.l.low * n.l.low;
244 a1.ll = (guint64) v.l.low * n.l.high;
245 b0.ll = (guint64) v.l.high * n.l.low;
247 /* add the high word of a0 to the low words of a1 and b0 using c1 as
248 * scrach space to capture the carry. the low word of the result becomes
249 * the final high word of c0 */
250 c1->ll = (guint64) c0->l.high + a1.l.low + b0.l.low;
251 c0->l.high = c1->l.low;
253 /* add the carry from the result above (found in the high word of c1) and
254 * the high words of a1 and b0 to b1, the result is c1. */
255 c1->ll = (guint64) v.l.high * n.l.high + c1->l.high + a1.l.high + b0.l.high;
258 /* based on Hacker's Delight p152 */
260 gst_util_div128_64 (GstUInt64 c1, GstUInt64 c0, guint64 denom)
262 GstUInt64 q1, q0, rhat;
263 GstUInt64 v, cmp1, cmp2;
268 /* count number of leading zeroes, we know they must be in the high
269 * part of denom since denom > G_MAXUINT32. */
270 s = v.l.high | (v.l.high >> 1);
274 s = ~(s | (s >> 16));
275 s = s - ((s >> 1) & 0x55555555);
276 s = (s & 0x33333333) + ((s >> 2) & 0x33333333);
277 s = (s + (s >> 4)) & 0x0f0f0f0f;
279 s = (s + (s >> 16)) & 0x3f;
282 /* normalize divisor and dividend */
284 c1.ll = (c1.ll << s) | (c0.l.high >> (32 - s));
288 q1.ll = c1.ll / v.l.high;
289 rhat.ll = c1.ll - q1.ll * v.l.high;
291 cmp1.l.high = rhat.l.low;
292 cmp1.l.low = c0.l.high;
293 cmp2.ll = q1.ll * v.l.low;
295 while (q1.l.high || cmp2.ll > cmp1.ll) {
300 cmp1.l.high = rhat.l.low;
303 c1.l.high = c1.l.low;
304 c1.l.low = c0.l.high;
305 c1.ll -= q1.ll * v.ll;
306 q0.ll = c1.ll / v.l.high;
307 rhat.ll = c1.ll - q0.ll * v.l.high;
309 cmp1.l.high = rhat.l.low;
310 cmp1.l.low = c0.l.low;
311 cmp2.ll = q0.ll * v.l.low;
313 while (q0.l.high || cmp2.ll > cmp1.ll) {
318 cmp1.l.high = rhat.l.low;
321 q0.l.high += q1.l.low;
326 /* multiply a 64-bit unsigned int by a 32-bit unsigned int into a 96-bit
327 * unsigned int. the high 64 bits and low 32 bits of the product are
328 * placed in c1 and c0 respectively. this operation cannot overflow. */
330 gst_util_uint64_mul_uint32 (GstUInt64 * c1, GstUInt64 * c0, guint64 arg1,
337 c0->ll = (guint64) a.l.low * arg2;
338 c1->ll = (guint64) a.l.high * arg2 + c0->l.high;
342 /* divide a 96-bit unsigned int by a 32-bit unsigned int when we know the
343 * quotient fits into 64 bits. the high 64 bits and low 32 bits of the
344 * numerator are expected in c1 and c0 respectively. */
346 gst_util_div96_32 (guint64 c1, guint64 c0, guint32 denom)
348 c0 += (c1 % denom) << 32;
349 return ((c1 / denom) << 32) + (c0 / denom);
352 /* add correction with carry */
353 #define CORRECT(c0,c1,val) \
355 if (G_MAXUINT64 - c0.ll < val) { \
356 if (G_UNLIKELY (c1.ll == G_MAXUINT64)) \
358 return G_MAXUINT64; \
365 gst_util_uint64_scale_uint64_unchecked (guint64 val, guint64 num,
366 guint64 denom, GstRoundingMode mode)
370 /* compute 128-bit numerator product */
371 gst_util_uint64_mul_uint64 (&c1, &c0, val, num);
373 /* condition numerator based on rounding mode */
375 case GST_ROUND_TONEAREST:
376 /* add 1/2 the denominator to the numerator with carry */
377 CORRECT (c0, c1, denom / 2);
381 /* add denominator - 1 to the numerator with carry */
382 CORRECT (c0, c1, denom - 1);
386 /* natural behaviour */
390 /* high word as big as or bigger than denom --> overflow */
391 if (G_UNLIKELY (c1.ll >= denom))
394 /* compute quotient, fits in 64 bits */
395 return gst_util_div128_64 (c1, c0, denom);
398 static inline guint64
399 gst_util_uint64_scale_uint32_unchecked (guint64 val, guint32 num,
400 guint32 denom, GstRoundingMode mode)
404 /* compute 96-bit numerator product */
405 gst_util_uint64_mul_uint32 (&c1, &c0, val, num);
407 /* condition numerator based on rounding mode */
409 case GST_ROUND_TONEAREST:
410 /* add 1/2 the denominator to the numerator with carry */
411 CORRECT (c0, c1, denom / 2);
415 /* add denominator - 1 to the numerator with carry */
416 CORRECT (c0, c1, denom - 1);
420 /* natural behaviour */
424 /* high 32 bits as big as or bigger than denom --> overflow */
425 if (G_UNLIKELY (c1.l.high >= denom))
428 /* compute quotient, fits in 64 bits */
429 return gst_util_div96_32 (c1.ll, c0.ll, denom);
432 /* the guts of the gst_util_uint64_scale() variants */
434 _gst_util_uint64_scale (guint64 val, guint64 num, guint64 denom,
435 GstRoundingMode mode)
437 g_return_val_if_fail (denom != 0, G_MAXUINT64);
439 if (G_UNLIKELY (num == 0))
442 if (G_UNLIKELY (num == denom))
445 /* denom is low --> try to use 96 bit muldiv */
446 if (G_LIKELY (denom <= G_MAXUINT32)) {
447 /* num is low --> use 96 bit muldiv */
448 if (G_LIKELY (num <= G_MAXUINT32))
449 return gst_util_uint64_scale_uint32_unchecked (val, (guint32) num,
450 (guint32) denom, mode);
452 /* num is high but val is low --> swap and use 96-bit muldiv */
453 if (G_LIKELY (val <= G_MAXUINT32))
454 return gst_util_uint64_scale_uint32_unchecked (num, (guint32) val,
455 (guint32) denom, mode);
458 /* val is high and num is high --> use 128-bit muldiv */
459 return gst_util_uint64_scale_uint64_unchecked (val, num, denom, mode);
463 * gst_util_uint64_scale:
464 * @val: the number to scale
465 * @num: the numerator of the scale ratio
466 * @denom: the denominator of the scale ratio
468 * Scale @val by the rational number @num / @denom, avoiding overflows and
469 * underflows and without loss of precision.
471 * This function can potentially be very slow if val and num are both
472 * greater than G_MAXUINT32.
474 * Returns: @val * @num / @denom. In the case of an overflow, this
475 * function returns G_MAXUINT64. If the result is not exactly
476 * representable as an integer it is truncated. See also
477 * gst_util_uint64_scale_round(), gst_util_uint64_scale_ceil(),
478 * gst_util_uint64_scale_int(), gst_util_uint64_scale_int_round(),
479 * gst_util_uint64_scale_int_ceil().
482 gst_util_uint64_scale (guint64 val, guint64 num, guint64 denom)
484 return _gst_util_uint64_scale (val, num, denom, GST_ROUND_DOWN);
488 * gst_util_uint64_scale_round:
489 * @val: the number to scale
490 * @num: the numerator of the scale ratio
491 * @denom: the denominator of the scale ratio
493 * Scale @val by the rational number @num / @denom, avoiding overflows and
494 * underflows and without loss of precision.
496 * This function can potentially be very slow if val and num are both
497 * greater than G_MAXUINT32.
499 * Returns: @val * @num / @denom. In the case of an overflow, this
500 * function returns G_MAXUINT64. If the result is not exactly
501 * representable as an integer, it is rounded to the nearest integer
502 * (half-way cases are rounded up). See also gst_util_uint64_scale(),
503 * gst_util_uint64_scale_ceil(), gst_util_uint64_scale_int(),
504 * gst_util_uint64_scale_int_round(), gst_util_uint64_scale_int_ceil().
507 gst_util_uint64_scale_round (guint64 val, guint64 num, guint64 denom)
509 return _gst_util_uint64_scale (val, num, denom, GST_ROUND_TONEAREST);
513 * gst_util_uint64_scale_ceil:
514 * @val: the number to scale
515 * @num: the numerator of the scale ratio
516 * @denom: the denominator of the scale ratio
518 * Scale @val by the rational number @num / @denom, avoiding overflows and
519 * underflows and without loss of precision.
521 * This function can potentially be very slow if val and num are both
522 * greater than G_MAXUINT32.
524 * Returns: @val * @num / @denom. In the case of an overflow, this
525 * function returns G_MAXUINT64. If the result is not exactly
526 * representable as an integer, it is rounded up. See also
527 * gst_util_uint64_scale(), gst_util_uint64_scale_round(),
528 * gst_util_uint64_scale_int(), gst_util_uint64_scale_int_round(),
529 * gst_util_uint64_scale_int_ceil().
532 gst_util_uint64_scale_ceil (guint64 val, guint64 num, guint64 denom)
534 return _gst_util_uint64_scale (val, num, denom, GST_ROUND_UP);
537 /* the guts of the gst_util_uint64_scale_int() variants */
539 _gst_util_uint64_scale_int (guint64 val, gint num, gint denom,
540 GstRoundingMode mode)
542 g_return_val_if_fail (denom > 0, G_MAXUINT64);
543 g_return_val_if_fail (num >= 0, G_MAXUINT64);
545 if (G_UNLIKELY (num == 0))
548 if (G_UNLIKELY (num == denom))
551 if (val <= G_MAXUINT32) {
552 /* simple case. num and denom are not negative so casts are OK. when
553 * not truncating, the additions to the numerator cannot overflow
554 * because val*num <= G_MAXUINT32 * G_MAXINT32 < G_MAXUINT64 -
555 * G_MAXINT32, so there's room to add another gint32. */
556 val *= (guint64) num;
558 case GST_ROUND_TONEAREST:
559 /* add 1/2 the denominator to the numerator. */
564 /* add denominator - 1 to the numerator. */
569 /* natural behaviour */
572 return val / (guint64) denom;
575 /* num and denom are not negative so casts are OK */
576 return gst_util_uint64_scale_uint32_unchecked (val, (guint32) num,
577 (guint32) denom, mode);
581 * gst_util_uint64_scale_int:
582 * @val: guint64 (such as a #GstClockTime) to scale.
583 * @num: numerator of the scale factor.
584 * @denom: denominator of the scale factor.
586 * Scale @val by the rational number @num / @denom, avoiding overflows and
587 * underflows and without loss of precision. @num must be non-negative and
588 * @denom must be positive.
590 * Returns: @val * @num / @denom. In the case of an overflow, this
591 * function returns G_MAXUINT64. If the result is not exactly
592 * representable as an integer, it is truncated. See also
593 * gst_util_uint64_scale_int_round(), gst_util_uint64_scale_int_ceil(),
594 * gst_util_uint64_scale(), gst_util_uint64_scale_round(),
595 * gst_util_uint64_scale_ceil().
598 gst_util_uint64_scale_int (guint64 val, gint num, gint denom)
600 return _gst_util_uint64_scale_int (val, num, denom, GST_ROUND_DOWN);
604 * gst_util_uint64_scale_int_round:
605 * @val: guint64 (such as a #GstClockTime) to scale.
606 * @num: numerator of the scale factor.
607 * @denom: denominator of the scale factor.
609 * Scale @val by the rational number @num / @denom, avoiding overflows and
610 * underflows and without loss of precision. @num must be non-negative and
611 * @denom must be positive.
613 * Returns: @val * @num / @denom. In the case of an overflow, this
614 * function returns G_MAXUINT64. If the result is not exactly
615 * representable as an integer, it is rounded to the nearest integer
616 * (half-way cases are rounded up). See also gst_util_uint64_scale_int(),
617 * gst_util_uint64_scale_int_ceil(), gst_util_uint64_scale(),
618 * gst_util_uint64_scale_round(), gst_util_uint64_scale_ceil().
621 gst_util_uint64_scale_int_round (guint64 val, gint num, gint denom)
623 return _gst_util_uint64_scale_int (val, num, denom, GST_ROUND_TONEAREST);
627 * gst_util_uint64_scale_int_ceil:
628 * @val: guint64 (such as a #GstClockTime) to scale.
629 * @num: numerator of the scale factor.
630 * @denom: denominator of the scale factor.
632 * Scale @val by the rational number @num / @denom, avoiding overflows and
633 * underflows and without loss of precision. @num must be non-negative and
634 * @denom must be positive.
636 * Returns: @val * @num / @denom. In the case of an overflow, this
637 * function returns G_MAXUINT64. If the result is not exactly
638 * representable as an integer, it is rounded up. See also
639 * gst_util_uint64_scale_int(), gst_util_uint64_scale_int_round(),
640 * gst_util_uint64_scale(), gst_util_uint64_scale_round(),
641 * gst_util_uint64_scale_ceil().
644 gst_util_uint64_scale_int_ceil (guint64 val, gint num, gint denom)
646 return _gst_util_uint64_scale_int (val, num, denom, GST_ROUND_UP);
650 * gst_util_seqnum_next:
652 * Return a constantly incrementing sequence number.
654 * This function is used internally to GStreamer to be able to determine which
655 * events and messages are "the same". For example, elements may set the seqnum
656 * on a segment-done message to be the same as that of the last seek event, to
657 * indicate that event and the message correspond to the same segment.
659 * Returns: A constantly incrementing 32-bit unsigned integer, which might
660 * overflow back to 0 at some point. Use gst_util_seqnum_compare() to make sure
661 * you handle wraparound correctly.
666 gst_util_seqnum_next (void)
668 static gint counter = 0;
669 return g_atomic_int_exchange_and_add (&counter, 1);
673 * gst_util_seqnum_compare:
674 * @s1: A sequence number.
675 * @s2: Another sequence number.
677 * Compare two sequence numbers, handling wraparound.
679 * The current implementation just returns (gint32)(@s1 - @s2).
681 * Returns: A negative number if @s1 is before @s2, 0 if they are equal, or a
682 * positive number if @s1 is after @s2.
687 gst_util_seqnum_compare (guint32 s1, guint32 s2)
689 return (gint32) (s1 - s2);
692 /* -----------------------------------------------------
694 * The following code will be moved out of the main
695 * gstreamer library someday.
701 string_append_indent (GString * str, gint count)
705 for (xx = 0; xx < count; xx++)
706 g_string_append_c (str, ' ');
710 * gst_print_pad_caps:
711 * @buf: the buffer to print the caps in
712 * @indent: initial indentation
713 * @pad: the pad to print the caps from
715 * Write the pad capabilities in a human readable format into
719 gst_print_pad_caps (GString * buf, gint indent, GstPad * pad)
726 string_append_indent (buf, indent);
727 g_string_printf (buf, "%s:%s has no capabilities",
728 GST_DEBUG_PAD_NAME (pad));
732 s = gst_caps_to_string (caps);
733 g_string_append (buf, s);
739 * gst_print_element_args:
740 * @buf: the buffer to print the args in
741 * @indent: initial indentation
742 * @element: the element to print the args of
744 * Print the element argument in a human readable format in the given
748 gst_print_element_args (GString * buf, gint indent, GstElement * element)
751 GValue value = { 0, }; /* the important thing is that value.type = 0 */
753 GParamSpec *spec, **specs, **walk;
755 specs = g_object_class_list_properties (G_OBJECT_GET_CLASS (element), NULL);
758 for (walk = specs; *walk; walk++) {
760 if (width < strlen (spec->name))
761 width = strlen (spec->name);
764 for (walk = specs; *walk; walk++) {
767 if (spec->flags & G_PARAM_READABLE) {
768 g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (spec));
769 g_object_get_property (G_OBJECT (element), spec->name, &value);
770 str = g_strdup_value_contents (&value);
771 g_value_unset (&value);
773 str = g_strdup ("Parameter not readable.");
776 string_append_indent (buf, indent);
777 g_string_append (buf, spec->name);
778 string_append_indent (buf, 2 + width - strlen (spec->name));
779 g_string_append (buf, str);
780 g_string_append_c (buf, '\n');
789 * gst_element_create_all_pads:
790 * @element: a #GstElement to create pads for
792 * Creates a pad for each pad template that is always available.
793 * This function is only useful during object intialization of
794 * subclasses of #GstElement.
797 gst_element_create_all_pads (GstElement * element)
801 /* FIXME: lock element */
804 gst_element_class_get_pad_template_list (GST_ELEMENT_CLASS
805 (G_OBJECT_GET_CLASS (element)));
808 GstPadTemplate *padtempl = (GstPadTemplate *) padlist->data;
810 if (padtempl->presence == GST_PAD_ALWAYS) {
813 pad = gst_pad_new_from_template (padtempl, padtempl->name_template);
815 gst_element_add_pad (element, pad);
817 padlist = padlist->next;
822 * gst_element_get_compatible_pad_template:
823 * @element: a #GstElement to get a compatible pad template for.
824 * @compattempl: the #GstPadTemplate to find a compatible template for.
826 * Retrieves a pad template from @element that is compatible with @compattempl.
827 * Pads from compatible templates can be linked together.
829 * Returns: a compatible #GstPadTemplate, or NULL if none was found. No
830 * unreferencing is necessary.
833 gst_element_get_compatible_pad_template (GstElement * element,
834 GstPadTemplate * compattempl)
836 GstPadTemplate *newtempl = NULL;
838 GstElementClass *class;
841 g_return_val_if_fail (element != NULL, NULL);
842 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
843 g_return_val_if_fail (compattempl != NULL, NULL);
845 class = GST_ELEMENT_GET_CLASS (element);
847 padlist = gst_element_class_get_pad_template_list (class);
849 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
850 "Looking for a suitable pad template in %s out of %d templates...",
851 GST_ELEMENT_NAME (element), g_list_length (padlist));
854 GstPadTemplate *padtempl = (GstPadTemplate *) padlist->data;
858 * Check direction (must be opposite)
861 GST_CAT_LOG (GST_CAT_CAPS,
862 "checking pad template %s", padtempl->name_template);
863 if (padtempl->direction != compattempl->direction) {
864 GST_CAT_DEBUG (GST_CAT_CAPS,
865 "compatible direction: found %s pad template \"%s\"",
866 padtempl->direction == GST_PAD_SRC ? "src" : "sink",
867 padtempl->name_template);
869 GST_CAT_DEBUG (GST_CAT_CAPS,
870 "intersecting %" GST_PTR_FORMAT, GST_PAD_TEMPLATE_CAPS (compattempl));
871 GST_CAT_DEBUG (GST_CAT_CAPS,
872 "..and %" GST_PTR_FORMAT, GST_PAD_TEMPLATE_CAPS (padtempl));
874 compatible = gst_caps_can_intersect (GST_PAD_TEMPLATE_CAPS (compattempl),
875 GST_PAD_TEMPLATE_CAPS (padtempl));
877 GST_CAT_DEBUG (GST_CAT_CAPS, "caps are %scompatible",
878 (compatible ? "" : "not "));
886 padlist = g_list_next (padlist);
889 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
890 "Returning new pad template %p", newtempl);
892 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "No compatible pad template found");
898 gst_element_request_pad (GstElement * element, GstPadTemplate * templ,
901 GstPad *newpad = NULL;
902 GstElementClass *oclass;
904 oclass = GST_ELEMENT_GET_CLASS (element);
906 if (oclass->request_new_pad)
907 newpad = (oclass->request_new_pad) (element, templ, name);
910 gst_object_ref (newpad);
918 * gst_element_get_pad_from_template:
919 * @element: a #GstElement.
920 * @templ: a #GstPadTemplate belonging to @element.
922 * Gets a pad from @element described by @templ. If the presence of @templ is
923 * #GST_PAD_REQUEST, requests a new pad. Can return %NULL for #GST_PAD_SOMETIMES
926 * Returns: the #GstPad, or NULL if one could not be found or created.
929 gst_element_get_pad_from_template (GstElement * element, GstPadTemplate * templ)
932 GstPadPresence presence;
934 /* If this function is ever exported, we need check the validity of `element'
935 * and `templ', and to make sure the template actually belongs to the
938 presence = GST_PAD_TEMPLATE_PRESENCE (templ);
942 case GST_PAD_SOMETIMES:
943 ret = gst_element_get_static_pad (element, templ->name_template);
944 if (!ret && presence == GST_PAD_ALWAYS)
946 ("Element %s has an ALWAYS template %s, but no pad of the same name",
947 GST_OBJECT_NAME (element), templ->name_template);
950 case GST_PAD_REQUEST:
951 ret = gst_element_request_pad (element, templ, NULL);
959 * gst_element_request_compatible_pad:
960 * @element: a #GstElement.
961 * @templ: the #GstPadTemplate to which the new pad should be able to link.
963 * Requests a pad from @element. The returned pad should be unlinked and
964 * compatible with @templ. Might return an existing pad, or request a new one.
966 * Returns: a #GstPad, or %NULL if one could not be found or created.
969 gst_element_request_compatible_pad (GstElement * element,
970 GstPadTemplate * templ)
972 GstPadTemplate *templ_new;
975 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
976 g_return_val_if_fail (GST_IS_PAD_TEMPLATE (templ), NULL);
978 /* FIXME: should really loop through the templates, testing each for
979 * compatibility and pad availability. */
980 templ_new = gst_element_get_compatible_pad_template (element, templ);
982 pad = gst_element_get_pad_from_template (element, templ_new);
984 /* This can happen for non-request pads. No need to unref. */
985 if (pad && GST_PAD_PEER (pad))
992 * Checks if the source pad and the sink pad can be linked.
993 * Both @srcpad and @sinkpad must be unlinked and have a parent.
996 gst_pad_check_link (GstPad * srcpad, GstPad * sinkpad)
998 /* FIXME This function is gross. It's almost a direct copy of
999 * gst_pad_link_filtered(). Any decent programmer would attempt
1000 * to merge the two functions, which I will do some day. --ds
1003 /* generic checks */
1004 g_return_val_if_fail (GST_IS_PAD (srcpad), FALSE);
1005 g_return_val_if_fail (GST_IS_PAD (sinkpad), FALSE);
1007 GST_CAT_INFO (GST_CAT_PADS, "trying to link %s:%s and %s:%s",
1008 GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (sinkpad));
1010 /* FIXME: shouldn't we convert this to g_return_val_if_fail? */
1011 if (GST_PAD_PEER (srcpad) != NULL) {
1012 GST_CAT_INFO (GST_CAT_PADS, "Source pad %s:%s has a peer, failed",
1013 GST_DEBUG_PAD_NAME (srcpad));
1016 if (GST_PAD_PEER (sinkpad) != NULL) {
1017 GST_CAT_INFO (GST_CAT_PADS, "Sink pad %s:%s has a peer, failed",
1018 GST_DEBUG_PAD_NAME (sinkpad));
1021 if (!GST_PAD_IS_SRC (srcpad)) {
1022 GST_CAT_INFO (GST_CAT_PADS, "Src pad %s:%s is not source pad, failed",
1023 GST_DEBUG_PAD_NAME (srcpad));
1026 if (!GST_PAD_IS_SINK (sinkpad)) {
1027 GST_CAT_INFO (GST_CAT_PADS, "Sink pad %s:%s is not sink pad, failed",
1028 GST_DEBUG_PAD_NAME (sinkpad));
1031 if (GST_PAD_PARENT (srcpad) == NULL) {
1032 GST_CAT_INFO (GST_CAT_PADS, "Src pad %s:%s has no parent, failed",
1033 GST_DEBUG_PAD_NAME (srcpad));
1036 if (GST_PAD_PARENT (sinkpad) == NULL) {
1037 GST_CAT_INFO (GST_CAT_PADS, "Sink pad %s:%s has no parent, failed",
1038 GST_DEBUG_PAD_NAME (srcpad));
1046 * gst_element_get_compatible_pad:
1047 * @element: a #GstElement in which the pad should be found.
1048 * @pad: the #GstPad to find a compatible one for.
1049 * @caps: the #GstCaps to use as a filter.
1051 * Looks for an unlinked pad to which the given pad can link. It is not
1052 * guaranteed that linking the pads will work, though it should work in most
1055 * Returns: the #GstPad to which a link can be made, or %NULL if one cannot be
1056 * found. gst_object_unref() after usage.
1059 gst_element_get_compatible_pad (GstElement * element, GstPad * pad,
1060 const GstCaps * caps)
1063 GstPadTemplate *templ;
1065 GstPad *foundpad = NULL;
1068 g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
1069 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
1071 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1072 "finding pad in %s compatible with %s:%s",
1073 GST_ELEMENT_NAME (element), GST_DEBUG_PAD_NAME (pad));
1075 g_return_val_if_fail (GST_PAD_PEER (pad) == NULL, NULL);
1078 /* try to get an existing unlinked pad */
1079 pads = gst_element_iterate_pads (element);
1083 switch (gst_iterator_next (pads, &padptr)) {
1084 case GST_ITERATOR_OK:
1089 current = GST_PAD (padptr);
1091 GST_CAT_LOG (GST_CAT_ELEMENT_PADS, "examining pad %s:%s",
1092 GST_DEBUG_PAD_NAME (current));
1094 peer = gst_pad_get_peer (current);
1096 if (peer == NULL && gst_pad_check_link (pad, current)) {
1097 GstCaps *temp, *intersection;
1098 gboolean compatible;
1100 /* Now check if the two pads' caps are compatible */
1101 temp = gst_pad_get_caps (pad);
1103 intersection = gst_caps_intersect (temp, caps);
1104 gst_caps_unref (temp);
1106 intersection = temp;
1109 temp = gst_pad_get_caps (current);
1110 compatible = gst_caps_can_intersect (temp, intersection);
1111 gst_caps_unref (temp);
1112 gst_caps_unref (intersection);
1115 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1116 "found existing unlinked compatible pad %s:%s",
1117 GST_DEBUG_PAD_NAME (current));
1118 gst_iterator_free (pads);
1122 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "incompatible pads");
1125 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1126 "already linked or cannot be linked (peer = %p)", peer);
1128 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "unreffing pads");
1130 gst_object_unref (current);
1132 gst_object_unref (peer);
1135 case GST_ITERATOR_DONE:
1138 case GST_ITERATOR_RESYNC:
1139 gst_iterator_resync (pads);
1141 case GST_ITERATOR_ERROR:
1142 g_assert_not_reached ();
1146 gst_iterator_free (pads);
1148 GST_CAT_DEBUG_OBJECT (GST_CAT_ELEMENT_PADS, element,
1149 "Could not find a compatible unlinked always pad to link to %s:%s, now checking request pads",
1150 GST_DEBUG_PAD_NAME (pad));
1152 /* try to create a new one */
1153 /* requesting is a little crazy, we need a template. Let's create one */
1154 /* FIXME: why not gst_pad_get_pad_template (pad); */
1155 templcaps = gst_pad_get_caps (pad);
1157 templ = gst_pad_template_new ((gchar *) GST_PAD_NAME (pad),
1158 GST_PAD_DIRECTION (pad), GST_PAD_ALWAYS, templcaps);
1160 foundpad = gst_element_request_compatible_pad (element, templ);
1161 gst_object_unref (templ);
1164 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1165 "found existing request pad %s:%s", GST_DEBUG_PAD_NAME (foundpad));
1169 GST_CAT_INFO_OBJECT (GST_CAT_ELEMENT_PADS, element,
1170 "Could not find a compatible pad to link to %s:%s",
1171 GST_DEBUG_PAD_NAME (pad));
1176 * gst_element_state_get_name:
1177 * @state: a #GstState to get the name of.
1179 * Gets a string representing the given state.
1181 * Returns: a string with the name of the state.
1183 G_CONST_RETURN gchar *
1184 gst_element_state_get_name (GstState state)
1187 #ifdef GST_DEBUG_COLOR
1188 case GST_STATE_VOID_PENDING:
1189 return "VOID_PENDING";
1190 case GST_STATE_NULL:
1191 return "\033[01;34mNULL\033[00m";
1192 case GST_STATE_READY:
1193 return "\033[01;31mREADY\033[00m";
1194 case GST_STATE_PLAYING:
1195 return "\033[01;32mPLAYING\033[00m";
1196 case GST_STATE_PAUSED:
1197 return "\033[01;33mPAUSED\033[00m";
1199 /* This is a memory leak */
1200 return g_strdup_printf ("\033[01;35;41mUNKNOWN!\033[00m(%d)", state);
1202 case GST_STATE_VOID_PENDING:
1203 return "VOID_PENDING";
1204 case GST_STATE_NULL:
1206 case GST_STATE_READY:
1208 case GST_STATE_PLAYING:
1210 case GST_STATE_PAUSED:
1213 /* This is a memory leak */
1214 return g_strdup_printf ("UNKNOWN!(%d)", state);
1220 * gst_element_state_change_return_get_name:
1221 * @state_ret: a #GstStateChangeReturn to get the name of.
1223 * Gets a string representing the given state change result.
1225 * Returns: a string with the name of the state change result.
1229 G_CONST_RETURN gchar *
1230 gst_element_state_change_return_get_name (GstStateChangeReturn state_ret)
1232 switch (state_ret) {
1233 #ifdef GST_DEBUG_COLOR
1234 case GST_STATE_CHANGE_FAILURE:
1235 return "\033[01;31mFAILURE\033[00m";
1236 case GST_STATE_CHANGE_SUCCESS:
1237 return "\033[01;32mSUCCESS\033[00m";
1238 case GST_STATE_CHANGE_ASYNC:
1239 return "\033[01;33mASYNC\033[00m";
1240 case GST_STATE_CHANGE_NO_PREROLL:
1241 return "\033[01;34mNO_PREROLL\033[00m";
1243 /* This is a memory leak */
1244 return g_strdup_printf ("\033[01;35;41mUNKNOWN!\033[00m(%d)", state_ret);
1246 case GST_STATE_CHANGE_FAILURE:
1248 case GST_STATE_CHANGE_SUCCESS:
1250 case GST_STATE_CHANGE_ASYNC:
1252 case GST_STATE_CHANGE_NO_PREROLL:
1253 return "NO PREROLL";
1255 /* This is a memory leak */
1256 return g_strdup_printf ("UNKNOWN!(%d)", state_ret);
1263 * gst_element_factory_can_src_caps :
1264 * @factory: factory to query
1265 * @caps: the caps to check
1267 * Checks if the factory can source the given capability.
1269 * Returns: true if it can src the capabilities
1272 gst_element_factory_can_src_caps (GstElementFactory * factory,
1273 const GstCaps * caps)
1277 g_return_val_if_fail (factory != NULL, FALSE);
1278 g_return_val_if_fail (caps != NULL, FALSE);
1280 templates = factory->staticpadtemplates;
1283 GstStaticPadTemplate *template = (GstStaticPadTemplate *) templates->data;
1285 if (template->direction == GST_PAD_SRC) {
1286 if (gst_caps_is_always_compatible (gst_static_caps_get
1287 (&template->static_caps), caps))
1290 templates = g_list_next (templates);
1297 * gst_element_factory_can_sink_caps :
1298 * @factory: factory to query
1299 * @caps: the caps to check
1301 * Checks if the factory can sink the given capability.
1303 * Returns: true if it can sink the capabilities
1306 gst_element_factory_can_sink_caps (GstElementFactory * factory,
1307 const GstCaps * caps)
1311 g_return_val_if_fail (factory != NULL, FALSE);
1312 g_return_val_if_fail (caps != NULL, FALSE);
1314 templates = factory->staticpadtemplates;
1317 GstStaticPadTemplate *template = (GstStaticPadTemplate *) templates->data;
1319 if (template->direction == GST_PAD_SINK) {
1320 if (gst_caps_is_always_compatible (caps,
1321 gst_static_caps_get (&template->static_caps)))
1324 templates = g_list_next (templates);
1331 /* if return val is true, *direct_child is a caller-owned ref on the direct
1332 * child of ancestor that is part of object's ancestry */
1334 object_has_ancestor (GstObject * object, GstObject * ancestor,
1335 GstObject ** direct_child)
1337 GstObject *child, *parent;
1340 *direct_child = NULL;
1342 child = gst_object_ref (object);
1343 parent = gst_object_get_parent (object);
1346 if (ancestor == parent) {
1348 *direct_child = child;
1350 gst_object_unref (child);
1351 gst_object_unref (parent);
1355 gst_object_unref (child);
1357 parent = gst_object_get_parent (parent);
1360 gst_object_unref (child);
1365 /* caller owns return */
1367 find_common_root (GstObject * o1, GstObject * o2)
1369 GstObject *top = o1;
1370 GstObject *kid1, *kid2;
1371 GstObject *root = NULL;
1373 while (GST_OBJECT_PARENT (top))
1374 top = GST_OBJECT_PARENT (top);
1376 /* the itsy-bitsy spider... */
1378 if (!object_has_ancestor (o2, top, &kid2))
1381 root = gst_object_ref (top);
1383 if (!object_has_ancestor (o1, kid2, &kid1)) {
1384 gst_object_unref (kid2);
1388 if (!object_has_ancestor (o2, kid1, &kid2)) {
1389 gst_object_unref (kid1);
1396 /* caller does not own return */
1398 ghost_up (GstElement * e, GstPad * pad)
1400 static gint ghost_pad_index = 0;
1403 GstObject *parent = GST_OBJECT_PARENT (e);
1405 name = g_strdup_printf ("ghost%d", ghost_pad_index++);
1406 gpad = gst_ghost_pad_new (name, pad);
1409 if (!gst_element_add_pad ((GstElement *) parent, gpad)) {
1410 g_warning ("Pad named %s already exists in element %s\n",
1411 GST_OBJECT_NAME (gpad), GST_OBJECT_NAME (parent));
1412 gst_object_unref ((GstObject *) gpad);
1420 remove_pad (gpointer ppad, gpointer unused)
1424 if (!gst_element_remove_pad ((GstElement *) GST_OBJECT_PARENT (pad), pad))
1425 g_warning ("Couldn't remove pad %s from element %s",
1426 GST_OBJECT_NAME (pad), GST_OBJECT_NAME (GST_OBJECT_PARENT (pad)));
1430 prepare_link_maybe_ghosting (GstPad ** src, GstPad ** sink,
1431 GSList ** pads_created)
1435 GSList *pads_created_local = NULL;
1437 g_assert (pads_created);
1439 e1 = GST_OBJECT_PARENT (*src);
1440 e2 = GST_OBJECT_PARENT (*sink);
1442 if (G_UNLIKELY (e1 == NULL)) {
1443 GST_WARNING ("Trying to ghost a pad that doesn't have a parent: %"
1444 GST_PTR_FORMAT, *src);
1447 if (G_UNLIKELY (e2 == NULL)) {
1448 GST_WARNING ("Trying to ghost a pad that doesn't have a parent: %"
1449 GST_PTR_FORMAT, *sink);
1453 if (GST_OBJECT_PARENT (e1) == GST_OBJECT_PARENT (e2)) {
1454 GST_CAT_INFO (GST_CAT_PADS, "%s and %s in same bin, no need for ghost pads",
1455 GST_OBJECT_NAME (e1), GST_OBJECT_NAME (e2));
1459 GST_CAT_INFO (GST_CAT_PADS, "%s and %s not in same bin, making ghost pads",
1460 GST_OBJECT_NAME (e1), GST_OBJECT_NAME (e2));
1462 /* we need to setup some ghost pads */
1463 root = find_common_root (e1, e2);
1465 g_warning ("Trying to connect elements that don't share a common "
1466 "ancestor: %s and %s", GST_ELEMENT_NAME (e1), GST_ELEMENT_NAME (e2));
1470 while (GST_OBJECT_PARENT (e1) != root) {
1471 *src = ghost_up ((GstElement *) e1, *src);
1474 e1 = GST_OBJECT_PARENT (*src);
1475 pads_created_local = g_slist_prepend (pads_created_local, *src);
1477 while (GST_OBJECT_PARENT (e2) != root) {
1478 *sink = ghost_up ((GstElement *) e2, *sink);
1481 e2 = GST_OBJECT_PARENT (*sink);
1482 pads_created_local = g_slist_prepend (pads_created_local, *sink);
1485 gst_object_unref (root);
1486 *pads_created = g_slist_concat (*pads_created, pads_created_local);
1490 gst_object_unref (root);
1491 g_slist_foreach (pads_created_local, remove_pad, NULL);
1492 g_slist_free (pads_created_local);
1497 pad_link_maybe_ghosting (GstPad * src, GstPad * sink)
1499 GSList *pads_created = NULL;
1502 if (!prepare_link_maybe_ghosting (&src, &sink, &pads_created)) {
1505 ret = (gst_pad_link (src, sink) == GST_PAD_LINK_OK);
1509 g_slist_foreach (pads_created, remove_pad, NULL);
1511 g_slist_free (pads_created);
1517 * gst_element_link_pads:
1518 * @src: a #GstElement containing the source pad.
1519 * @srcpadname: the name of the #GstPad in source element or NULL for any pad.
1520 * @dest: the #GstElement containing the destination pad.
1521 * @destpadname: the name of the #GstPad in destination element,
1522 * or NULL for any pad.
1524 * Links the two named pads of the source and destination elements.
1525 * Side effect is that if one of the pads has no parent, it becomes a
1526 * child of the parent of the other element. If they have different
1527 * parents, the link fails.
1529 * Returns: TRUE if the pads could be linked, FALSE otherwise.
1532 gst_element_link_pads (GstElement * src, const gchar * srcpadname,
1533 GstElement * dest, const gchar * destpadname)
1535 const GList *srcpads, *destpads, *srctempls, *desttempls, *l;
1536 GstPad *srcpad, *destpad;
1537 GstPadTemplate *srctempl, *desttempl;
1538 GstElementClass *srcclass, *destclass;
1541 g_return_val_if_fail (GST_IS_ELEMENT (src), FALSE);
1542 g_return_val_if_fail (GST_IS_ELEMENT (dest), FALSE);
1544 srcclass = GST_ELEMENT_GET_CLASS (src);
1545 destclass = GST_ELEMENT_GET_CLASS (dest);
1547 GST_CAT_INFO (GST_CAT_ELEMENT_PADS,
1548 "trying to link element %s:%s to element %s:%s", GST_ELEMENT_NAME (src),
1549 srcpadname ? srcpadname : "(any)", GST_ELEMENT_NAME (dest),
1550 destpadname ? destpadname : "(any)");
1554 /* name specified, look it up */
1555 if (!(srcpad = gst_element_get_static_pad (src, srcpadname)))
1556 srcpad = gst_element_get_request_pad (src, srcpadname);
1558 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "no pad %s:%s",
1559 GST_ELEMENT_NAME (src), srcpadname);
1562 if (!(GST_PAD_DIRECTION (srcpad) == GST_PAD_SRC)) {
1563 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is no src pad",
1564 GST_DEBUG_PAD_NAME (srcpad));
1565 gst_object_unref (srcpad);
1568 if (GST_PAD_PEER (srcpad) != NULL) {
1569 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is already linked",
1570 GST_DEBUG_PAD_NAME (srcpad));
1571 gst_object_unref (srcpad);
1577 /* no name given, get the first available pad */
1578 GST_OBJECT_LOCK (src);
1579 srcpads = GST_ELEMENT_PADS (src);
1580 srcpad = srcpads ? GST_PAD_CAST (srcpads->data) : NULL;
1582 gst_object_ref (srcpad);
1583 GST_OBJECT_UNLOCK (src);
1586 /* get a destination pad */
1588 /* name specified, look it up */
1589 if (!(destpad = gst_element_get_static_pad (dest, destpadname)))
1590 destpad = gst_element_get_request_pad (dest, destpadname);
1592 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "no pad %s:%s",
1593 GST_ELEMENT_NAME (dest), destpadname);
1596 if (!(GST_PAD_DIRECTION (destpad) == GST_PAD_SINK)) {
1597 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is no sink pad",
1598 GST_DEBUG_PAD_NAME (destpad));
1599 gst_object_unref (destpad);
1602 if (GST_PAD_PEER (destpad) != NULL) {
1603 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "pad %s:%s is already linked",
1604 GST_DEBUG_PAD_NAME (destpad));
1605 gst_object_unref (destpad);
1611 /* no name given, get the first available pad */
1612 GST_OBJECT_LOCK (dest);
1613 destpads = GST_ELEMENT_PADS (dest);
1614 destpad = destpads ? GST_PAD_CAST (destpads->data) : NULL;
1616 gst_object_ref (destpad);
1617 GST_OBJECT_UNLOCK (dest);
1620 if (srcpadname && destpadname) {
1623 /* two explicitly specified pads */
1624 result = pad_link_maybe_ghosting (srcpad, destpad);
1626 gst_object_unref (srcpad);
1627 gst_object_unref (destpad);
1633 /* loop through the allowed pads in the source, trying to find a
1634 * compatible destination pad */
1635 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1636 "looping through allowed src and dest pads");
1638 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "trying src pad %s:%s",
1639 GST_DEBUG_PAD_NAME (srcpad));
1640 if ((GST_PAD_DIRECTION (srcpad) == GST_PAD_SRC) &&
1641 (GST_PAD_PEER (srcpad) == NULL)) {
1646 gst_object_ref (temp);
1648 temp = gst_element_get_compatible_pad (dest, srcpad, NULL);
1651 if (temp && pad_link_maybe_ghosting (srcpad, temp)) {
1652 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "linked pad %s:%s to pad %s:%s",
1653 GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (temp));
1655 gst_object_unref (destpad);
1656 gst_object_unref (srcpad);
1657 gst_object_unref (temp);
1662 gst_object_unref (temp);
1665 /* find a better way for this mess */
1667 srcpads = g_list_next (srcpads);
1669 gst_object_unref (srcpad);
1670 srcpad = GST_PAD_CAST (srcpads->data);
1671 gst_object_ref (srcpad);
1677 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "no link possible from %s:%s to %s",
1678 GST_DEBUG_PAD_NAME (srcpad), GST_ELEMENT_NAME (dest));
1680 gst_object_unref (destpad);
1684 gst_object_unref (srcpad);
1688 /* loop through the existing pads in the destination */
1690 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "trying dest pad %s:%s",
1691 GST_DEBUG_PAD_NAME (destpad));
1692 if ((GST_PAD_DIRECTION (destpad) == GST_PAD_SINK) &&
1693 (GST_PAD_PEER (destpad) == NULL)) {
1694 GstPad *temp = gst_element_get_compatible_pad (src, destpad, NULL);
1696 if (temp && pad_link_maybe_ghosting (temp, destpad)) {
1697 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "linked pad %s:%s to pad %s:%s",
1698 GST_DEBUG_PAD_NAME (temp), GST_DEBUG_PAD_NAME (destpad));
1699 gst_object_unref (temp);
1700 gst_object_unref (destpad);
1704 gst_object_unref (temp);
1708 destpads = g_list_next (destpads);
1710 gst_object_unref (destpad);
1711 destpad = GST_PAD_CAST (destpads->data);
1712 gst_object_ref (destpad);
1719 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "no link possible from %s to %s:%s",
1720 GST_ELEMENT_NAME (src), GST_DEBUG_PAD_NAME (destpad));
1721 gst_object_unref (destpad);
1725 gst_object_unref (destpad);
1729 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1730 "we might have request pads on both sides, checking...");
1731 srctempls = gst_element_class_get_pad_template_list (srcclass);
1732 desttempls = gst_element_class_get_pad_template_list (destclass);
1734 if (srctempls && desttempls) {
1736 srctempl = (GstPadTemplate *) srctempls->data;
1737 if (srctempl->presence == GST_PAD_REQUEST) {
1738 for (l = desttempls; l; l = l->next) {
1739 desttempl = (GstPadTemplate *) l->data;
1740 if (desttempl->presence == GST_PAD_REQUEST &&
1741 desttempl->direction != srctempl->direction) {
1742 if (gst_caps_is_always_compatible (gst_pad_template_get_caps
1743 (srctempl), gst_pad_template_get_caps (desttempl))) {
1745 gst_element_get_request_pad (src, srctempl->name_template);
1747 gst_element_get_request_pad (dest, desttempl->name_template);
1748 if (srcpad && destpad
1749 && pad_link_maybe_ghosting (srcpad, destpad)) {
1750 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
1751 "linked pad %s:%s to pad %s:%s",
1752 GST_DEBUG_PAD_NAME (srcpad), GST_DEBUG_PAD_NAME (destpad));
1753 gst_object_unref (srcpad);
1754 gst_object_unref (destpad);
1757 /* it failed, so we release the request pads */
1759 gst_element_release_request_pad (src, srcpad);
1761 gst_element_release_request_pad (dest, destpad);
1766 srctempls = srctempls->next;
1770 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "no link possible from %s to %s",
1771 GST_ELEMENT_NAME (src), GST_ELEMENT_NAME (dest));
1776 * gst_element_link_pads_filtered:
1777 * @src: a #GstElement containing the source pad.
1778 * @srcpadname: the name of the #GstPad in source element or NULL for any pad.
1779 * @dest: the #GstElement containing the destination pad.
1780 * @destpadname: the name of the #GstPad in destination element or NULL for any pad.
1781 * @filter: the #GstCaps to filter the link, or #NULL for no filter.
1783 * Links the two named pads of the source and destination elements. Side effect
1784 * is that if one of the pads has no parent, it becomes a child of the parent of
1785 * the other element. If they have different parents, the link fails. If @caps
1786 * is not #NULL, makes sure that the caps of the link is a subset of @caps.
1788 * Returns: TRUE if the pads could be linked, FALSE otherwise.
1791 gst_element_link_pads_filtered (GstElement * src, const gchar * srcpadname,
1792 GstElement * dest, const gchar * destpadname, GstCaps * filter)
1795 g_return_val_if_fail (GST_IS_ELEMENT (src), FALSE);
1796 g_return_val_if_fail (GST_IS_ELEMENT (dest), FALSE);
1797 g_return_val_if_fail (filter == NULL || GST_IS_CAPS (filter), FALSE);
1800 GstElement *capsfilter;
1802 GstState state, pending;
1804 capsfilter = gst_element_factory_make ("capsfilter", NULL);
1806 GST_ERROR ("Could not make a capsfilter");
1810 parent = gst_object_get_parent (GST_OBJECT (src));
1811 g_return_val_if_fail (GST_IS_BIN (parent), FALSE);
1813 gst_element_get_state (GST_ELEMENT_CAST (parent), &state, &pending, 0);
1815 if (!gst_bin_add (GST_BIN (parent), capsfilter)) {
1816 GST_ERROR ("Could not add capsfilter");
1817 gst_object_unref (capsfilter);
1818 gst_object_unref (parent);
1822 if (pending != GST_STATE_VOID_PENDING)
1825 gst_element_set_state (capsfilter, state);
1827 gst_object_unref (parent);
1829 g_object_set (capsfilter, "caps", filter, NULL);
1831 if (gst_element_link_pads (src, srcpadname, capsfilter, "sink")
1832 && gst_element_link_pads (capsfilter, "src", dest, destpadname)) {
1835 GST_INFO ("Could not link elements");
1836 gst_element_set_state (capsfilter, GST_STATE_NULL);
1837 /* this will unlink and unref as appropriate */
1838 gst_bin_remove (GST_BIN (GST_OBJECT_PARENT (capsfilter)), capsfilter);
1842 return gst_element_link_pads (src, srcpadname, dest, destpadname);
1848 * @src: a #GstElement containing the source pad.
1849 * @dest: the #GstElement containing the destination pad.
1851 * Links @src to @dest. The link must be from source to
1852 * destination; the other direction will not be tried. The function looks for
1853 * existing pads that aren't linked yet. It will request new pads if necessary.
1854 * Such pads need to be released manualy when unlinking.
1855 * If multiple links are possible, only one is established.
1857 * Make sure you have added your elements to a bin or pipeline with
1858 * gst_bin_add() before trying to link them.
1860 * Returns: TRUE if the elements could be linked, FALSE otherwise.
1863 gst_element_link (GstElement * src, GstElement * dest)
1865 return gst_element_link_pads_filtered (src, NULL, dest, NULL, NULL);
1869 * gst_element_link_many:
1870 * @element_1: the first #GstElement in the link chain.
1871 * @element_2: the second #GstElement in the link chain.
1872 * @...: the NULL-terminated list of elements to link in order.
1874 * Chain together a series of elements. Uses gst_element_link().
1875 * Make sure you have added your elements to a bin or pipeline with
1876 * gst_bin_add() before trying to link them.
1878 * Returns: TRUE on success, FALSE otherwise.
1881 gst_element_link_many (GstElement * element_1, GstElement * element_2, ...)
1883 gboolean res = TRUE;
1886 g_return_val_if_fail (GST_IS_ELEMENT (element_1), FALSE);
1887 g_return_val_if_fail (GST_IS_ELEMENT (element_2), FALSE);
1889 va_start (args, element_2);
1892 if (!gst_element_link (element_1, element_2)) {
1897 element_1 = element_2;
1898 element_2 = va_arg (args, GstElement *);
1907 * gst_element_link_filtered:
1908 * @src: a #GstElement containing the source pad.
1909 * @dest: the #GstElement containing the destination pad.
1910 * @filter: the #GstCaps to filter the link, or #NULL for no filter.
1912 * Links @src to @dest using the given caps as filtercaps.
1913 * The link must be from source to
1914 * destination; the other direction will not be tried. The function looks for
1915 * existing pads that aren't linked yet. It will request new pads if necessary.
1916 * If multiple links are possible, only one is established.
1918 * Make sure you have added your elements to a bin or pipeline with
1919 * gst_bin_add() before trying to link them.
1921 * Returns: TRUE if the pads could be linked, FALSE otherwise.
1924 gst_element_link_filtered (GstElement * src, GstElement * dest,
1927 return gst_element_link_pads_filtered (src, NULL, dest, NULL, filter);
1931 * gst_element_unlink_pads:
1932 * @src: a #GstElement containing the source pad.
1933 * @srcpadname: the name of the #GstPad in source element.
1934 * @dest: a #GstElement containing the destination pad.
1935 * @destpadname: the name of the #GstPad in destination element.
1937 * Unlinks the two named pads of the source and destination elements.
1940 gst_element_unlink_pads (GstElement * src, const gchar * srcpadname,
1941 GstElement * dest, const gchar * destpadname)
1943 GstPad *srcpad, *destpad;
1944 gboolean srcrequest, destrequest;
1946 srcrequest = destrequest = FALSE;
1948 g_return_if_fail (src != NULL);
1949 g_return_if_fail (GST_IS_ELEMENT (src));
1950 g_return_if_fail (srcpadname != NULL);
1951 g_return_if_fail (dest != NULL);
1952 g_return_if_fail (GST_IS_ELEMENT (dest));
1953 g_return_if_fail (destpadname != NULL);
1955 /* obtain the pads requested */
1956 if (!(srcpad = gst_element_get_static_pad (src, srcpadname)))
1957 if ((srcpad = gst_element_get_request_pad (src, srcpadname)))
1959 if (srcpad == NULL) {
1960 GST_WARNING_OBJECT (src, "source element has no pad \"%s\"", srcpadname);
1963 if (!(destpad = gst_element_get_static_pad (dest, destpadname)))
1964 if ((destpad = gst_element_get_request_pad (dest, destpadname)))
1966 if (destpad == NULL) {
1967 GST_WARNING_OBJECT (dest, "destination element has no pad \"%s\"",
1972 /* we're satisified they can be unlinked, let's do it */
1973 gst_pad_unlink (srcpad, destpad);
1976 gst_element_release_request_pad (dest, destpad);
1977 gst_object_unref (destpad);
1981 gst_element_release_request_pad (src, srcpad);
1982 gst_object_unref (srcpad);
1986 * gst_element_unlink_many:
1987 * @element_1: the first #GstElement in the link chain.
1988 * @element_2: the second #GstElement in the link chain.
1989 * @...: the NULL-terminated list of elements to unlink in order.
1991 * Unlinks a series of elements. Uses gst_element_unlink().
1994 gst_element_unlink_many (GstElement * element_1, GstElement * element_2, ...)
1998 g_return_if_fail (element_1 != NULL && element_2 != NULL);
1999 g_return_if_fail (GST_IS_ELEMENT (element_1) && GST_IS_ELEMENT (element_2));
2001 va_start (args, element_2);
2004 gst_element_unlink (element_1, element_2);
2006 element_1 = element_2;
2007 element_2 = va_arg (args, GstElement *);
2014 * gst_element_unlink:
2015 * @src: the source #GstElement to unlink.
2016 * @dest: the sink #GstElement to unlink.
2018 * Unlinks all source pads of the source element with all sink pads
2019 * of the sink element to which they are linked.
2021 * If the link has been made using gst_element_link(), it could have created an
2022 * requestpad, which has to be released using gst_element_release_request_pad().
2025 gst_element_unlink (GstElement * src, GstElement * dest)
2028 gboolean done = FALSE;
2030 g_return_if_fail (GST_IS_ELEMENT (src));
2031 g_return_if_fail (GST_IS_ELEMENT (dest));
2033 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS, "unlinking \"%s\" and \"%s\"",
2034 GST_ELEMENT_NAME (src), GST_ELEMENT_NAME (dest));
2036 pads = gst_element_iterate_pads (src);
2040 switch (gst_iterator_next (pads, &data)) {
2041 case GST_ITERATOR_OK:
2043 GstPad *pad = GST_PAD_CAST (data);
2045 if (GST_PAD_IS_SRC (pad)) {
2046 GstPad *peerpad = gst_pad_get_peer (pad);
2048 /* see if the pad is linked and is really a pad of dest */
2050 GstElement *peerelem;
2052 peerelem = gst_pad_get_parent_element (peerpad);
2054 if (peerelem == dest) {
2055 gst_pad_unlink (pad, peerpad);
2058 gst_object_unref (peerelem);
2060 gst_object_unref (peerpad);
2063 gst_object_unref (pad);
2066 case GST_ITERATOR_RESYNC:
2067 gst_iterator_resync (pads);
2069 case GST_ITERATOR_DONE:
2073 g_assert_not_reached ();
2077 gst_iterator_free (pads);
2081 * gst_element_query_position:
2082 * @element: a #GstElement to invoke the position query on.
2083 * @format: a pointer to the #GstFormat asked for.
2084 * On return contains the #GstFormat used.
2085 * @cur: A location in which to store the current position, or NULL.
2087 * Queries an element for the stream position.
2089 * Returns: TRUE if the query could be performed.
2092 gst_element_query_position (GstElement * element, GstFormat * format,
2098 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2099 g_return_val_if_fail (format != NULL, FALSE);
2101 query = gst_query_new_position (*format);
2102 ret = gst_element_query (element, query);
2105 gst_query_parse_position (query, format, cur);
2107 gst_query_unref (query);
2113 * gst_element_query_duration:
2114 * @element: a #GstElement to invoke the duration query on.
2115 * @format: a pointer to the #GstFormat asked for.
2116 * On return contains the #GstFormat used.
2117 * @duration: A location in which to store the total duration, or NULL.
2119 * Queries an element for the total stream duration.
2121 * Returns: TRUE if the query could be performed.
2124 gst_element_query_duration (GstElement * element, GstFormat * format,
2130 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2131 g_return_val_if_fail (format != NULL, FALSE);
2133 query = gst_query_new_duration (*format);
2134 ret = gst_element_query (element, query);
2137 gst_query_parse_duration (query, format, duration);
2139 gst_query_unref (query);
2145 * gst_element_query_convert:
2146 * @element: a #GstElement to invoke the convert query on.
2147 * @src_format: a #GstFormat to convert from.
2148 * @src_val: a value to convert.
2149 * @dest_format: a pointer to the #GstFormat to convert to.
2150 * @dest_val: a pointer to the result.
2152 * Queries an element to convert @src_val in @src_format to @dest_format.
2154 * Returns: TRUE if the query could be performed.
2157 gst_element_query_convert (GstElement * element, GstFormat src_format,
2158 gint64 src_val, GstFormat * dest_format, gint64 * dest_val)
2163 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2164 g_return_val_if_fail (dest_format != NULL, FALSE);
2165 g_return_val_if_fail (dest_val != NULL, FALSE);
2167 if (*dest_format == src_format) {
2168 *dest_val = src_val;
2172 query = gst_query_new_convert (src_format, src_val, *dest_format);
2173 ret = gst_element_query (element, query);
2176 gst_query_parse_convert (query, NULL, NULL, dest_format, dest_val);
2178 gst_query_unref (query);
2184 * gst_element_seek_simple
2185 * @element: a #GstElement to seek on
2186 * @format: a #GstFormat to execute the seek in, such as #GST_FORMAT_TIME
2187 * @seek_flags: seek options; playback applications will usually want to use
2188 * GST_SEEK_FLAG_FLUSH | GST_SEEK_FLAG_KEY_UNIT here
2189 * @seek_pos: position to seek to (relative to the start); if you are doing
2190 * a seek in #GST_FORMAT_TIME this value is in nanoseconds -
2191 * multiply with #GST_SECOND to convert seconds to nanoseconds or
2192 * with #GST_MSECOND to convert milliseconds to nanoseconds.
2194 * Simple API to perform a seek on the given element, meaning it just seeks
2195 * to the given position relative to the start of the stream. For more complex
2196 * operations like segment seeks (e.g. for looping) or changing the playback
2197 * rate or seeking relative to the last configured playback segment you should
2198 * use gst_element_seek().
2200 * In a completely prerolled PAUSED or PLAYING pipeline, seeking is always
2201 * guaranteed to return %TRUE on a seekable media type or %FALSE when the media
2202 * type is certainly not seekable (such as a live stream).
2204 * Some elements allow for seeking in the READY state, in this
2205 * case they will store the seek event and execute it when they are put to
2206 * PAUSED. If the element supports seek in READY, it will always return %TRUE when
2207 * it receives the event in the READY state.
2209 * Returns: %TRUE if the seek operation succeeded (the seek might not always be
2210 * executed instantly though)
2215 gst_element_seek_simple (GstElement * element, GstFormat format,
2216 GstSeekFlags seek_flags, gint64 seek_pos)
2218 g_return_val_if_fail (GST_IS_ELEMENT (element), FALSE);
2219 g_return_val_if_fail (seek_pos >= 0, FALSE);
2221 return gst_element_seek (element, 1.0, format, seek_flags,
2222 GST_SEEK_TYPE_SET, seek_pos, GST_SEEK_TYPE_NONE, 0);
2226 * gst_pad_use_fixed_caps:
2227 * @pad: the pad to use
2229 * A helper function you can use that sets the
2230 * @gst_pad_get_fixed_caps_func as the getcaps function for the
2231 * pad. This way the function will always return the negotiated caps
2232 * or in case the pad is not negotiated, the padtemplate caps.
2234 * Use this function on a pad that, once _set_caps() has been called
2235 * on it, cannot be renegotiated to something else.
2238 gst_pad_use_fixed_caps (GstPad * pad)
2240 gst_pad_set_getcaps_function (pad, gst_pad_get_fixed_caps_func);
2244 * gst_pad_get_fixed_caps_func:
2245 * @pad: the pad to use
2247 * A helper function you can use as a GetCaps function that
2248 * will return the currently negotiated caps or the padtemplate
2251 * Returns: The currently negotiated caps or the padtemplate.
2254 gst_pad_get_fixed_caps_func (GstPad * pad)
2258 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2260 GST_OBJECT_LOCK (pad);
2261 if (GST_PAD_CAPS (pad)) {
2262 result = GST_PAD_CAPS (pad);
2264 GST_CAT_DEBUG (GST_CAT_CAPS,
2265 "using pad caps %p %" GST_PTR_FORMAT, result, result);
2267 result = gst_caps_ref (result);
2268 } else if (GST_PAD_PAD_TEMPLATE (pad)) {
2269 GstPadTemplate *templ = GST_PAD_PAD_TEMPLATE (pad);
2271 result = GST_PAD_TEMPLATE_CAPS (templ);
2272 GST_CAT_DEBUG (GST_CAT_CAPS,
2273 "using pad template %p with caps %p %" GST_PTR_FORMAT, templ, result,
2276 result = gst_caps_ref (result);
2278 GST_CAT_DEBUG (GST_CAT_CAPS, "pad has no caps");
2279 result = gst_caps_new_empty ();
2281 GST_OBJECT_UNLOCK (pad);
2287 * gst_pad_get_parent_element:
2290 * Gets the parent of @pad, cast to a #GstElement. If a @pad has no parent or
2291 * its parent is not an element, return NULL.
2293 * Returns: The parent of the pad. The caller has a reference on the parent, so
2294 * unref when you're finished with it.
2299 gst_pad_get_parent_element (GstPad * pad)
2303 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2305 p = gst_object_get_parent (GST_OBJECT_CAST (pad));
2307 if (p && !GST_IS_ELEMENT (p)) {
2308 gst_object_unref (p);
2311 return GST_ELEMENT_CAST (p);
2315 * gst_object_default_error:
2316 * @source: the #GstObject that initiated the error.
2317 * @error: the GError.
2318 * @debug: an additional debug information string, or NULL.
2320 * A default error function.
2322 * The default handler will simply print the error string using g_print.
2325 gst_object_default_error (GstObject * source, GError * error, gchar * debug)
2327 gchar *name = gst_object_get_path_string (source);
2329 g_print (_("ERROR: from element %s: %s\n"), name, error->message);
2331 g_print (_("Additional debug info:\n%s\n"), debug);
2339 * @element_1: the #GstElement element to add to the bin
2340 * @...: additional elements to add to the bin
2342 * Adds a NULL-terminated list of elements to a bin. This function is
2343 * equivalent to calling gst_bin_add() for each member of the list. The return
2344 * value of each gst_bin_add() is ignored.
2347 gst_bin_add_many (GstBin * bin, GstElement * element_1, ...)
2351 g_return_if_fail (GST_IS_BIN (bin));
2352 g_return_if_fail (GST_IS_ELEMENT (element_1));
2354 va_start (args, element_1);
2357 gst_bin_add (bin, element_1);
2359 element_1 = va_arg (args, GstElement *);
2366 * gst_bin_remove_many:
2368 * @element_1: the first #GstElement to remove from the bin
2369 * @...: NULL-terminated list of elements to remove from the bin
2371 * Remove a list of elements from a bin. This function is equivalent
2372 * to calling gst_bin_remove() with each member of the list.
2375 gst_bin_remove_many (GstBin * bin, GstElement * element_1, ...)
2379 g_return_if_fail (GST_IS_BIN (bin));
2380 g_return_if_fail (GST_IS_ELEMENT (element_1));
2382 va_start (args, element_1);
2385 gst_bin_remove (bin, element_1);
2387 element_1 = va_arg (args, GstElement *);
2394 gst_element_populate_std_props (GObjectClass * klass, const gchar * prop_name,
2395 guint arg_id, GParamFlags flags)
2397 GQuark prop_id = g_quark_from_string (prop_name);
2400 static GQuark fd_id = 0;
2401 static GQuark blocksize_id;
2402 static GQuark bytesperread_id;
2403 static GQuark dump_id;
2404 static GQuark filesize_id;
2405 static GQuark mmapsize_id;
2406 static GQuark location_id;
2407 static GQuark offset_id;
2408 static GQuark silent_id;
2409 static GQuark touch_id;
2412 fd_id = g_quark_from_static_string ("fd");
2413 blocksize_id = g_quark_from_static_string ("blocksize");
2414 bytesperread_id = g_quark_from_static_string ("bytesperread");
2415 dump_id = g_quark_from_static_string ("dump");
2416 filesize_id = g_quark_from_static_string ("filesize");
2417 mmapsize_id = g_quark_from_static_string ("mmapsize");
2418 location_id = g_quark_from_static_string ("location");
2419 offset_id = g_quark_from_static_string ("offset");
2420 silent_id = g_quark_from_static_string ("silent");
2421 touch_id = g_quark_from_static_string ("touch");
2424 if (prop_id == fd_id) {
2425 pspec = g_param_spec_int ("fd", "File-descriptor",
2426 "File-descriptor for the file being read", 0, G_MAXINT, 0, flags);
2427 } else if (prop_id == blocksize_id) {
2428 pspec = g_param_spec_ulong ("blocksize", "Block Size",
2429 "Block size to read per buffer", 0, G_MAXULONG, 4096, flags);
2431 } else if (prop_id == bytesperread_id) {
2432 pspec = g_param_spec_int ("bytesperread", "Bytes per read",
2433 "Number of bytes to read per buffer", G_MININT, G_MAXINT, 0, flags);
2435 } else if (prop_id == dump_id) {
2436 pspec = g_param_spec_boolean ("dump", "Dump",
2437 "Dump bytes to stdout", FALSE, flags);
2439 } else if (prop_id == filesize_id) {
2440 pspec = g_param_spec_int64 ("filesize", "File Size",
2441 "Size of the file being read", 0, G_MAXINT64, 0, flags);
2443 } else if (prop_id == mmapsize_id) {
2444 pspec = g_param_spec_ulong ("mmapsize", "mmap() Block Size",
2445 "Size in bytes of mmap()d regions", 0, G_MAXULONG, 4 * 1048576, flags);
2447 } else if (prop_id == location_id) {
2448 pspec = g_param_spec_string ("location", "File Location",
2449 "Location of the file to read", NULL, flags);
2451 } else if (prop_id == offset_id) {
2452 pspec = g_param_spec_int64 ("offset", "File Offset",
2453 "Byte offset of current read pointer", 0, G_MAXINT64, 0, flags);
2455 } else if (prop_id == silent_id) {
2456 pspec = g_param_spec_boolean ("silent", "Silent", "Don't produce events",
2459 } else if (prop_id == touch_id) {
2460 pspec = g_param_spec_boolean ("touch", "Touch read data",
2461 "Touch data to force disk read before " "push ()", TRUE, flags);
2463 g_warning ("Unknown - 'standard' property '%s' id %d from klass %s",
2464 prop_name, arg_id, g_type_name (G_OBJECT_CLASS_TYPE (klass)));
2469 g_object_class_install_property (klass, arg_id, pspec);
2474 * gst_element_class_install_std_props:
2475 * @klass: the #GstElementClass to add the properties to.
2476 * @first_name: the name of the first property.
2477 * in a NULL terminated
2478 * @...: the id and flags of the first property, followed by
2479 * further 'name', 'id', 'flags' triplets and terminated by NULL.
2481 * Adds a list of standardized properties with types to the @klass.
2482 * the id is for the property switch in your get_prop method, and
2483 * the flags determine readability / writeability.
2486 gst_element_class_install_std_props (GstElementClass * klass,
2487 const gchar * first_name, ...)
2493 g_return_if_fail (GST_IS_ELEMENT_CLASS (klass));
2495 va_start (args, first_name);
2500 int arg_id = va_arg (args, int);
2501 int flags = va_arg (args, int);
2503 gst_element_populate_std_props ((GObjectClass *) klass, name, arg_id,
2506 name = va_arg (args, char *);
2515 * @buf1: the first source #GstBuffer to merge.
2516 * @buf2: the second source #GstBuffer to merge.
2518 * Create a new buffer that is the concatenation of the two source
2519 * buffers. The original source buffers will not be modified or
2520 * unref'd. Make sure you unref the source buffers if they are not used
2521 * anymore afterwards.
2523 * If the buffers point to contiguous areas of memory, the buffer
2524 * is created without copying the data.
2526 * Returns: the new #GstBuffer which is the concatenation of the source buffers.
2529 gst_buffer_merge (GstBuffer * buf1, GstBuffer * buf2)
2533 /* we're just a specific case of the more general gst_buffer_span() */
2534 result = gst_buffer_span (buf1, 0, buf2, buf1->size + buf2->size);
2541 * @buf1: the first source #GstBuffer.
2542 * @buf2: the second source #GstBuffer.
2544 * Create a new buffer that is the concatenation of the two source
2545 * buffers, and unrefs the original source buffers.
2547 * If the buffers point to contiguous areas of memory, the buffer
2548 * is created without copying the data.
2550 * This is a convenience function for C programmers. See also
2551 * gst_buffer_merge(), which does the same thing without
2552 * unreffing the input parameters. Language bindings without
2553 * explicit reference counting should not wrap this function.
2555 * Returns: the new #GstBuffer which is the concatenation of the source buffers.
2558 gst_buffer_join (GstBuffer * buf1, GstBuffer * buf2)
2562 result = gst_buffer_span (buf1, 0, buf2, buf1->size + buf2->size);
2563 gst_buffer_unref (buf1);
2564 gst_buffer_unref (buf2);
2572 * @dest: buffer to stamp
2573 * @src: buffer to stamp from
2575 * Copies additional information (the timestamp, duration, and offset start
2576 * and end) from one buffer to the other.
2578 * This function does not copy any buffer flags or caps and is equivalent to
2579 * gst_buffer_copy_metadata(@dest, @src, GST_BUFFER_COPY_TIMESTAMPS).
2581 * Deprecated: use gst_buffer_copy_metadata() instead, it provides more
2584 #ifndef GST_REMOVE_DEPRECATED
2586 gst_buffer_stamp (GstBuffer * dest, const GstBuffer * src)
2588 gst_buffer_copy_metadata (dest, src, GST_BUFFER_COPY_TIMESTAMPS);
2590 #endif /* GST_REMOVE_DEPRECATED */
2593 intersect_caps_func (GstPad * pad, GValue * ret, GstPad * orig)
2595 /* skip the pad, the request came from */
2597 GstCaps *peercaps, *existing;
2599 existing = g_value_get_pointer (ret);
2600 peercaps = gst_pad_peer_get_caps (pad);
2601 if (peercaps == NULL)
2602 peercaps = gst_caps_new_any ();
2603 g_value_set_pointer (ret, gst_caps_intersect (existing, peercaps));
2604 gst_caps_unref (existing);
2605 gst_caps_unref (peercaps);
2607 gst_object_unref (pad);
2612 * gst_pad_proxy_getcaps:
2613 * @pad: a #GstPad to proxy.
2615 * Calls gst_pad_get_allowed_caps() for every other pad belonging to the
2616 * same element as @pad, and returns the intersection of the results.
2618 * This function is useful as a default getcaps function for an element
2619 * that can handle any stream format, but requires all its pads to have
2620 * the same caps. Two such elements are tee and aggregator.
2622 * Returns: the intersection of the other pads' allowed caps.
2625 gst_pad_proxy_getcaps (GstPad * pad)
2627 GstElement *element;
2628 GstCaps *caps, *intersected;
2630 GstIteratorResult res;
2631 GValue ret = { 0, };
2633 g_return_val_if_fail (GST_IS_PAD (pad), NULL);
2635 GST_CAT_DEBUG (GST_CAT_PADS, "proxying getcaps for %s:%s",
2636 GST_DEBUG_PAD_NAME (pad));
2638 element = gst_pad_get_parent_element (pad);
2639 if (element == NULL)
2642 /* value to hold the return, by default it holds ANY, the ref is taken by
2644 g_value_init (&ret, G_TYPE_POINTER);
2645 g_value_set_pointer (&ret, gst_caps_new_any ());
2647 iter = gst_element_iterate_pads (element);
2650 gst_iterator_fold (iter, (GstIteratorFoldFunction) intersect_caps_func,
2653 case GST_ITERATOR_RESYNC:
2654 /* unref any value stored */
2655 if ((caps = g_value_get_pointer (&ret)))
2656 gst_caps_unref (caps);
2657 /* need to reset the result again to ANY */
2658 g_value_set_pointer (&ret, gst_caps_new_any ());
2659 gst_iterator_resync (iter);
2661 case GST_ITERATOR_DONE:
2662 /* all pads iterated, return collected value */
2665 /* iterator returned _ERROR or premature end with _OK,
2666 * mark an error and exit */
2667 if ((caps = g_value_get_pointer (&ret)))
2668 gst_caps_unref (caps);
2669 g_value_set_pointer (&ret, NULL);
2674 gst_iterator_free (iter);
2676 gst_object_unref (element);
2678 caps = g_value_get_pointer (&ret);
2679 g_value_unset (&ret);
2681 intersected = gst_caps_intersect (caps, gst_pad_get_pad_template_caps (pad));
2682 gst_caps_unref (caps);
2689 g_warning ("Pad list returned error on element %s",
2690 GST_ELEMENT_NAME (element));
2691 gst_iterator_free (iter);
2692 gst_object_unref (element);
2704 link_fold_func (GstPad * pad, GValue * ret, LinkData * data)
2706 gboolean success = TRUE;
2708 if (pad != data->orig) {
2709 success = gst_pad_set_caps (pad, data->caps);
2710 g_value_set_boolean (ret, success);
2712 gst_object_unref (pad);
2718 * gst_pad_proxy_setcaps
2719 * @pad: a #GstPad to proxy from
2720 * @caps: the #GstCaps to link with
2722 * Calls gst_pad_set_caps() for every other pad belonging to the
2723 * same element as @pad. If gst_pad_set_caps() fails on any pad,
2724 * the proxy setcaps fails. May be used only during negotiation.
2726 * Returns: TRUE if sucessful
2729 gst_pad_proxy_setcaps (GstPad * pad, GstCaps * caps)
2731 GstElement *element;
2733 GstIteratorResult res;
2734 GValue ret = { 0, };
2737 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2738 g_return_val_if_fail (caps != NULL, FALSE);
2740 GST_CAT_DEBUG (GST_CAT_PADS, "proxying pad link for %s:%s",
2741 GST_DEBUG_PAD_NAME (pad));
2743 element = gst_pad_get_parent_element (pad);
2744 if (element == NULL)
2747 iter = gst_element_iterate_pads (element);
2749 g_value_init (&ret, G_TYPE_BOOLEAN);
2750 g_value_set_boolean (&ret, TRUE);
2754 res = gst_iterator_fold (iter, (GstIteratorFoldFunction) link_fold_func,
2756 gst_iterator_free (iter);
2758 if (res != GST_ITERATOR_DONE)
2761 gst_object_unref (element);
2763 /* ok not to unset the gvalue */
2764 return g_value_get_boolean (&ret);
2769 g_warning ("Pad list changed during proxy_pad_link for element %s",
2770 GST_ELEMENT_NAME (element));
2771 gst_object_unref (element);
2777 * gst_pad_query_position:
2778 * @pad: a #GstPad to invoke the position query on.
2779 * @format: a pointer to the #GstFormat asked for.
2780 * On return contains the #GstFormat used.
2781 * @cur: A location in which to store the current position, or NULL.
2783 * Queries a pad for the stream position.
2785 * Returns: TRUE if the query could be performed.
2788 gst_pad_query_position (GstPad * pad, GstFormat * format, gint64 * cur)
2793 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2794 g_return_val_if_fail (format != NULL, FALSE);
2796 query = gst_query_new_position (*format);
2797 ret = gst_pad_query (pad, query);
2800 gst_query_parse_position (query, format, cur);
2802 gst_query_unref (query);
2808 * gst_pad_query_peer_position:
2809 * @pad: a #GstPad on whose peer to invoke the position query on.
2810 * Must be a sink pad.
2811 * @format: a pointer to the #GstFormat asked for.
2812 * On return contains the #GstFormat used.
2813 * @cur: A location in which to store the current position, or NULL.
2815 * Queries the peer of a given sink pad for the stream position.
2817 * Returns: TRUE if the query could be performed.
2820 gst_pad_query_peer_position (GstPad * pad, GstFormat * format, gint64 * cur)
2822 gboolean ret = FALSE;
2825 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2826 g_return_val_if_fail (GST_PAD_IS_SINK (pad), FALSE);
2827 g_return_val_if_fail (format != NULL, FALSE);
2829 peer = gst_pad_get_peer (pad);
2831 ret = gst_pad_query_position (peer, format, cur);
2832 gst_object_unref (peer);
2839 * gst_pad_query_duration:
2840 * @pad: a #GstPad to invoke the duration query on.
2841 * @format: a pointer to the #GstFormat asked for.
2842 * On return contains the #GstFormat used.
2843 * @duration: A location in which to store the total duration, or NULL.
2845 * Queries a pad for the total stream duration.
2847 * Returns: TRUE if the query could be performed.
2850 gst_pad_query_duration (GstPad * pad, GstFormat * format, gint64 * duration)
2855 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2856 g_return_val_if_fail (format != NULL, FALSE);
2858 query = gst_query_new_duration (*format);
2859 ret = gst_pad_query (pad, query);
2862 gst_query_parse_duration (query, format, duration);
2864 gst_query_unref (query);
2870 * gst_pad_query_peer_duration:
2871 * @pad: a #GstPad on whose peer pad to invoke the duration query on.
2872 * Must be a sink pad.
2873 * @format: a pointer to the #GstFormat asked for.
2874 * On return contains the #GstFormat used.
2875 * @duration: A location in which to store the total duration, or NULL.
2877 * Queries the peer pad of a given sink pad for the total stream duration.
2879 * Returns: TRUE if the query could be performed.
2882 gst_pad_query_peer_duration (GstPad * pad, GstFormat * format,
2885 gboolean ret = FALSE;
2888 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2889 g_return_val_if_fail (GST_PAD_IS_SINK (pad), FALSE);
2890 g_return_val_if_fail (format != NULL, FALSE);
2892 peer = gst_pad_get_peer (pad);
2894 ret = gst_pad_query_duration (peer, format, duration);
2895 gst_object_unref (peer);
2902 * gst_pad_query_convert:
2903 * @pad: a #GstPad to invoke the convert query on.
2904 * @src_format: a #GstFormat to convert from.
2905 * @src_val: a value to convert.
2906 * @dest_format: a pointer to the #GstFormat to convert to.
2907 * @dest_val: a pointer to the result.
2909 * Queries a pad to convert @src_val in @src_format to @dest_format.
2911 * Returns: TRUE if the query could be performed.
2914 gst_pad_query_convert (GstPad * pad, GstFormat src_format, gint64 src_val,
2915 GstFormat * dest_format, gint64 * dest_val)
2920 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2921 g_return_val_if_fail (dest_format != NULL, FALSE);
2922 g_return_val_if_fail (dest_val != NULL, FALSE);
2924 if (*dest_format == src_format) {
2925 *dest_val = src_val;
2929 query = gst_query_new_convert (src_format, src_val, *dest_format);
2930 ret = gst_pad_query (pad, query);
2933 gst_query_parse_convert (query, NULL, NULL, dest_format, dest_val);
2935 gst_query_unref (query);
2941 * gst_pad_query_peer_convert:
2942 * @pad: a #GstPad, on whose peer pad to invoke the convert query on.
2943 * Must be a sink pad.
2944 * @src_format: a #GstFormat to convert from.
2945 * @src_val: a value to convert.
2946 * @dest_format: a pointer to the #GstFormat to convert to.
2947 * @dest_val: a pointer to the result.
2949 * Queries the peer pad of a given sink pad to convert @src_val in @src_format
2952 * Returns: TRUE if the query could be performed.
2955 gst_pad_query_peer_convert (GstPad * pad, GstFormat src_format, gint64 src_val,
2956 GstFormat * dest_format, gint64 * dest_val)
2958 gboolean ret = FALSE;
2961 g_return_val_if_fail (GST_IS_PAD (pad), FALSE);
2962 g_return_val_if_fail (GST_PAD_IS_SINK (pad), FALSE);
2963 g_return_val_if_fail (src_val >= 0, FALSE);
2964 g_return_val_if_fail (dest_format != NULL, FALSE);
2965 g_return_val_if_fail (dest_val != NULL, FALSE);
2967 peer = gst_pad_get_peer (pad);
2969 ret = gst_pad_query_convert (peer, src_format, src_val, dest_format,
2971 gst_object_unref (peer);
2978 * gst_atomic_int_set:
2979 * @atomic_int: pointer to an atomic integer
2980 * @value: value to set
2982 * Unconditionally sets the atomic integer to @value.
2984 * Deprecated: Use g_atomic_int_set().
2987 #ifndef GST_REMOVE_DEPRECATED
2989 gst_atomic_int_set (gint * atomic_int, gint value)
2991 g_atomic_int_set (atomic_int, value);
2996 * gst_pad_add_data_probe:
2997 * @pad: pad to add the data probe handler to
2998 * @handler: function to call when data is passed over pad
2999 * @data: data to pass along with the handler
3001 * Adds a "data probe" to a pad. This function will be called whenever data
3002 * passes through a pad. In this case data means both events and buffers. The
3003 * probe will be called with the data as an argument, meaning @handler should
3004 * have the same callback signature as the #GstPad::have-data signal.
3005 * Note that the data will have a reference count greater than 1, so it will
3006 * be immutable -- you must not change it.
3008 * For source pads, the probe will be called after the blocking function, if any
3009 * (see gst_pad_set_blocked_async()), but before looking up the peer to chain
3010 * to. For sink pads, the probe function will be called before configuring the
3011 * sink with new caps, if any, and before calling the pad's chain function.
3013 * Your data probe should return TRUE to let the data continue to flow, or FALSE
3014 * to drop it. Dropping data is rarely useful, but occasionally comes in handy
3017 * Although probes are implemented internally by connecting @handler to the
3018 * have-data signal on the pad, if you want to remove a probe it is insufficient
3019 * to only call g_signal_handler_disconnect on the returned handler id. To
3020 * remove a probe, use the appropriate function, such as
3021 * gst_pad_remove_data_probe().
3023 * Returns: The handler id.
3026 gst_pad_add_data_probe (GstPad * pad, GCallback handler, gpointer data)
3028 return gst_pad_add_data_probe_full (pad, handler, data, NULL);
3032 * gst_pad_add_data_probe_full:
3033 * @pad: pad to add the data probe handler to
3034 * @handler: function to call when data is passed over pad
3035 * @data: data to pass along with the handler
3036 * @notify: function to call when the probe is disconnected, or NULL
3038 * Adds a "data probe" to a pad. This function will be called whenever data
3039 * passes through a pad. In this case data means both events and buffers. The
3040 * probe will be called with the data as an argument, meaning @handler should
3041 * have the same callback signature as the #GstPad::have-data signal.
3042 * Note that the data will have a reference count greater than 1, so it will
3043 * be immutable -- you must not change it.
3045 * For source pads, the probe will be called after the blocking function, if any
3046 * (see gst_pad_set_blocked_async()), but before looking up the peer to chain
3047 * to. For sink pads, the probe function will be called before configuring the
3048 * sink with new caps, if any, and before calling the pad's chain function.
3050 * Your data probe should return TRUE to let the data continue to flow, or FALSE
3051 * to drop it. Dropping data is rarely useful, but occasionally comes in handy
3054 * Although probes are implemented internally by connecting @handler to the
3055 * have-data signal on the pad, if you want to remove a probe it is insufficient
3056 * to only call g_signal_handler_disconnect on the returned handler id. To
3057 * remove a probe, use the appropriate function, such as
3058 * gst_pad_remove_data_probe().
3060 * The @notify function is called when the probe is disconnected and usually
3061 * used to free @data.
3063 * Returns: The handler id.
3068 gst_pad_add_data_probe_full (GstPad * pad, GCallback handler,
3069 gpointer data, GDestroyNotify notify)
3073 g_return_val_if_fail (GST_IS_PAD (pad), 0);
3074 g_return_val_if_fail (handler != NULL, 0);
3076 GST_OBJECT_LOCK (pad);
3078 /* we only expose a GDestroyNotify in our API because that's less confusing */
3079 sigid = g_signal_connect_data (pad, "have-data", handler, data,
3080 (GClosureNotify) notify, 0);
3082 GST_PAD_DO_EVENT_SIGNALS (pad)++;
3083 GST_PAD_DO_BUFFER_SIGNALS (pad)++;
3084 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
3085 "adding data probe, now %d data, %d event probes",
3086 GST_PAD_DO_BUFFER_SIGNALS (pad), GST_PAD_DO_EVENT_SIGNALS (pad));
3087 GST_OBJECT_UNLOCK (pad);
3093 * gst_pad_add_event_probe:
3094 * @pad: pad to add the event probe handler to
3095 * @handler: function to call when events are passed over pad
3096 * @data: data to pass along with the handler
3098 * Adds a probe that will be called for all events passing through a pad. See
3099 * gst_pad_add_data_probe() for more information.
3101 * Returns: The handler id
3104 gst_pad_add_event_probe (GstPad * pad, GCallback handler, gpointer data)
3106 return gst_pad_add_event_probe_full (pad, handler, data, NULL);
3110 * gst_pad_add_event_probe_full:
3111 * @pad: pad to add the event probe handler to
3112 * @handler: function to call when events are passed over pad
3113 * @data: data to pass along with the handler, or NULL
3114 * @notify: function to call when probe is disconnected, or NULL
3116 * Adds a probe that will be called for all events passing through a pad. See
3117 * gst_pad_add_data_probe() for more information.
3119 * The @notify function is called when the probe is disconnected and usually
3120 * used to free @data.
3122 * Returns: The handler id
3127 gst_pad_add_event_probe_full (GstPad * pad, GCallback handler,
3128 gpointer data, GDestroyNotify notify)
3132 g_return_val_if_fail (GST_IS_PAD (pad), 0);
3133 g_return_val_if_fail (handler != NULL, 0);
3135 GST_OBJECT_LOCK (pad);
3137 /* we only expose a GDestroyNotify in our API because that's less confusing */
3138 sigid = g_signal_connect_data (pad, "have-data::event", handler, data,
3139 (GClosureNotify) notify, 0);
3141 GST_PAD_DO_EVENT_SIGNALS (pad)++;
3142 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "adding event probe, now %d probes",
3143 GST_PAD_DO_EVENT_SIGNALS (pad));
3144 GST_OBJECT_UNLOCK (pad);
3150 * gst_pad_add_buffer_probe:
3151 * @pad: pad to add the buffer probe handler to
3152 * @handler: function to call when buffers are passed over pad
3153 * @data: data to pass along with the handler
3155 * Adds a probe that will be called for all buffers passing through a pad. See
3156 * gst_pad_add_data_probe() for more information.
3158 * Returns: The handler id
3161 gst_pad_add_buffer_probe (GstPad * pad, GCallback handler, gpointer data)
3163 return gst_pad_add_buffer_probe_full (pad, handler, data, NULL);
3167 * gst_pad_add_buffer_probe_full:
3168 * @pad: pad to add the buffer probe handler to
3169 * @handler: function to call when buffer are passed over pad
3170 * @data: data to pass along with the handler
3171 * @notify: function to call when the probe is disconnected, or NULL
3173 * Adds a probe that will be called for all buffers passing through a pad. See
3174 * gst_pad_add_data_probe() for more information.
3176 * The @notify function is called when the probe is disconnected and usually
3177 * used to free @data.
3179 * Returns: The handler id
3184 gst_pad_add_buffer_probe_full (GstPad * pad, GCallback handler,
3185 gpointer data, GDestroyNotify notify)
3189 g_return_val_if_fail (GST_IS_PAD (pad), 0);
3190 g_return_val_if_fail (handler != NULL, 0);
3192 GST_OBJECT_LOCK (pad);
3194 /* we only expose a GDestroyNotify in our API because that's less confusing */
3195 sigid = g_signal_connect_data (pad, "have-data::buffer", handler, data,
3196 (GClosureNotify) notify, 0);
3198 GST_PAD_DO_BUFFER_SIGNALS (pad)++;
3199 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad, "adding buffer probe, now %d probes",
3200 GST_PAD_DO_BUFFER_SIGNALS (pad));
3201 GST_OBJECT_UNLOCK (pad);
3207 * gst_pad_remove_data_probe:
3208 * @pad: pad to remove the data probe handler from
3209 * @handler_id: handler id returned from gst_pad_add_data_probe
3211 * Removes a data probe from @pad.
3214 gst_pad_remove_data_probe (GstPad * pad, guint handler_id)
3216 g_return_if_fail (GST_IS_PAD (pad));
3217 g_return_if_fail (handler_id > 0);
3219 GST_OBJECT_LOCK (pad);
3220 g_signal_handler_disconnect (pad, handler_id);
3221 GST_PAD_DO_BUFFER_SIGNALS (pad)--;
3222 GST_PAD_DO_EVENT_SIGNALS (pad)--;
3223 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
3224 "removed data probe, now %d event, %d buffer probes",
3225 GST_PAD_DO_EVENT_SIGNALS (pad), GST_PAD_DO_BUFFER_SIGNALS (pad));
3226 GST_OBJECT_UNLOCK (pad);
3231 * gst_pad_remove_event_probe:
3232 * @pad: pad to remove the event probe handler from
3233 * @handler_id: handler id returned from gst_pad_add_event_probe
3235 * Removes an event probe from @pad.
3238 gst_pad_remove_event_probe (GstPad * pad, guint handler_id)
3240 g_return_if_fail (GST_IS_PAD (pad));
3241 g_return_if_fail (handler_id > 0);
3243 GST_OBJECT_LOCK (pad);
3244 g_signal_handler_disconnect (pad, handler_id);
3245 GST_PAD_DO_EVENT_SIGNALS (pad)--;
3246 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
3247 "removed event probe, now %d event probes",
3248 GST_PAD_DO_EVENT_SIGNALS (pad));
3249 GST_OBJECT_UNLOCK (pad);
3253 * gst_pad_remove_buffer_probe:
3254 * @pad: pad to remove the buffer probe handler from
3255 * @handler_id: handler id returned from gst_pad_add_buffer_probe
3257 * Removes a buffer probe from @pad.
3260 gst_pad_remove_buffer_probe (GstPad * pad, guint handler_id)
3262 g_return_if_fail (GST_IS_PAD (pad));
3263 g_return_if_fail (handler_id > 0);
3265 GST_OBJECT_LOCK (pad);
3266 g_signal_handler_disconnect (pad, handler_id);
3267 GST_PAD_DO_BUFFER_SIGNALS (pad)--;
3268 GST_CAT_DEBUG_OBJECT (GST_CAT_PADS, pad,
3269 "removed buffer probe, now %d buffer probes",
3270 GST_PAD_DO_BUFFER_SIGNALS (pad));
3271 GST_OBJECT_UNLOCK (pad);
3276 * gst_element_found_tags_for_pad:
3277 * @element: element for which to post taglist to bus.
3278 * @pad: pad on which to push tag-event.
3279 * @list: the taglist to post on the bus and create event from.
3281 * Posts a message to the bus that new tags were found and pushes the
3282 * tags as event. Takes ownership of the @list.
3284 * This is a utility method for elements. Applications should use the
3285 * #GstTagSetter interface.
3288 gst_element_found_tags_for_pad (GstElement * element,
3289 GstPad * pad, GstTagList * list)
3291 g_return_if_fail (element != NULL);
3292 g_return_if_fail (pad != NULL);
3293 g_return_if_fail (list != NULL);
3295 gst_pad_push_event (pad, gst_event_new_tag (gst_tag_list_copy (list)));
3296 /* FIXME 0.11: Set the pad as source. */
3297 gst_element_post_message (element,
3298 gst_message_new_tag_full (GST_OBJECT (element), pad, list));
3302 push_and_ref (GstPad * pad, GstEvent * event)
3304 gst_pad_push_event (pad, gst_event_ref (event));
3305 /* iterator refs pad, we unref when we are done with it */
3306 gst_object_unref (pad);
3310 * gst_element_found_tags:
3311 * @element: element for which we found the tags.
3312 * @list: list of tags.
3314 * Posts a message to the bus that new tags were found, and pushes an event
3315 * to all sourcepads. Takes ownership of the @list.
3317 * This is a utility method for elements. Applications should use the
3318 * #GstTagSetter interface.
3321 gst_element_found_tags (GstElement * element, GstTagList * list)
3326 g_return_if_fail (element != NULL);
3327 g_return_if_fail (list != NULL);
3329 iter = gst_element_iterate_src_pads (element);
3330 event = gst_event_new_tag (gst_tag_list_copy (list));
3331 gst_iterator_foreach (iter, (GFunc) push_and_ref, event);
3332 gst_iterator_free (iter);
3333 gst_event_unref (event);
3335 gst_element_post_message (element,
3336 gst_message_new_tag (GST_OBJECT (element), list));
3340 element_find_unlinked_pad (GstElement * element, GstPadDirection direction)
3343 GstPad *unlinked_pad = NULL;
3346 switch (direction) {
3348 iter = gst_element_iterate_src_pads (element);
3351 iter = gst_element_iterate_sink_pads (element);
3354 g_return_val_if_reached (NULL);
3361 switch (gst_iterator_next (iter, &pad)) {
3362 case GST_ITERATOR_OK:{
3365 GST_CAT_LOG (GST_CAT_ELEMENT_PADS, "examining pad %s:%s",
3366 GST_DEBUG_PAD_NAME (pad));
3368 peer = gst_pad_get_peer (GST_PAD (pad));
3372 GST_CAT_DEBUG (GST_CAT_ELEMENT_PADS,
3373 "found existing unlinked pad %s:%s",
3374 GST_DEBUG_PAD_NAME (unlinked_pad));
3376 gst_object_unref (pad);
3377 gst_object_unref (peer);
3381 case GST_ITERATOR_DONE:
3384 case GST_ITERATOR_RESYNC:
3385 gst_iterator_resync (iter);
3387 case GST_ITERATOR_ERROR:
3388 g_return_val_if_reached (NULL);
3393 gst_iterator_free (iter);
3395 return unlinked_pad;
3399 * gst_bin_find_unlinked_pad:
3400 * @bin: bin in which to look for elements with unlinked pads
3401 * @direction: whether to look for an unlinked source or sink pad
3403 * Recursively looks for elements with an unlinked pad of the given
3404 * direction within the specified bin and returns an unlinked pad
3405 * if one is found, or NULL otherwise. If a pad is found, the caller
3406 * owns a reference to it and should use gst_object_unref() on the
3407 * pad when it is not needed any longer.
3409 * Returns: unlinked pad of the given direction, or NULL.
3414 gst_bin_find_unlinked_pad (GstBin * bin, GstPadDirection direction)
3420 g_return_val_if_fail (GST_IS_BIN (bin), NULL);
3421 g_return_val_if_fail (direction != GST_PAD_UNKNOWN, NULL);
3424 iter = gst_bin_iterate_recurse (bin);
3428 switch (gst_iterator_next (iter, &element)) {
3429 case GST_ITERATOR_OK:
3430 pad = element_find_unlinked_pad (GST_ELEMENT (element), direction);
3431 gst_object_unref (element);
3435 case GST_ITERATOR_DONE:
3438 case GST_ITERATOR_RESYNC:
3439 gst_iterator_resync (iter);
3441 case GST_ITERATOR_ERROR:
3442 g_return_val_if_reached (NULL);
3447 gst_iterator_free (iter);
3453 * gst_bin_find_unconnected_pad:
3454 * @bin: bin in which to look for elements with unlinked pads
3455 * @direction: whether to look for an unlinked source or sink pad
3457 * Recursively looks for elements with an unlinked pad of the given
3458 * direction within the specified bin and returns an unlinked pad
3459 * if one is found, or NULL otherwise. If a pad is found, the caller
3460 * owns a reference to it and should use gst_object_unref() on the
3461 * pad when it is not needed any longer.
3463 * Returns: unlinked pad of the given direction, or NULL.
3467 * Deprecated: use gst_bin_find_unlinked_pad() instead.
3469 #ifndef GST_REMOVE_DEPRECATED
3471 gst_bin_find_unconnected_pad (GstBin * bin, GstPadDirection direction)
3473 return gst_bin_find_unlinked_pad (bin, direction);
3478 * gst_parse_bin_from_description:
3479 * @bin_description: command line describing the bin
3480 * @ghost_unlinked_pads: whether to automatically create ghost pads
3481 * for unlinked source or sink pads within the bin
3482 * @err: where to store the error message in case of an error, or NULL
3484 * This is a convenience wrapper around gst_parse_launch() to create a
3485 * #GstBin from a gst-launch-style pipeline description. See
3486 * gst_parse_launch() and the gst-launch man page for details about the
3487 * syntax. Ghost pads on the bin for unlinked source or sink pads
3488 * within the bin can automatically be created (but only a maximum of
3489 * one ghost pad for each direction will be created; if you expect
3490 * multiple unlinked source pads or multiple unlinked sink pads
3491 * and want them all ghosted, you will have to create the ghost pads
3494 * Returns: a newly-created bin, or NULL if an error occurred.
3499 gst_parse_bin_from_description (const gchar * bin_description,
3500 gboolean ghost_unlinked_pads, GError ** err)
3502 return gst_parse_bin_from_description_full (bin_description,
3503 ghost_unlinked_pads, NULL, 0, err);
3507 * gst_parse_bin_from_description_full:
3508 * @bin_description: command line describing the bin
3509 * @ghost_unlinked_pads: whether to automatically create ghost pads
3510 * for unlinked source or sink pads within the bin
3511 * @context: a parse context allocated with gst_parse_context_new(), or %NULL
3512 * @flags: parsing options, or #GST_PARSE_FLAG_NONE
3513 * @err: where to store the error message in case of an error, or NULL
3515 * This is a convenience wrapper around gst_parse_launch() to create a
3516 * #GstBin from a gst-launch-style pipeline description. See
3517 * gst_parse_launch() and the gst-launch man page for details about the
3518 * syntax. Ghost pads on the bin for unlinked source or sink pads
3519 * within the bin can automatically be created (but only a maximum of
3520 * one ghost pad for each direction will be created; if you expect
3521 * multiple unlinked source pads or multiple unlinked sink pads
3522 * and want them all ghosted, you will have to create the ghost pads
3525 * Returns: a newly-created bin, or NULL if an error occurred.
3530 gst_parse_bin_from_description_full (const gchar * bin_description,
3531 gboolean ghost_unlinked_pads, GstParseContext * context,
3532 GstParseFlags flags, GError ** err)
3534 #ifndef GST_DISABLE_PARSE
3539 g_return_val_if_fail (bin_description != NULL, NULL);
3540 g_return_val_if_fail (err == NULL || *err == NULL, NULL);
3542 GST_DEBUG ("Making bin from description '%s'", bin_description);
3544 /* parse the pipeline to a bin */
3545 desc = g_strdup_printf ("bin.( %s )", bin_description);
3546 bin = (GstBin *) gst_parse_launch_full (desc, context, flags, err);
3549 if (bin == NULL || (err && *err != NULL)) {
3551 gst_object_unref (bin);
3555 /* find pads and ghost them if necessary */
3556 if (ghost_unlinked_pads) {
3557 if ((pad = gst_bin_find_unlinked_pad (bin, GST_PAD_SRC))) {
3558 gst_element_add_pad (GST_ELEMENT (bin), gst_ghost_pad_new ("src", pad));
3559 gst_object_unref (pad);
3561 if ((pad = gst_bin_find_unlinked_pad (bin, GST_PAD_SINK))) {
3562 gst_element_add_pad (GST_ELEMENT (bin), gst_ghost_pad_new ("sink", pad));
3563 gst_object_unref (pad);
3567 return GST_ELEMENT (bin);
3571 GST_WARNING ("Disabled API called");
3573 msg = gst_error_get_message (GST_CORE_ERROR, GST_CORE_ERROR_DISABLED);
3574 g_set_error (err, GST_CORE_ERROR, GST_CORE_ERROR_DISABLED, "%s", msg);
3582 * gst_type_register_static_full:
3583 * @parent_type: The GType of the parent type the newly registered type will
3585 * @type_name: NULL-terminated string used as the name of the new type
3586 * @class_size: Size of the class structure.
3587 * @base_init: Location of the base initialization function (optional).
3588 * @base_finalize: Location of the base finalization function (optional).
3589 * @class_init: Location of the class initialization function for class types
3590 * Location of the default vtable inititalization function for interface
3592 * @class_finalize: Location of the class finalization function for class types.
3593 * Location of the default vtable finalization function for interface types.
3595 * @class_data: User-supplied data passed to the class init/finalize functions.
3596 * @instance_size: Size of the instance (object) structure (required for
3597 * instantiatable types only).
3598 * @n_preallocs: The number of pre-allocated (cached) instances to reserve
3599 * memory for (0 indicates no caching). Ignored on recent GLib's.
3600 * @instance_init: Location of the instance initialization function (optional,
3601 * for instantiatable types only).
3602 * @value_table: A GTypeValueTable function table for generic handling of
3603 * GValues of this type (usually only useful for fundamental types).
3604 * @flags: #GTypeFlags for this GType. E.g: G_TYPE_FLAG_ABSTRACT
3606 * Helper function which constructs a #GTypeInfo structure and registers a
3607 * GType, but which generates less linker overhead than a static const
3608 * #GTypeInfo structure. For further details of the parameters, please see
3609 * #GTypeInfo in the GLib documentation.
3611 * Registers type_name as the name of a new static type derived from
3612 * parent_type. The value of flags determines the nature (e.g. abstract or
3613 * not) of the type. It works by filling a GTypeInfo struct and calling
3614 * g_type_info_register_static().
3616 * Returns: A #GType for the newly-registered type.
3621 gst_type_register_static_full (GType parent_type,
3622 const gchar * type_name,
3624 GBaseInitFunc base_init,
3625 GBaseFinalizeFunc base_finalize,
3626 GClassInitFunc class_init,
3627 GClassFinalizeFunc class_finalize,
3628 gconstpointer class_data,
3629 guint instance_size,
3630 guint16 n_preallocs,
3631 GInstanceInitFunc instance_init,
3632 const GTypeValueTable * value_table, GTypeFlags flags)
3636 info.class_size = class_size;
3637 info.base_init = base_init;
3638 info.base_finalize = base_finalize;
3639 info.class_init = class_init;
3640 info.class_finalize = class_finalize;
3641 info.class_data = class_data;
3642 info.instance_size = instance_size;
3643 info.n_preallocs = n_preallocs;
3644 info.instance_init = instance_init;
3645 info.value_table = value_table;
3647 return g_type_register_static (parent_type, type_name, &info, flags);
3652 * gst_util_get_timestamp:
3654 * Get a timestamp as GstClockTime to be used for interval meassurements.
3655 * The timestamp should not be interpreted in any other way.
3657 * Returns: the timestamp
3662 gst_util_get_timestamp (void)
3664 #if defined (HAVE_POSIX_TIMERS) && defined(HAVE_MONOTONIC_CLOCK)
3665 struct timespec now;
3667 clock_gettime (CLOCK_MONOTONIC, &now);
3668 return GST_TIMESPEC_TO_TIME (now);
3672 g_get_current_time (&now);
3673 return GST_TIMEVAL_TO_TIME (now);
3678 * gst_util_array_binary_search:
3679 * @array: the sorted input array
3680 * @num_elements: number of elements in the array
3681 * @element_size: size of every element in bytes
3682 * @search_func: function to compare two elements, @search_data will always be passed as second argument
3683 * @mode: search mode that should be used
3684 * @search_data: element that should be found
3685 * @user_data: data to pass to @search_func
3687 * Searches inside @array for @search_data by using the comparison function
3688 * @search_func. @array must be sorted ascending.
3690 * As @search_data is always passed as second argument to @search_func it's
3691 * not required that @search_data has the same type as the array elements.
3693 * The complexity of this search function is O(log (num_elements)).
3695 * Returns: The address of the found element or %NULL if nothing was found
3700 gst_util_array_binary_search (gpointer array, guint num_elements,
3701 gsize element_size, GCompareDataFunc search_func, GstSearchMode mode,
3702 gconstpointer search_data, gpointer user_data)
3704 glong left = 0, right = num_elements - 1, m;
3706 guint8 *data = (guint8 *) array;
3708 g_return_val_if_fail (array != NULL, NULL);
3709 g_return_val_if_fail (element_size > 0, NULL);
3710 g_return_val_if_fail (search_func != NULL, NULL);
3712 /* 0. No elements => return NULL */
3713 if (num_elements == 0)
3716 /* 1. If search_data is before the 0th element return the 0th element */
3717 ret = search_func (data, search_data, user_data);
3718 if ((ret >= 0 && mode == GST_SEARCH_MODE_AFTER) || ret == 0)
3723 /* 2. If search_data is after the last element return the last element */
3725 search_func (data + (num_elements - 1) * element_size, search_data,
3727 if ((ret <= 0 && mode == GST_SEARCH_MODE_BEFORE) || ret == 0)
3728 return data + (num_elements - 1) * element_size;
3732 /* 3. else binary search */
3734 m = left + (right - left) / 2;
3736 ret = search_func (data + m * element_size, search_data, user_data);
3739 return data + m * element_size;
3740 } else if (ret < 0) {
3746 /* No exact match found */
3748 if (mode == GST_SEARCH_MODE_EXACT) {
3750 } else if (mode == GST_SEARCH_MODE_AFTER) {
3752 return (m < num_elements) ? data + (m + 1) * element_size : NULL;
3754 return data + m * element_size;
3757 return data + m * element_size;
3759 return (m > 0) ? data + (m - 1) * element_size : NULL;