gst/gstclock.h

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *
   5  * gstclock.h: Header for clock subsystem
   6  *
   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.
  11  *
  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.
  16  *
  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.
  21  */
  22
  23 #ifndef __GST_CLOCK_H__
  24 #define __GST_CLOCK_H__
  25
  26 #include <gst/gstobject.h>
  27
  28 G_BEGIN_DECLS
  29
  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))
  38
  39 /**
  40  * GstClockTime:
  41  *
  42  * A datatype to hold a time, measured in nanoseconds.
  43  */
  44 typedef guint64 GstClockTime;
  45
  46 #define GST_TYPE_CLOCK_TIME G_TYPE_UINT64
  47
  48 /**
  49  * GstClockTimeDiff:
  50  *
  51  * A datatype to hold a timedifference, measured in nanoseconds.
  52  */
  53 typedef gint64 GstClockTimeDiff;
  54 /**
  55  * GstClockID:
  56  *
  57  * A detatype to hold the handle to an outstanding async clock callback
  58  */
  59 typedef gpointer GstClockID;
  60
  61 /**
  62  * GST_CLOCK_TIME_NONE:
  63  *
  64  * Constant to define an undefined clock time
  65  */
  66 #define GST_CLOCK_TIME_NONE             ((GstClockTime) -1)
  67 /**
  68  * GST_CLOCK_TIME_IS_VALID:
  69  * @time: clock time to validate
  70  *
  71  * Tests if a given #GstClockTime represents a valid defined time.
  72  */
  73 #define GST_CLOCK_TIME_IS_VALID(time)   ((time) != GST_CLOCK_TIME_NONE)
  74
  75 /**
  76  * GST_SECOND:
  77  *
  78  * Constant that defines one GStreamer second
  79  */
  80 #define GST_SECOND  (G_USEC_PER_SEC * G_GINT64_CONSTANT (1000))
  81 /**
  82  * GST_MSECOND:
  83  *
  84  * Constant that defines one GStreamer millisecond
  85  */
  86 #define GST_MSECOND (GST_SECOND / G_GINT64_CONSTANT (1000))
  87 /**
  88  * GST_USECOND:
  89  *
  90  * Constant that defines one GStreamer microsecond
  91  */
  92 #define GST_USECOND (GST_SECOND / G_GINT64_CONSTANT (1000000))
  93 /**
  94  * GST_NSECOND:
  95  *
  96  * Constant that defines one GStreamer nanosecond
  97  */
  98 #define GST_NSECOND (GST_SECOND / G_GINT64_CONSTANT (1000000000))
  99
 100 /**
 101  * GST_CLOCK_DIFF:
 102  * @s: the first time
 103  * @e: the second time
 104  *
 105  * Calculate a difference between two clock times as a #GstClockTimeDiff.
 106  */
 107 #define GST_CLOCK_DIFF(s, e)            (GstClockTimeDiff)((e) - (s))
 108
 109 /**
 110  * GST_TIMEVAL_TO_TIME:
 111  * @tv: the timeval to convert
 112  *
 113  * Convert a GTimeVal to a #GstClockTime.
 114  */
 115 #define GST_TIMEVAL_TO_TIME(tv)         ((tv).tv_sec * GST_SECOND + (tv).tv_usec * GST_USECOND)
 116 /**
 117  * GST_TIME_TO_TIMEVAL:
 118  * @t: The GstClockTime to convert
 119  * @tv: The target timeval
 120  *
 121  * Convert a GstClockTime to a GTimeVal
 122  */
 123 #define GST_TIME_TO_TIMEVAL(t,tv)                       \
 124 G_STMT_START {                                          \
 125   (tv).tv_sec  =  (t) / GST_SECOND;                     \
 126   (tv).tv_usec = ((t) - (tv).tv_sec * GST_SECOND) / GST_USECOND;        \
 127 } G_STMT_END
 128
 129 /**
 130  * GST_TIMESPEC_TO_TIME:
 131  * @ts: the timespec to convert
 132  *
 133  * Convert a struct timespec (see man pselect) to a #GstClockTime.
 134  */
 135 #define GST_TIMESPEC_TO_TIME(ts)                ((ts).tv_sec * GST_SECOND + (ts).tv_nsec * GST_NSECOND)
 136 /**
 137  * GST_TIME_TO_TIMESPEC:
 138  * @t: The GstClockTime to convert
 139  * @ts: The target timespec
 140  *
 141  * Convert a #GstClockTime to a struct timespec (see man pselect)
 142  */
 143 #define GST_TIME_TO_TIMESPEC(t,ts)                      \
 144 G_STMT_START {                                          \
 145   (ts).tv_sec  =  (t) / GST_SECOND;                     \
 146   (ts).tv_nsec = ((t) - (ts).tv_sec * GST_SECOND) / GST_NSECOND;        \
 147 } G_STMT_END
 148
 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)
 156
 157 /**
 158  * GST_CLOCK_ENTRY_TRACE_NAME:
 159  *
 160  * The name used for tracing clock entry allocations.
 161  */
 162 #define GST_CLOCK_ENTRY_TRACE_NAME "GstClockEntry"
 163
 164 typedef struct _GstClockEntry   GstClockEntry;
 165 typedef struct _GstClock        GstClock;
 166 typedef struct _GstClockClass   GstClockClass;
 167
 168 /* --- prototype for async callbacks --- */
 169 /**
 170  * GstClockCallback:
 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
 175  *
 176  * The function prototype of the callback.
 177  *
 178  * Returns: %TRUE or %FALSE (currently unused)
 179  */
 180 typedef gboolean        (*GstClockCallback)     (GstClock *clock, GstClockTime time,
 181                                                  GstClockID id, gpointer user_data);
 182 /**
 183  * GstClockReturn:
 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
 191  *
 192  * The return value of a clock operation.
 193  */
 194 typedef enum
 195 {
 196   GST_CLOCK_OK          =  0,
 197   GST_CLOCK_EARLY       =  1,
 198   GST_CLOCK_UNSCHEDULED =  2,
 199   GST_CLOCK_BUSY        =  3,
 200   GST_CLOCK_BADTIME     =  4,
 201   GST_CLOCK_ERROR       =  5,
 202   GST_CLOCK_UNSUPPORTED =  6,
 203 } GstClockReturn;
 204
 205 /**
 206  * GstClockEntryType:
 207  * @GST_CLOCK_ENTRY_SINGLE: a single shot timeout
 208  * @GST_CLOCK_ENTRY_PERIODIC: a periodic timeout request
 209  *
 210  * The type of the clock entry
 211  */
 212 typedef enum {
 213   GST_CLOCK_ENTRY_SINGLE,
 214   GST_CLOCK_ENTRY_PERIODIC
 215 } GstClockEntryType;
 216
 217 /**
 218  * GST_CLOCK_ENTRY:
 219  * @entry: the entry to cast
 220  *
 221  * Cast to a clock entry
 222  */
 223 #define GST_CLOCK_ENTRY(entry)          ((GstClockEntry *)(entry))
 224 /**
 225  * GST_CLOCK_ENTRY_CLOCK:
 226  * @entry: the entry to query
 227  *
 228  * Get the owner clock of the entry
 229  */
 230 #define GST_CLOCK_ENTRY_CLOCK(entry)    ((entry)->clock)
 231 /**
 232  * GST_CLOCK_ENTRY_TYPE:
 233  * @entry: the entry to query
 234  *
 235  * Get the type of the clock entry
 236  */
 237 #define GST_CLOCK_ENTRY_TYPE(entry)     ((entry)->type)
 238 /**
 239  * GST_CLOCK_ENTRY_TIME:
 240  * @entry: the entry to query
 241  *
 242  * Get the requested time of this entry
 243  */
 244 #define GST_CLOCK_ENTRY_TIME(entry)     ((entry)->time)
 245 /**
 246  * GST_CLOCK_ENTRY_INTERVAL:
 247  * @entry: the entry to query
 248  *
 249  * Get the interval of this periodic entry
 250  */
 251 #define GST_CLOCK_ENTRY_INTERVAL(entry) ((entry)->interval)
 252 /**
 253  * GST_CLOCK_ENTRY_STATUS:
 254  * @entry: the entry to query
 255  *
 256  * The status of the entry
 257  */
 258 #define GST_CLOCK_ENTRY_STATUS(entry)   ((entry)->status)
 259
 260 /**
 261  * GstClockEntry:
 262  * @refcount: reference counter (read-only)
 263  *
 264  * All pending timeouts or periodic notifies are converted into
 265  * an entry.
 266  */
 267 struct _GstClockEntry {
 268   gint                  refcount;
 269   /*< protected >*/
 270   GstClock              *clock;
 271   GstClockEntryType      type;
 272   GstClockTime           time;
 273   GstClockTime           interval;
 274   GstClockReturn         status;
 275   GstClockCallback       func;
 276   gpointer               user_data;
 277 };
 278
 279 /**
 280  * GstClockFlags:
 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
 286  *
 287  * The capabilities of this clock
 288  */
 289 typedef enum {
 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),
 295 } GstClockFlags;
 296
 297 /**
 298  * GST_CLOCK_FLAGS:
 299  * @clock: the clock to query
 300  *
 301  * Gets the #GstClockFlags clock flags.
 302  */
 303 #define GST_CLOCK_FLAGS(clock)  (GST_CLOCK(clock)->flags)
 304
 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))
 309
 310 struct _GstClock {
 311   GstObject      object;
 312
 313   /*< public >*/
 314   GstClockFlags  flags;
 315
 316   /*< protected >*/ /* with LOCK */
 317   GstClockTime   adjust;
 318   GstClockTime   last_time;
 319   GList         *entries;
 320   GCond         *entries_changed;
 321
 322   /*< private >*/
 323   guint64        resolution;
 324   gboolean       stats;
 325
 326   gpointer _gst_reserved[GST_PADDING];
 327 };
 328
 329 struct _GstClockClass {
 330   GstObjectClass        parent_class;
 331
 332   /*< protected >*/
 333   /* vtable */
 334   guint64               (*change_resolution)    (GstClock *clock, guint64 old_resolution,
 335                                                  guint64 new_resolution);
 336   guint64               (*get_resolution)       (GstClock *clock);
 337
 338   GstClockTime          (*get_internal_time)    (GstClock *clock);
 339
 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);
 344
 345   /*< private >*/
 346   gpointer _gst_reserved[GST_PADDING];
 347 };
 348
 349 GType                   gst_clock_get_type              (void);
 350
 351 guint64                 gst_clock_set_resolution        (GstClock *clock, guint64 resolution);
 352 guint64                 gst_clock_get_resolution        (GstClock *clock);
 353
 354 GstClockTime            gst_clock_get_time              (GstClock *clock);
 355 void                    gst_clock_set_time_adjust       (GstClock *clock, GstClockTime adjust);
 356
 357 GstClockTime            gst_clock_adjust_unlocked       (GstClock *clock, GstClockTime internal);
 358
 359
 360 /* creating IDs that can be used to get notifications */
 361 GstClockID              gst_clock_new_single_shot_id    (GstClock *clock,
 362                                                          GstClockTime time);
 363 GstClockID              gst_clock_new_periodic_id       (GstClock *clock,
 364                                                          GstClockTime start_time,
 365                                                          GstClockTime interval);
 366
 367 /* reference counting */
 368 GstClockID              gst_clock_id_ref                (GstClockID id);
 369 void                    gst_clock_id_unref              (GstClockID id);
 370
 371 /* operations on IDs */
 372 gint                    gst_clock_id_compare_func       (gconstpointer id1, gconstpointer id2);
 373
 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,
 379                                                          gpointer user_data);
 380 void                    gst_clock_id_unschedule         (GstClockID id);
 381
 382 G_END_DECLS
 383
 384 #endif /* __GST_CLOCK_H__ */