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