VLC  4.0.0-dev
vlc_tick.h
Go to the documentation of this file.
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 #define VLC_TICK_MIN INT64_MIN
48 #define VLC_TICK_MAX INT64_MAX
49 
50 /*
51  * vlc_tick_t <> seconds (sec) conversions
52  */
53 #define VLC_TICK_FROM_SEC(sec) (CLOCK_FREQ * (sec))
54 #define SEC_FROM_VLC_TICK(vtk) ((vtk) / CLOCK_FREQ)
55 
56 #ifdef __cplusplus
57 #include <type_traits>
58 
59 template <typename T>
60 static inline auto vlc_tick_from_sec(T sec)
61  -> typename std::enable_if<std::is_integral<T>::value, vlc_tick_t>::type
62 {
63  return CLOCK_FREQ * sec;
64 }
65 
66 /* seconds in floating point */
67 static inline vlc_tick_t vlc_tick_from_sec(double secf)
68 {
69  return (vlc_tick_t)(CLOCK_FREQ * secf); /* TODO use llround ? */
70 }
71 #else /* !__cplusplus */
72 static inline vlc_tick_t vlc_tick_from_seci(int64_t sec)
73 {
74  return CLOCK_FREQ * sec;
75 }
76 /* seconds in floating point */
77 static inline vlc_tick_t vlc_tick_from_secf(double secf)
78 {
79  return (vlc_tick_t)(CLOCK_FREQ * secf); /* TODO use llround ? */
80 }
81 
82 #define vlc_tick_from_sec(sec) _Generic((sec), \
83  double: vlc_tick_from_secf(sec), \
84  float: vlc_tick_from_secf(sec), \
85  default: vlc_tick_from_seci(sec) )
86 #endif /* !__cplusplus */
87 
88 /* seconds in floating point from vlc_tick_t */
89 static inline double secf_from_vlc_tick(vlc_tick_t vtk)
90 {
91  return (double)vtk / (double)CLOCK_FREQ;
92 }
93 
94 static inline vlc_tick_t vlc_tick_rate_duration(float frame_rate)
95 {
96  return CLOCK_FREQ / frame_rate;
97 }
98 
99 /*
100  * samples<>vlc_tick_t
101  */
102 static inline vlc_tick_t vlc_tick_from_samples(int64_t samples, int samp_rate)
103 {
104  return CLOCK_FREQ * samples / samp_rate;
105 }
106 static inline int64_t samples_from_vlc_tick(vlc_tick_t t, int samp_rate)
107 {
108  return t * samp_rate / CLOCK_FREQ;
109 }
110 
111 
112 static inline vlc_tick_t vlc_tick_from_frac(uint64_t num, uint64_t den)
113 {
114  lldiv_t d = lldiv (num, den);
115  return vlc_tick_from_sec( d.quot ) + vlc_tick_from_samples(d.rem, den);
116 }
117 
118 
119 /*
120  * vlc_tick_t <> milliseconds (ms) conversions
121  */
122 #if (CLOCK_FREQ % 1000) == 0
123 #define VLC_TICK_FROM_MS(ms) ((CLOCK_FREQ / INT64_C(1000)) * (ms))
124 #define MS_FROM_VLC_TICK(vtk) ((vtk) / (CLOCK_FREQ / INT64_C(1000)))
125 #elif (1000 % CLOCK_FREQ) == 0
126 #define VLC_TICK_FROM_MS(ms) ((ms) / (INT64_C(1000) / CLOCK_FREQ))
127 #define MS_FROM_VLC_TICK(vtk) ((vtk) * (INT64_C(1000) / CLOCK_FREQ))
128 #else /* rounded overflowing conversion */
129 #define VLC_TICK_FROM_MS(ms) (CLOCK_FREQ * (ms) / 1000)
130 #define MS_FROM_VLC_TICK(vtk) ((vtk) * 1000 / CLOCK_FREQ)
131 #endif /* CLOCK_FREQ / 1000 */
132 
133 
134 /*
135  * vlc_tick_t <> microseconds (us) conversions
136  */
137 #if (CLOCK_FREQ % 1000000) == 0
138 #define VLC_TICK_FROM_US(us) ((CLOCK_FREQ / INT64_C(1000000)) * (us))
139 #define US_FROM_VLC_TICK(vtk) ((vtk) / (CLOCK_FREQ / INT64_C(1000000)))
140 #elif (1000000 % CLOCK_FREQ) == 0
141 #define VLC_TICK_FROM_US(us) ((us) / (INT64_C(1000000) / CLOCK_FREQ))
142 #define US_FROM_VLC_TICK(vtk) ((vtk) * (INT64_C(1000000) / CLOCK_FREQ))
143 #else /* rounded overflowing conversion */
144 #define VLC_TICK_FROM_US(us) (CLOCK_FREQ * (us) / INT64_C(1000000))
145 #define US_FROM_VLC_TICK(vtk) ((vtk) * INT64_C(1000000) / CLOCK_FREQ)
146 #endif /* CLOCK_FREQ / 1000000 */
147 
148 
149 /*
150  * vlc_tick_t <> nanoseconds (ns) conversions
151  */
152 #if (CLOCK_FREQ % 1000000000) == 0
153 #define VLC_TICK_FROM_NS(ns) ((ns) * (CLOCK_FREQ / (INT64_C(1000000000))))
154 #define NS_FROM_VLC_TICK(vtk) ((vtk) / (CLOCK_FREQ / (INT64_C(1000000000))))
155 #elif (1000000000 % CLOCK_FREQ) == 0
156 #define VLC_TICK_FROM_NS(ns) ((ns) / (INT64_C(1000000000) / CLOCK_FREQ))
157 #define NS_FROM_VLC_TICK(vtk) ((vtk) * (INT64_C(1000000000) / CLOCK_FREQ))
158 #else /* rounded overflowing conversion */
159 #define VLC_TICK_FROM_NS(ns) (CLOCK_FREQ * (ns) / INT64_C(1000000000))
160 #define NS_FROM_VLC_TICK(vtk) ((vtk) * INT64_C(1000000000) / CLOCK_FREQ)
161 #endif /* CLOCK_FREQ / 1000000000 */
162 
163 
164 /*
165  * msftime_t is a time with 100ns resolutions, typically used by Microsoft
166  */
167 typedef int64_t msftime_t;
168 
169 #define MSFTIME_FROM_SEC(sec) (INT64_C(10000000) * (sec)) /* seconds in msftime_t */
170 #define MSFTIME_FROM_MS(sec) (INT64_C(10000) * (sec)) /* milliseconds in msftime_t */
171 
172 #if (CLOCK_FREQ % 10000000) == 0
173 #define VLC_TICK_FROM_MSFTIME(msft) ((msft) * (CLOCK_FREQ / INT64_C(10000000))
174 #define MSFTIME_FROM_VLC_TICK(vtk) ((vtk) / (CLOCK_FREQ / INT64_C(10000000))
175 #elif (10000000 % CLOCK_FREQ) == 0
176 #define VLC_TICK_FROM_MSFTIME(msft) ((msft) / (INT64_C(10000000) / CLOCK_FREQ))
177 #define MSFTIME_FROM_VLC_TICK(vtk) ((vtk) * (INT64_C(10000000) / CLOCK_FREQ))
178 #else /* rounded overflowing conversion */
179 #define VLC_TICK_FROM_MSFTIME(msft) (CLOCK_FREQ * (msft) / INT64_C(10000000))
180 #define MSFTIME_FROM_VLC_TICK(vtk) ((vtk) * INT64_C(10000000) / CLOCK_FREQ)
181 #endif /* CLOCK_FREQ / 10000000 */
182 
183 #define vlc_tick_from_timeval(tv) \
184  (vlc_tick_from_sec( (tv)->tv_sec ) + VLC_TICK_FROM_US( (tv)->tv_usec ))
185 
186 #define vlc_tick_from_timespec(tv) \
187  (vlc_tick_from_sec( (tv)->tv_sec ) + VLC_TICK_FROM_NS( (tv)->tv_nsec ))
188 
190 
191 
192 /*****************************************************************************
193  * MSTRTIME_MAX_SIZE: maximum possible size of vlc_tick_to_str
194  *****************************************************************************
195  * This values is the maximal possible size of the string returned by the
196  * vlc_tick_to_str() function, including '-' and the final '\0'. It should be
197  * used to allocate the buffer.
198  *****************************************************************************/
199 #define MSTRTIME_MAX_SIZE 22
200 
201 /*****************************************************************************
202  * Prototypes
203  *****************************************************************************/
204 
205 /**
206  * Convert seconds to a time in the format h:mm:ss.
207  *
208  * This function is provided for any interface function which need to print a
209  * time string in the format h:mm:ss
210  * date.
211  * \param ticks the time to be converted
212  * \param psz_buffer should be a buffer at least MSTRTIME_MAX_SIZE characters
213  * \return psz_buffer is returned so this can be used as printf parameter.
214  */
215 VLC_API char * vlc_tick_to_str( char *psz_buffer, vlc_tick_t ticks );
216 
217 /**
218  * \defgroup date Timestamps, error-free
219  * These functions support generating timestamps without long term rounding
220  * errors due to sample rate conversions.
221  * \ingroup input
222  * @{
223  */
224 /**
225  * Timestamps without long-term rounding errors
226  */
227 struct date_t
228 {
230  uint32_t i_divider_num;
231  uint32_t i_divider_den;
232  uint32_t i_remainder;
233 };
234 
235 /**
236  * Initializes a date_t.
237  *
238  * \param date date to initialize [OUT]
239  * \param num divider (sample rate) numerator
240  * \param den divider (sample rate) denominator
241  */
242 VLC_API void date_Init(date_t *restrict date, uint32_t num, uint32_t den);
243 
244 /**
245  * Changes the rate of a date_t.
246  *
247  * \param date date to change
248  * \param num divider (sample rate) numerator
249  * \param den divider (sample rate) denominator
250  */
251 VLC_API void date_Change(date_t *restrict date, uint32_t num, uint32_t den);
252 
253 /**
254  * Sets the exact timestamp of a date_t.
255  *
256  * \param date date to set the timestamp into
257  * \param value date value
258  */
259 static inline void date_Set(date_t *restrict date, vlc_tick_t value)
260 {
261  date->date = value;
262  date->i_remainder = 0;
263 }
264 
265 /**
266  * Gets the current timestamp from a date_t.
267  *
268  * \param date date to fetch the timestamp from
269  * \return date value
270  */
271 VLC_USED static inline vlc_tick_t date_Get(const date_t *restrict date)
272 {
273  return date->date;
274 }
275 
276 /**
277  * Increments a date.
278  *
279  * Moves the date_t timestamp forward by a given number of samples.
280  *
281  * \param date date to move forward
282  * \param count number of samples
283  * \return timestamp value after incrementing
284  */
285 VLC_API vlc_tick_t date_Increment(date_t *restrict date, uint32_t count);
286 
287 /**
288  * Decrements a date.
289  *
290  * Moves the date_t timestamp backward by a given number of samples.
291  *
292  * \param date date to move backward
293  * \param count number of samples
294  * \return date value
295  */
296 VLC_API vlc_tick_t date_Decrement(date_t *restrict date, uint32_t count);
297 
298 /** @} */
299 
300 /**
301  * @return NTP 64-bits timestamp in host byte order.
302  */
303 VLC_API uint64_t NTPtime64( void );
304 #endif /* !__VLC_MTIME_ */
size_t count
Definition: core.c:398
#define VLC_USED
Definition: fourcc_gen.c:32
#define VLC_API
Definition: fourcc_gen.c:31
static void date_Set(date_t *restrict date, vlc_tick_t value)
Sets the exact timestamp of a date_t.
Definition: vlc_tick.h:260
vlc_tick_t date_Increment(date_t *restrict date, uint32_t count)
Increments a date.
void date_Change(date_t *restrict date, uint32_t num, uint32_t den)
Changes the rate of a date_t.
void date_Init(date_t *restrict date, uint32_t num, uint32_t den)
Initializes a date_t.
static vlc_tick_t date_Get(const date_t *restrict date)
Gets the current timestamp from a date_t.
Definition: vlc_tick.h:272
vlc_tick_t date_Decrement(date_t *restrict date, uint32_t count)
Decrements a date.
Timestamps without long-term rounding errors.
Definition: vlc_tick.h:229
uint32_t i_divider_num
Definition: vlc_tick.h:231
uint32_t i_remainder
Definition: vlc_tick.h:233
vlc_tick_t date
Definition: vlc_tick.h:230
uint32_t i_divider_den
Definition: vlc_tick.h:232
Definition: vlc_fixups.h:76
long long rem
Definition: vlc_fixups.h:78
long long quot
Definition: vlc_fixups.h:77
Definition: vlc_fixups.h:421
#define CLOCK_FREQ
Definition: vlc_config.h:47
lldiv_t lldiv(long long, long long)
static vlc_tick_t vlc_tick_rate_duration(float frame_rate)
Definition: vlc_tick.h:95
uint64_t NTPtime64(void)
Definition: mtime.c:130
vlc_tick_t mtime_t
Definition: vlc_tick.h:46
int64_t vlc_tick_t
High precision date or time interval.
Definition: vlc_tick.h:45
static vlc_tick_t vlc_tick_from_samples(int64_t samples, int samp_rate)
Definition: vlc_tick.h:103
static vlc_tick_t vlc_tick_from_secf(double secf)
Definition: vlc_tick.h:78
struct timespec timespec_from_vlc_tick(vlc_tick_t date)
Definition: mtime.c:147
static vlc_tick_t vlc_tick_from_frac(uint64_t num, uint64_t den)
Definition: vlc_tick.h:113
#define vlc_tick_from_sec(sec)
Definition: vlc_tick.h:83
static double secf_from_vlc_tick(vlc_tick_t vtk)
Definition: vlc_tick.h:90
static int64_t samples_from_vlc_tick(vlc_tick_t t, int samp_rate)
Definition: vlc_tick.h:107
int64_t msftime_t
Definition: vlc_tick.h:168
static vlc_tick_t vlc_tick_from_seci(int64_t sec)
Definition: vlc_tick.h:73
char * vlc_tick_to_str(char *psz_buffer, vlc_tick_t ticks)
Convert seconds to a time in the format h:mm:ss.
Definition: mtime.c:41