2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
3 * 2000 Wim Taymans <wtay@chello.be>
5 * gstclock.h: Header for clock subsystem
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.
23 #ifndef __GST_CLOCK_H__
24 #define __GST_CLOCK_H__
26 #include <gst/gstobject.h>
30 /* --- standard type macros --- */
31 #define GST_TYPE_CLOCK (gst_clock_get_type ())
32 #define GST_CLOCK(clock) (G_TYPE_CHECK_INSTANCE_CAST ((clock), GST_TYPE_CLOCK, GstClock))
33 #define GST_IS_CLOCK(clock) (G_TYPE_CHECK_INSTANCE_TYPE ((clock), GST_TYPE_CLOCK))
34 #define GST_CLOCK_CLASS(cclass) (G_TYPE_CHECK_CLASS_CAST ((cclass), GST_TYPE_CLOCK, GstClockClass))
35 #define GST_IS_CLOCK_CLASS(cclass) (G_TYPE_CHECK_CLASS_TYPE ((cclass), GST_TYPE_CLOCK))
36 #define GST_CLOCK_GET_CLASS(clock) (G_TYPE_INSTANCE_GET_CLASS ((clock), GST_TYPE_CLOCK, GstClockClass))
37 #define GST_CLOCK_CAST(clock) ((GstClock*)(clock))
42 * A datatype to hold a time, measured in nanoseconds.
44 typedef guint64 GstClockTime;
46 #define GST_TYPE_CLOCK_TIME G_TYPE_UINT64
51 * A datatype to hold a timedifference, measured in nanoseconds.
53 typedef gint64 GstClockTimeDiff;
57 * A detatype to hold the handle to an outstanding async clock callback
59 typedef gpointer GstClockID;
62 * GST_CLOCK_TIME_NONE:
64 * Constant to define an undefined clock time
66 #define GST_CLOCK_TIME_NONE ((GstClockTime) -1)
68 * GST_CLOCK_TIME_IS_VALID:
69 * @time: clock time to validate
71 * Tests if a given #GstClockTime represents a valid defined time.
73 #define GST_CLOCK_TIME_IS_VALID(time) ((time) != GST_CLOCK_TIME_NONE)
78 * Constant that defines one GStreamer second
80 #define GST_SECOND (G_USEC_PER_SEC * G_GINT64_CONSTANT (1000))
84 * Constant that defines one GStreamer millisecond
86 #define GST_MSECOND (GST_SECOND / G_GINT64_CONSTANT (1000))
90 * Constant that defines one GStreamer microsecond
92 #define GST_USECOND (GST_SECOND / G_GINT64_CONSTANT (1000000))
96 * Constant that defines one GStreamer nanosecond
98 #define GST_NSECOND (GST_SECOND / G_GINT64_CONSTANT (1000000000))
103 * @e: the second time
105 * Calculate a difference between two clock times as a #GstClockTimeDiff.
107 #define GST_CLOCK_DIFF(s, e) (GstClockTimeDiff)((e) - (s))
110 * GST_TIMEVAL_TO_TIME:
111 * @tv: the timeval to convert
113 * Convert a GTimeVal to a #GstClockTime.
115 #define GST_TIMEVAL_TO_TIME(tv) ((tv).tv_sec * GST_SECOND + (tv).tv_usec * GST_USECOND)
117 * GST_TIME_TO_TIMEVAL:
118 * @t: The GstClockTime to convert
119 * @tv: The target timeval
121 * Convert a GstClockTime to a GTimeVal
123 #define GST_TIME_TO_TIMEVAL(t,tv) \
125 (tv).tv_sec = (t) / GST_SECOND; \
126 (tv).tv_usec = ((t) - (tv).tv_sec * GST_SECOND) / GST_USECOND; \
130 * GST_TIMESPEC_TO_TIME:
131 * @ts: the timespec to convert
133 * Convert a struct timespec (see man pselect) to a #GstClockTime.
135 #define GST_TIMESPEC_TO_TIME(ts) ((ts).tv_sec * GST_SECOND + (ts).tv_nsec * GST_NSECOND)
137 * GST_TIME_TO_TIMESPEC:
138 * @t: The GstClockTime to convert
139 * @ts: The target timespec
141 * Convert a #GstClockTime to a struct timespec (see man pselect)
143 #define GST_TIME_TO_TIMESPEC(t,ts) \
145 (ts).tv_sec = (t) / GST_SECOND; \
146 (ts).tv_nsec = ((t) - (ts).tv_sec * GST_SECOND) / GST_NSECOND; \
149 /* timestamp debugging macros */
150 #define GST_TIME_FORMAT "u:%02u:%02u.%09u"
151 #define GST_TIME_ARGS(t) \
152 (guint) (((GstClockTime)(t)) / (GST_SECOND * 60 * 60)), \
153 (guint) ((((GstClockTime)(t)) / (GST_SECOND * 60)) % 60), \
154 (guint) ((((GstClockTime)(t)) / GST_SECOND) % 60), \
155 (guint) (((GstClockTime)(t)) % GST_SECOND)
158 * GST_CLOCK_ENTRY_TRACE_NAME:
160 * The name used for tracing clock entry allocations.
162 #define GST_CLOCK_ENTRY_TRACE_NAME "GstClockEntry"
164 typedef struct _GstClockEntry GstClockEntry;
165 typedef struct _GstClock GstClock;
166 typedef struct _GstClockClass GstClockClass;
168 /* --- prototype for async callbacks --- */
171 * @clock: The clock that triggered the callback
172 * @time: The time it was triggered
173 * @id: The #GstClockID that expired
174 * @user_data: user data passed in the async_wait call
176 * The function prototype of the callback.
178 * Returns: %TRUE or %FALSE (currently unused)
180 typedef gboolean (*GstClockCallback) (GstClock *clock, GstClockTime time,
181 GstClockID id, gpointer user_data);
184 * @GST_CLOCK_OK: The operation succeded.
185 * @GST_CLOCK_EARLY: The operation was scheduled too late.
186 * @GST_CLOCK_UNSCHEDULED: The clockID was unscheduled
187 * @GST_CLOCK_BUSY: The ClockID is busy
188 * @GST_CLOCK_BADTIME: A bad time was provided to a function.
189 * @GST_CLOCK_ERROR: An error occured
190 * @GST_CLOCK_UNSUPPORTED: Operation is not supported
192 * The return value of a clock operation.
198 GST_CLOCK_UNSCHEDULED = 2,
200 GST_CLOCK_BADTIME = 4,
202 GST_CLOCK_UNSUPPORTED = 6,
207 * @GST_CLOCK_ENTRY_SINGLE: a single shot timeout
208 * @GST_CLOCK_ENTRY_PERIODIC: a periodic timeout request
210 * The type of the clock entry
213 GST_CLOCK_ENTRY_SINGLE,
214 GST_CLOCK_ENTRY_PERIODIC
219 * @entry: the entry to cast
221 * Cast to a clock entry
223 #define GST_CLOCK_ENTRY(entry) ((GstClockEntry *)(entry))
225 * GST_CLOCK_ENTRY_CLOCK:
226 * @entry: the entry to query
228 * Get the owner clock of the entry
230 #define GST_CLOCK_ENTRY_CLOCK(entry) ((entry)->clock)
232 * GST_CLOCK_ENTRY_TYPE:
233 * @entry: the entry to query
235 * Get the type of the clock entry
237 #define GST_CLOCK_ENTRY_TYPE(entry) ((entry)->type)
239 * GST_CLOCK_ENTRY_TIME:
240 * @entry: the entry to query
242 * Get the requested time of this entry
244 #define GST_CLOCK_ENTRY_TIME(entry) ((entry)->time)
246 * GST_CLOCK_ENTRY_INTERVAL:
247 * @entry: the entry to query
249 * Get the interval of this periodic entry
251 #define GST_CLOCK_ENTRY_INTERVAL(entry) ((entry)->interval)
253 * GST_CLOCK_ENTRY_STATUS:
254 * @entry: the entry to query
256 * The status of the entry
258 #define GST_CLOCK_ENTRY_STATUS(entry) ((entry)->status)
262 * @refcount: reference counter (read-only)
264 * All pending timeouts or periodic notifies are converted into
267 struct _GstClockEntry {
271 GstClockEntryType type;
273 GstClockTime interval;
274 GstClockReturn status;
275 GstClockCallback func;
281 * @GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC: clock can do a single sync timeout request
282 * @GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC: clock can do a single async timeout request
283 * @GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC: clock can do sync periodic timeout requests
284 * @GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC: clock can do async periodic timeout callbacks
285 * @GST_CLOCK_FLAG_CAN_SET_RESOLUTION: clock's resolution can be changed
287 * The capabilities of this clock
290 GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC = (1 << 1),
291 GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC = (1 << 2),
292 GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC = (1 << 3),
293 GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC = (1 << 4),
294 GST_CLOCK_FLAG_CAN_SET_RESOLUTION = (1 << 5),
299 * @clock: the clock to query
301 * Gets the #GstClockFlags clock flags.
303 #define GST_CLOCK_FLAGS(clock) (GST_CLOCK(clock)->flags)
305 #define GST_CLOCK_COND(clock) (GST_CLOCK_CAST(clock)->entries_changed)
306 #define GST_CLOCK_WAIT(clock) g_cond_wait(GST_CLOCK_COND(clock),GST_GET_LOCK(clock))
307 #define GST_CLOCK_TIMED_WAIT(clock,tv) g_cond_timed_wait(GST_CLOCK_COND(clock),GST_GET_LOCK(clock),tv)
308 #define GST_CLOCK_BROADCAST(clock) g_cond_broadcast(GST_CLOCK_COND(clock))
316 /*< protected >*/ /* with LOCK */
318 GstClockTime last_time;
320 GCond *entries_changed;
326 gpointer _gst_reserved[GST_PADDING];
329 struct _GstClockClass {
330 GstObjectClass parent_class;
334 guint64 (*change_resolution) (GstClock *clock, guint64 old_resolution,
335 guint64 new_resolution);
336 guint64 (*get_resolution) (GstClock *clock);
338 GstClockTime (*get_internal_time) (GstClock *clock);
340 /* waiting on an ID */
341 GstClockReturn (*wait) (GstClock *clock, GstClockEntry *entry);
342 GstClockReturn (*wait_async) (GstClock *clock, GstClockEntry *entry);
343 void (*unschedule) (GstClock *clock, GstClockEntry *entry);
346 gpointer _gst_reserved[GST_PADDING];
349 GType gst_clock_get_type (void);
351 guint64 gst_clock_set_resolution (GstClock *clock, guint64 resolution);
352 guint64 gst_clock_get_resolution (GstClock *clock);
354 GstClockTime gst_clock_get_time (GstClock *clock);
355 void gst_clock_set_time_adjust (GstClock *clock, GstClockTime adjust);
357 GstClockTime gst_clock_adjust_unlocked (GstClock *clock, GstClockTime internal);
360 /* creating IDs that can be used to get notifications */
361 GstClockID gst_clock_new_single_shot_id (GstClock *clock,
363 GstClockID gst_clock_new_periodic_id (GstClock *clock,
364 GstClockTime start_time,
365 GstClockTime interval);
367 /* reference counting */
368 GstClockID gst_clock_id_ref (GstClockID id);
369 void gst_clock_id_unref (GstClockID id);
371 /* operations on IDs */
372 gint gst_clock_id_compare_func (gconstpointer id1, gconstpointer id2);
374 GstClockTime gst_clock_id_get_time (GstClockID id);
375 GstClockReturn gst_clock_id_wait (GstClockID id,
376 GstClockTimeDiff *jitter);
377 GstClockReturn gst_clock_id_wait_async (GstClockID id,
378 GstClockCallback func,
380 void gst_clock_id_unschedule (GstClockID id);
384 #endif /* __GST_CLOCK_H__ */