src/clock/clock.h

   1 /*****************************************************************************
   2  * clock.h: Output modules synchronisation clock
   3  *****************************************************************************
   4  * Copyright (C) 2018-2019 VLC authors, VideoLAN and Videolabs SAS
   5  *
   6  * This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU Lesser General Public License as published by
   8  * the Free Software Foundation; either version 2.1 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  * GNU Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public License
  17  * along with this program; if not, write to the Free Software Foundation,
  18  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  19  *****************************************************************************/
  20 #ifndef VLC_CLOCK_H
  21 #define VLC_CLOCK_H
  22
  23 enum vlc_clock_master_source
  24 {
  25     VLC_CLOCK_MASTER_AUDIO = 0,
  26     VLC_CLOCK_MASTER_MONOTONIC,
  27     VLC_CLOCK_MASTER_DEFAULT = VLC_CLOCK_MASTER_AUDIO,
  28 };
  29
  30 typedef struct vlc_clock_main_t vlc_clock_main_t;
  31 typedef struct vlc_clock_t vlc_clock_t;
  32
  33 /**
  34  * Callbacks for the owner of the main clock
  35  */
  36 struct vlc_clock_cbs
  37 {
  38     /**
  39      * Called when a clock is updated
  40      *
  41      * @param system_ts system date when the ts will be rendered,
  42      * VLC_TICK_INVALID when the clock is reset or INT64_MAX when the update is
  43      * forced (an output was still rendered while paused for example). Note:
  44      * when valid, this date can be in the future, it is not necessarily now.
  45      * @param ts stream timestamp or VLC_TICK_INVALID when the clock is reset,
  46      * should be subtracted with VLC_TICK_0 to get the original value
  47      * @param rate rate used when updated
  48      * @param frame_rate fps of the video owning the clock
  49      * @param frame_rate_base fps denominator
  50      * @param data opaque pointer set from vlc_clock_main_New()
  51      */
  52     void (*on_update)(vlc_tick_t system_ts, vlc_tick_t ts, double rate,
  53                       unsigned frame_rate, unsigned frame_rate_base,
  54                       void *data);
  55 };
  56
  57 /**
  58  * This function creates the vlc_clock_main_t of the program
  59  */
  60 vlc_clock_main_t *vlc_clock_main_New(void);
  61
  62 /**
  63  * Destroy the clock main
  64  */
  65 void vlc_clock_main_Delete(vlc_clock_main_t *main_clock);
  66
  67 /**
  68  * Abort all the pending vlc_clock_Wait
  69  */
  70 void vlc_clock_main_Abort(vlc_clock_main_t *main_clock);
  71
  72 /**
  73  * Reset the vlc_clock_main_t
  74  */
  75 void vlc_clock_main_Reset(vlc_clock_main_t *main_clock);
  76
  77 void vlc_clock_main_SetFirstPcr(vlc_clock_main_t *main_clock,
  78                                 vlc_tick_t system_now, vlc_tick_t ts);
  79 void vlc_clock_main_SetInputDejitter(vlc_clock_main_t *main_clock,
  80                                      vlc_tick_t delay);
  81
  82 /**
  83  * This function sets the dejitter delay to absorb the clock jitter
  84  *
  85  * Also used as the maximum delay before the synchro is considered to kick in.
  86  */
  87 void vlc_clock_main_SetDejitter(vlc_clock_main_t *main_clock, vlc_tick_t dejitter);
  88
  89
  90 /**
  91  * This function allows changing the pause status.
  92  */
  93 void vlc_clock_main_ChangePause(vlc_clock_main_t *clock, vlc_tick_t system_now,
  94                                 bool paused);
  95
  96 /**
  97  * This function set the allocated interface as the master making the current
  98  * master if any a slave.
  99  */
 100 void vlc_clock_main_SetMaster(vlc_clock_main_t *main_clock, vlc_clock_t *clock);
 101
 102 /**
 103  * This function creates a new master vlc_clock_t interface
 104  *
 105  * You must use vlc_clock_Delete to free it.
 106  */
 107 vlc_clock_t *vlc_clock_main_CreateMaster(vlc_clock_main_t *main_clock,
 108                                          const struct vlc_clock_cbs *cbs,
 109                                          void *cbs_data);
 110
 111 /**
 112  * This function creates a new slave vlc_clock_t interface
 113  *
 114  * You must use vlc_clock_Delete to free it.
 115  */
 116 vlc_clock_t *vlc_clock_main_CreateSlave(vlc_clock_main_t *main_clock,
 117                                         enum es_format_category_e cat,
 118                                         const struct vlc_clock_cbs *cbs,
 119                                         void *cbs_data);
 120
 121 /**
 122  * This function creates a new slave vlc_clock_t interface
 123  *
 124  * You must use vlc_clock_Delete to free it.
 125  */
 126 vlc_clock_t *vlc_clock_CreateSlave(const vlc_clock_t *clock,
 127                                    enum es_format_category_e cat);
 128
 129 /**
 130  * This function free the resources allocated by vlc_clock*Create*()
 131  */
 132 void vlc_clock_Delete(vlc_clock_t *clock);
 133
 134 /**
 135  * This function will update the clock drift and returns the drift
 136  * @param system_now valid system time or INT64_MAX is the updated point is
 137  * forced (when paused for example)
 138  * @return a valid drift relative time, VLC_TICK_INVALID if there is no drift
 139  * (clock is master) or INT64_MAX if the clock is paused
 140  */
 141 vlc_tick_t vlc_clock_Update(vlc_clock_t *clock, vlc_tick_t system_now,
 142                             vlc_tick_t ts, double rate);
 143
 144 /**
 145  * This function will update the video clock drift and returns the drift
 146  *
 147  * Same behavior than vlc_clock_Update() except that the video is passed to the
 148  * clock, this will be used for clock update callbacks.
 149  */
 150 vlc_tick_t vlc_clock_UpdateVideo(vlc_clock_t *clock, vlc_tick_t system_now,
 151                                  vlc_tick_t ts, double rate,
 152                                  unsigned frame_rate, unsigned frame_rate_base);
 153
 154 /**
 155  * This function resets the clock drift
 156  */
 157 void vlc_clock_Reset(vlc_clock_t *clock);
 158
 159 /**
 160  * This functions change the clock delay
 161  *
 162  * It returns the amount of time the clock owner need to wait in order to reach
 163  * the time introduced by the new positive delay.
 164  */
 165 vlc_tick_t vlc_clock_SetDelay(vlc_clock_t *clock, vlc_tick_t ts_delay);
 166
 167 /**
 168  * Wait for a timestamp expressed in stream time
 169  */
 170 int vlc_clock_Wait(vlc_clock_t *clock, vlc_tick_t system_now, vlc_tick_t ts,
 171                    double rate, vlc_tick_t max_duration);
 172
 173 /**
 174  * This function converts a timestamp from stream to system
 175  * @return the valid system time or INT64_MAX when the clock is paused
 176  */
 177 vlc_tick_t vlc_clock_ConvertToSystem(vlc_clock_t *clock, vlc_tick_t system_now,
 178                                      vlc_tick_t ts, double rate);
 179
 180 /**
 181  * This functon converts an array of timestamp from stream to system
 182  */
 183 void vlc_clock_ConvertArrayToSystem(vlc_clock_t *clock, vlc_tick_t system_now,
 184                                     vlc_tick_t *ts_array, size_t ts_count,
 185                                     double rate);
 186
 187 #endif /*VLC_CLOCK_H*/