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., 51 Franklin St, Fifth Floor,
21 * Boston, MA 02110-1301, USA.
24 #ifndef __GST_CLOCK_H__
25 #define __GST_CLOCK_H__
27 #include <gst/gstconfig.h>
32 /* --- standard type macros --- */
33 #define GST_TYPE_CLOCK (gst_clock_get_type ())
34 #define GST_CLOCK(clock) (G_TYPE_CHECK_INSTANCE_CAST ((clock), GST_TYPE_CLOCK, GstClock))
35 #define GST_IS_CLOCK(clock) (G_TYPE_CHECK_INSTANCE_TYPE ((clock), GST_TYPE_CLOCK))
36 #define GST_CLOCK_CLASS(cclass) (G_TYPE_CHECK_CLASS_CAST ((cclass), GST_TYPE_CLOCK, GstClockClass))
37 #define GST_IS_CLOCK_CLASS(cclass) (G_TYPE_CHECK_CLASS_TYPE ((cclass), GST_TYPE_CLOCK))
38 #define GST_CLOCK_GET_CLASS(clock) (G_TYPE_INSTANCE_GET_CLASS ((clock), GST_TYPE_CLOCK, GstClockClass))
39 #define GST_CLOCK_CAST(clock) ((GstClock*)(clock))
44 * A datatype to hold a time, measured in nanoseconds.
46 typedef guint64 GstClockTime;
49 * GST_TYPE_CLOCK_TIME:
51 * The #GType of a #GstClockTime.
53 #define GST_TYPE_CLOCK_TIME G_TYPE_UINT64
58 * A datatype to hold a time difference, measured in nanoseconds.
60 typedef gint64 GstClockTimeDiff;
64 * A datatype to hold the handle to an outstanding sync or async clock callback.
66 typedef gpointer GstClockID;
69 * GST_CLOCK_TIME_NONE: (value 18446744073709551615) (type GstClockTime)
71 * Constant to define an undefined clock time.
73 #define GST_CLOCK_TIME_NONE ((GstClockTime) -1)
75 * GST_CLOCK_TIME_IS_VALID:
76 * @time: clock time to validate
78 * Tests if a given #GstClockTime represents a valid defined time.
80 #define GST_CLOCK_TIME_IS_VALID(time) (((GstClockTime)(time)) != GST_CLOCK_TIME_NONE)
83 * GST_CLOCK_STIME_NONE: (value -9223372036854775808) (type GstClockTimeDiff)
85 * Constant to define an undefined clock time.
87 #define GST_CLOCK_STIME_NONE ((GstClockTimeDiff)G_MININT64)
89 * GST_CLOCK_STIME_IS_VALID:
90 * @time: signed clock time to validate
92 * Tests if a given #GstClockTimeDiff of #gint64 represents a valid defined time.
96 #define GST_CLOCK_STIME_IS_VALID(time) (((GstClockTimeDiff)(time)) != GST_CLOCK_STIME_NONE)
99 * GST_SECOND: (value 1000000000) (type GstClockTimeDiff)
101 * Constant that defines one GStreamer second.
103 #define GST_SECOND ((GstClockTimeDiff)(G_USEC_PER_SEC * G_GINT64_CONSTANT (1000)))
105 * GST_MSECOND: (value 1000000) (type GstClockTimeDiff)
107 * Constant that defines one GStreamer millisecond.
109 #define GST_MSECOND ((GstClockTimeDiff)(GST_SECOND / G_GINT64_CONSTANT (1000)))
111 * GST_USECOND: (value 1000) (type GstClockTimeDiff)
113 * Constant that defines one GStreamer microsecond.
115 #define GST_USECOND ((GstClockTimeDiff)(GST_SECOND / G_GINT64_CONSTANT (1000000)))
117 * GST_NSECOND: (value 1) (type GstClockTimeDiff)
119 * Constant that defines one GStreamer nanosecond
121 #define GST_NSECOND ((GstClockTimeDiff)(GST_SECOND / G_GINT64_CONSTANT (1000000000)))
125 * GST_TIME_AS_SECONDS:
128 * Convert a #GstClockTime to seconds.
130 #define GST_TIME_AS_SECONDS(time) ((time) / GST_SECOND)
132 * GST_TIME_AS_MSECONDS:
135 * Convert a #GstClockTime to milliseconds (1/1000 of a second).
137 #define GST_TIME_AS_MSECONDS(time) ((time) / G_GINT64_CONSTANT (1000000))
139 * GST_TIME_AS_USECONDS:
142 * Convert a #GstClockTime to microseconds (1/1000000 of a second).
144 #define GST_TIME_AS_USECONDS(time) ((time) / G_GINT64_CONSTANT (1000))
146 * GST_TIME_AS_NSECONDS:
149 * Convert a #GstClockTime to nanoseconds (1/1000000000 of a second).
151 #define GST_TIME_AS_NSECONDS(time) (time)
156 * @e: the second time
158 * Calculate a difference between two clock times as a #GstClockTimeDiff.
159 * The difference is calculated as @e - @s.
161 #define GST_CLOCK_DIFF(s, e) (GstClockTimeDiff)((e) - (s))
164 * GST_TIMEVAL_TO_TIME:
165 * @tv: the timeval to convert
167 * Convert a #GTimeVal to a #GstClockTime.
169 #define GST_TIMEVAL_TO_TIME(tv) (GstClockTime)((tv).tv_sec * GST_SECOND + (tv).tv_usec * GST_USECOND)
172 * GST_TIME_TO_TIMEVAL:
173 * @t: The #GstClockTime to convert
174 * @tv: The target timeval
176 * Convert a #GstClockTime to a #GTimeVal
178 * > on 32-bit systems, a timeval has a range of only 2^32 - 1 seconds,
179 * > which is about 68 years. Expect trouble if you want to schedule stuff
180 * > in your pipeline for 2038.
182 #define GST_TIME_TO_TIMEVAL(t,tv) \
184 g_assert ("Value of time " #t " is out of timeval's range" && \
185 ((t) / GST_SECOND) < G_MAXLONG); \
186 (tv).tv_sec = (glong) (((GstClockTime) (t)) / GST_SECOND); \
187 (tv).tv_usec = (glong) ((((GstClockTime) (t)) - \
188 ((GstClockTime) (tv).tv_sec) * GST_SECOND) \
193 * GST_TIMESPEC_TO_TIME:
194 * @ts: the timespec to convert
196 * Convert a struct timespec (see man pselect) to a #GstClockTime.
198 #define GST_TIMESPEC_TO_TIME(ts) (GstClockTime)((ts).tv_sec * GST_SECOND + (ts).tv_nsec * GST_NSECOND)
200 * GST_TIME_TO_TIMESPEC:
201 * @t: The #GstClockTime to convert
202 * @ts: The target timespec
204 * Convert a #GstClockTime to a struct timespec (see man pselect)
206 #define GST_TIME_TO_TIMESPEC(t,ts) \
208 g_assert ("Value of time " #t " is out of timespec's range" && \
209 ((t) / GST_SECOND) < G_MAXLONG); \
210 (ts).tv_sec = (glong) ((t) / GST_SECOND); \
211 (ts).tv_nsec = (glong) (((t) - (ts).tv_sec * GST_SECOND) / GST_NSECOND); \
214 /* timestamp debugging macros */
216 * GST_TIME_FORMAT: (skip):
218 * A string that can be used in printf-like format strings to display a
219 * #GstClockTime value in h:m:s format. Use GST_TIME_ARGS() to construct
220 * the matching arguments.
223 * |[<!-- language="C" -->
224 * printf("%" GST_TIME_FORMAT "\n", GST_TIME_ARGS(ts));
227 #define GST_TIME_FORMAT "u:%02u:%02u.%09u"
229 * GST_TIME_ARGS: (skip):
230 * @t: a #GstClockTime
232 * Format @t for the #GST_TIME_FORMAT format string. Note: @t will be
233 * evaluated more than once.
235 #define GST_TIME_ARGS(t) \
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)) % 60) : 99, \
240 GST_CLOCK_TIME_IS_VALID (t) ? \
241 (guint) ((((GstClockTime)(t)) / GST_SECOND) % 60) : 99, \
242 GST_CLOCK_TIME_IS_VALID (t) ? \
243 (guint) (((GstClockTime)(t)) % GST_SECOND) : 999999999
245 * GST_STIME_FORMAT: (skip):
247 * A string that can be used in printf-like format strings to display a signed
248 * #GstClockTimeDiff or #gint64 value in h:m:s format. Use GST_TIME_ARGS() to
249 * construct the matching arguments.
253 * printf("%" GST_STIME_FORMAT "\n", GST_STIME_ARGS(ts));
258 #define GST_STIME_FORMAT "c%" GST_TIME_FORMAT
260 * GST_STIME_ARGS: (skip):
261 * @t: a #GstClockTimeDiff or #gint64
263 * Format @t for the #GST_STIME_FORMAT format string. Note: @t will be
264 * evaluated more than once.
268 #define GST_STIME_ARGS(t) \
269 ((t) == GST_CLOCK_STIME_NONE || (t) >= 0) ? '+' : '-', \
270 GST_CLOCK_STIME_IS_VALID (t) ? \
271 (guint) (((GstClockTime)(ABS(t))) / (GST_SECOND * 60 * 60)) : 99, \
272 GST_CLOCK_STIME_IS_VALID (t) ? \
273 (guint) ((((GstClockTime)(ABS(t))) / (GST_SECOND * 60)) % 60) : 99, \
274 GST_CLOCK_STIME_IS_VALID (t) ? \
275 (guint) ((((GstClockTime)(ABS(t))) / GST_SECOND) % 60) : 99, \
276 GST_CLOCK_STIME_IS_VALID (t) ? \
277 (guint) (((GstClockTime)(ABS(t))) % GST_SECOND) : 999999999
279 typedef struct _GstClockEntry GstClockEntry;
280 typedef struct _GstClock GstClock;
281 typedef struct _GstClockClass GstClockClass;
282 typedef struct _GstClockPrivate GstClockPrivate;
284 /* --- prototype for async callbacks --- */
287 * @clock: The clock that triggered the callback
288 * @time: The time it was triggered
289 * @id: The #GstClockID that expired
290 * @user_data: user data passed in the gst_clock_id_wait_async() function
292 * The function prototype of the callback.
294 * Returns: %TRUE or %FALSE (currently unused)
296 typedef gboolean (*GstClockCallback) (GstClock *clock, GstClockTime time,
297 GstClockID id, gpointer user_data);
300 * @GST_CLOCK_OK: The operation succeeded.
301 * @GST_CLOCK_EARLY: The operation was scheduled too late.
302 * @GST_CLOCK_UNSCHEDULED: The clockID was unscheduled
303 * @GST_CLOCK_BUSY: The ClockID is busy
304 * @GST_CLOCK_BADTIME: A bad time was provided to a function.
305 * @GST_CLOCK_ERROR: An error occurred
306 * @GST_CLOCK_UNSUPPORTED: Operation is not supported
307 * @GST_CLOCK_DONE: The ClockID is done waiting
309 * The return value of a clock operation.
315 GST_CLOCK_UNSCHEDULED = 2,
317 GST_CLOCK_BADTIME = 4,
319 GST_CLOCK_UNSUPPORTED = 6,
325 * @GST_CLOCK_ENTRY_SINGLE: a single shot timeout
326 * @GST_CLOCK_ENTRY_PERIODIC: a periodic timeout request
328 * The type of the clock entry
331 GST_CLOCK_ENTRY_SINGLE,
332 GST_CLOCK_ENTRY_PERIODIC
337 * @entry: the entry to cast
339 * Cast to a clock entry
341 #define GST_CLOCK_ENTRY(entry) ((GstClockEntry *)(entry))
343 #ifndef GST_DISABLE_DEPRECATED
345 * GST_CLOCK_ENTRY_CLOCK:
346 * @entry: the entry to query
348 * Get the owner clock of the entry
350 * Deprecated: Use gst_clock_id_get_clock() instead.
352 #define GST_CLOCK_ENTRY_CLOCK(entry) ((entry)->clock)
355 * GST_CLOCK_ENTRY_TYPE:
356 * @entry: the entry to query
358 * Get the type of the clock entry
360 #define GST_CLOCK_ENTRY_TYPE(entry) ((entry)->type)
362 * GST_CLOCK_ENTRY_TIME:
363 * @entry: the entry to query
365 * Get the requested time of this entry
367 #define GST_CLOCK_ENTRY_TIME(entry) ((entry)->time)
369 * GST_CLOCK_ENTRY_INTERVAL:
370 * @entry: the entry to query
372 * Get the interval of this periodic entry
374 #define GST_CLOCK_ENTRY_INTERVAL(entry) ((entry)->interval)
376 * GST_CLOCK_ENTRY_STATUS:
377 * @entry: the entry to query
379 * The status of the entry
381 #define GST_CLOCK_ENTRY_STATUS(entry) ((entry)->status)
385 * @refcount: reference counter (read-only)
387 * All pending timeouts or periodic notifies are converted into
389 * Note that GstClockEntry should be treated as an opaque structure. It must
390 * not be extended or allocated using a custom allocator.
392 struct _GstClockEntry {
395 #ifndef GST_REMOVE_DEPRECATED
396 #ifndef GST_DISABLE_DEPRECATED
402 GstClockEntryType type;
404 GstClockTime interval;
405 GstClockReturn status;
406 GstClockCallback func;
408 GDestroyNotify destroy_data;
409 gboolean unscheduled;
413 gpointer _gst_reserved[GST_PADDING];
416 #include <gst/gstobject.h>
420 * @GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC: clock can do a single sync timeout request
421 * @GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC: clock can do a single async timeout request
422 * @GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC: clock can do sync periodic timeout requests
423 * @GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC: clock can do async periodic timeout callbacks
424 * @GST_CLOCK_FLAG_CAN_SET_RESOLUTION: clock's resolution can be changed
425 * @GST_CLOCK_FLAG_CAN_SET_MASTER: clock can be slaved to a master clock
426 * @GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC: clock needs to be synced before it can be used
428 * @GST_CLOCK_FLAG_LAST: subclasses can add additional flags starting from this flag
430 * The capabilities of this clock
433 GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC = (GST_OBJECT_FLAG_LAST << 0),
434 GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC = (GST_OBJECT_FLAG_LAST << 1),
435 GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC = (GST_OBJECT_FLAG_LAST << 2),
436 GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC = (GST_OBJECT_FLAG_LAST << 3),
437 GST_CLOCK_FLAG_CAN_SET_RESOLUTION = (GST_OBJECT_FLAG_LAST << 4),
438 GST_CLOCK_FLAG_CAN_SET_MASTER = (GST_OBJECT_FLAG_LAST << 5),
439 GST_CLOCK_FLAG_NEEDS_STARTUP_SYNC = (GST_OBJECT_FLAG_LAST << 6),
441 GST_CLOCK_FLAG_LAST = (GST_OBJECT_FLAG_LAST << 8)
446 * @clock: the clock to query
448 * Gets the #GstClockFlags clock flags.
450 #define GST_CLOCK_FLAGS(clock) GST_OBJECT_FLAGS(clock)
455 * #GstClock base structure. The values of this structure are
456 * protected for subclasses, use the methods to use the #GstClock.
462 GstClockPrivate *priv;
464 gpointer _gst_reserved[GST_PADDING];
469 * @parent_class: the parent class structure
470 * @change_resolution: change the resolution of the clock. Not all values might
471 * be acceptable. The new resolution should be returned.
472 * @get_resolution: get the resolution of the clock.
473 * @get_internal_time: get the internal unadjusted time of the clock.
474 * implement @wait_jitter instead.
475 * @wait: perform a blocking wait on the given #GstClockEntry and return
477 * @wait_async: perform an asynchronous wait for the given #GstClockEntry.
478 * @unschedule: unblock a blocking or async wait operation.
480 * GStreamer clock class. Override the vmethods to implement the clock
483 struct _GstClockClass {
484 GstObjectClass parent_class;
488 GstClockTime (*change_resolution) (GstClock *clock,
489 GstClockTime old_resolution,
490 GstClockTime new_resolution);
491 GstClockTime (*get_resolution) (GstClock *clock);
493 GstClockTime (*get_internal_time) (GstClock *clock);
495 /* waiting on an ID */
496 GstClockReturn (*wait) (GstClock *clock, GstClockEntry *entry,
497 GstClockTimeDiff *jitter);
498 GstClockReturn (*wait_async) (GstClock *clock, GstClockEntry *entry);
499 void (*unschedule) (GstClock *clock, GstClockEntry *entry);
502 gpointer _gst_reserved[GST_PADDING];
506 GType gst_clock_get_type (void);
509 GstClockTime gst_clock_set_resolution (GstClock *clock,
510 GstClockTime resolution);
512 GstClockTime gst_clock_get_resolution (GstClock *clock);
515 GstClockTime gst_clock_get_time (GstClock *clock);
518 void gst_clock_set_calibration (GstClock *clock, GstClockTime internal,
519 GstClockTime external,
520 GstClockTime rate_num,
521 GstClockTime rate_denom);
523 void gst_clock_get_calibration (GstClock *clock, GstClockTime *internal,
524 GstClockTime *external,
525 GstClockTime *rate_num,
526 GstClockTime *rate_denom);
528 /* master/slave clocks */
531 gboolean gst_clock_set_master (GstClock *clock, GstClock *master);
534 GstClock* gst_clock_get_master (GstClock *clock);
537 void gst_clock_set_timeout (GstClock *clock,
538 GstClockTime timeout);
540 GstClockTime gst_clock_get_timeout (GstClock *clock);
543 gboolean gst_clock_add_observation (GstClock *clock, GstClockTime slave,
544 GstClockTime master, gdouble *r_squared);
546 gboolean gst_clock_add_observation_unapplied (GstClock *clock, GstClockTime slave,
547 GstClockTime master, gdouble *r_squared,
548 GstClockTime *internal,
549 GstClockTime *external,
550 GstClockTime *rate_num,
551 GstClockTime *rate_denom);
553 /* getting and adjusting internal/external time */
556 GstClockTime gst_clock_get_internal_time (GstClock *clock);
559 GstClockTime gst_clock_adjust_unlocked (GstClock *clock, GstClockTime internal);
562 GstClockTime gst_clock_adjust_with_calibration (GstClock *clock,
563 GstClockTime internal_target,
564 GstClockTime cinternal,
565 GstClockTime cexternal,
567 GstClockTime cdenom);
569 GstClockTime gst_clock_unadjust_with_calibration (GstClock *clock,
570 GstClockTime external_target,
571 GstClockTime cinternal,
572 GstClockTime cexternal,
574 GstClockTime cdenom);
576 GstClockTime gst_clock_unadjust_unlocked (GstClock * clock, GstClockTime external);
578 /* waiting for, signalling and checking for synchronization */
581 gboolean gst_clock_wait_for_sync (GstClock * clock, GstClockTime timeout);
584 gboolean gst_clock_is_synced (GstClock * clock);
586 /* to be used by subclasses only */
589 void gst_clock_set_synced (GstClock * clock, gboolean synced);
591 /* creating IDs that can be used to get notifications */
594 GstClockID gst_clock_new_single_shot_id (GstClock *clock,
597 GstClockID gst_clock_new_periodic_id (GstClock *clock,
598 GstClockTime start_time,
599 GstClockTime interval);
601 /* reference counting */
604 GstClockID gst_clock_id_ref (GstClockID id);
607 void gst_clock_id_unref (GstClockID id);
609 /* operations on IDs */
612 gint gst_clock_id_compare_func (gconstpointer id1, gconstpointer id2);
615 GstClock * gst_clock_id_get_clock (GstClockID id);
618 gboolean gst_clock_id_uses_clock (GstClockID id, GstClock * clock);
621 GstClockTime gst_clock_id_get_time (GstClockID id);
624 GstClockReturn gst_clock_id_wait (GstClockID id,
625 GstClockTimeDiff *jitter);
627 GstClockReturn gst_clock_id_wait_async (GstClockID id,
628 GstClockCallback func,
630 GDestroyNotify destroy_data);
632 void gst_clock_id_unschedule (GstClockID id);
635 gboolean gst_clock_single_shot_id_reinit (GstClock * clock,
639 gboolean gst_clock_periodic_id_reinit (GstClock * clock,
641 GstClockTime start_time,
642 GstClockTime interval);
644 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
645 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstClock, gst_object_unref)
650 #endif /* __GST_CLOCK_H__ */