vlc_mtime.h 4.98 KB
Newer Older
1
/*****************************************************************************
2 3
 * vlc_mtime.h: high resolution time management functions
 *****************************************************************************
Michel Kaempf's avatar
Michel Kaempf committed
4 5 6 7 8 9 10
 * This header provides portable high precision time management functions,
 * which should be the only ones used in other segments of the program, since
 * functions like gettimeofday() and ftime() are not always supported.
 * Most functions are declared as inline or as macros since they are only
 * interfaces to system calls and have to be called frequently.
 * 'm' stands for 'micro', since maximum resolution is the microsecond.
 * Functions prototyped are implemented in interface/mtime.c.
11
 *****************************************************************************
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
12
 * Copyright (C) 1996, 1997, 1998, 1999, 2000 VLC authors and VideoLAN
13
 * $Id$
14
 *
15
 * Authors: Vincent Seguin <seguin@via.ecp.fr>
16
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
17 18 19
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
20
 * (at your option) any later version.
21
 *
22 23
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
24 25
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
26
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
27 28 29
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
30 31
 *****************************************************************************/

32 33 34
#ifndef __VLC_MTIME_H
# define __VLC_MTIME_H 1

35 36 37 38 39 40 41 42 43 44 45 46 47
/**
 * High precision date or time interval
 *
 * Store a high precision date or time interval. The maximum precision is the
 * microsecond, and a 64 bits integer is used to avoid overflows (maximum
 * time interval is then 292271 years, which should be long enough for any
 * video). Dates are stored as microseconds since a common date (usually the
 * epoch). Note that date and time intervals can be manipulated using regular
 * arithmetic operators, and that no special functions are required.
 */
typedef int64_t vlc_tick_t;
typedef vlc_tick_t mtime_t; /* deprecated, use vlc_tick_t */

48
/*****************************************************************************
Michel Kaempf's avatar
Michel Kaempf committed
49
 * MSTRTIME_MAX_SIZE: maximum possible size of mstrtime
50
 *****************************************************************************
Michel Kaempf's avatar
Michel Kaempf committed
51
 * This values is the maximal possible size of the string returned by the
Michel Kaempf's avatar
Michel Kaempf committed
52 53
 * mstrtime() function, including '-' and the final '\0'. It should be used to
 * allocate the buffer.
54
 *****************************************************************************/
Michel Kaempf's avatar
Michel Kaempf committed
55
#define MSTRTIME_MAX_SIZE 22
Michel Kaempf's avatar
Michel Kaempf committed
56

57
/*****************************************************************************
Michel Kaempf's avatar
Michel Kaempf committed
58
 * Prototypes
59
 *****************************************************************************/
60
VLC_API char * secstotimestr( char *psz_buffer, int32_t secs );
Sam Hocevar's avatar
Sam Hocevar committed
61

62 63 64 65 66 67 68 69 70 71
/**
 * \defgroup date Timestamps, error-free
 * These functions support generating timestamps without long term rounding
 * errors due to sample rate conversions.
 * \ingroup input
 * @{
 */
/**
 * Timestamps without long-term rounding errors
 */
72 73
struct date_t
{
Steve Lhomme's avatar
Steve Lhomme committed
74
    vlc_tick_t  date;
75 76 77 78 79
    uint32_t i_divider_num;
    uint32_t i_divider_den;
    uint32_t i_remainder;
};

80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
/**
 * Initializes a date_t.
 *
 * \param date date to initialize [OUT]
 * \param num divider (sample rate) numerator
 * \param den divider (sample rate) denominator
 */
VLC_API void date_Init(date_t *restrict date, uint32_t num, uint32_t den);

/**
 * Changes the rate of a date_t.
 *
 * \param date date to change
 * \param num divider (sample rate) numerator
 * \param den divider (sample rate) denominator
 */
VLC_API void date_Change(date_t *restrict date, uint32_t num, uint32_t den);

/**
 * Sets the exact timestamp of a date_t.
 *
 * \param date date to set the timestamp into
 * \param value date value
 */
Steve Lhomme's avatar
Steve Lhomme committed
104
static inline void date_Set(date_t *restrict date, vlc_tick_t value)
105 106 107 108
{
    date->date = value;
    date->i_remainder = 0;
}
109 110 111 112 113 114 115

/**
 * Gets the current timestamp from a date_t.
 *
 * \param date date to fetch the timestamp from
 * \return date value
 */
Steve Lhomme's avatar
Steve Lhomme committed
116
VLC_USED static inline vlc_tick_t date_Get(const date_t *restrict date)
117 118 119
{
    return date->date;
}
120 121 122 123 124 125 126 127 128 129

/**
 * Increments a date.
 *
 * Moves the date_t timestamp forward by a given number of samples.
 *
 * \param date date to move forward
 * \param count number of samples
 * \return timestamp value after incrementing
 */
Steve Lhomme's avatar
Steve Lhomme committed
130
VLC_API vlc_tick_t date_Increment(date_t *restrict date, uint32_t count);
131 132 133 134 135 136 137 138 139 140

/**
 * Decrements a date.
 *
 * Moves the date_t timestamp backward by a given number of samples.
 *
 * \param date date to move backward
 * \param count number of samples
 * \return date value
 */
Steve Lhomme's avatar
Steve Lhomme committed
141
VLC_API vlc_tick_t date_Decrement(date_t *restrict date, uint32_t count);
142 143 144

/** @} */

145
VLC_API uint64_t NTPtime64( void );
146
#endif /* !__VLC_MTIME_ */