Merge branch 'master' into 0.11
[platform/upstream/gstreamer.git] / gst / gstclock.h
1 /* GStreamer
2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3  *                    2000 Wim Taymans <wtay@chello.be>
4  *                    2005 Wim Taymans <wim@fluendo.com>
5  *
6  * gstclock.h: Header for clock subsystem
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 #ifndef __GST_CLOCK_H__
25 #define __GST_CLOCK_H__
26
27 G_BEGIN_DECLS
28
29 /* --- standard type macros --- */
30 #define GST_TYPE_CLOCK                  (gst_clock_get_type ())
31 #define GST_CLOCK(clock)                (G_TYPE_CHECK_INSTANCE_CAST ((clock), GST_TYPE_CLOCK, GstClock))
32 #define GST_IS_CLOCK(clock)             (G_TYPE_CHECK_INSTANCE_TYPE ((clock), GST_TYPE_CLOCK))
33 #define GST_CLOCK_CLASS(cclass)         (G_TYPE_CHECK_CLASS_CAST ((cclass), GST_TYPE_CLOCK, GstClockClass))
34 #define GST_IS_CLOCK_CLASS(cclass)      (G_TYPE_CHECK_CLASS_TYPE ((cclass), GST_TYPE_CLOCK))
35 #define GST_CLOCK_GET_CLASS(clock)      (G_TYPE_INSTANCE_GET_CLASS ((clock), GST_TYPE_CLOCK, GstClockClass))
36 #define GST_CLOCK_CAST(clock)           ((GstClock*)(clock))
37
38 /**
39  * GstClockTime:
40  *
41  * A datatype to hold a time, measured in nanoseconds.
42  */
43 typedef guint64 GstClockTime;
44
45 /**
46  * GST_TYPE_CLOCK_TIME:
47  *
48  * The #GType of a #GstClockTime.
49  */
50 #define GST_TYPE_CLOCK_TIME G_TYPE_UINT64
51
52 /**
53  * GstClockTimeDiff:
54  *
55  * A datatype to hold a time difference, measured in nanoseconds.
56  */
57 typedef gint64 GstClockTimeDiff;
58 /**
59  * GstClockID:
60  *
61  * A datatype to hold the handle to an outstanding sync or async clock callback.
62  */
63 typedef gpointer GstClockID;
64
65 /**
66  * GST_CLOCK_TIME_NONE:
67  *
68  * Constant to define an undefined clock time.
69  */
70 #define GST_CLOCK_TIME_NONE             ((GstClockTime) -1)
71 /**
72  * GST_CLOCK_TIME_IS_VALID:
73  * @time: clock time to validate
74  *
75  * Tests if a given #GstClockTime represents a valid defined time.
76  */
77 #define GST_CLOCK_TIME_IS_VALID(time)   (((GstClockTime)(time)) != GST_CLOCK_TIME_NONE)
78
79 /* FIXME: still need to explicitly force types on the defines below */
80 /**
81  * GST_SECOND:
82  *
83  * Constant that defines one GStreamer second.
84  *
85  * Value: 1000000000
86  *
87  */
88 #define GST_SECOND  (G_USEC_PER_SEC * G_GINT64_CONSTANT (1000))
89 /**
90  * GST_MSECOND:
91  *
92  * Constant that defines one GStreamer millisecond.
93  *
94  * Value: 1000000
95  *
96  */
97 #define GST_MSECOND (GST_SECOND / G_GINT64_CONSTANT (1000))
98 /**
99  * GST_USECOND:
100  *
101  * Constant that defines one GStreamer microsecond.
102  *
103  * Value: 1000
104  *
105  */
106 #define GST_USECOND (GST_SECOND / G_GINT64_CONSTANT (1000000))
107 /**
108  * GST_NSECOND:
109  *
110  * Constant that defines one GStreamer nanosecond
111  *
112  * Value: 1
113  *
114  */
115 #define GST_NSECOND (GST_SECOND / G_GINT64_CONSTANT (1000000000))
116
117
118 /**
119  * GST_TIME_AS_SECONDS:
120  * @time: the time
121  *
122  * Convert a #GstClockTime to seconds.
123  *
124  * Since: 0.10.16
125  */
126 #define GST_TIME_AS_SECONDS(time)  ((time) / GST_SECOND)
127 /**
128  * GST_TIME_AS_MSECONDS:
129  * @time: the time
130  *
131  * Convert a #GstClockTime to milliseconds (1/1000 of a second).
132  *
133  * Since: 0.10.16
134  */
135 #define GST_TIME_AS_MSECONDS(time) ((time) / G_GINT64_CONSTANT (1000000))
136 /**
137  * GST_TIME_AS_USECONDS:
138  * @time: the time
139  *
140  * Convert a #GstClockTime to microseconds (1/1000000 of a second).
141  *
142  * Since: 0.10.16
143  */
144 #define GST_TIME_AS_USECONDS(time) ((time) / G_GINT64_CONSTANT (1000))
145 /**
146  * GST_TIME_AS_NSECONDS:
147  * @time: the time
148  *
149  * Convert a #GstClockTime to nanoseconds (1/1000000000 of a second).
150  *
151  * Since: 0.10.16
152  */
153 #define GST_TIME_AS_NSECONDS(time) (time)
154
155 /**
156  * GST_CLOCK_DIFF:
157  * @s: the first time
158  * @e: the second time
159  *
160  * Calculate a difference between two clock times as a #GstClockTimeDiff.
161  * The difference is calculated as @e - @s.
162  */
163 #define GST_CLOCK_DIFF(s, e)            (GstClockTimeDiff)((e) - (s))
164
165 /**
166  * GST_TIMEVAL_TO_TIME:
167  * @tv: the timeval to convert
168  *
169  * Convert a #GTimeVal to a #GstClockTime.
170  */
171 #define GST_TIMEVAL_TO_TIME(tv)         (GstClockTime)((tv).tv_sec * GST_SECOND + (tv).tv_usec * GST_USECOND)
172
173 /**
174  * GST_TIME_TO_TIMEVAL:
175  * @t: The #GstClockTime to convert
176  * @tv: The target timeval
177  *
178  * Convert a #GstClockTime to a #GTimeVal
179  *
180  * <note>on 32-bit systems, a timeval has a range of only 2^32 - 1 seconds,
181  * which is about 68 years.  Expect trouble if you want to schedule stuff
182  * in your pipeline for 2038.</note>
183  */
184 #define GST_TIME_TO_TIMEVAL(t,tv)                               \
185 G_STMT_START {                                                  \
186   (tv).tv_sec  = ((GstClockTime) (t)) / GST_SECOND;             \
187   (tv).tv_usec = (((GstClockTime) (t)) -                        \
188                   ((GstClockTime) (tv).tv_sec) * GST_SECOND)    \
189                  / GST_USECOND;                                 \
190 } G_STMT_END
191
192 /**
193  * GST_TIMESPEC_TO_TIME:
194  * @ts: the timespec to convert
195  *
196  * Convert a struct timespec (see man pselect) to a #GstClockTime.
197  */
198 #define GST_TIMESPEC_TO_TIME(ts)        (GstClockTime)((ts).tv_sec * GST_SECOND + (ts).tv_nsec * GST_NSECOND)
199 /**
200  * GST_TIME_TO_TIMESPEC:
201  * @t: The #GstClockTime to convert
202  * @ts: The target timespec
203  *
204  * Convert a #GstClockTime to a struct timespec (see man pselect)
205  */
206 #define GST_TIME_TO_TIMESPEC(t,ts)                      \
207 G_STMT_START {                                          \
208   (ts).tv_sec  =  (t) / GST_SECOND;                     \
209   (ts).tv_nsec = ((t) - (ts).tv_sec * GST_SECOND) / GST_NSECOND;        \
210 } G_STMT_END
211
212 /* timestamp debugging macros */
213 /**
214  * GST_TIME_FORMAT:
215  *
216  * A string that can be used in printf-like format strings to display a
217  * #GstClockTime value in h:m:s format.  Use GST_TIME_ARGS() to construct
218  * the matching arguments.
219  *
220  * Example:
221  * |[
222  * printf("%" GST_TIME_FORMAT "\n", GST_TIME_ARGS(ts));
223  * ]|
224  */
225 #define GST_TIME_FORMAT "u:%02u:%02u.%09u"
226 /**
227  * GST_TIME_ARGS:
228  * @t: a #GstClockTime
229  *
230  * Format @t for the #GST_TIME_FORMAT format string. Note: @t will be
231  * evaluated more than once.
232  */
233 #define GST_TIME_ARGS(t) \
234         GST_CLOCK_TIME_IS_VALID (t) ? \
235         (guint) (((GstClockTime)(t)) / (GST_SECOND * 60 * 60)) : 99, \
236         GST_CLOCK_TIME_IS_VALID (t) ? \
237         (guint) ((((GstClockTime)(t)) / (GST_SECOND * 60)) % 60) : 99, \
238         GST_CLOCK_TIME_IS_VALID (t) ? \
239         (guint) ((((GstClockTime)(t)) / GST_SECOND) % 60) : 99, \
240         GST_CLOCK_TIME_IS_VALID (t) ? \
241         (guint) (((GstClockTime)(t)) % GST_SECOND) : 999999999
242
243 typedef struct _GstClockEntry   GstClockEntry;
244 typedef struct _GstClock        GstClock;
245 typedef struct _GstClockClass   GstClockClass;
246 typedef struct _GstClockPrivate GstClockPrivate;
247
248 /* --- prototype for async callbacks --- */
249 /**
250  * GstClockCallback:
251  * @clock: The clock that triggered the callback
252  * @time: The time it was triggered
253  * @id: The #GstClockID that expired
254  * @user_data: user data passed in the gst_clock_id_wait_async() function
255  *
256  * The function prototype of the callback.
257  *
258  * Returns: %TRUE or %FALSE (currently unused)
259  */
260 typedef gboolean        (*GstClockCallback)     (GstClock *clock, GstClockTime time,
261                                                  GstClockID id, gpointer user_data);
262 /**
263  * GstClockReturn:
264  * @GST_CLOCK_OK: The operation succeeded.
265  * @GST_CLOCK_EARLY: The operation was scheduled too late.
266  * @GST_CLOCK_UNSCHEDULED: The clockID was unscheduled
267  * @GST_CLOCK_BUSY: The ClockID is busy
268  * @GST_CLOCK_BADTIME: A bad time was provided to a function.
269  * @GST_CLOCK_ERROR: An error occurred
270  * @GST_CLOCK_UNSUPPORTED: Operation is not supported
271  * @GST_CLOCK_DONE: The ClockID is done waiting (Since: 0.10.32)
272  *
273  * The return value of a clock operation.
274  */
275 typedef enum
276 {
277   GST_CLOCK_OK          =  0,
278   GST_CLOCK_EARLY       =  1,
279   GST_CLOCK_UNSCHEDULED =  2,
280   GST_CLOCK_BUSY        =  3,
281   GST_CLOCK_BADTIME     =  4,
282   GST_CLOCK_ERROR       =  5,
283   GST_CLOCK_UNSUPPORTED =  6,
284   GST_CLOCK_DONE        =  7
285 } GstClockReturn;
286
287 /**
288  * GstClockEntryType:
289  * @GST_CLOCK_ENTRY_SINGLE: a single shot timeout
290  * @GST_CLOCK_ENTRY_PERIODIC: a periodic timeout request
291  *
292  * The type of the clock entry
293  */
294 typedef enum {
295   GST_CLOCK_ENTRY_SINGLE,
296   GST_CLOCK_ENTRY_PERIODIC
297 } GstClockEntryType;
298
299 /**
300  * GST_CLOCK_ENTRY:
301  * @entry: the entry to cast
302  *
303  * Cast to a clock entry
304  */
305 #define GST_CLOCK_ENTRY(entry)          ((GstClockEntry *)(entry))
306 /**
307  * GST_CLOCK_ENTRY_CLOCK:
308  * @entry: the entry to query
309  *
310  * Get the owner clock of the entry
311  */
312 #define GST_CLOCK_ENTRY_CLOCK(entry)    ((entry)->clock)
313 /**
314  * GST_CLOCK_ENTRY_TYPE:
315  * @entry: the entry to query
316  *
317  * Get the type of the clock entry
318  */
319 #define GST_CLOCK_ENTRY_TYPE(entry)     ((entry)->type)
320 /**
321  * GST_CLOCK_ENTRY_TIME:
322  * @entry: the entry to query
323  *
324  * Get the requested time of this entry
325  */
326 #define GST_CLOCK_ENTRY_TIME(entry)     ((entry)->time)
327 /**
328  * GST_CLOCK_ENTRY_INTERVAL:
329  * @entry: the entry to query
330  *
331  * Get the interval of this periodic entry
332  */
333 #define GST_CLOCK_ENTRY_INTERVAL(entry) ((entry)->interval)
334 /**
335  * GST_CLOCK_ENTRY_STATUS:
336  * @entry: the entry to query
337  *
338  * The status of the entry
339  */
340 #define GST_CLOCK_ENTRY_STATUS(entry)   ((entry)->status)
341
342 /**
343  * GstClockEntry:
344  * @refcount: reference counter (read-only)
345  *
346  * All pending timeouts or periodic notifies are converted into
347  * an entry.
348  * Note that GstClockEntry should be treated as an opaque structure. It must
349  * not be extended or allocated using a custom allocator.
350  */
351 struct _GstClockEntry {
352   gint                  refcount;
353   /*< protected >*/
354   GstClock              *clock;
355   GstClockEntryType      type;
356   GstClockTime           time;
357   GstClockTime           interval;
358   GstClockReturn         status;
359   GstClockCallback       func;
360   gpointer               user_data;
361   GDestroyNotify         destroy_data;
362   gboolean               unscheduled;
363   gboolean               woken_up;
364
365   gpointer _gst_reserved[GST_PADDING];
366 };
367
368 #include <gst/gstobject.h>
369
370 /**
371  * GstClockFlags:
372  * @GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC: clock can do a single sync timeout request
373  * @GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC: clock can do a single async timeout request
374  * @GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC: clock can do sync periodic timeout requests
375  * @GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC: clock can do async periodic timeout callbacks
376  * @GST_CLOCK_FLAG_CAN_SET_RESOLUTION: clock's resolution can be changed
377  * @GST_CLOCK_FLAG_CAN_SET_MASTER: clock can be slaved to a master clock
378  * @GST_CLOCK_FLAG_LAST: subclasses can add additional flags starting from this flag
379  *
380  * The capabilities of this clock
381  */
382 typedef enum {
383   GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC     = (GST_OBJECT_FLAG_LAST << 0),
384   GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC    = (GST_OBJECT_FLAG_LAST << 1),
385   GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC   = (GST_OBJECT_FLAG_LAST << 2),
386   GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC  = (GST_OBJECT_FLAG_LAST << 3),
387   GST_CLOCK_FLAG_CAN_SET_RESOLUTION     = (GST_OBJECT_FLAG_LAST << 4),
388   GST_CLOCK_FLAG_CAN_SET_MASTER         = (GST_OBJECT_FLAG_LAST << 5),
389   /* padding */
390   GST_CLOCK_FLAG_LAST                   = (GST_OBJECT_FLAG_LAST << 8)
391 } GstClockFlags;
392
393 /**
394  * GST_CLOCK_FLAGS:
395  * @clock: the clock to query
396  *
397  * Gets the #GstClockFlags clock flags.
398  */
399 #define GST_CLOCK_FLAGS(clock)  GST_OBJECT_FLAGS(clock)
400
401 /**
402  * GstClock:
403  *
404  * #GstClock base structure. The values of this structure are
405  * protected for subclasses, use the methods to use the #GstClock.
406  */
407 struct _GstClock {
408   GstObject      object;
409
410   /*< private >*/
411   GstClockPrivate *priv;
412
413   gpointer _gst_reserved[GST_PADDING];
414 };
415
416 /**
417  * GstClockClass:
418  * @parent_class: the parent class structure
419  * @change_resolution: change the resolution of the clock. Not all values might
420  *                     be acceptable. The new resolution should be returned.
421  * @get_resolution: get the resolution of the clock.
422  * @get_internal_time: get the internal unadjusted time of the clock.
423  *        implement @wait_jitter instead.
424  * @wait: perform a blocking wait on the given #GstClockEntry and return
425  *               the jitter.
426  * @wait_async: perform an asynchronous wait for the given #GstClockEntry.
427  * @unschedule: unblock a blocking or async wait operation.
428  *
429  * GStreamer clock class. Override the vmethods to implement the clock
430  * functionality.
431  */
432 struct _GstClockClass {
433   GstObjectClass        parent_class;
434
435   /*< public >*/
436   /* vtable */
437   GstClockTime          (*change_resolution)    (GstClock *clock,
438                                                  GstClockTime old_resolution,
439                                                  GstClockTime new_resolution);
440   GstClockTime          (*get_resolution)       (GstClock *clock);
441
442   GstClockTime          (*get_internal_time)    (GstClock *clock);
443
444   /* waiting on an ID */
445   GstClockReturn        (*wait)                 (GstClock *clock, GstClockEntry *entry,
446                                                  GstClockTimeDiff *jitter);
447   GstClockReturn        (*wait_async)           (GstClock *clock, GstClockEntry *entry);
448   void                  (*unschedule)           (GstClock *clock, GstClockEntry *entry);
449
450   /*< private >*/
451   gpointer _gst_reserved[GST_PADDING];
452 };
453
454 GType                   gst_clock_get_type              (void);
455
456 GstClockTime            gst_clock_set_resolution        (GstClock *clock,
457                                                          GstClockTime resolution);
458 GstClockTime            gst_clock_get_resolution        (GstClock *clock);
459
460 GstClockTime            gst_clock_get_time              (GstClock *clock);
461 void                    gst_clock_set_calibration       (GstClock *clock, GstClockTime internal,
462                                                          GstClockTime external,
463                                                          GstClockTime rate_num,
464                                                          GstClockTime rate_denom);
465 void                    gst_clock_get_calibration       (GstClock *clock, GstClockTime *internal,
466                                                          GstClockTime *external,
467                                                          GstClockTime *rate_num,
468                                                          GstClockTime *rate_denom);
469
470 /* master/slave clocks */
471 gboolean                gst_clock_set_master            (GstClock *clock, GstClock *master);
472 GstClock*               gst_clock_get_master            (GstClock *clock);
473
474 void                    gst_clock_set_timeout           (GstClock *clock,
475                                                          GstClockTime timeout);
476 GstClockTime            gst_clock_get_timeout           (GstClock *clock);
477
478 gboolean                gst_clock_add_observation       (GstClock *clock, GstClockTime slave,
479                                                          GstClockTime master, gdouble *r_squared);
480
481
482 /* getting and adjusting internal/external time */
483 GstClockTime            gst_clock_get_internal_time     (GstClock *clock);
484 GstClockTime            gst_clock_adjust_unlocked       (GstClock *clock, GstClockTime internal);
485 GstClockTime            gst_clock_unadjust_unlocked     (GstClock * clock, GstClockTime external);
486
487
488 /* creating IDs that can be used to get notifications */
489 GstClockID              gst_clock_new_single_shot_id    (GstClock *clock,
490                                                          GstClockTime time);
491 GstClockID              gst_clock_new_periodic_id       (GstClock *clock,
492                                                          GstClockTime start_time,
493                                                          GstClockTime interval);
494
495 /* reference counting */
496 GstClockID              gst_clock_id_ref                (GstClockID id);
497 void                    gst_clock_id_unref              (GstClockID id);
498
499 /* operations on IDs */
500 gint                    gst_clock_id_compare_func       (gconstpointer id1, gconstpointer id2);
501
502 GstClockTime            gst_clock_id_get_time           (GstClockID id);
503 GstClockReturn          gst_clock_id_wait               (GstClockID id,
504                                                          GstClockTimeDiff *jitter);
505 GstClockReturn          gst_clock_id_wait_async         (GstClockID id,
506                                                          GstClockCallback func,
507                                                          gpointer user_data);
508 GstClockReturn          gst_clock_id_wait_async_full    (GstClockID id,
509                                                          GstClockCallback func,
510                                                          gpointer user_data,
511                                                          GDestroyNotify destroy_data);
512 void                    gst_clock_id_unschedule         (GstClockID id);
513
514 gboolean                gst_clock_single_shot_id_reinit (GstClock * clock,
515                                                          GstClockID id,
516                                                          GstClockTime time);
517 gboolean                gst_clock_periodic_id_reinit    (GstClock * clock,
518                                                          GstClockID id,
519                                                          GstClockTime start_time,
520                                                          GstClockTime interval);
521
522 G_END_DECLS
523
524 #endif /* __GST_CLOCK_H__ */