2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2000 Wim Taymans <wtay@chello.be>
5 * gstutils.h: Header for various utility functions
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.
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.
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.
24 #ifndef __GST_UTILS_H__
25 #define __GST_UTILS_H__
28 #include <gst/gstbin.h>
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);
35 void gst_util_dump_mem (const guchar *mem, guint size);
37 guint64 gst_util_uint64_scale (guint64 val, guint64 num, guint64 denom);
39 void gst_print_pad_caps (GString *buf, gint indent, GstPad *pad);
40 void gst_print_element_args (GString *buf, gint indent, GstElement *element);
43 /* Macros for defining classes. Ideas taken from Bonobo, which took theirs
44 from Nautilus and GOB. */
46 /* Define the boilerplate type stuff to reduce typos and code size. Defines
47 the get_type method and the parent_class static variable.
48 void additional_initializations (GType type) is for initializing interfaces
49 and stuff like that */
51 #define GST_BOILERPLATE_FULL(type, type_as_function, parent_type, parent_type_macro, additional_initializations) \
53 static void type_as_function ## _base_init (gpointer g_class); \
54 static void type_as_function ## _class_init (type ## Class *g_class);\
55 static void type_as_function ## _init (type *object, \
56 type ## Class *g_class);\
57 static parent_type ## Class *parent_class = NULL; \
59 type_as_function ## _class_init_trampoline (gpointer g_class, \
62 parent_class = (parent_type ## Class *) \
63 g_type_class_peek_parent (g_class); \
64 type_as_function ## _class_init ((type ## Class *)g_class); \
68 type_as_function ## _get_type (void) \
70 static GType object_type = 0; \
71 if (object_type == 0) { \
72 static const GTypeInfo object_info = { \
73 sizeof (type ## Class), \
74 type_as_function ## _base_init, \
75 NULL, /* base_finalize */ \
76 type_as_function ## _class_init_trampoline, \
77 NULL, /* class_finalize */ \
78 NULL, /* class_data */ \
80 0, /* n_preallocs */ \
81 (GInstanceInitFunc) type_as_function ## _init \
83 object_type = g_type_register_static (parent_type_macro, #type, \
84 &object_info, (GTypeFlags) 0); \
85 additional_initializations (object_type); \
90 #define __GST_DO_NOTHING(type) /* NOP */
91 #define GST_BOILERPLATE(type,type_as_function,parent_type,parent_type_macro) \
92 GST_BOILERPLATE_FULL (type, type_as_function, parent_type, parent_type_macro, \
95 /* Like GST_BOILERPLATE, but makes the type 1) implement an interface, and 2)
96 * implement GstImplementsInterface for that type
98 * After this you will need to implement interface_as_function ## _supported
99 * and interface_as_function ## _interface_init
101 #define GST_BOILERPLATE_WITH_INTERFACE(type, type_as_function, parent_type, \
102 parent_type_as_macro, interface_type, interface_type_as_macro, \
103 interface_as_function) \
105 static void interface_as_function ## _interface_init (interface_type ## Class *klass); \
106 static gboolean interface_as_function ## _supported (type *object, GType iface_type); \
109 type_as_function ## _implements_interface_init (GstImplementsInterfaceClass *klass) \
111 klass->supported = (gpointer)interface_as_function ## _supported; \
115 type_as_function ## _init_interfaces (GType type) \
117 static const GInterfaceInfo implements_iface_info = { \
118 (GInterfaceInitFunc) type_as_function ## _implements_interface_init, \
122 static const GInterfaceInfo iface_info = { \
123 (GInterfaceInitFunc) interface_as_function ## _interface_init, \
128 g_type_add_interface_static (type, GST_TYPE_IMPLEMENTS_INTERFACE, \
129 &implements_iface_info); \
130 g_type_add_interface_static (type, interface_type_as_macro, &iface_info); \
133 GST_BOILERPLATE_FULL (type, type_as_function, parent_type, \
134 parent_type_as_macro, type_as_function ## _init_interfaces)
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)
144 /* Same as above, but in case there is no implementation, it evaluates
146 #define GST_CALL_PARENT_WITH_DEFAULT(parent_class_cast, name, args, def_return) \
147 ((parent_class_cast(parent_class)->name != NULL) ? \
148 parent_class_cast(parent_class)->name args : def_return)
150 /* Define possibly unaligned memory access method whether the type of
152 #if GST_HAVE_UNALIGNED_ACCESS
154 #define _GST_GET(__data, __size, __end) \
155 (GUINT##__size##_FROM_##__end (* ((guint##__size *) (__data))))
157 #define GST_READ_UINT64_BE(data) _GST_GET (data, 64, BE)
158 #define GST_READ_UINT64_LE(data) _GST_GET (data, 64, LE)
159 #define GST_READ_UINT32_BE(data) _GST_GET (data, 32, BE)
160 #define GST_READ_UINT32_LE(data) _GST_GET (data, 32, LE)
161 #define GST_READ_UINT16_BE(data) _GST_GET (data, 16, BE)
162 #define GST_READ_UINT16_LE(data) _GST_GET (data, 16, LE)
163 #define GST_READ_UINT8(data) (* ((guint8 *) (data)))
165 #define _GST_PUT(__data, __size, __end, __num) \
166 ((* (guint##__size *) (__data)) = GUINT##__size##_TO_##__end (__num))
168 #define GST_WRITE_UINT64_BE(data, num) _GST_PUT(data, 64, BE, num)
169 #define GST_WRITE_UINT64_LE(data, num) _GST_PUT(data, 64, LE, num)
170 #define GST_WRITE_UINT32_BE(data, num) _GST_PUT(data, 32, BE, num)
171 #define GST_WRITE_UINT32_LE(data, num) _GST_PUT(data, 32, LE, num)
172 #define GST_WRITE_UINT16_BE(data, num) _GST_PUT(data, 16, BE, num)
173 #define GST_WRITE_UINT16_LE(data, num) _GST_PUT(data, 16, LE, num)
174 #define GST_WRITE_UINT8(data, num) ((* (guint8 *) (data)) = (num))
176 #else /* GST_HAVE_UNALIGNED_ACCESS */
178 #define _GST_GET(__data, __idx, __size, __shift) \
179 (((guint##__size) (((guint8 *) (__data))[__idx])) << __shift)
181 #define GST_READ_UINT64_BE(data) (_GST_GET (data, 0, 64, 56) | \
182 _GST_GET (data, 1, 64, 48) | \
183 _GST_GET (data, 2, 64, 40) | \
184 _GST_GET (data, 3, 64, 32) | \
185 _GST_GET (data, 4, 64, 24) | \
186 _GST_GET (data, 5, 64, 16) | \
187 _GST_GET (data, 6, 64, 8) | \
188 _GST_GET (data, 7, 64, 0))
190 #define GST_READ_UINT64_LE(data) (_GST_GET (data, 7, 64, 56) | \
191 _GST_GET (data, 6, 64, 48) | \
192 _GST_GET (data, 5, 64, 40) | \
193 _GST_GET (data, 4, 64, 32) | \
194 _GST_GET (data, 3, 64, 24) | \
195 _GST_GET (data, 2, 64, 16) | \
196 _GST_GET (data, 1, 64, 8) | \
197 _GST_GET (data, 0, 64, 0))
199 #define GST_READ_UINT32_BE(data) (_GST_GET (data, 0, 32, 24) | \
200 _GST_GET (data, 1, 32, 16) | \
201 _GST_GET (data, 2, 32, 8) | \
202 _GST_GET (data, 3, 32, 0))
204 #define GST_READ_UINT32_LE(data) (_GST_GET (data, 3, 32, 24) | \
205 _GST_GET (data, 2, 32, 16) | \
206 _GST_GET (data, 1, 32, 8) | \
207 _GST_GET (data, 0, 32, 0))
209 #define GST_READ_UINT16_BE(data) (_GST_GET (data, 0, 16, 8) | \
210 _GST_GET (data, 1, 16, 0))
212 #define GST_READ_UINT16_LE(data) (_GST_GET (data, 1, 16, 8) | \
213 _GST_GET (data, 0, 16, 0))
215 #define GST_READ_UINT8(data) (_GST_GET (data, 0, 8, 0))
217 #define _GST_PUT(__data, __idx, __size, __shift, __num) \
218 (((guint8 *) (__data))[__idx] = (((guint##__size) __num) >> __shift) & 0xff)
220 #define GST_WRITE_UINT64_BE(data, num) do { \
221 _GST_PUT (data, 0, 64, 56, num); \
222 _GST_PUT (data, 1, 64, 48, num); \
223 _GST_PUT (data, 2, 64, 40, num); \
224 _GST_PUT (data, 3, 64, 32, num); \
225 _GST_PUT (data, 4, 64, 24, num); \
226 _GST_PUT (data, 5, 64, 16, num); \
227 _GST_PUT (data, 6, 64, 8, num); \
228 _GST_PUT (data, 7, 64, 0, num); \
231 #define GST_WRITE_UINT64_LE(data, num) do { \
232 _GST_PUT (data, 0, 64, 0, num); \
233 _GST_PUT (data, 1, 64, 8, num); \
234 _GST_PUT (data, 2, 64, 16, num); \
235 _GST_PUT (data, 3, 64, 24, num); \
236 _GST_PUT (data, 4, 64, 32, num); \
237 _GST_PUT (data, 5, 64, 40, num); \
238 _GST_PUT (data, 6, 64, 48, num); \
239 _GST_PUT (data, 7, 64, 56, num); \
242 #define GST_WRITE_UINT32_BE(data, num) do { \
243 _GST_PUT (data, 0, 32, 24, num); \
244 _GST_PUT (data, 1, 32, 16, num); \
245 _GST_PUT (data, 2, 32, 8, num); \
246 _GST_PUT (data, 3, 32, 0, num); \
249 #define GST_WRITE_UINT32_LE(data, num) do { \
250 _GST_PUT (data, 0, 32, 0, num); \
251 _GST_PUT (data, 1, 32, 8, num); \
252 _GST_PUT (data, 2, 32, 16, num); \
253 _GST_PUT (data, 3, 32, 24, num); \
256 #define GST_WRITE_UINT16_BE(data, num) do { \
257 _GST_PUT (data, 0, 16, 8, num); \
258 _GST_PUT (data, 1, 16, 0, num); \
261 #define GST_WRITE_UINT16_LE(data, num) do { \
262 _GST_PUT (data, 0, 16, 0, num); \
263 _GST_PUT (data, 1, 16, 8, num); \
266 #define GST_WRITE_UINT8(data, num) do { \
267 _GST_PUT (data, 0, 8, 0, num); \
270 #endif /* GST_HAVE_UNALIGNED_ACCESS */
273 /* Miscellaneous utility macros */
274 #define GST_ROUND_UP_2(num) (((num)+1)&~1)
275 #define GST_ROUND_UP_4(num) (((num)+3)&~3)
276 #define GST_ROUND_UP_8(num) (((num)+7)&~7)
277 #define GST_ROUND_UP_16(num) (((num)+15)&~15)
278 #define GST_ROUND_UP_32(num) (((num)+31)&~31)
279 #define GST_ROUND_UP_64(num) (((num)+63)&~63)
281 void gst_object_default_error (GstObject * source,
282 GError * error, gchar * debug);
285 /* element functions */
286 GstFlowReturn gst_element_abort_preroll (GstElement *element);
287 GstFlowReturn gst_element_finish_preroll (GstElement *element, GstPad *pad);
289 void gst_element_create_all_pads (GstElement *element);
290 GstPad* gst_element_get_compatible_pad (GstElement *element, GstPad *pad,
291 const GstCaps *caps);
293 GstPadTemplate* gst_element_get_compatible_pad_template (GstElement *element, GstPadTemplate *compattempl);
295 G_CONST_RETURN gchar* gst_element_state_get_name (GstElementState state);
297 gboolean gst_element_link (GstElement *src, GstElement *dest);
298 gboolean gst_element_link_many (GstElement *element_1,
299 GstElement *element_2, ...);
300 void gst_element_unlink (GstElement *src, GstElement *dest);
301 void gst_element_unlink_many (GstElement *element_1,
302 GstElement *element_2, ...);
304 gboolean gst_element_link_pads (GstElement *src, const gchar *srcpadname,
305 GstElement *dest, const gchar *destpadname);
306 void gst_element_unlink_pads (GstElement *src, const gchar *srcpadname,
307 GstElement *dest, const gchar *destpadname);
309 gboolean gst_element_link_pads_filtered (GstElement * src, const gchar * srcpadname,
310 GstElement * dest, const gchar * destpadname,
313 /* util elementfactory functions */
314 gboolean gst_element_factory_can_src_caps(GstElementFactory *factory, const GstCaps *caps);
315 gboolean gst_element_factory_can_sink_caps(GstElementFactory *factory, const GstCaps *caps);
317 /* util query functions */
318 gboolean gst_element_query_position (GstElement *element, GstFormat *format,
319 gint64 *cur, gint64 *end);
320 gboolean gst_element_query_convert (GstElement *element, GstFormat src_format, gint64 src_val,
321 GstFormat *dest_fmt, gint64 *dest_val);
323 /* element class functions */
324 void gst_element_class_install_std_props (GstElementClass * klass,
325 const gchar * first_name, ...);
328 gboolean gst_pad_can_link (GstPad *srcpad, GstPad *sinkpad);
330 void gst_pad_use_fixed_caps (GstPad *pad);
331 GstCaps* gst_pad_get_fixed_caps_func (GstPad *pad);
332 GstCaps* gst_pad_proxy_getcaps (GstPad * pad);
333 gboolean gst_pad_proxy_setcaps (GstPad * pad, GstCaps * caps);
335 GstElement* gst_pad_get_parent_element (GstPad *pad);
338 G_CONST_RETURN gchar* gst_flow_get_name (GstFlowReturn ret);
341 /* util query functions */
342 gboolean gst_pad_query_position (GstPad *pad, GstFormat *format,
343 gint64 *cur, gint64 *end);
344 gboolean gst_pad_query_convert (GstPad *pad, GstFormat src_format, gint64 src_val,
345 GstFormat *dest_format, gint64 *dest_val);
348 void gst_bin_add_many (GstBin *bin, GstElement *element_1, ...);
349 void gst_bin_remove_many (GstBin *bin, GstElement *element_1, ...);
350 void gst_bin_watch_for_state_change (GstBin *bin);
352 /* buffer functions */
353 GstBuffer * gst_buffer_merge (GstBuffer * buf1, GstBuffer * buf2);
354 GstBuffer * gst_buffer_join (GstBuffer * buf1, GstBuffer * buf2);
355 void gst_buffer_stamp (GstBuffer * dest, const GstBuffer * src);
357 /* atomic functions */
358 void gst_atomic_int_set (gint * atomic_int, gint value);
361 gulong gst_pad_add_data_probe (GstPad * pad,
364 void gst_pad_remove_data_probe (GstPad * pad,
367 gulong gst_pad_add_event_probe (GstPad * pad,
370 void gst_pad_remove_event_probe (GstPad * pad,
373 gulong gst_pad_add_buffer_probe (GstPad * pad,
376 void gst_pad_remove_buffer_probe (GstPad * pad,
380 /* tag emission utility functions */
381 void gst_element_found_tags_for_pad (GstElement * element,
384 void gst_element_found_tags (GstElement * element,
389 #endif /* __GST_UTILS_H__ */