gst/gstutils.h

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *
   5  * gstutils.h: Header for various utility functions
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23
  24 #ifndef __GST_UTILS_H__
  25 #define __GST_UTILS_H__
  26
  27 #include <glib.h>
  28 #include <gst/gstbin.h>
  29
  30 G_BEGIN_DECLS
  31
  32 void            gst_util_set_value_from_string  (GValue *value, const gchar *value_str);
  33 void            gst_util_set_object_arg         (GObject *object, const gchar *name, const gchar *value);
  34 void            gst_util_dump_mem               (const guchar *mem, guint size);
  35
  36 guint64         gst_util_uint64_scale           (guint64 val, guint64 num, guint64 denom);
  37
  38 void            gst_print_pad_caps              (GString *buf, gint indent, GstPad *pad);
  39 void            gst_print_element_args          (GString *buf, gint indent, GstElement *element);
  40
  41
  42 /* Macros for defining classes.  Ideas taken from Bonobo, which took theirs
  43    from Nautilus and GOB. */
  44
  45 /* Define the boilerplate type stuff to reduce typos and code size.  Defines
  46    the get_type method and the parent_class static variable.
  47    void additional_initializations (GType type) is for initializing interfaces
  48    and stuff like that */
  49
  50 #define GST_BOILERPLATE_FULL(type, type_as_function, parent_type, parent_type_macro, additional_initializations)        \
  51                                                                         \
  52 static void type_as_function ## _base_init     (gpointer      g_class); \
  53 static void type_as_function ## _class_init    (type ## Class *g_class);\
  54 static void type_as_function ## _init          (type          *object,  \
  55                                                 type ## Class *g_class);\
  56 static parent_type ## Class *parent_class = NULL;                       \
  57 static void                                                             \
  58 type_as_function ## _class_init_trampoline (gpointer g_class,           \
  59                                             gpointer data)              \
  60 {                                                                       \
  61   parent_class = (parent_type ## Class *)                               \
  62       g_type_class_peek_parent (g_class);                               \
  63   type_as_function ## _class_init ((type ## Class *)g_class);           \
  64 }                                                                       \
  65                                                                         \
  66 GType                                                                   \
  67 type_as_function ## _get_type (void)                                    \
  68 {                                                                       \
  69   static GType object_type = 0;                                         \
  70   if (object_type == 0) {                                               \
  71     static const GTypeInfo object_info = {                              \
  72       sizeof (type ## Class),                                           \
  73       type_as_function ## _base_init,                                   \
  74       NULL,               /* base_finalize */                           \
  75       type_as_function ## _class_init_trampoline,                       \
  76       NULL,               /* class_finalize */                          \
  77       NULL,               /* class_data */                              \
  78       sizeof (type),                                                    \
  79       0,                  /* n_preallocs */                             \
  80       (GInstanceInitFunc) type_as_function ## _init                     \
  81     };                                                                  \
  82     object_type = g_type_register_static (parent_type_macro, #type,     \
  83         &object_info, (GTypeFlags) 0);                                  \
  84     additional_initializations (object_type);                           \
  85   }                                                                     \
  86   return object_type;                                                   \
  87 }
  88
  89 #define __GST_DO_NOTHING(type)  /* NOP */
  90 #define GST_BOILERPLATE(type,type_as_function,parent_type,parent_type_macro)    \
  91   GST_BOILERPLATE_FULL (type, type_as_function, parent_type, parent_type_macro, \
  92       __GST_DO_NOTHING)
  93
  94 /* Like GST_BOILERPLATE, but makes the type 1) implement an interface, and 2)
  95  * implement GstImplementsInterface for that type
  96  *
  97  * After this you will need to implement interface_as_function ## _supported
  98  * and interface_as_function ## _interface_init
  99  */
 100 #define GST_BOILERPLATE_WITH_INTERFACE(type, type_as_function,          \
 101     parent_type, parent_type_as_macro, interface_type,                  \
 102     interface_type_as_macro, interface_as_function)                     \
 103                                                                         \
 104 static void interface_as_function ## _interface_init (interface_type ## Class *klass);  \
 105 static gboolean interface_as_function ## _supported (type *object, GType iface_type);   \
 106                                                                         \
 107 static void                                                             \
 108 type_as_function ## _implements_interface_init (GstImplementsInterfaceClass *klass)     \
 109 {                                                                       \
 110   klass->supported = (gpointer)interface_as_function ## _supported;     \
 111 }                                                                       \
 112                                                                         \
 113 static void                                                             \
 114 type_as_function ## _init_interfaces (GType type)                       \
 115 {                                                                       \
 116   static const GInterfaceInfo implements_iface_info = {                 \
 117     (GInterfaceInitFunc) type_as_function ## _implements_interface_init,\
 118     NULL,                                                               \
 119     NULL,                                                               \
 120   };                                                                    \
 121   static const GInterfaceInfo iface_info = {                            \
 122     (GInterfaceInitFunc) interface_as_function ## _interface_init,      \
 123     NULL,                                                               \
 124     NULL,                                                               \
 125   };                                                                    \
 126                                                                         \
 127   g_type_add_interface_static (type, GST_TYPE_IMPLEMENTS_INTERFACE,     \
 128       &implements_iface_info);                                          \
 129   g_type_add_interface_static (type, interface_type_as_macro,           \
 130       &iface_info);                                                     \
 131 }                                                                       \
 132                                                                         \
 133 GST_BOILERPLATE_FULL (type, type_as_function, parent_type,              \
 134     parent_type_as_macro, type_as_function ## _init_interfaces)
 135
 136 /* Just call the parent handler.  This assumes that there is a variable
 137  * named parent_class that points to the (duh!) parent class.  Note that
 138  * this macro is not to be used with things that return something, use
 139  * the _WITH_DEFAULT version for that */
 140 #define GST_CALL_PARENT(parent_class_cast, name, args)                  \
 141         ((parent_class_cast(parent_class)->name != NULL) ?              \
 142          parent_class_cast(parent_class)->name args : (void) 0)
 143
 144 /* Same as above, but in case there is no implementation, it evaluates
 145  * to def_return */
 146 #define GST_CALL_PARENT_WITH_DEFAULT(parent_class_cast, name, args,     \
 147     def_return)                                                         \
 148         ((parent_class_cast(parent_class)->name != NULL) ?              \
 149          parent_class_cast(parent_class)->name args : def_return)
 150
 151 /* Define possibly unaligned memory access method whether the type of
 152  * architecture. */
 153 #if GST_HAVE_UNALIGNED_ACCESS
 154
 155 #define _GST_GET(__data, __size, __end) \
 156     (GUINT##__size##_FROM_##__end (* ((guint##__size *) (__data))))
 157
 158 #define GST_READ_UINT64_BE(data)        _GST_GET (data, 64, BE)
 159 #define GST_READ_UINT64_LE(data)        _GST_GET (data, 64, LE)
 160 #define GST_READ_UINT32_BE(data)        _GST_GET (data, 32, BE)
 161 #define GST_READ_UINT32_LE(data)        _GST_GET (data, 32, LE)
 162 #define GST_READ_UINT16_BE(data)        _GST_GET (data, 16, BE)
 163 #define GST_READ_UINT16_LE(data)        _GST_GET (data, 16, LE)
 164 #define GST_READ_UINT8(data)            (* ((guint8 *) (data)))
 165
 166 #define _GST_PUT(__data, __size, __end, __num) \
 167     ((* (guint##__size *) (__data)) = GUINT##__size##_TO_##__end (__num))
 168
 169 #define GST_WRITE_UINT64_BE(data, num)  _GST_PUT(data, 64, BE, num)
 170 #define GST_WRITE_UINT64_LE(data, num)  _GST_PUT(data, 64, LE, num)
 171 #define GST_WRITE_UINT32_BE(data, num)  _GST_PUT(data, 32, BE, num)
 172 #define GST_WRITE_UINT32_LE(data, num)  _GST_PUT(data, 32, LE, num)
 173 #define GST_WRITE_UINT16_BE(data, num)  _GST_PUT(data, 16, BE, num)
 174 #define GST_WRITE_UINT16_LE(data, num)  _GST_PUT(data, 16, LE, num)
 175 #define GST_WRITE_UINT8(data, num)      ((* (guint8 *) (data)) = (num))
 176
 177 #else /* GST_HAVE_UNALIGNED_ACCESS */
 178
 179 #define _GST_GET(__data, __idx, __size, __shift) \
 180     (((guint##__size) (((guint8 *) (__data))[__idx])) << __shift)
 181
 182 #define GST_READ_UINT64_BE(data)        (_GST_GET (data, 0, 64, 56) | \
 183                                          _GST_GET (data, 1, 64, 48) | \
 184                                          _GST_GET (data, 2, 64, 40) | \
 185                                          _GST_GET (data, 3, 64, 32) | \
 186                                          _GST_GET (data, 4, 64, 24) | \
 187                                          _GST_GET (data, 5, 64, 16) | \
 188                                          _GST_GET (data, 6, 64,  8) | \
 189                                          _GST_GET (data, 7, 64,  0))
 190
 191 #define GST_READ_UINT64_LE(data)        (_GST_GET (data, 7, 64, 56) | \
 192                                          _GST_GET (data, 6, 64, 48) | \
 193                                          _GST_GET (data, 5, 64, 40) | \
 194                                          _GST_GET (data, 4, 64, 32) | \
 195                                          _GST_GET (data, 3, 64, 24) | \
 196                                          _GST_GET (data, 2, 64, 16) | \
 197                                          _GST_GET (data, 1, 64,  8) | \
 198                                          _GST_GET (data, 0, 64,  0))
 199
 200 #define GST_READ_UINT32_BE(data)        (_GST_GET (data, 0, 32, 24) | \
 201                                          _GST_GET (data, 1, 32, 16) | \
 202                                          _GST_GET (data, 2, 32,  8) | \
 203                                          _GST_GET (data, 3, 32,  0))
 204
 205 #define GST_READ_UINT32_LE(data)        (_GST_GET (data, 3, 32, 24) | \
 206                                          _GST_GET (data, 2, 32, 16) | \
 207                                          _GST_GET (data, 1, 32,  8) | \
 208                                          _GST_GET (data, 0, 32,  0))
 209
 210 #define GST_READ_UINT16_BE(data)        (_GST_GET (data, 0, 16,  8) | \
 211                                          _GST_GET (data, 1, 16,  0))
 212
 213 #define GST_READ_UINT16_LE(data)        (_GST_GET (data, 1, 16,  8) | \
 214                                          _GST_GET (data, 0, 16,  0))
 215
 216 #define GST_READ_UINT8(data)            (_GST_GET (data, 0,  8,  0))
 217
 218 #define _GST_PUT(__data, __idx, __size, __shift, __num) \
 219     (((guint8 *) (__data))[__idx] = (((guint##__size) __num) >> __shift) & 0xff)
 220
 221 #define GST_WRITE_UINT64_BE(data, num)  do { \
 222                                           _GST_PUT (data, 0, 64, 56, num); \
 223                                           _GST_PUT (data, 1, 64, 48, num); \
 224                                           _GST_PUT (data, 2, 64, 40, num); \
 225                                           _GST_PUT (data, 3, 64, 32, num); \
 226                                           _GST_PUT (data, 4, 64, 24, num); \
 227                                           _GST_PUT (data, 5, 64, 16, num); \
 228                                           _GST_PUT (data, 6, 64,  8, num); \
 229                                           _GST_PUT (data, 7, 64,  0, num); \
 230                                         } while (0)
 231
 232 #define GST_WRITE_UINT64_LE(data, num)  do { \
 233                                           _GST_PUT (data, 0, 64,  0, num); \
 234                                           _GST_PUT (data, 1, 64,  8, num); \
 235                                           _GST_PUT (data, 2, 64, 16, num); \
 236                                           _GST_PUT (data, 3, 64, 24, num); \
 237                                           _GST_PUT (data, 4, 64, 32, num); \
 238                                           _GST_PUT (data, 5, 64, 40, num); \
 239                                           _GST_PUT (data, 6, 64, 48, num); \
 240                                           _GST_PUT (data, 7, 64, 56, num); \
 241                                         } while (0)
 242
 243 #define GST_WRITE_UINT32_BE(data, num)  do { \
 244                                           _GST_PUT (data, 0, 32, 24, num); \
 245                                           _GST_PUT (data, 1, 32, 16, num); \
 246                                           _GST_PUT (data, 2, 32,  8, num); \
 247                                           _GST_PUT (data, 3, 32,  0, num); \
 248                                         } while (0)
 249
 250 #define GST_WRITE_UINT32_LE(data, num)  do { \
 251                                           _GST_PUT (data, 0, 32,  0, num); \
 252                                           _GST_PUT (data, 1, 32,  8, num); \
 253                                           _GST_PUT (data, 2, 32, 16, num); \
 254                                           _GST_PUT (data, 3, 32, 24, num); \
 255                                         } while (0)
 256
 257 #define GST_WRITE_UINT16_BE(data, num)  do { \
 258                                           _GST_PUT (data, 0, 16,  8, num); \
 259                                           _GST_PUT (data, 1, 16,  0, num); \
 260                                         } while (0)
 261
 262 #define GST_WRITE_UINT16_LE(data, num)  do { \
 263                                           _GST_PUT (data, 0, 16,  0, num); \
 264                                           _GST_PUT (data, 1, 16,  8, num); \
 265                                         } while (0)
 266
 267 #define GST_WRITE_UINT8(data, num)      do { \
 268                                           _GST_PUT (data, 0,  8,  0, num); \
 269                                         } while (0)
 270
 271 #endif /* GST_HAVE_UNALIGNED_ACCESS */
 272
 273
 274 /* Miscellaneous utility macros */
 275 #define GST_ROUND_UP_2(num)  (((num)+1)&~1)
 276 #define GST_ROUND_UP_4(num)  (((num)+3)&~3)
 277 #define GST_ROUND_UP_8(num)  (((num)+7)&~7)
 278 #define GST_ROUND_UP_16(num) (((num)+15)&~15)
 279 #define GST_ROUND_UP_32(num) (((num)+31)&~31)
 280 #define GST_ROUND_UP_64(num) (((num)+63)&~63)
 281
 282 void                    gst_object_default_error        (GstObject * source,
 283                                                          GError * error, gchar * debug);
 284
 285
 286 /* element functions */
 287 GstFlowReturn           gst_element_abort_preroll       (GstElement *element);
 288 GstFlowReturn           gst_element_finish_preroll      (GstElement *element, GstPad *pad);
 289
 290 void                    gst_element_create_all_pads     (GstElement *element);
 291 GstPad*                 gst_element_get_compatible_pad  (GstElement *element, GstPad *pad,
 292                                                          const GstCaps *caps);
 293
 294 GstPadTemplate*         gst_element_get_compatible_pad_template (GstElement *element, GstPadTemplate *compattempl);
 295
 296 G_CONST_RETURN gchar*   gst_element_state_get_name      (GstState state);
 297
 298 gboolean                gst_element_link                (GstElement *src, GstElement *dest);
 299 gboolean                gst_element_link_many           (GstElement *element_1,
 300                                                          GstElement *element_2, ...);
 301 gboolean                gst_element_link_filtered       (GstElement * src,
 302                                                          GstElement * dest,
 303                                                          GstCaps *filter);
 304 void                    gst_element_unlink              (GstElement *src, GstElement *dest);
 305 void                    gst_element_unlink_many         (GstElement *element_1,
 306                                                          GstElement *element_2, ...);
 307
 308 gboolean                gst_element_link_pads           (GstElement *src, const gchar *srcpadname,
 309                                                          GstElement *dest, const gchar *destpadname);
 310 void                    gst_element_unlink_pads         (GstElement *src, const gchar *srcpadname,
 311                                                          GstElement *dest, const gchar *destpadname);
 312
 313 gboolean                gst_element_link_pads_filtered  (GstElement * src, const gchar * srcpadname,
 314                                                          GstElement * dest, const gchar * destpadname,
 315                                                          GstCaps *filter);
 316 GstStateChangeReturn    gst_element_set_state_async     (GstElement * element, GstState state);
 317
 318 /* util elementfactory functions */
 319 gboolean                gst_element_factory_can_src_caps(GstElementFactory *factory, const GstCaps *caps);
 320 gboolean                gst_element_factory_can_sink_caps(GstElementFactory *factory, const GstCaps *caps);
 321
 322 /* util query functions */
 323 gboolean                gst_element_query_position      (GstElement *element, GstFormat *format,
 324                                                          gint64 *cur, gint64 *end);
 325 gboolean                gst_element_query_convert       (GstElement *element, GstFormat src_format, gint64 src_val,
 326                                                          GstFormat *dest_fmt, gint64 *dest_val);
 327
 328 /* element class functions */
 329 void                    gst_element_class_install_std_props (GstElementClass * klass,
 330                                                          const gchar * first_name, ...);
 331
 332 /* pad functions */
 333 gboolean                gst_pad_can_link                (GstPad *srcpad, GstPad *sinkpad);
 334
 335 void                    gst_pad_use_fixed_caps          (GstPad *pad);
 336 GstCaps*                gst_pad_get_fixed_caps_func     (GstPad *pad);
 337 GstCaps*                gst_pad_proxy_getcaps           (GstPad * pad);
 338 gboolean                gst_pad_proxy_setcaps           (GstPad * pad, GstCaps * caps);
 339
 340 GstElement*             gst_pad_get_parent_element      (GstPad *pad);
 341
 342 /* flow */
 343 G_CONST_RETURN gchar*   gst_flow_get_name               (GstFlowReturn ret);
 344
 345
 346 /* util query functions */
 347 gboolean                gst_pad_query_position          (GstPad *pad, GstFormat *format,
 348                                                          gint64 *cur, gint64 *end);
 349 gboolean                gst_pad_query_convert           (GstPad *pad, GstFormat src_format, gint64 src_val,
 350                                                          GstFormat *dest_format, gint64 *dest_val);
 351
 352 /* bin functions */
 353 void                    gst_bin_add_many                (GstBin *bin, GstElement *element_1, ...);
 354 void                    gst_bin_remove_many             (GstBin *bin, GstElement *element_1, ...);
 355 void                    gst_bin_watch_for_state_change  (GstBin *bin);
 356
 357 /* buffer functions */
 358 GstBuffer *             gst_buffer_merge                (GstBuffer * buf1, GstBuffer * buf2);
 359 GstBuffer *             gst_buffer_join                 (GstBuffer * buf1, GstBuffer * buf2);
 360 void                    gst_buffer_stamp                (GstBuffer * dest, const GstBuffer * src);
 361
 362 /* atomic functions */
 363 void                    gst_atomic_int_set              (gint * atomic_int, gint value);
 364
 365 /* probes */
 366 gulong                  gst_pad_add_data_probe          (GstPad * pad,
 367                                                          GCallback handler,
 368                                                          gpointer data);
 369 void                    gst_pad_remove_data_probe       (GstPad * pad, guint handler_id);
 370 gulong                  gst_pad_add_event_probe         (GstPad * pad,
 371                                                          GCallback handler,
 372                                                          gpointer data);
 373 void                    gst_pad_remove_event_probe      (GstPad * pad, guint handler_id);
 374 gulong                  gst_pad_add_buffer_probe        (GstPad * pad,
 375                                                          GCallback handler,
 376                                                          gpointer data);
 377 void                    gst_pad_remove_buffer_probe     (GstPad * pad, guint handler_id);
 378
 379 /* tag emission utility functions */
 380 void                    gst_element_found_tags_for_pad  (GstElement * element,
 381                                                          GstPad * pad,
 382                                                          GstTagList * list);
 383 void                    gst_element_found_tags          (GstElement * element,
 384                                                          GstTagList * list);
 385
 386 G_END_DECLS
 387
 388 #endif /* __GST_UTILS_H__ */