gst/gstutils.h

   1 /* GStreamer
   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>
   5  *
   6  * gstutils.h: Header for various utility functions
   7  *
   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.
  12  *
  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.
  17  *
  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.
  22  */
  23
  24
  25 #ifndef __GST_UTILS_H__
  26 #define __GST_UTILS_H__
  27
  28 #include <glib.h>
  29 #include <gst/gstbin.h>
  30 #include <gst/gstparse.h>
  31
  32 G_BEGIN_DECLS
  33
  34 void            gst_util_set_value_from_string  (GValue *value, const gchar *value_str);
  35 void            gst_util_set_object_arg         (GObject *object, const gchar *name, const gchar *value);
  36 void            gst_util_dump_mem               (const guchar *mem, guint size);
  37
  38 guint64         gst_util_gdouble_to_guint64     (gdouble value)  G_GNUC_CONST;
  39 gdouble         gst_util_guint64_to_gdouble     (guint64 value)  G_GNUC_CONST;
  40
  41 /**
  42  * gst_guint64_to_gdouble:
  43  * @value: the #guint64 value to convert
  44  *
  45  * Convert @value to a gdouble.
  46  *
  47  * Returns: @value converted to a #gdouble.
  48  */
  49
  50 /**
  51  * gst_gdouble_to_guint64:
  52  * @value: the #gdouble value to convert
  53  *
  54  * Convert @value to a guint64.
  55  *
  56  * Returns: @value converted to a #guint64.
  57  */
  58 #ifdef WIN32
  59 #define         gst_gdouble_to_guint64(value)   gst_util_gdouble_to_guint64(value)
  60 #define         gst_guint64_to_gdouble(value)   gst_util_guint64_to_gdouble(value)
  61 #else
  62 #define         gst_gdouble_to_guint64(value)   ((guint64) (value))
  63 #define         gst_guint64_to_gdouble(value)   ((gdouble) (value))
  64 #endif
  65
  66 guint64         gst_util_uint64_scale           (guint64 val, guint64 num, guint64 denom);
  67 guint64         gst_util_uint64_scale_round     (guint64 val, guint64 num, guint64 denom);
  68 guint64         gst_util_uint64_scale_ceil      (guint64 val, guint64 num, guint64 denom);
  69
  70 guint64         gst_util_uint64_scale_int       (guint64 val, gint num, gint denom);
  71 guint64         gst_util_uint64_scale_int_round (guint64 val, gint num, gint denom);
  72 guint64         gst_util_uint64_scale_int_ceil  (guint64 val, gint num, gint denom);
  73
  74 guint32         gst_util_seqnum_next            (void);
  75 gint32          gst_util_seqnum_compare         (guint32 s1, guint32 s2);
  76
  77 void            gst_print_pad_caps              (GString *buf, gint indent, GstPad *pad);
  78 void            gst_print_element_args          (GString *buf, gint indent, GstElement *element);
  79
  80
  81 GType gst_type_register_static_full (GType parent_type,
  82                                            const gchar       *type_name,
  83                                guint              class_size,
  84                                GBaseInitFunc      base_init,
  85                                GBaseFinalizeFunc  base_finalize,
  86                                GClassInitFunc     class_init,
  87                                GClassFinalizeFunc class_finalize,
  88                                gconstpointer      class_data,
  89                                guint              instance_size,
  90                                guint16            n_preallocs,
  91                                GInstanceInitFunc  instance_init,
  92                                const GTypeValueTable *value_table,
  93                                GTypeFlags        flags);
  94
  95
  96 /* Macros for defining classes.  Ideas taken from Bonobo, which took theirs
  97    from Nautilus and GOB. */
  98
  99 /**
 100  * GST_BOILERPLATE_FULL:
 101  * @type: the name of the type struct
 102  * @type_as_function: the prefix for the functions
 103  * @parent_type: the parent type struct name
 104  * @parent_type_macro: the parent type macro
 105  * @additional_initializations: function pointer in the form of
 106  * void additional_initializations (GType type) that can be used for
 107  * initializing interfaces and the like
 108  *
 109  * Define the boilerplate type stuff to reduce typos and code size.  Defines
 110  * the get_type method and the parent_class static variable.
 111  *
 112  * <informalexample>
 113  * <programlisting>
 114  *   GST_BOILERPLATE_FULL (GstFdSink, gst_fdsink, GstElement, GST_TYPE_ELEMENT, _do_init);
 115  * </programlisting>
 116  * </informalexample>
 117  */
 118 #define GST_BOILERPLATE_FULL(type, type_as_function, parent_type, parent_type_macro, additional_initializations)        \
 119                                                                         \
 120 static void type_as_function ## _base_init     (gpointer      g_class); \
 121 static void type_as_function ## _class_init    (type ## Class *g_class);\
 122 static void type_as_function ## _init          (type          *object,  \
 123                                                 type ## Class *g_class);\
 124 static parent_type ## Class *parent_class = NULL;                       \
 125 static void                                                             \
 126 type_as_function ## _class_init_trampoline (gpointer g_class)           \
 127 {                                                                       \
 128   parent_class = (parent_type ## Class *)                               \
 129       g_type_class_peek_parent (g_class);                               \
 130   type_as_function ## _class_init ((type ## Class *)g_class);           \
 131 }                                                                       \
 132                                                                         \
 133 GType                                                                   \
 134 type_as_function ## _get_type (void)                                    \
 135 {                                                                       \
 136   /* The typedef for GType may be gulong or gsize, depending on the     \
 137    * system and whether the compiler is c++ or not. The g_once_init_*   \
 138    * functions always take a gsize * though ... */                      \
 139   static volatile gsize gonce_data = 0;                                 \
 140   if (g_once_init_enter (&gonce_data)) {                                \
 141     GType _type;                                                        \
 142     _type = gst_type_register_static_full (parent_type_macro,           \
 143         g_intern_static_string (#type),                                 \
 144         sizeof (type ## Class),                                         \
 145         type_as_function ## _base_init,                                 \
 146         NULL,             /* base_finalize */                           \
 147         (GClassInitFunc) type_as_function ## _class_init_trampoline,    \
 148         NULL,             /* class_finalize */                          \
 149         NULL,               /* class_data */                            \
 150         sizeof (type),                                                  \
 151         0,                  /* n_preallocs */                           \
 152         (GInstanceInitFunc) type_as_function ## _init,                  \
 153         NULL,                                                           \
 154         (GTypeFlags) 0);                                                \
 155     additional_initializations (_type);                                 \
 156     g_once_init_leave (&gonce_data, (gsize) _type);                     \
 157   }                                                                     \
 158   return (GType) gonce_data;                                            \
 159 }
 160
 161 #define __GST_DO_NOTHING(type)  /* NOP */
 162
 163 /**
 164  * GST_BOILERPLATE:
 165  * @type: the name of the type struct
 166  * @type_as_function: the prefix for the functions
 167  * @parent_type: the parent type struct name
 168  * @parent_type_macro: the parent type macro
 169  *
 170  * Define the boilerplate type stuff to reduce typos and code size.  Defines
 171  * the get_type method and the parent_class static variable.
 172  *
 173  * <informalexample>
 174  * <programlisting>
 175  *   GST_BOILERPLATE (GstFdSink, gst_fdsink, GstElement, GST_TYPE_ELEMENT);
 176  * </programlisting>
 177  * </informalexample>
 178  */
 179 #define GST_BOILERPLATE(type,type_as_function,parent_type,parent_type_macro)    \
 180   GST_BOILERPLATE_FULL (type, type_as_function, parent_type, parent_type_macro, \
 181       __GST_DO_NOTHING)
 182
 183 /* Like GST_BOILERPLATE, but makes the type 1) implement an interface, and 2)
 184  * implement GstImplementsInterface for that type
 185  *
 186  * After this you will need to implement interface_as_function ## _supported
 187  * and interface_as_function ## _interface_init
 188  */
 189 /**
 190  * GST_BOILERPLATE_WITH_INTERFACE:
 191  * @type: the name of the type struct
 192  * @type_as_function: the prefix for the functions
 193  * @parent_type: the parent type struct name
 194  * @parent_type_as_macro: the parent type macro
 195  * @interface_type: the name of the interface type struct
 196  * @interface_type_as_macro: the interface type macro
 197  * @interface_as_function: the interface function name prefix
 198  *
 199  * Like GST_BOILERPLATE, but makes the type 1) implement an interface, and 2)
 200  * implement GstImplementsInterface for that type.
 201  *
 202  * After this you will need to implement interface_as_function ## _supported
 203  * and interface_as_function ## _interface_init
 204  */
 205 #define GST_BOILERPLATE_WITH_INTERFACE(type, type_as_function,          \
 206     parent_type, parent_type_as_macro, interface_type,                  \
 207     interface_type_as_macro, interface_as_function)                     \
 208                                                                         \
 209 static void interface_as_function ## _interface_init (interface_type ## Class *klass);  \
 210 static gboolean interface_as_function ## _supported (type *object, GType iface_type);   \
 211                                                                         \
 212 static void                                                             \
 213 type_as_function ## _implements_interface_init (GstImplementsInterfaceClass *klass)     \
 214 {                                                                       \
 215   klass->supported = (gboolean (*)(GstImplementsInterface*, GType))interface_as_function ## _supported;     \
 216 }                                                                       \
 217                                                                         \
 218 static void                                                             \
 219 type_as_function ## _init_interfaces (GType type)                       \
 220 {                                                                       \
 221   static const GInterfaceInfo implements_iface_info = {                 \
 222     (GInterfaceInitFunc) type_as_function ## _implements_interface_init,\
 223     NULL,                                                               \
 224     NULL,                                                               \
 225   };                                                                    \
 226   static const GInterfaceInfo iface_info = {                            \
 227     (GInterfaceInitFunc) interface_as_function ## _interface_init,      \
 228     NULL,                                                               \
 229     NULL,                                                               \
 230   };                                                                    \
 231                                                                         \
 232   g_type_add_interface_static (type, GST_TYPE_IMPLEMENTS_INTERFACE,     \
 233       &implements_iface_info);                                          \
 234   g_type_add_interface_static (type, interface_type_as_macro,           \
 235       &iface_info);                                                     \
 236 }                                                                       \
 237                                                                         \
 238 GST_BOILERPLATE_FULL (type, type_as_function, parent_type,              \
 239     parent_type_as_macro, type_as_function ## _init_interfaces)
 240
 241 /**
 242  * GST_CALL_PARENT:
 243  * @parent_class_cast: the name of the class cast macro for the parent type
 244  * @name: name of the function to call
 245  * @args: arguments enclosed in '( )'
 246  *
 247  * Just call the parent handler.  This assumes that there is a variable
 248  * named parent_class that points to the (duh!) parent class.  Note that
 249  * this macro is not to be used with things that return something, use
 250  * the _WITH_DEFAULT version for that
 251  */
 252 #define GST_CALL_PARENT(parent_class_cast, name, args)                  \
 253         ((parent_class_cast(parent_class)->name != NULL) ?              \
 254          parent_class_cast(parent_class)->name args : (void) 0)
 255
 256 /**
 257  * GST_CALL_PARENT_WITH_DEFAULT:
 258  * @parent_class_cast: the name of the class cast macro for the parent type
 259  * @name: name of the function to call
 260  * @args: arguments enclosed in '( )'
 261  * @def_return: default result
 262  *
 263  * Same as GST_CALL_PARENT(), but in case there is no implementation, it
 264  * evaluates to @def_return.
 265  */
 266 #define GST_CALL_PARENT_WITH_DEFAULT(parent_class_cast, name, args, def_return)\
 267         ((parent_class_cast(parent_class)->name != NULL) ?              \
 268          parent_class_cast(parent_class)->name args : def_return)
 269
 270 /* Define PUT and GET functions for unaligned memory */
 271 #define _GST_GET(__data, __idx, __size, __shift) \
 272     (((guint##__size) (((const guint8 *) (__data))[__idx])) << (__shift))
 273
 274 #define _GST_PUT(__data, __idx, __size, __shift, __num) \
 275     (((guint8 *) (__data))[__idx] = (((guint##__size) (__num)) >> (__shift)) & 0xff)
 276
 277 /**
 278  * GST_READ_UINT64_BE:
 279  * @data: memory location
 280  *
 281  * Read a 64 bit unsigned integer value in big endian format from the memory buffer.
 282  */
 283 #define GST_READ_UINT64_BE(data)        (_GST_GET (data, 0, 64, 56) | \
 284                                          _GST_GET (data, 1, 64, 48) | \
 285                                          _GST_GET (data, 2, 64, 40) | \
 286                                          _GST_GET (data, 3, 64, 32) | \
 287                                          _GST_GET (data, 4, 64, 24) | \
 288                                          _GST_GET (data, 5, 64, 16) | \
 289                                          _GST_GET (data, 6, 64,  8) | \
 290                                          _GST_GET (data, 7, 64,  0))
 291
 292 /**
 293  * GST_READ_UINT64_LE:
 294  * @data: memory location
 295  *
 296  * Read a 64 bit unsigned integer value in little endian format from the memory buffer.
 297  */
 298 #define GST_READ_UINT64_LE(data)        (_GST_GET (data, 7, 64, 56) | \
 299                                          _GST_GET (data, 6, 64, 48) | \
 300                                          _GST_GET (data, 5, 64, 40) | \
 301                                          _GST_GET (data, 4, 64, 32) | \
 302                                          _GST_GET (data, 3, 64, 24) | \
 303                                          _GST_GET (data, 2, 64, 16) | \
 304                                          _GST_GET (data, 1, 64,  8) | \
 305                                          _GST_GET (data, 0, 64,  0))
 306
 307 /**
 308  * GST_READ_UINT32_BE:
 309  * @data: memory location
 310  *
 311  * Read a 32 bit unsigned integer value in big endian format from the memory buffer.
 312  */
 313 #define GST_READ_UINT32_BE(data)        (_GST_GET (data, 0, 32, 24) | \
 314                                          _GST_GET (data, 1, 32, 16) | \
 315                                          _GST_GET (data, 2, 32,  8) | \
 316                                          _GST_GET (data, 3, 32,  0))
 317
 318 /**
 319  * GST_READ_UINT32_LE:
 320  * @data: memory location
 321  *
 322  * Read a 32 bit unsigned integer value in little endian format from the memory buffer.
 323  */
 324 #define GST_READ_UINT32_LE(data)        (_GST_GET (data, 3, 32, 24) | \
 325                                          _GST_GET (data, 2, 32, 16) | \
 326                                          _GST_GET (data, 1, 32,  8) | \
 327                                          _GST_GET (data, 0, 32,  0))
 328
 329 /**
 330  * GST_READ_UINT24_BE:
 331  * @data: memory location
 332  *
 333  * Read a 24 bit unsigned integer value in big endian format from the memory buffer.
 334  *
 335  * Since: 0.10.22
 336  */
 337 #define GST_READ_UINT24_BE(data)        (_GST_GET (data, 0, 32, 16) | \
 338                                          _GST_GET (data, 1, 32,  8) | \
 339                                          _GST_GET (data, 2, 32,  0))
 340
 341 /**
 342  * GST_READ_UINT24_LE:
 343  * @data: memory location
 344  *
 345  * Read a 24 bit unsigned integer value in little endian format from the memory buffer.
 346  *
 347  * Since: 0.10.22
 348  */
 349 #define GST_READ_UINT24_LE(data)        (_GST_GET (data, 2, 32, 16) | \
 350                                          _GST_GET (data, 1, 32,  8) | \
 351                                          _GST_GET (data, 0, 32,  0))
 352
 353 /**
 354  * GST_READ_UINT16_BE:
 355  * @data: memory location
 356  *
 357  * Read a 16 bit unsigned integer value in big endian format from the memory buffer.
 358  */
 359 #define GST_READ_UINT16_BE(data)        (_GST_GET (data, 0, 16,  8) | \
 360                                          _GST_GET (data, 1, 16,  0))
 361
 362 /**
 363  * GST_READ_UINT16_LE:
 364  * @data: memory location
 365  *
 366  * Read a 16 bit unsigned integer value in little endian format from the memory buffer.
 367  */
 368 #define GST_READ_UINT16_LE(data)        (_GST_GET (data, 1, 16,  8) | \
 369                                          _GST_GET (data, 0, 16,  0))
 370
 371 /**
 372  * GST_READ_UINT8:
 373  * @data: memory location
 374  *
 375  * Read an 8 bit unsigned integer value from the memory buffer.
 376  */
 377 #define GST_READ_UINT8(data)            (_GST_GET (data, 0,  8,  0))
 378
 379 /**
 380  * GST_WRITE_UINT64_BE:
 381  * @data: memory location
 382  * @num: value to store
 383  *
 384  * Store a 64 bit unsigned integer value in big endian format into the memory buffer.
 385  */
 386 #define GST_WRITE_UINT64_BE(data, num)  do { \
 387                                           _GST_PUT (data, 0, 64, 56, num); \
 388                                           _GST_PUT (data, 1, 64, 48, num); \
 389                                           _GST_PUT (data, 2, 64, 40, num); \
 390                                           _GST_PUT (data, 3, 64, 32, num); \
 391                                           _GST_PUT (data, 4, 64, 24, num); \
 392                                           _GST_PUT (data, 5, 64, 16, num); \
 393                                           _GST_PUT (data, 6, 64,  8, num); \
 394                                           _GST_PUT (data, 7, 64,  0, num); \
 395                                         } while (0)
 396
 397 /**
 398  * GST_WRITE_UINT64_LE:
 399  * @data: memory location
 400  * @num: value to store
 401  *
 402  * Store a 64 bit unsigned integer value in little endian format into the memory buffer.
 403  */
 404 #define GST_WRITE_UINT64_LE(data, num)  do { \
 405                                           _GST_PUT (data, 0, 64,  0, num); \
 406                                           _GST_PUT (data, 1, 64,  8, num); \
 407                                           _GST_PUT (data, 2, 64, 16, num); \
 408                                           _GST_PUT (data, 3, 64, 24, num); \
 409                                           _GST_PUT (data, 4, 64, 32, num); \
 410                                           _GST_PUT (data, 5, 64, 40, num); \
 411                                           _GST_PUT (data, 6, 64, 48, num); \
 412                                           _GST_PUT (data, 7, 64, 56, num); \
 413                                         } while (0)
 414
 415 /**
 416  * GST_WRITE_UINT32_BE:
 417  * @data: memory location
 418  * @num: value to store
 419  *
 420  * Store a 32 bit unsigned integer value in big endian format into the memory buffer.
 421  */
 422 #define GST_WRITE_UINT32_BE(data, num)  do { \
 423                                           _GST_PUT (data, 0, 32, 24, num); \
 424                                           _GST_PUT (data, 1, 32, 16, num); \
 425                                           _GST_PUT (data, 2, 32,  8, num); \
 426                                           _GST_PUT (data, 3, 32,  0, num); \
 427                                         } while (0)
 428
 429 /**
 430  * GST_WRITE_UINT32_LE:
 431  * @data: memory location
 432  * @num: value to store
 433  *
 434  * Store a 32 bit unsigned integer value in little endian format into the memory buffer.
 435  */
 436 #define GST_WRITE_UINT32_LE(data, num)  do { \
 437                                           _GST_PUT (data, 0, 32,  0, num); \
 438                                           _GST_PUT (data, 1, 32,  8, num); \
 439                                           _GST_PUT (data, 2, 32, 16, num); \
 440                                           _GST_PUT (data, 3, 32, 24, num); \
 441                                         } while (0)
 442
 443 /**
 444  * GST_WRITE_UINT24_BE:
 445  * @data: memory location
 446  * @num: value to store
 447  *
 448  * Store a 24 bit unsigned integer value in big endian format into the memory buffer.
 449  *
 450  * Since: 0.10.22
 451  */
 452 #define GST_WRITE_UINT24_BE(data, num)  do { \
 453                                           _GST_PUT (data, 0, 32,  16, num); \
 454                                           _GST_PUT (data, 1, 32,  8, num); \
 455                                           _GST_PUT (data, 2, 32,  0, num); \
 456                                         } while (0)
 457
 458 /**
 459  * GST_WRITE_UINT24_LE:
 460  * @data: memory location
 461  * @num: value to store
 462  *
 463  * Store a 24 bit unsigned integer value in little endian format into the memory buffer.
 464  *
 465  * Since: 0.10.22
 466  */
 467 #define GST_WRITE_UINT24_LE(data, num)  do { \
 468                                           _GST_PUT (data, 0, 32,  0, num); \
 469                                           _GST_PUT (data, 1, 32,  8, num); \
 470                                           _GST_PUT (data, 2, 32,  16, num); \
 471                                         } while (0)
 472
 473 /**
 474  * GST_WRITE_UINT16_BE:
 475  * @data: memory location
 476  * @num: value to store
 477  *
 478  * Store a 16 bit unsigned integer value in big endian format into the memory buffer.
 479  */
 480 #define GST_WRITE_UINT16_BE(data, num)  do { \
 481                                           _GST_PUT (data, 0, 16,  8, num); \
 482                                           _GST_PUT (data, 1, 16,  0, num); \
 483                                         } while (0)
 484
 485 /**
 486  * GST_WRITE_UINT16_LE:
 487  * @data: memory location
 488  * @num: value to store
 489  *
 490  * Store a 16 bit unsigned integer value in little endian format into the memory buffer.
 491  */
 492 #define GST_WRITE_UINT16_LE(data, num)  do { \
 493                                           _GST_PUT (data, 0, 16,  0, num); \
 494                                           _GST_PUT (data, 1, 16,  8, num); \
 495                                         } while (0)
 496
 497 /**
 498  * GST_WRITE_UINT8:
 499  * @data: memory location
 500  * @num: value to store
 501  *
 502  * Store an 8 bit unsigned integer value into the memory buffer.
 503  */
 504 #define GST_WRITE_UINT8(data, num)      do { \
 505                                           _GST_PUT (data, 0,  8,  0, num); \
 506                                         } while (0)
 507
 508 /* Float endianess conversion macros */
 509
 510 /* FIXME: Remove this once we depend on a GLib version with this */
 511 #ifndef GFLOAT_FROM_LE
 512 /**
 513  * GFLOAT_SWAP_LE_BE:
 514  * @in: input value
 515  *
 516  * Swap byte order of a 32-bit floating point value (float).
 517  *
 518  * Returns: @in byte-swapped.
 519  *
 520  * Since: 0.10.22
 521  *
 522  */
 523 #ifdef _FOOL_GTK_DOC_
 524 G_INLINE_FUNC gfloat GFLOAT_SWAP_LE_BE (gfloat in);
 525 #endif
 526
 527 inline static gfloat
 528 GFLOAT_SWAP_LE_BE(gfloat in)
 529 {
 530   union
 531   {
 532     guint32 i;
 533     gfloat f;
 534   } u;
 535
 536   u.f = in;
 537   u.i = GUINT32_SWAP_LE_BE (u.i);
 538   return u.f;
 539 }
 540
 541 /**
 542  * GDOUBLE_SWAP_LE_BE:
 543  * @in: input value
 544  *
 545  * Swap byte order of a 64-bit floating point value (double).
 546  *
 547  * Returns: @in byte-swapped.
 548  *
 549  * Since: 0.10.22
 550  *
 551  */
 552 #ifdef _FOOL_GTK_DOC_
 553 G_INLINE_FUNC gdouble GDOUBLE_SWAP_LE_BE (gdouble in);
 554 #endif
 555
 556 inline static gdouble
 557 GDOUBLE_SWAP_LE_BE(gdouble in)
 558 {
 559   union
 560   {
 561     guint64 i;
 562     gdouble d;
 563   } u;
 564
 565   u.d = in;
 566   u.i = GUINT64_SWAP_LE_BE (u.i);
 567   return u.d;
 568 }
 569
 570 /**
 571  * GDOUBLE_TO_LE:
 572  * @val: value
 573  *
 574  * Convert 64-bit floating point value (double) from native byte order into
 575  * little endian byte order.
 576  *
 577  * Since: 0.10.22
 578  *
 579  */
 580 /**
 581  * GDOUBLE_TO_BE:
 582  * @val: value
 583  *
 584  * Convert 64-bit floating point value (double) from native byte order into
 585  * big endian byte order.
 586  *
 587  * Since: 0.10.22
 588  *
 589  */
 590 /**
 591  * GDOUBLE_FROM_LE:
 592  * @val: value
 593  *
 594  * Convert 64-bit floating point value (double) from little endian byte order
 595  * into native byte order.
 596  *
 597  * Since: 0.10.22
 598  *
 599  */
 600 /**
 601  * GDOUBLE_FROM_BE:
 602  * @val: value
 603  *
 604  * Convert 64-bit floating point value (double) from big endian byte order
 605  * into native byte order.
 606  *
 607  * Since: 0.10.22
 608  *
 609  */
 610
 611 /**
 612  * GFLOAT_TO_LE:
 613  * @val: value
 614  *
 615  * Convert 32-bit floating point value (float) from native byte order into
 616  * little endian byte order.
 617  *
 618  * Since: 0.10.22
 619  *
 620  */
 621 /**
 622  * GFLOAT_TO_BE:
 623  * @val: value
 624  *
 625  * Convert 32-bit floating point value (float) from native byte order into
 626  * big endian byte order.
 627  *
 628  * Since: 0.10.22
 629  *
 630  */
 631 /**
 632  * GFLOAT_FROM_LE:
 633  * @val: value
 634  *
 635  * Convert 32-bit floating point value (float) from little endian byte order
 636  * into native byte order.
 637  *
 638  * Since: 0.10.22
 639  *
 640  */
 641 /**
 642  * GFLOAT_FROM_BE:
 643  * @val: value
 644  *
 645  * Convert 32-bit floating point value (float) from big endian byte order
 646  * into native byte order.
 647  *
 648  * Since: 0.10.22
 649  *
 650  */
 651
 652 #if G_BYTE_ORDER == G_LITTLE_ENDIAN
 653 #define GFLOAT_TO_LE(val)    ((gfloat) (val))
 654 #define GFLOAT_TO_BE(val)    (GFLOAT_SWAP_LE_BE (val))
 655 #define GDOUBLE_TO_LE(val)   ((gdouble) (val))
 656 #define GDOUBLE_TO_BE(val)   (GDOUBLE_SWAP_LE_BE (val))
 657
 658 #elif G_BYTE_ORDER == G_BIG_ENDIAN
 659 #define GFLOAT_TO_LE(val)    (GFLOAT_SWAP_LE_BE (val))
 660 #define GFLOAT_TO_BE(val)    ((gfloat) (val))
 661 #define GDOUBLE_TO_LE(val)   (GDOUBLE_SWAP_LE_BE (val))
 662 #define GDOUBLE_TO_BE(val)   ((gdouble) (val))
 663
 664 #else /* !G_LITTLE_ENDIAN && !G_BIG_ENDIAN */
 665 #error unknown ENDIAN type
 666 #endif /* !G_LITTLE_ENDIAN && !G_BIG_ENDIAN */
 667
 668 #define GFLOAT_FROM_LE(val)  (GFLOAT_TO_LE (val))
 669 #define GFLOAT_FROM_BE(val)  (GFLOAT_TO_BE (val))
 670 #define GDOUBLE_FROM_LE(val) (GDOUBLE_TO_LE (val))
 671 #define GDOUBLE_FROM_BE(val) (GDOUBLE_TO_BE (val))
 672
 673 #endif /* !defined(GFLOAT_FROM_LE) */
 674
 675 /**
 676  * GST_READ_FLOAT_LE:
 677  * @data: memory location
 678  *
 679  * Read a 32 bit float value in little endian format from the memory buffer.
 680  *
 681  * Returns: The floating point value read from @data
 682  *
 683  * Since: 0.10.22
 684  *
 685  */
 686 #ifdef _FOOL_GTK_DOC_
 687 G_INLINE_FUNC gfloat GST_READ_FLOAT_LE (const guint8 *data);
 688 #endif
 689
 690 inline static gfloat
 691 GST_READ_FLOAT_LE(const guint8 *data)
 692 {
 693   union
 694   {
 695     guint32 i;
 696     gfloat f;
 697   } u;
 698
 699   u.i = GST_READ_UINT32_LE (data);
 700   return u.f;
 701 }
 702
 703 /**
 704  * GST_READ_FLOAT_BE:
 705  * @data: memory location
 706  *
 707  * Read a 32 bit float value in big endian format from the memory buffer.
 708  *
 709  * Returns: The floating point value read from @data
 710  *
 711  * Since: 0.10.22
 712  *
 713  */
 714 #ifdef _FOOL_GTK_DOC_
 715 G_INLINE_FUNC gfloat GST_READ_FLOAT_BE (const guint8 *data);
 716 #endif
 717
 718 inline static gfloat
 719 GST_READ_FLOAT_BE(const guint8 *data)
 720 {
 721   union
 722   {
 723     guint32 i;
 724     gfloat f;
 725   } u;
 726
 727   u.i = GST_READ_UINT32_BE (data);
 728   return u.f;
 729 }
 730
 731 /**
 732  * GST_READ_DOUBLE_LE:
 733  * @data: memory location
 734  *
 735  * Read a 64 bit double value in little endian format from the memory buffer.
 736  *
 737  * Returns: The double-precision floating point value read from @data
 738  *
 739  * Since: 0.10.22
 740  *
 741  */
 742 #ifdef _FOOL_GTK_DOC_
 743 G_INLINE_FUNC gdouble GST_READ_DOUBLE_LE (const guint8 *data);
 744 #endif
 745
 746 inline static gdouble
 747 GST_READ_DOUBLE_LE(const guint8 *data)
 748 {
 749   union
 750   {
 751     guint64 i;
 752     gdouble d;
 753   } u;
 754
 755   u.i = GST_READ_UINT64_LE (data);
 756   return u.d;
 757 }
 758
 759 /**
 760  * GST_READ_DOUBLE_BE:
 761  * @data: memory location
 762  *
 763  * Read a 64 bit double value in big endian format from the memory buffer.
 764  *
 765  * Returns: The double-precision floating point value read from @data
 766  *
 767  * Since: 0.10.22
 768  *
 769  */
 770 #ifdef _FOOL_GTK_DOC_
 771 G_INLINE_FUNC gdouble GST_READ_DOUBLE_BE (const guint8 *data);
 772 #endif
 773
 774 inline static gdouble
 775 GST_READ_DOUBLE_BE(const guint8 *data)
 776 {
 777   union
 778   {
 779     guint64 i;
 780     gdouble d;
 781   } u;
 782
 783   u.i = GST_READ_UINT64_BE (data);
 784   return u.d;
 785 }
 786
 787 /**
 788  * GST_WRITE_FLOAT_LE:
 789  * @data: memory location
 790  * @num: value to store
 791  *
 792  * Store a 32 bit float value in little endian format into the memory buffer.
 793  *
 794  * Since: 0.10.22
 795  *
 796  */
 797 #ifdef _FOOL_GTK_DOC_
 798 G_INLINE_FUNC void GST_WRITE_FLOAT_LE (guint8 *data, gfloat num);
 799 #endif
 800
 801 inline static void
 802 GST_WRITE_FLOAT_LE(guint8 *data, gfloat num)
 803 {
 804   union
 805   {
 806     guint32 i;
 807     gfloat f;
 808   } u;
 809
 810   u.f = num;
 811   GST_WRITE_UINT32_LE (data, u.i);
 812 }
 813
 814 /**
 815  * GST_WRITE_FLOAT_BE:
 816  * @data: memory location
 817  * @num: value to store
 818  *
 819  * Store a 32 bit float value in big endian format into the memory buffer.
 820  *
 821  * Since: 0.10.22
 822  *
 823  */
 824 #ifdef _FOOL_GTK_DOC_
 825 G_INLINE_FUNC void GST_WRITE_FLOAT_BE (guint8 *data, gfloat num);
 826 #endif
 827
 828 inline static void
 829 GST_WRITE_FLOAT_BE(guint8 *data, gfloat num)
 830 {
 831   union
 832   {
 833     guint32 i;
 834     gfloat f;
 835   } u;
 836
 837   u.f = num;
 838   GST_WRITE_UINT32_BE (data, u.i);
 839 }
 840
 841 /**
 842  * GST_WRITE_DOUBLE_LE:
 843  * @data: memory location
 844  * @num: value to store
 845  *
 846  * Store a 64 bit double value in little endian format into the memory buffer.
 847  *
 848  * Since: 0.10.22
 849  *
 850  */
 851 #ifdef _FOOL_GTK_DOC_
 852 G_INLINE_FUNC void GST_WRITE_DOUBLE_LE (guint8 *data, gdouble num);
 853 #endif
 854
 855 inline static void
 856 GST_WRITE_DOUBLE_LE(guint8 *data, gdouble num)
 857 {
 858   union
 859   {
 860     guint64 i;
 861     gdouble d;
 862   } u;
 863
 864   u.d = num;
 865   GST_WRITE_UINT64_LE (data, u.i);
 866 }
 867
 868 /**
 869  * GST_WRITE_DOUBLE_BE:
 870  * @data: memory location
 871  * @num: value to store
 872  *
 873  * Store a 64 bit double value in big endian format into the memory buffer.
 874  *
 875  * Since: 0.10.22
 876  *
 877  */
 878 #ifdef _FOOL_GTK_DOC_
 879 G_INLINE_FUNC void GST_WRITE_DOUBLE_BE (guint8 *data, gdouble num);
 880 #endif
 881
 882 inline static void
 883 GST_WRITE_DOUBLE_BE(guint8 *data, gdouble num)
 884 {
 885   union
 886   {
 887     guint64 i;
 888     gdouble d;
 889   } u;
 890
 891   u.d = num;
 892   GST_WRITE_UINT64_BE (data, u.i);
 893 }
 894
 895 /* Miscellaneous utility macros */
 896
 897 /**
 898  * GST_ROUND_UP_2:
 899  * @num: integer value to round up
 900  *
 901  * Rounds an integer value up to the next multiple of 2.
 902  */
 903 #define GST_ROUND_UP_2(num)  (((num)+1)&~1)
 904 /**
 905  * GST_ROUND_UP_4:
 906  * @num: integer value to round up
 907  *
 908  * Rounds an integer value up to the next multiple of 4.
 909  */
 910 #define GST_ROUND_UP_4(num)  (((num)+3)&~3)
 911 /**
 912  * GST_ROUND_UP_8:
 913  * @num: integer value to round up
 914  *
 915  * Rounds an integer value up to the next multiple of 8.
 916  */
 917 #define GST_ROUND_UP_8(num)  (((num)+7)&~7)
 918 /**
 919  * GST_ROUND_UP_16:
 920  * @num: integer value to round up
 921  *
 922  * Rounds an integer value up to the next multiple of 16.
 923  */
 924 #define GST_ROUND_UP_16(num) (((num)+15)&~15)
 925 /**
 926  * GST_ROUND_UP_32:
 927  * @num: integer value to round up
 928  *
 929  * Rounds an integer value up to the next multiple of 32.
 930  */
 931 #define GST_ROUND_UP_32(num) (((num)+31)&~31)
 932 /**
 933  * GST_ROUND_UP_64:
 934  * @num: integer value to round up
 935  *
 936  * Rounds an integer value up to the next multiple of 64.
 937  */
 938 #define GST_ROUND_UP_64(num) (((num)+63)&~63)
 939
 940 /**
 941  * GST_ROUND_DOWN_2:
 942  * @num: integer value to round down
 943  *
 944  * Rounds an integer value down to the next multiple of 2.
 945  *
 946  * Since: 0.10.12
 947  */
 948 #define GST_ROUND_DOWN_2(num)  ((num)&(~1))
 949 /**
 950  * GST_ROUND_DOWN_4:
 951  * @num: integer value to round down
 952  *
 953  * Rounds an integer value down to the next multiple of 4.
 954  *
 955  * Since: 0.10.12
 956  */
 957 #define GST_ROUND_DOWN_4(num)  ((num)&(~3))
 958 /**
 959  * GST_ROUND_DOWN_8:
 960  * @num: integer value to round down
 961  *
 962  * Rounds an integer value down to the next multiple of 8.
 963  *
 964  * Since: 0.10.12
 965  */
 966 #define GST_ROUND_DOWN_8(num)  ((num)&(~7))
 967 /**
 968  * GST_ROUND_DOWN_16:
 969  * @num: integer value to round down
 970  *
 971  * Rounds an integer value down to the next multiple of 16.
 972  *
 973  * Since: 0.10.12
 974  */
 975 #define GST_ROUND_DOWN_16(num) ((num)&(~15))
 976 /**
 977  * GST_ROUND_DOWN_32:
 978  * @num: integer value to round down
 979  *
 980  * Rounds an integer value down to the next multiple of 32.
 981  *
 982  * Since: 0.10.12
 983  */
 984 #define GST_ROUND_DOWN_32(num) ((num)&(~31))
 985 /**
 986  * GST_ROUND_DOWN_64:
 987  * @num: integer value to round down
 988  *
 989  * Rounds an integer value down to the next multiple of 64.
 990  *
 991  * Since: 0.10.12
 992  */
 993 #define GST_ROUND_DOWN_64(num) ((num)&(~63))
 994
 995 void                    gst_object_default_error        (GstObject * source,
 996                                                          GError * error, gchar * debug);
 997
 998 /* element functions */
 999 void                    gst_element_create_all_pads     (GstElement *element);
