include/vlc_tick.h

   1 /*****************************************************************************
   2  * vlc_tick.h: high resolution time management functions
   3  *****************************************************************************
   4  * This header provides portable high precision time management functions,
   5  * which should be the only ones used in other segments of the program, since
   6  * functions like gettimeofday() and ftime() are not always supported.
   7  * Most functions are declared as inline or as macros since they are only
   8  * interfaces to system calls and have to be called frequently.
   9  * 'm' stands for 'micro', since maximum resolution is the microsecond.
  10  * Functions prototyped are implemented in interface/mtime.c.
  11  *****************************************************************************
  12  * Copyright (C) 1996, 1997, 1998, 1999, 2000 VLC authors and VideoLAN
  13  * $Id$
  14  *
  15  * Authors: Vincent Seguin <seguin@via.ecp.fr>
  16  *
  17  * This program is free software; you can redistribute it and/or modify it
  18  * under the terms of the GNU Lesser General Public License as published by
  19  * the Free Software Foundation; either version 2.1 of the License, or
  20  * (at your option) any later version.
  21  *
  22  * This program is distributed in the hope that it will be useful,
  23  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  25  * GNU Lesser General Public License for more details.
  26  *
  27  * You should have received a copy of the GNU Lesser General Public License
  28  * along with this program; if not, write to the Free Software Foundation,
  29  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  30  *****************************************************************************/
  31
  32 #ifndef __VLC_MTIME_H
  33 # define __VLC_MTIME_H 1
  34
  35 /**
  36  * High precision date or time interval
  37  *
  38  * Store a high precision date or time interval. The maximum precision is the
  39  * microsecond, and a 64 bits integer is used to avoid overflows (maximum
  40  * time interval is then 292271 years, which should be long enough for any
  41  * video). Dates are stored as microseconds since a common date (usually the
  42  * epoch). Note that date and time intervals can be manipulated using regular
  43  * arithmetic operators, and that no special functions are required.
  44  */
  45 typedef int64_t vlc_tick_t;
  46 typedef vlc_tick_t mtime_t; /* deprecated, use vlc_tick_t */
  47
  48
  49 /*
  50  * vlc_tick_t <> seconds (sec) conversions
  51  */
  52 #define VLC_TICK_FROM_SEC(sec)   (CLOCK_FREQ * (sec))
  53 #define SEC_FROM_VLC_TICK(vtk)   ((vtk) / CLOCK_FREQ)
  54
  55 #ifdef __cplusplus
  56 #include <type_traits>
  57
  58 template <typename T>
  59 static inline auto vlc_tick_from_sec(T sec)
  60     -> typename std::enable_if<std::is_integral<T>::value, vlc_tick_t>::type
  61 {
  62     return CLOCK_FREQ * sec;
  63 }
  64
  65 /* seconds in floating point */
  66 static inline vlc_tick_t vlc_tick_from_sec(double secf)
  67 {
  68     return (vlc_tick_t)(CLOCK_FREQ * secf); /* TODO use llround ? */
  69 }
  70 #else /* !__cplusplus */
  71 static inline vlc_tick_t vlc_tick_from_seci(int64_t sec)
  72 {
  73     return CLOCK_FREQ * sec;
  74 }
  75 /* seconds in floating point */
  76 static inline vlc_tick_t vlc_tick_from_secf(double secf)
  77 {
  78     return (vlc_tick_t)(CLOCK_FREQ * secf); /* TODO use llround ? */
  79 }
  80
  81 #define vlc_tick_from_sec(sec) _Generic((sec), \
  82         double:  vlc_tick_from_secf(sec), \
  83         float:   vlc_tick_from_secf(sec), \
  84         default: vlc_tick_from_seci(sec) )
  85 #endif /* !__cplusplus */
  86
  87 /* seconds in floating point from vlc_tick_t */
  88 static inline double secf_from_vlc_tick(vlc_tick_t vtk)
  89 {
  90     return (double)vtk / (double)CLOCK_FREQ;
  91 }
  92
  93 static inline vlc_tick_t vlc_tick_rate_duration(float frame_rate)
  94 {
  95     return CLOCK_FREQ / frame_rate;
  96 }
  97
  98 /*
  99  * samples<>vlc_tick_t
 100  */
 101 static inline vlc_tick_t vlc_tick_from_samples(int64_t samples, int samp_rate)
 102 {
 103     return CLOCK_FREQ * samples / samp_rate;
 104 }
 105 static inline int64_t samples_from_vlc_tick(vlc_tick_t t, int samp_rate)
 106 {
 107     return t * samp_rate / CLOCK_FREQ;
 108 }
 109
 110
 111 static inline vlc_tick_t vlc_tick_from_frac(uint64_t num, uint64_t den)
 112 {
 113     lldiv_t d = lldiv (num, den);
 114     return vlc_tick_from_sec( d.quot ) + vlc_tick_from_samples(d.rem, den);
 115 }
 116
 117
 118 /*
 119  * vlc_tick_t <> milliseconds (ms) conversions
 120  */
 121 #if (CLOCK_FREQ % 1000) == 0
 122 #define VLC_TICK_FROM_MS(ms)  ((CLOCK_FREQ / INT64_C(1000)) * (ms))
 123 #define MS_FROM_VLC_TICK(vtk) ((vtk) / (CLOCK_FREQ / INT64_C(1000)))
 124 #elif (1000 % CLOCK_FREQ) == 0
 125 #define VLC_TICK_FROM_MS(ms)  ((ms)  / (INT64_C(1000) / CLOCK_FREQ))
 126 #define MS_FROM_VLC_TICK(vtk) ((vtk) * (INT64_C(1000) / CLOCK_FREQ))
 127 #else /* rounded overflowing conversion */
 128 #define VLC_TICK_FROM_MS(ms)  (CLOCK_FREQ * (ms) / 1000)
 129 #define MS_FROM_VLC_TICK(vtk) ((vtk) * 1000 / CLOCK_FREQ)
 130 #endif /* CLOCK_FREQ / 1000 */
 131
 132
 133 /*
 134  * vlc_tick_t <> microseconds (us) conversions
 135  */
 136 #if (CLOCK_FREQ % 1000000) == 0
 137 #define VLC_TICK_FROM_US(us)    ((CLOCK_FREQ / INT64_C(1000000)) * (us))
 138 #define US_FROM_VLC_TICK(vtk)   ((vtk) / (CLOCK_FREQ / INT64_C(1000000)))
 139 #elif (1000000 % CLOCK_FREQ) == 0
 140 #define VLC_TICK_FROM_US(us)    ((us)  / (INT64_C(1000000) / CLOCK_FREQ))
 141 #define US_FROM_VLC_TICK(vtk)   ((vtk) * (INT64_C(1000000) / CLOCK_FREQ))
 142 #else /* rounded overflowing conversion */
 143 #define VLC_TICK_FROM_US(us)    (CLOCK_FREQ * (us) / INT64_C(1000000))
 144 #define US_FROM_VLC_TICK(vtk)   ((vtk) * INT64_C(1000000) / CLOCK_FREQ)
 145 #endif /* CLOCK_FREQ / 1000000 */
 146
 147
 148 /*
 149  * vlc_tick_t <> nanoseconds (ns) conversions
 150  */
 151 #if (CLOCK_FREQ % 1000000000) == 0
 152 #define VLC_TICK_FROM_NS(ns)    ((ns)  * (CLOCK_FREQ / (INT64_C(1000000000))))
 153 #define NS_FROM_VLC_TICK(vtk)   ((vtk) / (CLOCK_FREQ / (INT64_C(1000000000))))
 154 #elif (1000000000 % CLOCK_FREQ) == 0
 155 #define VLC_TICK_FROM_NS(ns)    ((ns)  / (INT64_C(1000000000) / CLOCK_FREQ))
 156 #define NS_FROM_VLC_TICK(vtk)   ((vtk) * (INT64_C(1000000000) / CLOCK_FREQ))
 157 #else /* rounded overflowing conversion */
 158 #define VLC_TICK_FROM_NS(ns)    (CLOCK_FREQ * (ns) / INT64_C(1000000000))
 159 #define NS_FROM_VLC_TICK(vtk)   ((vtk) * INT64_C(1000000000) / CLOCK_FREQ)
 160 #endif /* CLOCK_FREQ / 1000000000 */
 161
 162
 163 /*
 164  * msftime_t is a time with 100ns resolutions, typically used by Microsoft
 165  */
 166 typedef int64_t msftime_t;
 167
 168 #define MSFTIME_FROM_SEC(sec)       (INT64_C(10000000) * (sec))  /* seconds in msftime_t */
 169 #define MSFTIME_FROM_MS(sec)        (INT64_C(10000) * (sec))     /* milliseconds in msftime_t */
 170
 171 #if (CLOCK_FREQ % 10000000) == 0
 172 #define VLC_TICK_FROM_MSFTIME(msft) ((msft) * (CLOCK_FREQ / INT64_C(10000000))
 173 #define MSFTIME_FROM_VLC_TICK(vtk)  ((vtk)  / (CLOCK_FREQ / INT64_C(10000000))
 174 #elif (10000000 % CLOCK_FREQ) == 0
 175 #define VLC_TICK_FROM_MSFTIME(msft) ((msft) / (INT64_C(10000000) / CLOCK_FREQ))
 176 #define MSFTIME_FROM_VLC_TICK(vtk)  ((vtk)  * (INT64_C(10000000) / CLOCK_FREQ))
 177 #else /* rounded overflowing conversion */
 178 #define VLC_TICK_FROM_MSFTIME(msft) (CLOCK_FREQ * (msft) / INT64_C(10000000))
 179 #define MSFTIME_FROM_VLC_TICK(vtk)  ((vtk)  * INT64_C(10000000) / CLOCK_FREQ)
 180 #endif /* CLOCK_FREQ / 10000000 */
 181
 182 #define vlc_tick_from_timeval(tv) \
 183     (vlc_tick_from_sec( (tv)->tv_sec ) + VLC_TICK_FROM_US( (tv)->tv_usec ))
 184
 185 #define vlc_tick_from_timespec(tv) \
 186     (vlc_tick_from_sec( (tv)->tv_sec ) + VLC_TICK_FROM_NS( (tv)->tv_nsec ))
 187
 188 struct timespec timespec_from_vlc_tick(vlc_tick_t date);
 189
 190
 191 /*****************************************************************************
 192  * MSTRTIME_MAX_SIZE: maximum possible size of secstotimestr
 193  *****************************************************************************
 194  * This values is the maximal possible size of the string returned by the
 195  * secstotimestr() function, including '-' and the final '\0'. It should be
 196  * used to allocate the buffer.
 197  *****************************************************************************/
 198 #define MSTRTIME_MAX_SIZE 22
 199
 200 /*****************************************************************************
 201  * Prototypes
 202  *****************************************************************************/
 203
 204 /**
 205  * Convert seconds to a time in the format h:mm:ss.
 206  *
 207  * This function is provided for any interface function which need to print a
 208  * time string in the format h:mm:ss
 209  * date.
 210  * \param secs  the date to be converted
 211  * \param psz_buffer should be a buffer at least MSTRTIME_MAX_SIZE characters
 212  * \return psz_buffer is returned so this can be used as printf parameter.
 213  */
 214 VLC_API char * secstotimestr( char *psz_buffer, int32_t secs );
 215
 216 /**
 217  * \defgroup date Timestamps, error-free
 218  * These functions support generating timestamps without long term rounding
 219  * errors due to sample rate conversions.
 220  * \ingroup input
 221  * @{
 222  */
 223 /**
 224  * Timestamps without long-term rounding errors
 225  */
 226 struct date_t
 227 {
 228     vlc_tick_t  date;
 229     uint32_t i_divider_num;
 230     uint32_t i_divider_den;
 231     uint32_t i_remainder;
 232 };
 233
 234 /**
 235  * Initializes a date_t.
 236  *
 237  * \param date date to initialize [OUT]
 238  * \param num divider (sample rate) numerator
 239  * \param den divider (sample rate) denominator
 240  */
 241 VLC_API void date_Init(date_t *restrict date, uint32_t num, uint32_t den);
 242
 243 /**
 244  * Changes the rate of a date_t.
 245  *
 246  * \param date date to change
 247  * \param num divider (sample rate) numerator
 248  * \param den divider (sample rate) denominator
 249  */
 250 VLC_API void date_Change(date_t *restrict date, uint32_t num, uint32_t den);
 251
 252 /**
 253  * Sets the exact timestamp of a date_t.
 254  *
 255  * \param date date to set the timestamp into
 256  * \param value date value
 257  */
 258 static inline void date_Set(date_t *restrict date, vlc_tick_t value)
 259 {
 260     date->date = value;
 261     date->i_remainder = 0;
 262 }
 263
 264 /**
 265  * Gets the current timestamp from a date_t.
 266  *
 267  * \param date date to fetch the timestamp from
 268  * \return date value
 269  */
 270 VLC_USED static inline vlc_tick_t date_Get(const date_t *restrict date)
 271 {
 272     return date->date;
 273 }
 274
 275 /**
 276  * Increments a date.
 277  *
 278  * Moves the date_t timestamp forward by a given number of samples.
 279  *
 280  * \param date date to move forward
 281  * \param count number of samples
 282  * \return timestamp value after incrementing
 283  */
 284 VLC_API vlc_tick_t date_Increment(date_t *restrict date, uint32_t count);
 285
 286 /**
 287  * Decrements a date.
 288  *
 289  * Moves the date_t timestamp backward by a given number of samples.
 290  *
 291  * \param date date to move backward
 292  * \param count number of samples
 293  * \return date value
 294  */
 295 VLC_API vlc_tick_t date_Decrement(date_t *restrict date, uint32_t count);
 296
 297 /** @} */
 298
 299 /**
 300  * @return NTP 64-bits timestamp in host byte order.
 301  */
 302 VLC_API uint64_t NTPtime64( void );
 303 #endif /* !__VLC_MTIME_ */