VLC  4.0.0-dev
clock.h
Go to the documentation of this file.
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 
24 {
29 };
30 
31 typedef struct vlc_clock_main_t vlc_clock_main_t;
32 typedef struct vlc_clock_t vlc_clock_t;
33 
34 /**
35  * Callbacks for the owner of the main clock
36  */
38 {
39  /**
40  * Called when a clock is updated
41  *
42  * @param system_ts system date when the ts will be rendered,
43  * VLC_TICK_INVALID when the clock is reset or VLC_TICK_MAX when the update
44  * is forced (an output was still rendered while paused for example). Note:
45  * when valid, this date can be in the future, it is not necessarily now.
46  * @param ts stream timestamp or VLC_TICK_INVALID when the clock is reset,
47  * should be subtracted with VLC_TICK_0 to get the original value
48  * @param rate rate used when updated
49  * @param frame_rate fps of the video owning the clock
50  * @param frame_rate_base fps denominator
51  * @param data opaque pointer set from vlc_clock_main_New()
52  */
53  void (*on_update)(vlc_tick_t system_ts, vlc_tick_t ts, double rate,
54  unsigned frame_rate, unsigned frame_rate_base,
55  void *data);
56 };
57 
58 /**
59  * This function creates the vlc_clock_main_t of the program
60  */
61 vlc_clock_main_t *vlc_clock_main_New(struct vlc_logger *parent_logger, struct vlc_tracer *parent_tracer);
62 
63 /**
64  * Destroy the clock main
65  */
66 void vlc_clock_main_Delete(vlc_clock_main_t *main_clock);
67 
68 /**
69  * Reset the vlc_clock_main_t
70  */
71 void vlc_clock_main_Reset(vlc_clock_main_t *main_clock);
72 
74  vlc_tick_t system_now, vlc_tick_t ts);
76  vlc_tick_t delay);
77 
78 /**
79  * This function sets the dejitter delay to absorb the clock jitter
80  *
81  * Also used as the maximum delay before the synchro is considered to kick in.
82  */
83 void vlc_clock_main_SetDejitter(vlc_clock_main_t *main_clock, vlc_tick_t dejitter);
84 
85 
86 /**
87  * This function allows changing the pause status.
88  */
90  bool paused);
91 
92 /**
93  * This function creates a new master vlc_clock_t interface
94  *
95  * @warning There can be only one master at a given time.
96  *
97  * You must use vlc_clock_Delete to free it.
98  */
100  const char *track_str_id,
101  const struct vlc_clock_cbs *cbs,
102  void *cbs_data);
103 
104 /**
105  * This function creates a new input master vlc_clock_t interface
106  *
107  * Once the input master is created, the current or future master clock created
108  * from vlc_clock_main_CreateMaster() will be demoted as slave.
109  *
110  * @warning There can be only one input master at a given time.
111  *
112  * You must use vlc_clock_Delete to free it.
113  */
115 
116 /**
117  * This function creates a new slave vlc_clock_t interface
118  *
119  * You must use vlc_clock_Delete to free it.
120  */
122  const char *track_str_id,
123  enum es_format_category_e cat,
124  const struct vlc_clock_cbs *cbs,
125  void *cbs_data);
126 
127 /**
128  * This function creates a new slave vlc_clock_t interface
129  *
130  * You must use vlc_clock_Delete to free it.
131  */
133  enum es_format_category_e cat);
134 
135 /**
136  * This function free the resources allocated by vlc_clock*Create*()
137  */
138 void vlc_clock_Delete(vlc_clock_t *clock);
139 
140 /**
141  * This function will update the clock drift and returns the drift
142  * @param system_now valid system time or VLC_TICK_MAX is the updated point is
143  * forced (when paused for example)
144  * @return a valid drift relative time, VLC_TICK_INVALID if there is no drift
145  * (clock is master) or VLC_TICK_MAX if the clock is paused
146  */
148  vlc_tick_t ts, double rate);
149 
150 /**
151  * This function will update the video clock drift and returns the drift
152  *
153  * Same behavior than vlc_clock_Update() except that the video is passed to the
154  * clock, this will be used for clock update callbacks.
155  */
157  vlc_tick_t ts, double rate,
158  unsigned frame_rate, unsigned frame_rate_base);
159 
160 /**
161  * This function resets the clock drift
162  */
163 void vlc_clock_Reset(vlc_clock_t *clock);
164 
165 /**
166  * This functions change the clock delay
167  *
168  * It returns the amount of time the clock owner need to wait in order to reach
169  * the time introduced by the new positive delay.
170  */
172 
173 /**
174  * Lock the clock mutex
175  */
176 void vlc_clock_Lock(vlc_clock_t *clock);
177 
178 /**
179  * Unlock the clock mutex
180  */
181 void vlc_clock_Unlock(vlc_clock_t *clock);
182 
183 /**
184  * Indicate if the clock is paused
185  *
186  * The clock mutex must be locked.
187  *
188  * @retval true if the clock is paused
189  * @retval false if the clock is not paused
190  */
191 bool vlc_clock_IsPaused(vlc_clock_t *clock);
192 
193 /**
194  * Wait for a timestamp expressed in system time
195  *
196  * The wait will be interrupted (signaled) on clock state changes which could
197  * invalidate the computed deadline. In that case, the caller must recompute
198  * the new deadline and call it again.
199  *
200  * The clock mutex must be locked.
201  *
202  * @return 0 if the condition was signaled, an error code in case of timeout
203  */
204 int vlc_clock_Wait(vlc_clock_t *clock, vlc_tick_t system_deadline);
205 
206 /**
207  * Wake up any vlc_clock_Wait()
208  */
209 void vlc_clock_Wake(vlc_clock_t *clock);
210 
211 /**
212  * This function converts a timestamp from stream to system
213  *
214  * The clock mutex must be locked.
215  *
216  * @return the valid system time or VLC_TICK_MAX when the clock is paused
217  */
219  vlc_tick_t system_now, vlc_tick_t ts,
220  double rate);
221 
222 static inline vlc_tick_t
224  vlc_tick_t ts, double rate)
225 {
226  vlc_clock_Lock(clock);
227  vlc_tick_t system =
228  vlc_clock_ConvertToSystemLocked(clock, system_now, ts, rate);
229  vlc_clock_Unlock(clock);
230  return system;
231 }
232 
233 #endif /*VLC_CLOCK_H*/
void vlc_clock_Unlock(vlc_clock_t *clock)
Unlock the clock mutex.
Definition: clock.c:363
vlc_tick_t vlc_clock_UpdateVideo(vlc_clock_t *clock, vlc_tick_t system_now, vlc_tick_t ts, double rate, unsigned frame_rate, unsigned frame_rate_base)
This function will update the video clock drift and returns the drift.
Definition: clock.c:519
void vlc_clock_main_Delete(vlc_clock_main_t *main_clock)
Destroy the clock main.
Definition: clock.c:506
void vlc_clock_main_Reset(vlc_clock_main_t *main_clock)
Reset the vlc_clock_main_t.
Definition: clock.c:437
void vlc_clock_Delete(vlc_clock_t *clock)
This function free the resources allocated by vlc_clock*Create*()
Definition: clock.c:673
void vlc_clock_Lock(vlc_clock_t *clock)
Lock the clock mutex.
Definition: clock.c:357
bool vlc_clock_IsPaused(vlc_clock_t *clock)
Indicate if the clock is paused.
Definition: clock.c:375
vlc_tick_t vlc_clock_Update(vlc_clock_t *clock, vlc_tick_t system_now, vlc_tick_t ts, double rate)
This function will update the clock drift and returns the drift.
Definition: clock.c:513
void vlc_clock_Reset(vlc_clock_t *clock)
This function resets the clock drift.
Definition: clock.c:526
vlc_tick_t vlc_clock_ConvertToSystemLocked(vlc_clock_t *clock, vlc_tick_t system_now, vlc_tick_t ts, double rate)
This function converts a timestamp from stream to system.
Definition: clock.c:536
void vlc_clock_main_ChangePause(vlc_clock_main_t *clock, vlc_tick_t system_now, bool paused)
This function allows changing the pause status.
Definition: clock.c:476
int vlc_clock_Wait(vlc_clock_t *clock, vlc_tick_t system_deadline)
Wait for a timestamp expressed in system time.
Definition: clock.c:383
vlc_clock_t * vlc_clock_CreateSlave(const vlc_clock_t *clock, enum es_format_category_e cat)
This function creates a new slave vlc_clock_t interface.
Definition: clock.c:667
vlc_clock_t * vlc_clock_main_CreateSlave(vlc_clock_main_t *main_clock, const char *track_str_id, enum es_format_category_e cat, const struct vlc_clock_cbs *cbs, void *cbs_data)
This function creates a new slave vlc_clock_t interface.
Definition: clock.c:631
vlc_clock_master_source
Definition: clock.h:24
@ VLC_CLOCK_MASTER_INPUT
Definition: clock.h:27
@ VLC_CLOCK_MASTER_MONOTONIC
Definition: clock.h:28
@ VLC_CLOCK_MASTER_AUTO
Definition: clock.h:25
@ VLC_CLOCK_MASTER_AUDIO
Definition: clock.h:26
void vlc_clock_main_SetFirstPcr(vlc_clock_main_t *main_clock, vlc_tick_t system_now, vlc_tick_t ts)
Definition: clock.c:446
void vlc_clock_Wake(vlc_clock_t *clock)
Wake up any vlc_clock_Wait()
Definition: clock.c:391
void vlc_clock_main_SetInputDejitter(vlc_clock_main_t *main_clock, vlc_tick_t delay)
Definition: clock.c:460
vlc_clock_main_t * vlc_clock_main_New(struct vlc_logger *parent_logger, struct vlc_tracer *parent_tracer)
This function creates the vlc_clock_main_t of the program.
Definition: clock.c:397
vlc_tick_t vlc_clock_SetDelay(vlc_clock_t *clock, vlc_tick_t ts_delay)
This functions change the clock delay.
Definition: clock.c:531
void vlc_clock_main_SetDejitter(vlc_clock_main_t *main_clock, vlc_tick_t dejitter)
This function sets the dejitter delay to absorb the clock jitter.
Definition: clock.c:468
static vlc_tick_t vlc_clock_ConvertToSystem(vlc_clock_t *clock, vlc_tick_t system_now, vlc_tick_t ts, double rate)
Definition: clock.h:223
vlc_clock_t * vlc_clock_main_CreateMaster(vlc_clock_main_t *main_clock, const char *track_str_id, const struct vlc_clock_cbs *cbs, void *cbs_data)
This function creates a new master vlc_clock_t interface.
Definition: clock.c:580
vlc_clock_t * vlc_clock_main_CreateInputMaster(vlc_clock_main_t *main_clock)
This function creates a new input master vlc_clock_t interface.
Definition: clock.c:605
Callbacks for the owner of the main clock.
Definition: clock.h:38
void(* on_update)(vlc_tick_t system_ts, vlc_tick_t ts, double rate, unsigned frame_rate, unsigned frame_rate_base, void *data)
Called when a clock is updated.
Definition: clock.h:53
Definition: clock.c:33
Definition: clock.c:65
Definition: messages.c:54
Definition: tracer.c:36
es_format_category_e
ES Categories.
Definition: vlc_es.h:602
int64_t vlc_tick_t
High precision date or time interval.
Definition: vlc_tick.h:45