gst/gstclock.h

   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  */
  23
  24 #ifndef __GST_CLOCK_H__
  25 #define __GST_CLOCK_H__
  26
  27 #include <gst/gstobject.h>
  28
  29 G_BEGIN_DECLS
  30
  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))
  39
  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)
  42
  43 /**
  44  * GstClockTime:
  45  *
  46  * A datatype to hold a time, measured in nanoseconds.
  47  */
  48 typedef guint64 GstClockTime;
  49
  50 /**
  51  * GST_TYPE_CLOCK_TIME:
  52  *
  53  * The GType of a GstClockTime.
  54  */
  55 #define GST_TYPE_CLOCK_TIME G_TYPE_UINT64
  56
  57 /**
  58  * GstClockTimeDiff:
  59  *
  60  * A datatype to hold a timedifference, 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;
  69
  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)
  83
  84 /**
  85  * GST_SECOND:
  86  *
  87  * Constant that defines one GStreamer second.
  88  */
  89 #define GST_SECOND  (G_USEC_PER_SEC * G_GINT64_CONSTANT (1000))
  90 /**
  91  * GST_MSECOND:
  92  *
  93  * Constant that defines one GStreamer millisecond.
  94  */
  95 #define GST_MSECOND (GST_SECOND / G_GINT64_CONSTANT (1000))
  96 /**
  97  * GST_USECOND:
  98  *
  99  * Constant that defines one GStreamer microsecond.
 100  */
 101 #define GST_USECOND (GST_SECOND / G_GINT64_CONSTANT (1000000))
 102 /**
 103  * GST_NSECOND:
 104  *
 105  * Constant that defines one GStreamer nanosecond
 106  */
 107 #define GST_NSECOND (GST_SECOND / G_GINT64_CONSTANT (1000000000))
 108
 109 /**
 110  * GST_CLOCK_DIFF:
 111  * @s: the first time
 112  * @e: the second time
 113  *
 114  * Calculate a difference between two clock times as a #GstClockTimeDiff.
 115  * The difference is calculated as @e - @s.
 116  */
 117 #define GST_CLOCK_DIFF(s, e)            (GstClockTimeDiff)((e) - (s))
 118
 119 /**
 120  * GST_TIMEVAL_TO_TIME:
 121  * @tv: the timeval to convert
 122  *
 123  * Convert a GTimeVal to a #GstClockTime.
 124  */
 125 #define GST_TIMEVAL_TO_TIME(tv)         ((tv).tv_sec * GST_SECOND + (tv).tv_usec * GST_USECOND)
 126
 127 /**
 128  * GST_TIME_TO_TIMEVAL:
 129  * @t: The GstClockTime to convert
 130  * @tv: The target timeval
 131  *
 132  * Note: on 32-bit systems, a timeval has a range of only 2^32 - 1 seconds,
 133  * which is about 68 years.  Expect trouble if you want to schedule stuff
 134  * in your pipeline for 2038.
 135  *
 136  * Convert a GstClockTime to a GTimeVal
 137  */
 138 #define GST_TIME_TO_TIMEVAL(t,tv)                               \
 139 G_STMT_START {                                                  \
 140   (tv).tv_sec  = ((GstClockTime) (t)) / GST_SECOND;             \
 141   (tv).tv_usec = (((GstClockTime) (t)) -                        \
 142                   ((GstClockTime) (tv).tv_sec) * GST_SECOND)    \
 143                  / GST_USECOND;                                 \
 144 } G_STMT_END
 145
 146 /**
 147  * GST_TIMESPEC_TO_TIME:
 148  * @ts: the timespec to convert
 149  *
 150  * Convert a struct timespec (see man pselect) to a #GstClockTime.
 151  */
 152 #define GST_TIMESPEC_TO_TIME(ts)                ((ts).tv_sec * GST_SECOND + (ts).tv_nsec * GST_NSECOND)
 153 /**
 154  * GST_TIME_TO_TIMESPEC:
 155  * @t: The GstClockTime to convert
 156  * @ts: The target timespec
 157  *
 158  * Convert a #GstClockTime to a struct timespec (see man pselect)
 159  */
 160 #define GST_TIME_TO_TIMESPEC(t,ts)                      \
 161 G_STMT_START {                                          \
 162   (ts).tv_sec  =  (t) / GST_SECOND;                     \
 163   (ts).tv_nsec = ((t) - (ts).tv_sec * GST_SECOND) / GST_NSECOND;        \
 164 } G_STMT_END
 165
 166 /* timestamp debugging macros */
 167 /**
 168  * GST_TIME_FORMAT:
 169  *
 170  * A format that can be used in printf like format strings to format
 171  * a GstClockTime value.
 172  */
 173 #define GST_TIME_FORMAT "u:%02u:%02u.%09u"
 174 /**
 175  * GST_TIME_ARGS:
 176  * @t: a #GstClockTime
 177  *
 178  * Format @t for the GST_TIME_FORMAT format string.
 179  */
 180 #define GST_TIME_ARGS(t) \
 181         GST_CLOCK_TIME_IS_VALID (t) ? \
 182         (guint) (((GstClockTime)(t)) / (GST_SECOND * 60 * 60)) : 99, \
 183         GST_CLOCK_TIME_IS_VALID (t) ? \
 184         (guint) ((((GstClockTime)(t)) / (GST_SECOND * 60)) % 60) : 99, \
 185         GST_CLOCK_TIME_IS_VALID (t) ? \
 186         (guint) ((((GstClockTime)(t)) / GST_SECOND) % 60) : 99, \
 187         GST_CLOCK_TIME_IS_VALID (t) ? \
 188         (guint) (((GstClockTime)(t)) % GST_SECOND) : 999999999
 189
 190 /**
 191  * GST_CLOCK_ENTRY_TRACE_NAME:
 192  *
 193  * The name used for tracing clock entry allocations.
 194  */
 195 #define GST_CLOCK_ENTRY_TRACE_NAME "GstClockEntry"
 196
 197 typedef struct _GstClockEntry   GstClockEntry;
 198 typedef struct _GstClock        GstClock;
 199 typedef struct _GstClockClass   GstClockClass;
 200
 201 /* --- prototype for async callbacks --- */
 202 /**
 203  * GstClockCallback:
 204  * @clock: The clock that triggered the callback
 205  * @time: The time it was triggered
 206  * @id: The #GstClockID that expired
 207  * @user_data: user data passed in the async_wait call
 208  *
 209  * The function prototype of the callback.
 210  *
 211  * Returns: %TRUE or %FALSE (currently unused)
 212  */
 213 typedef gboolean        (*GstClockCallback)     (GstClock *clock, GstClockTime time,
 214                                                  GstClockID id, gpointer user_data);
 215 /**
 216  * GstClockReturn:
 217  * @GST_CLOCK_OK: The operation succeded.
 218  * @GST_CLOCK_EARLY: The operation was scheduled too late.
 219  * @GST_CLOCK_UNSCHEDULED: The clockID was unscheduled
 220  * @GST_CLOCK_BUSY: The ClockID is busy
 221  * @GST_CLOCK_BADTIME: A bad time was provided to a function.
 222  * @GST_CLOCK_ERROR: An error occured
 223  * @GST_CLOCK_UNSUPPORTED: Operation is not supported
 224  *
 225  * The return value of a clock operation.
 226  */
 227 typedef enum
 228 {
 229   GST_CLOCK_OK          =  0,
 230   GST_CLOCK_EARLY       =  1,
 231   GST_CLOCK_UNSCHEDULED =  2,
 232   GST_CLOCK_BUSY        =  3,
 233   GST_CLOCK_BADTIME     =  4,
 234   GST_CLOCK_ERROR       =  5,
 235   GST_CLOCK_UNSUPPORTED =  6,
 236 } GstClockReturn;
 237
 238 /**
 239  * GstClockEntryType:
 240  * @GST_CLOCK_ENTRY_SINGLE: a single shot timeout
 241  * @GST_CLOCK_ENTRY_PERIODIC: a periodic timeout request
 242  *
 243  * The type of the clock entry
 244  */
 245 typedef enum {
 246   GST_CLOCK_ENTRY_SINGLE,
 247   GST_CLOCK_ENTRY_PERIODIC
 248 } GstClockEntryType;
 249
 250 /**
 251  * GST_CLOCK_ENTRY:
 252  * @entry: the entry to cast
 253  *
 254  * Cast to a clock entry
 255  */
 256 #define GST_CLOCK_ENTRY(entry)          ((GstClockEntry *)(entry))
 257 /**
 258  * GST_CLOCK_ENTRY_CLOCK:
 259  * @entry: the entry to query
 260  *
 261  * Get the owner clock of the entry
 262  */
 263 #define GST_CLOCK_ENTRY_CLOCK(entry)    ((entry)->clock)
 264 /**
 265  * GST_CLOCK_ENTRY_TYPE:
 266  * @entry: the entry to query
 267  *
 268  * Get the type of the clock entry
 269  */
 270 #define GST_CLOCK_ENTRY_TYPE(entry)     ((entry)->type)
 271 /**
 272  * GST_CLOCK_ENTRY_TIME:
 273  * @entry: the entry to query
 274  *
 275  * Get the requested time of this entry
 276  */
 277 #define GST_CLOCK_ENTRY_TIME(entry)     ((entry)->time)
 278 /**
 279  * GST_CLOCK_ENTRY_INTERVAL:
 280  * @entry: the entry to query
 281  *
 282  * Get the interval of this periodic entry
 283  */
 284 #define GST_CLOCK_ENTRY_INTERVAL(entry) ((entry)->interval)
 285 /**
 286  * GST_CLOCK_ENTRY_STATUS:
 287  * @entry: the entry to query
 288  *
 289  * The status of the entry
 290  */
 291 #define GST_CLOCK_ENTRY_STATUS(entry)   ((entry)->status)
 292
 293 /**
 294  * GstClockEntry:
 295  * @refcount: reference counter (read-only)
 296  *
 297  * All pending timeouts or periodic notifies are converted into
 298  * an entry.
 299  */
 300 struct _GstClockEntry {
 301   gint                  refcount;
 302   /*< protected >*/
 303   GstClock              *clock;
 304   GstClockEntryType      type;
 305   GstClockTime           time;
 306   GstClockTime           interval;
 307   GstClockReturn         status;
 308   GstClockCallback       func;
 309   gpointer               user_data;
 310 };
 311
 312 /**
 313  * GstClockFlags:
 314  * @GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC: clock can do a single sync timeout request
 315  * @GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC: clock can do a single async timeout request
 316  * @GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC: clock can do sync periodic timeout requests
 317  * @GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC: clock can do async periodic timeout callbacks
 318  * @GST_CLOCK_FLAG_CAN_SET_RESOLUTION: clock's resolution can be changed
 319  * @GST_CLOCK_FLAG_CAN_SET_MASTER: clock can be slaved to a master clock
 320  * @GST_CLOCK_FLAG_LAST: subclasses can add additional flags starting from this flag
 321  *
 322  * The capabilities of this clock
 323  */
 324 typedef enum {
 325   GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC     = (GST_OBJECT_FLAG_LAST << 0),
 326   GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC    = (GST_OBJECT_FLAG_LAST << 1),
 327   GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC   = (GST_OBJECT_FLAG_LAST << 2),
 328   GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC  = (GST_OBJECT_FLAG_LAST << 3),
 329   GST_CLOCK_FLAG_CAN_SET_RESOLUTION     = (GST_OBJECT_FLAG_LAST << 4),
 330   GST_CLOCK_FLAG_CAN_SET_MASTER         = (GST_OBJECT_FLAG_LAST << 5),
 331   /* padding */
 332   GST_CLOCK_FLAG_LAST                   = (GST_OBJECT_FLAG_LAST << 8),
 333 } GstClockFlags;
 334
 335 /**
 336  * GST_CLOCK_FLAGS:
 337  * @clock: the clock to query
 338  *
 339  * Gets the #GstClockFlags clock flags.
 340  */
 341 #define GST_CLOCK_FLAGS(clock)  (GST_CLOCK(clock)->flags)
 342
 343 /**
 344  * GST_CLOCK_COND:
 345  * @clock: the clock to query
 346  *
 347  * Gets the #GCond that gets signaled when the entries of the clock
 348  * changed.
 349  */
 350 #define GST_CLOCK_COND(clock)            (GST_CLOCK_CAST(clock)->entries_changed)
 351 /**
 352  * GST_CLOCK_WAIT:
 353  * @clock: the clock to wait on
 354  *
 355  * Wait on the clock until the entries changed.
 356  */
 357 #define GST_CLOCK_WAIT(clock)            g_cond_wait(GST_CLOCK_COND(clock),GST_OBJECT_GET_LOCK(clock))
 358 /**
 359  * GST_CLOCK_TIMED_WAIT:
 360  * @clock: the clock to wait on
 361  * @tv: a GTimeVal to wait.
 362  *
 363  * Wait on the clock until the entries changed or the specified timeout
 364  * occured.
 365  */
 366 #define GST_CLOCK_TIMED_WAIT(clock,tv)   g_cond_timed_wait(GST_CLOCK_COND(clock),GST_OBJECT_GET_LOCK(clock),tv)
 367 /**
 368  * GST_CLOCK_BROADCAST:
 369  * @clock: the clock to broadcast
 370  *
 371  * Signal that the entries in the clock have changed.
 372  */
 373 #define GST_CLOCK_BROADCAST(clock)       g_cond_broadcast(GST_CLOCK_COND(clock))
 374
 375 /**
 376  * GstClock:
 377  * @flags: The flags specifying the capabilities of the clock.
 378  *
 379  * GstClock base structure. The values of this structure are
 380  * protected for subclasses, use the methods to use the #GstClock.
 381  */
 382 struct _GstClock {
 383   GstObject      object;
 384
 385   GMutex        *slave_lock; /* order: SLAVE_LOCK, OBJECT_LOCK */
 386
 387   /*< protected >*/ /* with LOCK */
 388   GstClockTime   internal_calibration;
 389   GstClockTime   external_calibration;
 390   GstClockTime   rate_numerator;
 391   GstClockTime   rate_denominator;
 392   GstClockTime   last_time;
 393   GList         *entries;
 394   GCond         *entries_changed;
 395
 396   /*< private >*/ /* with LOCK */
 397   GstClockTime   resolution;
 398   gboolean       stats;
 399
 400   /* for master/slave clocks */
 401   GstClock      *master;
 402
 403   /* with SLAVE_LOCK */
 404   gboolean       filling;
 405   gint           window_size;
 406   gint           window_threshold;
 407   gint           time_index;
 408   GstClockTime   timeout;
 409   GstClockTime  *times;
 410   GstClockID     clockid;
 411
 412   /*< private >*/
 413   GstClockTime   _gst_reserved[GST_PADDING];
 414 };
 415
 416 struct _GstClockClass {
 417   GstObjectClass        parent_class;
 418
 419   /*< protected >*/
 420   /* vtable */
 421   GstClockTime          (*change_resolution)    (GstClock *clock,
 422                                                  GstClockTime old_resolution,
 423                                                  GstClockTime new_resolution);
 424   GstClockTime          (*get_resolution)       (GstClock *clock);
 425
 426   GstClockTime          (*get_internal_time)    (GstClock *clock);
 427
 428   /* waiting on an ID */
 429   GstClockReturn        (*wait)                 (GstClock *clock, GstClockEntry *entry);
 430   GstClockReturn        (*wait_async)           (GstClock *clock, GstClockEntry *entry);
 431   void                  (*unschedule)           (GstClock *clock, GstClockEntry *entry);
 432
 433   /*< private >*/
 434   gpointer _gst_reserved[GST_PADDING];
 435 };
 436
 437 GType                   gst_clock_get_type              (void);
 438
 439 GstClockTime            gst_clock_set_resolution        (GstClock *clock,
 440                                                          GstClockTime resolution);
 441 GstClockTime            gst_clock_get_resolution        (GstClock *clock);
 442
 443 GstClockTime            gst_clock_get_time              (GstClock *clock);
 444 void                    gst_clock_set_calibration       (GstClock *clock, GstClockTime internal,
 445                                                          GstClockTime external,
 446                                                          GstClockTime rate_num,
 447                                                          GstClockTime rate_denom);
 448 void                    gst_clock_get_calibration       (GstClock *clock, GstClockTime *internal,
 449                                                          GstClockTime *external,
 450                                                          GstClockTime *rate_num,
 451                                                          GstClockTime *rate_denom);
 452
 453 /* master/slave clocks */
 454 gboolean                gst_clock_set_master            (GstClock *clock, GstClock *master);
 455 GstClock*               gst_clock_get_master            (GstClock *clock);
 456 gboolean                gst_clock_add_observation       (GstClock *clock, GstClockTime slave,
 457                                                          GstClockTime master, gdouble *r_squared);
 458
 459
 460 /* getting and adjusting internal time */
 461 GstClockTime            gst_clock_get_internal_time     (GstClock *clock);
 462 GstClockTime            gst_clock_adjust_unlocked       (GstClock *clock, GstClockTime internal);
 463
 464
 465 /* creating IDs that can be used to get notifications */
 466 GstClockID              gst_clock_new_single_shot_id    (GstClock *clock,
 467                                                          GstClockTime time);
 468 GstClockID              gst_clock_new_periodic_id       (GstClock *clock,
 469                                                          GstClockTime start_time,
 470                                                          GstClockTime interval);
 471
 472 /* reference counting */
 473 GstClockID              gst_clock_id_ref                (GstClockID id);
 474 void                    gst_clock_id_unref              (GstClockID id);
 475
 476 /* operations on IDs */
 477 gint                    gst_clock_id_compare_func       (gconstpointer id1, gconstpointer id2);
 478
 479 GstClockTime            gst_clock_id_get_time           (GstClockID id);
 480 GstClockReturn          gst_clock_id_wait               (GstClockID id,
 481                                                          GstClockTimeDiff *jitter);
 482 GstClockReturn          gst_clock_id_wait_async         (GstClockID id,
 483                                                          GstClockCallback func,
 484                                                          gpointer user_data);
 485 void                    gst_clock_id_unschedule         (GstClockID id);
 486
 487
 488 G_END_DECLS
 489
 490 #endif /* __GST_CLOCK_H__ */