1000 GstPad*                 gst_element_get_compatible_pad  (GstElement *element, GstPad *pad,
1001                                                          const GstCaps *caps);
1002
1003 GstPadTemplate*         gst_element_get_compatible_pad_template (GstElement *element, GstPadTemplate *compattempl);
1004
1005 G_CONST_RETURN gchar*   gst_element_state_get_name      (GstState state);
1006 G_CONST_RETURN gchar *  gst_element_state_change_return_get_name (GstStateChangeReturn state_ret);
1007
1008 gboolean                gst_element_link                (GstElement *src, GstElement *dest);
1009 gboolean                gst_element_link_many           (GstElement *element_1,
1010                                                          GstElement *element_2, ...) G_GNUC_NULL_TERMINATED;
1011 gboolean                gst_element_link_filtered       (GstElement * src,
1012                                                          GstElement * dest,
1013                                                          GstCaps *filter);
1014 void                    gst_element_unlink              (GstElement *src, GstElement *dest);
1015 void                    gst_element_unlink_many         (GstElement *element_1,
1016                                                          GstElement *element_2, ...) G_GNUC_NULL_TERMINATED;
1017
1018 gboolean                gst_element_link_pads           (GstElement *src, const gchar *srcpadname,
1019                                                          GstElement *dest, const gchar *destpadname);
1020 gboolean                gst_element_link_pads_full      (GstElement *src, const gchar *srcpadname,
1021                                                          GstElement *dest, const gchar *destpadname,
1022                                                          GstPadLinkCheck flags);
1023 void                    gst_element_unlink_pads         (GstElement *src, const gchar *srcpadname,
1024                                                          GstElement *dest, const gchar *destpadname);
1025
1026 gboolean                gst_element_link_pads_filtered  (GstElement * src, const gchar * srcpadname,
1027                                                          GstElement * dest, const gchar * destpadname,
1028                                                          GstCaps *filter);
1029
1030 gboolean                gst_element_seek_simple         (GstElement   *element,
1031                                                          GstFormat     format,
1032                                                          GstSeekFlags  seek_flags,
1033                                                          gint64        seek_pos);
1034
1035 /* util elementfactory functions */
1036 gboolean                gst_element_factory_can_src_caps(GstElementFactory *factory, const GstCaps *caps);
1037 gboolean                gst_element_factory_can_sink_caps(GstElementFactory *factory, const GstCaps *caps);
1038
1039 /* util query functions */
1040 gboolean                gst_element_query_position      (GstElement *element, GstFormat *format,
1041                                                          gint64 *cur);
1042 gboolean                gst_element_query_duration      (GstElement *element, GstFormat *format,
1043                                                          gint64 *duration);
1044 gboolean                gst_element_query_convert       (GstElement *element, GstFormat src_format, gint64 src_val,
1045                                                          GstFormat *dest_format, gint64 *dest_val);
1046
1047 /* element class functions */
1048 void                    gst_element_class_install_std_props (GstElementClass * klass,
1049                                                          const gchar * first_name, ...) G_GNUC_NULL_TERMINATED;
1050
1051 /* pad functions */
1052 void                    gst_pad_use_fixed_caps          (GstPad *pad);
1053 GstCaps*                gst_pad_get_fixed_caps_func     (GstPad *pad);
1054 GstCaps*                gst_pad_proxy_getcaps           (GstPad * pad);
1055 gboolean                gst_pad_proxy_setcaps           (GstPad * pad, GstCaps * caps);
1056
1057 GstElement*             gst_pad_get_parent_element      (GstPad *pad);
1058
1059 /* util query functions */
1060 gboolean                gst_pad_query_position          (GstPad *pad, GstFormat *format,
1061                                                          gint64 *cur);
1062 gboolean                gst_pad_query_duration          (GstPad *pad, GstFormat *format,
1063                                                          gint64 *duration);
1064 gboolean                gst_pad_query_convert           (GstPad *pad, GstFormat src_format, gint64 src_val,
1065                                                          GstFormat *dest_format, gint64 *dest_val);
1066
1067 gboolean                gst_pad_query_peer_position     (GstPad *pad, GstFormat *format,
1068                                                          gint64 *cur);
1069 gboolean                gst_pad_query_peer_duration     (GstPad *pad, GstFormat *format,
1070                                                          gint64 *duration);
1071 gboolean                gst_pad_query_peer_convert      (GstPad *pad, GstFormat src_format, gint64 src_val,
1072                                                          GstFormat *dest_format, gint64 *dest_val);
1073
1074 /* bin functions */
1075 void                    gst_bin_add_many                (GstBin *bin, GstElement *element_1, ...) G_GNUC_NULL_TERMINATED;
1076 void                    gst_bin_remove_many             (GstBin *bin, GstElement *element_1, ...) G_GNUC_NULL_TERMINATED;
1077 GstPad *                gst_bin_find_unlinked_pad       (GstBin *bin, GstPadDirection direction);
1078
1079 /* buffer functions */
1080 GstBuffer *             gst_buffer_merge                (GstBuffer * buf1, GstBuffer * buf2);
1081 GstBuffer *             gst_buffer_join                 (GstBuffer * buf1, GstBuffer * buf2);
1082
1083 /* probes */
1084 gulong                  gst_pad_add_data_probe          (GstPad   * pad,
1085                                                          GCallback  handler,
1086                                                          gpointer   data);
1087
1088 gulong                  gst_pad_add_data_probe_full     (GstPad       * pad,
1089                                                          GCallback      handler,
1090                                                          gpointer       data,
1091                                                          GDestroyNotify notify);
1092
1093 void                    gst_pad_remove_data_probe       (GstPad * pad, guint handler_id);
1094
1095 gulong                  gst_pad_add_event_probe         (GstPad   * pad,
1096                                                          GCallback  handler,
1097                                                          gpointer   data);
1098
1099 gulong                  gst_pad_add_event_probe_full    (GstPad       * pad,
1100                                                          GCallback      handler,
1101                                                          gpointer       data,
1102                                                          GDestroyNotify notify);
1103
1104 void                    gst_pad_remove_event_probe      (GstPad * pad, guint handler_id);
1105
1106 gulong                  gst_pad_add_buffer_probe        (GstPad   * pad,
1107                                                          GCallback  handler,
1108                                                          gpointer   data);
1109
1110 gulong                  gst_pad_add_buffer_probe_full   (GstPad       * pad,
1111                                                          GCallback      handler,
1112                                                          gpointer       data,
1113                                                          GDestroyNotify notify);
1114
1115 void                    gst_pad_remove_buffer_probe     (GstPad * pad, guint handler_id);
1116
1117 /* tag emission utility functions */
1118 void                    gst_element_found_tags_for_pad  (GstElement * element,
1119                                                          GstPad * pad,
1120                                                          GstTagList * list);
1121 void                    gst_element_found_tags          (GstElement * element,
1122                                                          GstTagList * list);
1123
1124 /* parse utility functions */
1125 GstElement *            gst_parse_bin_from_description      (const gchar     * bin_description,
1126                                                              gboolean          ghost_unlinked_pads,
1127                                                              GError         ** err);
1128
1129 GstElement *            gst_parse_bin_from_description_full (const gchar     * bin_description,
1130                                                              gboolean          ghost_unlinked_pads,
1131                                                              GstParseContext * context,
1132                                                              GstParseFlags     flags,
1133                                                              GError         ** err);
1134
1135 GstClockTime            gst_util_get_timestamp          (void);
1136
1137 /**
1138  * GstSearchMode:
1139  * @GST_SEARCH_MODE_EXACT : Only search for exact matches.
1140  * @GST_SEARCH_MODE_BEFORE: Search for an exact match or the element just before.
1141  * @GST_SEARCH_MODE_AFTER : Search for an exact match or the element just after.
1142  *
1143  * The different search modes.
1144  *
1145  * Since: 0.10.23
1146  */
1147 typedef enum {
1148   GST_SEARCH_MODE_EXACT = 0,
1149   GST_SEARCH_MODE_BEFORE,
1150   GST_SEARCH_MODE_AFTER
1151 } GstSearchMode;
1152
1153 gpointer                gst_util_array_binary_search      (gpointer array, guint num_elements,
1154                                                            gsize element_size, GCompareDataFunc search_func,
1155                                                            GstSearchMode mode, gconstpointer search_data,
1156                                                            gpointer user_data);
1157
1158 gint gst_util_greatest_common_divisor (gint a, gint b);
1159 void gst_util_fraction_to_double (gint src_n, gint src_d, gdouble *dest);
1160 void gst_util_double_to_fraction (gdouble src, gint *dest_n, gint *dest_d);
1161 gboolean gst_util_fraction_multiply (gint a_n, gint a_d, gint b_n, gint b_d, gint *res_n, gint *res_d);
1162 gboolean gst_util_fraction_add (gint a_n, gint a_d, gint b_n, gint b_d, gint *res_n, gint *res_d);
1163 gint gst_util_fraction_compare (gint a_n, gint a_d, gint b_n, gint b_d);
1164
1165
1166 /* sink message event
1167  *
1168  * FIXME: This should be in gstevent.h but can't because
1169  * it needs GstMessage and this would introduce circular
1170  * header includes. And forward declarations of typedefs
1171  * are unfortunately not possible. The implementation of
1172  * these functions is in gstevent.c.
1173  */
1174 GstEvent*       gst_event_new_sink_message      (GstMessage *msg);
1175 void            gst_event_parse_sink_message    (GstEvent *event, GstMessage **msg);
1176
1177
1178 G_END_DECLS
1179
1180 #endif /* __GST_UTILS_H__ */