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>
6 * gstclock.h: Header for clock subsystem
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.
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.
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.
24 #ifndef __GST_CLOCK_H__
25 #define __GST_CLOCK_H__
27 #include <gst/gstobject.h>
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)
46 * A datatype to hold a time, measured in nanoseconds.
48 typedef guint64 GstClockTime;
51 * GST_TYPE_CLOCK_TIME:
53 * The #GType of a #GstClockTime.
55 #define GST_TYPE_CLOCK_TIME G_TYPE_UINT64
60 * A datatype to hold a time difference, measured in nanoseconds.
62 typedef gint64 GstClockTimeDiff;
66 * A datatype to hold the handle to an outstanding sync or async clock callback.
68 typedef gpointer GstClockID;
71 * GST_CLOCK_TIME_NONE:
73 * Constant to define an undefined clock time.
75 #define GST_CLOCK_TIME_NONE ((GstClockTime) -1)
77 * GST_CLOCK_TIME_IS_VALID:
78 * @time: clock time to validate
80 * Tests if a given #GstClockTime represents a valid defined time.
82 #define GST_CLOCK_TIME_IS_VALID(time) (((GstClockTime)(time)) != GST_CLOCK_TIME_NONE)
87 * Constant that defines one GStreamer second.
89 #define GST_SECOND (G_USEC_PER_SEC * G_GINT64_CONSTANT (1000))
93 * Constant that defines one GStreamer millisecond.
95 #define GST_MSECOND (GST_SECOND / G_GINT64_CONSTANT (1000))
99 * Constant that defines one GStreamer microsecond.
101 #define GST_USECOND (GST_SECOND / G_GINT64_CONSTANT (1000000))
105 * Constant that defines one GStreamer nanosecond
107 #define GST_NSECOND (GST_SECOND / G_GINT64_CONSTANT (1000000000))
111 * GST_TIME_AS_SECONDS:
114 * Convert a #GstClockTime to seconds.
118 #define GST_TIME_AS_SECONDS(time) ((time) / GST_SECOND)
120 * GST_TIME_AS_MSECONDS:
123 * Convert a #GstClockTime to milliseconds (1/1000 of a second).
127 #define GST_TIME_AS_MSECONDS(time) ((time) / G_GINT64_CONSTANT (1000000))
129 * GST_TIME_AS_USECONDS:
132 * Convert a #GstClockTime to microseconds (1/1000000 of a second).
136 #define GST_TIME_AS_USECONDS(time) ((time) / G_GINT64_CONSTANT (1000))
138 * GST_TIME_AS_NSECONDS:
141 * Convert a #GstClockTime to nanoseconds (1/1000000000 of a second).
145 #define GST_TIME_AS_NSECONDS(time) (time)
150 * @e: the second time
152 * Calculate a difference between two clock times as a #GstClockTimeDiff.
153 * The difference is calculated as @e - @s.
155 #define GST_CLOCK_DIFF(s, e) (GstClockTimeDiff)((e) - (s))
158 * GST_TIMEVAL_TO_TIME:
159 * @tv: the timeval to convert
161 * Convert a #GTimeVal to a #GstClockTime.
163 #define GST_TIMEVAL_TO_TIME(tv) (GstClockTime)((tv).tv_sec * GST_SECOND + (tv).tv_usec * GST_USECOND)
166 * GST_TIME_TO_TIMEVAL:
167 * @t: The #GstClockTime to convert
168 * @tv: The target timeval
170 * Convert a #GstClockTime to a #GTimeVal
172 * <note>on 32-bit systems, a timeval has a range of only 2^32 - 1 seconds,
173 * which is about 68 years. Expect trouble if you want to schedule stuff
174 * in your pipeline for 2038.</note>
176 #define GST_TIME_TO_TIMEVAL(t,tv) \
178 (tv).tv_sec = ((GstClockTime) (t)) / GST_SECOND; \
179 (tv).tv_usec = (((GstClockTime) (t)) - \
180 ((GstClockTime) (tv).tv_sec) * GST_SECOND) \
185 * GST_TIMESPEC_TO_TIME:
186 * @ts: the timespec to convert
188 * Convert a struct timespec (see man pselect) to a #GstClockTime.
190 #define GST_TIMESPEC_TO_TIME(ts) (GstClockTime)((ts).tv_sec * GST_SECOND + (ts).tv_nsec * GST_NSECOND)
192 * GST_TIME_TO_TIMESPEC:
193 * @t: The #GstClockTime to convert
194 * @ts: The target timespec
196 * Convert a #GstClockTime to a struct timespec (see man pselect)
198 #define GST_TIME_TO_TIMESPEC(t,ts) \
200 (ts).tv_sec = (t) / GST_SECOND; \
201 (ts).tv_nsec = ((t) - (ts).tv_sec * GST_SECOND) / GST_NSECOND; \
204 /* timestamp debugging macros */
208 * A format that can be used in printf like format strings to format
209 * a #GstClockTime value.
211 #define GST_TIME_FORMAT "u:%02u:%02u.%09u"
214 * @t: a #GstClockTime
216 * Format @t for the GST_TIME_FORMAT format string.
218 #define GST_TIME_ARGS(t) \
219 GST_CLOCK_TIME_IS_VALID (t) ? \
220 (guint) (((GstClockTime)(t)) / (GST_SECOND * 60 * 60)) : 99, \
221 GST_CLOCK_TIME_IS_VALID (t) ? \
222 (guint) ((((GstClockTime)(t)) / (GST_SECOND * 60)) % 60) : 99, \
223 GST_CLOCK_TIME_IS_VALID (t) ? \
224 (guint) ((((GstClockTime)(t)) / GST_SECOND) % 60) : 99, \
225 GST_CLOCK_TIME_IS_VALID (t) ? \
226 (guint) (((GstClockTime)(t)) % GST_SECOND) : 999999999
229 * GST_CLOCK_ENTRY_TRACE_NAME:
231 * The name used for tracing clock entry allocations.
233 #define GST_CLOCK_ENTRY_TRACE_NAME "GstClockEntry"
235 typedef struct _GstClockEntry GstClockEntry;
236 typedef struct _GstClock GstClock;
237 typedef struct _GstClockClass GstClockClass;
238 typedef struct _GstClockPrivate GstClockPrivate;
240 /* --- prototype for async callbacks --- */
243 * @clock: The clock that triggered the callback
244 * @time: The time it was triggered
245 * @id: The #GstClockID that expired
246 * @user_data: user data passed in the gst_clock_id_wait_async() function
248 * The function prototype of the callback.
250 * Returns: %TRUE or %FALSE (currently unused)
252 typedef gboolean (*GstClockCallback) (GstClock *clock, GstClockTime time,
253 GstClockID id, gpointer user_data);
256 * @GST_CLOCK_OK: The operation succeeded.
257 * @GST_CLOCK_EARLY: The operation was scheduled too late.
258 * @GST_CLOCK_UNSCHEDULED: The clockID was unscheduled
259 * @GST_CLOCK_BUSY: The ClockID is busy
260 * @GST_CLOCK_BADTIME: A bad time was provided to a function.
261 * @GST_CLOCK_ERROR: An error occurred
262 * @GST_CLOCK_UNSUPPORTED: Operation is not supported
263 * @GST_CLOCK_DONE: The ClockID is done waiting (Since: 0.10.32)
265 * The return value of a clock operation.
271 GST_CLOCK_UNSCHEDULED = 2,
273 GST_CLOCK_BADTIME = 4,
275 GST_CLOCK_UNSUPPORTED = 6,
281 * @GST_CLOCK_ENTRY_SINGLE: a single shot timeout
282 * @GST_CLOCK_ENTRY_PERIODIC: a periodic timeout request
284 * The type of the clock entry
287 GST_CLOCK_ENTRY_SINGLE,
288 GST_CLOCK_ENTRY_PERIODIC
293 * @entry: the entry to cast
295 * Cast to a clock entry
297 #define GST_CLOCK_ENTRY(entry) ((GstClockEntry *)(entry))
299 * GST_CLOCK_ENTRY_CLOCK:
300 * @entry: the entry to query
302 * Get the owner clock of the entry
304 #define GST_CLOCK_ENTRY_CLOCK(entry) ((entry)->clock)
306 * GST_CLOCK_ENTRY_TYPE:
307 * @entry: the entry to query
309 * Get the type of the clock entry
311 #define GST_CLOCK_ENTRY_TYPE(entry) ((entry)->type)
313 * GST_CLOCK_ENTRY_TIME:
314 * @entry: the entry to query
316 * Get the requested time of this entry
318 #define GST_CLOCK_ENTRY_TIME(entry) ((entry)->time)
320 * GST_CLOCK_ENTRY_INTERVAL:
321 * @entry: the entry to query
323 * Get the interval of this periodic entry
325 #define GST_CLOCK_ENTRY_INTERVAL(entry) ((entry)->interval)
327 * GST_CLOCK_ENTRY_STATUS:
328 * @entry: the entry to query
330 * The status of the entry
332 #define GST_CLOCK_ENTRY_STATUS(entry) ((entry)->status)
336 * @refcount: reference counter (read-only)
338 * All pending timeouts or periodic notifies are converted into
340 * Note that GstClockEntry should be treated as an opaque structure. It must
341 * not be extended or allocated using a custom allocator.
343 struct _GstClockEntry {
347 GstClockEntryType type;
349 GstClockTime interval;
350 GstClockReturn status;
351 GstClockCallback func;
353 GDestroyNotify destroy_data;
354 gboolean unscheduled;
360 * @GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC: clock can do a single sync timeout request
361 * @GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC: clock can do a single async timeout request
362 * @GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC: clock can do sync periodic timeout requests
363 * @GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC: clock can do async periodic timeout callbacks
364 * @GST_CLOCK_FLAG_CAN_SET_RESOLUTION: clock's resolution can be changed
365 * @GST_CLOCK_FLAG_CAN_SET_MASTER: clock can be slaved to a master clock
366 * @GST_CLOCK_FLAG_LAST: subclasses can add additional flags starting from this flag
368 * The capabilities of this clock
371 GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC = (GST_OBJECT_FLAG_LAST << 0),
372 GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC = (GST_OBJECT_FLAG_LAST << 1),
373 GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC = (GST_OBJECT_FLAG_LAST << 2),
374 GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC = (GST_OBJECT_FLAG_LAST << 3),
375 GST_CLOCK_FLAG_CAN_SET_RESOLUTION = (GST_OBJECT_FLAG_LAST << 4),
376 GST_CLOCK_FLAG_CAN_SET_MASTER = (GST_OBJECT_FLAG_LAST << 5),
378 GST_CLOCK_FLAG_LAST = (GST_OBJECT_FLAG_LAST << 8)
383 * @clock: the clock to query
385 * Gets the #GstClockFlags clock flags.
387 #define GST_CLOCK_FLAGS(clock) GST_OBJECT_FLAGS(clock)
391 * @clock: the clock to query
393 * Gets the #GCond that gets signalled when the entries of the clock
396 #define GST_CLOCK_COND(clock) (GST_CLOCK_CAST(clock)->entries_changed)
399 * @clock: the clock to wait on
401 * Wait on the clock until the entries changed.
403 #define GST_CLOCK_WAIT(clock) g_cond_wait(GST_CLOCK_COND(clock),GST_OBJECT_GET_LOCK(clock))
405 * GST_CLOCK_TIMED_WAIT:
406 * @clock: the clock to wait on
407 * @tv: a #GTimeVal to wait.
409 * Wait on the clock until the entries changed or the specified timeout
412 #define GST_CLOCK_TIMED_WAIT(clock,tv) g_cond_timed_wait(GST_CLOCK_COND(clock),GST_OBJECT_GET_LOCK(clock),tv)
414 * GST_CLOCK_BROADCAST:
415 * @clock: the clock to broadcast
417 * Signal that the entries in the clock have changed.
419 #define GST_CLOCK_BROADCAST(clock) g_cond_broadcast(GST_CLOCK_COND(clock))
424 * #GstClock base structure. The values of this structure are
425 * protected for subclasses, use the methods to use the #GstClock.
430 GMutex *slave_lock; /* order: SLAVE_LOCK, OBJECT_LOCK */
432 /*< protected >*/ /* with LOCK */
433 GstClockTime internal_calibration;
434 GstClockTime external_calibration;
435 GstClockTime rate_numerator;
436 GstClockTime rate_denominator;
437 GstClockTime last_time;
439 GCond *entries_changed;
441 /*< private >*/ /* with LOCK */
442 GstClockTime resolution;
445 /* for master/slave clocks */
448 /* with SLAVE_LOCK */
451 gint window_threshold;
453 GstClockTime timeout;
459 GstClockPrivate *priv;
460 GstClockTime _gst_reserved[GST_PADDING];
466 * @parent_class: the parent class structure
467 * @change_resolution: change the resolution of the clock. Not all values might
468 * be acceptable. The new resolution should be returned.
469 * @get_resolution: get the resolution of the clock.
470 * @get_internal_time: get the internal unadjusted time of the clock.
471 * @wait: perform a blocking wait for the given #GstClockEntry. Deprecated,
472 * implement @wait_jitter instead.
473 * @wait_async: perform an asynchronous wait for the given #GstClockEntry.
474 * @unschedule: unblock a blocking or async wait operation.
475 * @wait_jitter: perform a blocking wait on the given #GstClockEntry and return
476 * the jitter. (Since: 0.10.10)
478 * GStreamer clock class. Override the vmethods to implement the clock
481 struct _GstClockClass {
482 GstObjectClass parent_class;
486 GstClockTime (*change_resolution) (GstClock *clock,
487 GstClockTime old_resolution,
488 GstClockTime new_resolution);
489 GstClockTime (*get_resolution) (GstClock *clock);
491 GstClockTime (*get_internal_time) (GstClock *clock);
493 /* waiting on an ID */
494 GstClockReturn (*wait) (GstClock *clock, GstClockEntry *entry);
495 GstClockReturn (*wait_async) (GstClock *clock, GstClockEntry *entry);
496 void (*unschedule) (GstClock *clock, GstClockEntry *entry);
498 /* ABI added to replace the deprecated wait */
499 GstClockReturn (*wait_jitter) (GstClock *clock, GstClockEntry *entry,
500 GstClockTimeDiff *jitter);
502 gpointer _gst_reserved[GST_PADDING - 1];
505 GType gst_clock_get_type (void);
507 GstClockTime gst_clock_set_resolution (GstClock *clock,
508 GstClockTime resolution);
509 GstClockTime gst_clock_get_resolution (GstClock *clock);
511 GstClockTime gst_clock_get_time (GstClock *clock);
512 void gst_clock_set_calibration (GstClock *clock, GstClockTime internal,
513 GstClockTime external,
514 GstClockTime rate_num,
515 GstClockTime rate_denom);
516 void gst_clock_get_calibration (GstClock *clock, GstClockTime *internal,
517 GstClockTime *external,
518 GstClockTime *rate_num,
519 GstClockTime *rate_denom);
521 /* master/slave clocks */
522 gboolean gst_clock_set_master (GstClock *clock, GstClock *master);
523 GstClock* gst_clock_get_master (GstClock *clock);
524 gboolean gst_clock_add_observation (GstClock *clock, GstClockTime slave,
525 GstClockTime master, gdouble *r_squared);
528 /* getting and adjusting internal/external time */
529 GstClockTime gst_clock_get_internal_time (GstClock *clock);
530 GstClockTime gst_clock_adjust_unlocked (GstClock *clock, GstClockTime internal);
531 GstClockTime gst_clock_unadjust_unlocked (GstClock * clock, GstClockTime external);
534 /* creating IDs that can be used to get notifications */
535 GstClockID gst_clock_new_single_shot_id (GstClock *clock,
537 GstClockID gst_clock_new_periodic_id (GstClock *clock,
538 GstClockTime start_time,
539 GstClockTime interval);
541 /* reference counting */
542 GstClockID gst_clock_id_ref (GstClockID id);
543 void gst_clock_id_unref (GstClockID id);
545 /* operations on IDs */
546 gint gst_clock_id_compare_func (gconstpointer id1, gconstpointer id2);
548 GstClockTime gst_clock_id_get_time (GstClockID id);
549 GstClockReturn gst_clock_id_wait (GstClockID id,
550 GstClockTimeDiff *jitter);
551 GstClockReturn gst_clock_id_wait_async (GstClockID id,
552 GstClockCallback func,
554 GstClockReturn gst_clock_id_wait_async_full (GstClockID id,
555 GstClockCallback func,
557 GDestroyNotify destroy_data);
558 void gst_clock_id_unschedule (GstClockID id);
560 gboolean gst_clock_single_shot_id_reinit (GstClock * clock,
563 gboolean gst_clock_periodic_id_reinit (GstClock * clock,
565 GstClockTime start_time,
566 GstClockTime interval);
570 #endif /* __GST_CLOCK_H__ */