include/vlc_mtime.h

   1 /*****************************************************************************
   2  * vlc_mtime.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  * MSTRTIME_MAX_SIZE: maximum possible size of mstrtime
  37  *****************************************************************************
  38  * This values is the maximal possible size of the string returned by the
  39  * mstrtime() function, including '-' and the final '\0'. It should be used to
  40  * allocate the buffer.
  41  *****************************************************************************/
  42 #define MSTRTIME_MAX_SIZE 22
  43
  44 /*****************************************************************************
  45  * Prototypes
  46  *****************************************************************************/
  47 VLC_API char * secstotimestr( char *psz_buffer, int32_t secs );
  48
  49 /**
  50  * \defgroup date Timestamps, error-free
  51  * These functions support generating timestamps without long term rounding
  52  * errors due to sample rate conversions.
  53  * \ingroup input
  54  * @{
  55  */
  56 /**
  57  * Timestamps without long-term rounding errors
  58  */
  59 struct date_t
  60 {
  61     mtime_t  date;
  62     uint32_t i_divider_num;
  63     uint32_t i_divider_den;
  64     uint32_t i_remainder;
  65 };
  66
  67 /**
  68  * Initializes a date_t.
  69  *
  70  * \param date date to initialize [OUT]
  71  * \param num divider (sample rate) numerator
  72  * \param den divider (sample rate) denominator
  73  */
  74 VLC_API void date_Init(date_t *restrict date, uint32_t num, uint32_t den);
  75
  76 /**
  77  * Changes the rate of a date_t.
  78  *
  79  * \param date date to change
  80  * \param num divider (sample rate) numerator
  81  * \param den divider (sample rate) denominator
  82  */
  83 VLC_API void date_Change(date_t *restrict date, uint32_t num, uint32_t den);
  84
  85 /**
  86  * Sets the exact timestamp of a date_t.
  87  *
  88  * \param date date to set the timestamp into
  89  * \param value date value
  90  */
  91 static inline void date_Set(date_t *restrict date, mtime_t value)
  92 {
  93     date->date = value;
  94     date->i_remainder = 0;
  95 }
  96
  97 /**
  98  * Gets the current timestamp from a date_t.
  99  *
 100  * \param date date to fetch the timestamp from
 101  * \return date value
 102  */
 103 VLC_USED static inline mtime_t date_Get(const date_t *restrict date)
 104 {
 105     return date->date;
 106 }
 107
 108 /**
 109  * Increments a date.
 110  *
 111  * Moves the date_t timestamp forward by a given number of samples.
 112  *
 113  * \param date date to move forward
 114  * \param count number of samples
 115  * \return timestamp value after incrementing
 116  */
 117 VLC_API mtime_t date_Increment(date_t *restrict date, uint32_t count);
 118
 119 /**
 120  * Decrements a date.
 121  *
 122  * Moves the date_t timestamp backward by a given number of samples.
 123  *
 124  * \param date date to move backward
 125  * \param count number of samples
 126  * \return date value
 127  */
 128 VLC_API mtime_t date_Decrement(date_t *restrict date, uint32_t count);
 129
 130 /** @} */
 131
 132 VLC_API uint64_t NTPtime64( void );
 133 #endif /* !__VLC_MTIME_ */