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