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 G_BEGIN_DECLS
  28
  29 /* --- standard type macros --- */
  30 #define GST_TYPE_CLOCK                  (gst_clock_get_type ())
  31 #define GST_CLOCK(clock)                (G_TYPE_CHECK_INSTANCE_CAST ((clock), GST_TYPE_CLOCK, GstClock))
  32 #define GST_IS_CLOCK(clock)             (G_TYPE_CHECK_INSTANCE_TYPE ((clock), GST_TYPE_CLOCK))
  33 #define GST_CLOCK_CLASS(cclass)         (G_TYPE_CHECK_CLASS_CAST ((cclass), GST_TYPE_CLOCK, GstClockClass))
  34 #define GST_IS_CLOCK_CLASS(cclass)      (G_TYPE_CHECK_CLASS_TYPE ((cclass), GST_TYPE_CLOCK))
  35 #define GST_CLOCK_GET_CLASS(clock)      (G_TYPE_INSTANCE_GET_CLASS ((clock), GST_TYPE_CLOCK, GstClockClass))
  36 #define GST_CLOCK_CAST(clock)           ((GstClock*)(clock))
  37
  38 /**
  39  * GstClockTime:
  40  *
  41  * A datatype to hold a time, measured in nanoseconds.
  42  */
  43 typedef guint64 GstClockTime;
  44
  45 /**
  46  * GST_TYPE_CLOCK_TIME:
  47  *
  48  * The #GType of a #GstClockTime.
  49  */
  50 #define GST_TYPE_CLOCK_TIME G_TYPE_UINT64
  51
  52 /**
  53  * GstClockTimeDiff:
  54  *
  55  * A datatype to hold a time difference, measured in nanoseconds.
  56  */
  57 typedef gint64 GstClockTimeDiff;
  58 /**
  59  * GstClockID:
  60  *
  61  * A datatype to hold the handle to an outstanding sync or async clock callback.
  62  */
  63 typedef gpointer GstClockID;
  64
  65 /**
  66  * GST_CLOCK_TIME_NONE:
  67  *
  68  * Constant to define an undefined clock time.
  69  */
  70 #define GST_CLOCK_TIME_NONE             ((GstClockTime) -1)
  71 /**
  72  * GST_CLOCK_TIME_IS_VALID:
  73  * @time: clock time to validate
  74  *
  75  * Tests if a given #GstClockTime represents a valid defined time.
  76  */
  77 #define GST_CLOCK_TIME_IS_VALID(time)   (((GstClockTime)(time)) != GST_CLOCK_TIME_NONE)
  78
  79 /* FIXME: still need to explicitly force types on the defines below */
  80 /**
  81  * GST_SECOND:
  82  *
  83  * Constant that defines one GStreamer second.
  84  *
  85  * Value: 1000000000
  86  *
  87  */
  88 #define GST_SECOND  (G_USEC_PER_SEC * G_GINT64_CONSTANT (1000))
  89 /**
  90  * GST_MSECOND:
  91  *
  92  * Constant that defines one GStreamer millisecond.
  93  *
  94  * Value: 1000000
  95  *
  96  */
  97 #define GST_MSECOND (GST_SECOND / G_GINT64_CONSTANT (1000))
  98 /**
  99  * GST_USECOND:
 100  *
 101  * Constant that defines one GStreamer microsecond.
 102  *
 103  * Value: 1000
 104  *
 105  */
 106 #define GST_USECOND (GST_SECOND / G_GINT64_CONSTANT (1000000))
 107 /**
 108  * GST_NSECOND:
 109  *
 110  * Constant that defines one GStreamer nanosecond
 111  *
 112  * Value: 1
 113  *
 114  */
 115 #define GST_NSECOND (GST_SECOND / G_GINT64_CONSTANT (1000000000))
 116
 117
 118 /**
 119  * GST_TIME_AS_SECONDS:
 120  * @time: the time
 121  *
 122  * Convert a #GstClockTime to seconds.
 123  *
 124  * Since: 0.10.16
 125  */
 126 #define GST_TIME_AS_SECONDS(time)  ((time) / GST_SECOND)
 127 /**
 128  * GST_TIME_AS_MSECONDS:
 129  * @time: the time
 130  *
 131  * Convert a #GstClockTime to milliseconds (1/1000 of a second).
 132  *
 133  * Since: 0.10.16
 134  */
 135 #define GST_TIME_AS_MSECONDS(time) ((time) / G_GINT64_CONSTANT (1000000))
 136 /**
 137  * GST_TIME_AS_USECONDS:
 138  * @time: the time
 139  *
 140  * Convert a #GstClockTime to microseconds (1/1000000 of a second).
 141  *
 142  * Since: 0.10.16
 143  */
 144 #define GST_TIME_AS_USECONDS(time) ((time) / G_GINT64_CONSTANT (1000))
 145 /**
 146  * GST_TIME_AS_NSECONDS:
 147  * @time: the time
 148  *
 149  * Convert a #GstClockTime to nanoseconds (1/1000000000 of a second).
 150  *
 151  * Since: 0.10.16
 152  */
 153 #define GST_TIME_AS_NSECONDS(time) (time)
 154
 155 /**
 156  * GST_CLOCK_DIFF:
 157  * @s: the first time
 158  * @e: the second time
 159  *
 160  * Calculate a difference between two clock times as a #GstClockTimeDiff.
 161  * The difference is calculated as @e - @s.
 162  */
 163 #define GST_CLOCK_DIFF(s, e)            (GstClockTimeDiff)((e) - (s))
 164
 165 /**
 166  * GST_TIMEVAL_TO_TIME:
 167  * @tv: the timeval to convert
 168  *
 169  * Convert a #GTimeVal to a #GstClockTime.
 170  */
 171 #define GST_TIMEVAL_TO_TIME(tv)         (GstClockTime)((tv).tv_sec * GST_SECOND + (tv).tv_usec * GST_USECOND)
 172
 173 /**
 174  * GST_TIME_TO_TIMEVAL:
 175  * @t: The #GstClockTime to convert
 176  * @tv: The target timeval
 177  *
 178  * Convert a #GstClockTime to a #GTimeVal
 179  *
 180  * <note>on 32-bit systems, a timeval has a range of only 2^32 - 1 seconds,
 181  * which is about 68 years.  Expect trouble if you want to schedule stuff
 182  * in your pipeline for 2038.</note>
 183  */
 184 #define GST_TIME_TO_TIMEVAL(t,tv)                               \
 185 G_STMT_START {                                                  \
 186   g_assert ("Value of time " #t " is out of timeval's range" && \
 187       ((t) / GST_SECOND) < G_MAXLONG);                          \
 188   (tv).tv_sec  = (glong) (((GstClockTime) (t)) / GST_SECOND);   \
 189   (tv).tv_usec = (glong) ((((GstClockTime) (t)) -               \
 190                   ((GstClockTime) (tv).tv_sec) * GST_SECOND)    \
 191                  / GST_USECOND);                                \
 192 } G_STMT_END
 193
 194 /**
 195  * GST_TIMESPEC_TO_TIME:
 196  * @ts: the timespec to convert
 197  *
 198  * Convert a struct timespec (see man pselect) to a #GstClockTime.
 199  */
 200 #define GST_TIMESPEC_TO_TIME(ts)        (GstClockTime)((ts).tv_sec * GST_SECOND + (ts).tv_nsec * GST_NSECOND)
 201 /**
 202  * GST_TIME_TO_TIMESPEC:
 203  * @t: The #GstClockTime to convert
 204  * @ts: The target timespec
 205  *
 206  * Convert a #GstClockTime to a struct timespec (see man pselect)
 207  */
 208 #define GST_TIME_TO_TIMESPEC(t,ts)                                \
 209 G_STMT_START {                                                    \
 210   g_assert ("Value of time " #t " is out of timespec's range" &&  \
 211       ((t) / GST_SECOND) < G_MAXLONG);                            \
 212   (ts).tv_sec  =  (glong) ((t) / GST_SECOND);                     \
 213   (ts).tv_nsec = (glong) (((t) - (ts).tv_sec * GST_SECOND) / GST_NSECOND);        \
 214 } G_STMT_END
 215
 216 /* timestamp debugging macros */
 217 /**
 218  * GST_TIME_FORMAT:
 219  *
 220  * A string that can be used in printf-like format strings to display a
 221  * #GstClockTime value in h:m:s format.  Use GST_TIME_ARGS() to construct
 222  * the matching arguments.
 223  *
 224  * Example:
 225  * |[
 226  * printf("%" GST_TIME_FORMAT "\n", GST_TIME_ARGS(ts));
 227  * ]|
 228  */
 229 #define GST_TIME_FORMAT "u:%02u:%02u.%09u"
 230 /**
 231  * GST_TIME_ARGS:
 232  * @t: a #GstClockTime
 233  *
 234  * Format @t for the #GST_TIME_FORMAT format string. Note: @t will be
 235  * evaluated more than once.
 236  */
 237 #define GST_TIME_ARGS(t) \
 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)) % 60) : 99, \
 242         GST_CLOCK_TIME_IS_VALID (t) ? \
 243         (guint) ((((GstClockTime)(t)) / GST_SECOND) % 60) : 99, \
 244         GST_CLOCK_TIME_IS_VALID (t) ? \
 245         (guint) (((GstClockTime)(t)) % GST_SECOND) : 999999999
 246
 247 typedef struct _GstClockEntry   GstClockEntry;
 248 typedef struct _GstClock        GstClock;
 249 typedef struct _GstClockClass   GstClockClass;
 250 typedef struct _GstClockPrivate GstClockPrivate;
 251
 252 /* --- prototype for async callbacks --- */
 253 /**
 254  * GstClockCallback:
 255  * @clock: The clock that triggered the callback
 256  * @time: The time it was triggered
 257  * @id: The #GstClockID that expired
 258  * @user_data: user data passed in the gst_clock_id_wait_async() function
 259  *
 260  * The function prototype of the callback.
 261  *
 262  * Returns: %TRUE or %FALSE (currently unused)
 263  */
 264 typedef gboolean        (*GstClockCallback)     (GstClock *clock, GstClockTime time,
 265                                                  GstClockID id, gpointer user_data);
 266 /**
 267  * GstClockReturn:
 268  * @GST_CLOCK_OK: The operation succeeded.
 269  * @GST_CLOCK_EARLY: The operation was scheduled too late.
 270  * @GST_CLOCK_UNSCHEDULED: The clockID was unscheduled
 271  * @GST_CLOCK_BUSY: The ClockID is busy
 272  * @GST_CLOCK_BADTIME: A bad time was provided to a function.
 273  * @GST_CLOCK_ERROR: An error occurred
 274  * @GST_CLOCK_UNSUPPORTED: Operation is not supported
 275  * @GST_CLOCK_DONE: The ClockID is done waiting (Since: 0.10.32)
 276  *
 277  * The return value of a clock operation.
 278  */
 279 typedef enum
 280 {
 281   GST_CLOCK_OK          =  0,
 282   GST_CLOCK_EARLY       =  1,
 283   GST_CLOCK_UNSCHEDULED =  2,
 284   GST_CLOCK_BUSY        =  3,
 285   GST_CLOCK_BADTIME     =  4,
 286   GST_CLOCK_ERROR       =  5,
 287   GST_CLOCK_UNSUPPORTED =  6,
 288   GST_CLOCK_DONE        =  7
 289 } GstClockReturn;
 290
 291 /**
 292  * GstClockEntryType:
 293  * @GST_CLOCK_ENTRY_SINGLE: a single shot timeout
 294  * @GST_CLOCK_ENTRY_PERIODIC: a periodic timeout request
 295  *
 296  * The type of the clock entry
 297  */
 298 typedef enum {
 299   GST_CLOCK_ENTRY_SINGLE,
 300   GST_CLOCK_ENTRY_PERIODIC
 301 } GstClockEntryType;
 302
 303 /**
 304  * GST_CLOCK_ENTRY:
 305  * @entry: the entry to cast
 306  *
 307  * Cast to a clock entry
 308  */
 309 #define GST_CLOCK_ENTRY(entry)          ((GstClockEntry *)(entry))
 310 /**
 311  * GST_CLOCK_ENTRY_CLOCK:
 312  * @entry: the entry to query
 313  *
 314  * Get the owner clock of the entry
 315  */
 316 #define GST_CLOCK_ENTRY_CLOCK(entry)    ((entry)->clock)
 317 /**
 318  * GST_CLOCK_ENTRY_TYPE:
 319  * @entry: the entry to query
 320  *
 321  * Get the type of the clock entry
 322  */
 323 #define GST_CLOCK_ENTRY_TYPE(entry)     ((entry)->type)
 324 /**
 325  * GST_CLOCK_ENTRY_TIME:
 326  * @entry: the entry to query
 327  *
 328  * Get the requested time of this entry
 329  */
 330 #define GST_CLOCK_ENTRY_TIME(entry)     ((entry)->time)
 331 /**
 332  * GST_CLOCK_ENTRY_INTERVAL:
 333  * @entry: the entry to query
 334  *
 335  * Get the interval of this periodic entry
 336  */
 337 #define GST_CLOCK_ENTRY_INTERVAL(entry) ((entry)->interval)
 338 /**
 339  * GST_CLOCK_ENTRY_STATUS:
 340  * @entry: the entry to query
 341  *
 342  * The status of the entry
 343  */
 344 #define GST_CLOCK_ENTRY_STATUS(entry)   ((entry)->status)
 345
 346 /**
 347  * GstClockEntry:
 348  * @refcount: reference counter (read-only)
 349  *
 350  * All pending timeouts or periodic notifies are converted into
 351  * an entry.
 352  * Note that GstClockEntry should be treated as an opaque structure. It must
 353  * not be extended or allocated using a custom allocator.
 354  */
 355 struct _GstClockEntry {
 356   gint                  refcount;
 357   /*< protected >*/
 358   GstClock              *clock;
 359   GstClockEntryType      type;
 360   GstClockTime           time;
 361   GstClockTime           interval;
 362   GstClockReturn         status;
 363   GstClockCallback       func;
 364   gpointer               user_data;
 365   GDestroyNotify         destroy_data;
 366   gboolean               unscheduled;
 367   gboolean               woken_up;
 368
 369   /*< private >*/
 370   gpointer _gst_reserved[GST_PADDING];
 371 };
 372
 373 #include <gst/gstobject.h>
 374
 375 /**
 376  * GstClockFlags:
 377  * @GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC: clock can do a single sync timeout request
 378  * @GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC: clock can do a single async timeout request
 379  * @GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC: clock can do sync periodic timeout requests
 380  * @GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC: clock can do async periodic timeout callbacks
 381  * @GST_CLOCK_FLAG_CAN_SET_RESOLUTION: clock's resolution can be changed
 382  * @GST_CLOCK_FLAG_CAN_SET_MASTER: clock can be slaved to a master clock
 383  * @GST_CLOCK_FLAG_LAST: subclasses can add additional flags starting from this flag
 384  *
 385  * The capabilities of this clock
 386  */
 387 typedef enum {
 388   GST_CLOCK_FLAG_CAN_DO_SINGLE_SYNC     = (GST_OBJECT_FLAG_LAST << 0),
 389   GST_CLOCK_FLAG_CAN_DO_SINGLE_ASYNC    = (GST_OBJECT_FLAG_LAST << 1),
 390   GST_CLOCK_FLAG_CAN_DO_PERIODIC_SYNC   = (GST_OBJECT_FLAG_LAST << 2),
 391   GST_CLOCK_FLAG_CAN_DO_PERIODIC_ASYNC  = (GST_OBJECT_FLAG_LAST << 3),
 392   GST_CLOCK_FLAG_CAN_SET_RESOLUTION     = (GST_OBJECT_FLAG_LAST << 4),
 393   GST_CLOCK_FLAG_CAN_SET_MASTER         = (GST_OBJECT_FLAG_LAST << 5),
 394   /* padding */
 395   GST_CLOCK_FLAG_LAST                   = (GST_OBJECT_FLAG_LAST << 8)
 396 } GstClockFlags;
 397
 398 /**
 399  * GST_CLOCK_FLAGS:
 400  * @clock: the clock to query
 401  *
 402  * Gets the #GstClockFlags clock flags.
 403  */
 404 #define GST_CLOCK_FLAGS(clock)  GST_OBJECT_FLAGS(clock)
 405
 406 /**
 407  * GstClock:
 408  *
 409  * #GstClock base structure. The values of this structure are
 410  * protected for subclasses, use the methods to use the #GstClock.
 411  */
 412 struct _GstClock {
 413   GstObject      object;
 414
 415   /*< private >*/
 416   GstClockPrivate *priv;
 417
 418   gpointer _gst_reserved[GST_PADDING];
 419 };
 420
 421 /**
 422  * GstClockClass:
 423  * @parent_class: the parent class structure
 424  * @change_resolution: change the resolution of the clock. Not all values might
 425  *                     be acceptable. The new resolution should be returned.
 426  * @get_resolution: get the resolution of the clock.
 427  * @get_internal_time: get the internal unadjusted time of the clock.
 428  *        implement @wait_jitter instead.
 429  * @wait: perform a blocking wait on the given #GstClockEntry and return
 430  *               the jitter.
 431  * @wait_async: perform an asynchronous wait for the given #GstClockEntry.
 432  * @unschedule: unblock a blocking or async wait operation.
 433  *
 434  * GStreamer clock class. Override the vmethods to implement the clock
 435  * functionality.
 436  */
 437 struct _GstClockClass {
 438   GstObjectClass        parent_class;
 439
 440   /*< public >*/
 441   /* vtable */
 442   GstClockTime          (*change_resolution)    (GstClock *clock,
 443                                                  GstClockTime old_resolution,
 444                                                  GstClockTime new_resolution);
 445   GstClockTime          (*get_resolution)       (GstClock *clock);
 446
 447   GstClockTime          (*get_internal_time)    (GstClock *clock);
 448
 449   /* waiting on an ID */
 450   GstClockReturn        (*wait)                 (GstClock *clock, GstClockEntry *entry,
 451                                                  GstClockTimeDiff *jitter);
 452   GstClockReturn        (*wait_async)           (GstClock *clock, GstClockEntry *entry);
 453   void                  (*unschedule)           (GstClock *clock, GstClockEntry *entry);
 454
 455   /*< private >*/
 456   gpointer _gst_reserved[GST_PADDING];
 457 };
 458
 459 GType                   gst_clock_get_type              (void);
 460
 461 GstClockTime            gst_clock_set_resolution        (GstClock *clock,
 462                                                          GstClockTime resolution);
 463 GstClockTime            gst_clock_get_resolution        (GstClock *clock);
 464
 465 GstClockTime            gst_clock_get_time              (GstClock *clock);
 466 void                    gst_clock_set_calibration       (GstClock *clock, GstClockTime internal,
 467                                                          GstClockTime external,
 468                                                          GstClockTime rate_num,
 469                                                          GstClockTime rate_denom);
 470 void                    gst_clock_get_calibration       (GstClock *clock, GstClockTime *internal,
 471                                                          GstClockTime *external,
 472                                                          GstClockTime *rate_num,
 473                                                          GstClockTime *rate_denom);
 474
 475 /* master/slave clocks */
 476 gboolean                gst_clock_set_master            (GstClock *clock, GstClock *master);
 477 GstClock*               gst_clock_get_master            (GstClock *clock);
 478
 479 void                    gst_clock_set_timeout           (GstClock *clock,
 480                                                          GstClockTime timeout);
 481 GstClockTime            gst_clock_get_timeout           (GstClock *clock);
 482
 483 gboolean                gst_clock_add_observation       (GstClock *clock, GstClockTime slave,
 484                                                          GstClockTime master, gdouble *r_squared);
 485
 486
 487 /* getting and adjusting internal/external time */
 488 GstClockTime            gst_clock_get_internal_time     (GstClock *clock);
 489 GstClockTime            gst_clock_adjust_unlocked       (GstClock *clock, GstClockTime internal);
 490 GstClockTime            gst_clock_unadjust_unlocked     (GstClock * clock, GstClockTime external);
 491
 492
 493 /* creating IDs that can be used to get notifications */
 494 GstClockID              gst_clock_new_single_shot_id    (GstClock *clock,
 495                                                          GstClockTime time);
 496 GstClockID              gst_clock_new_periodic_id       (GstClock *clock,
 497                                                          GstClockTime start_time,
 498                                                          GstClockTime interval);
 499
 500 /* reference counting */
 501 GstClockID              gst_clock_id_ref                (GstClockID id);
 502 void                    gst_clock_id_unref              (GstClockID id);
 503
 504 /* operations on IDs */
 505 gint                    gst_clock_id_compare_func       (gconstpointer id1, gconstpointer id2);
 506
 507 GstClockTime            gst_clock_id_get_time           (GstClockID id);
 508 GstClockReturn          gst_clock_id_wait               (GstClockID id,
 509                                                          GstClockTimeDiff *jitter);
 510 GstClockReturn          gst_clock_id_wait_async         (GstClockID id,
 511                                                          GstClockCallback func,
 512                                                          gpointer user_data);
 513 GstClockReturn          gst_clock_id_wait_async_full    (GstClockID id,
 514                                                          GstClockCallback func,
 515                                                          gpointer user_data,
 516                                                          GDestroyNotify destroy_data);
 517 void                    gst_clock_id_unschedule         (GstClockID id);
 518
 519 gboolean                gst_clock_single_shot_id_reinit (GstClock * clock,
 520                                                          GstClockID id,
 521                                                          GstClockTime time);
 522 gboolean                gst_clock_periodic_id_reinit    (GstClock * clock,
 523                                                          GstClockID id,
 524                                                          GstClockTime start_time,
 525                                                          GstClockTime interval);
 526
 527 G_END_DECLS
 528
 529 #endif /* __GST_CLOCK_H__ */