VLC 4.0.0-dev
Loading...
Searching...
No Matches
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 CLOCK_H
21#define CLOCK_H
22
23#include <vlc_clock.h>
24
32
33/**
34 * Callbacks for the owner of the main clock
35 */
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 VLC_TICK_MAX when the update
43 * is 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 * Event callbacks for the user of a vlc_clock_t
59 */
61{
62 /**
63 * Called when the master source triggered a discontinuity.
64 *
65 * A discontinuity happens when:
66 * - The first point is updated from the master source
67 *
68 * @param data opaque pointer set from vlc_clock_main_New()
69 */
70 void (*on_discontinuity)(void *data);
71};
72
74
75/**
76 * This function creates the vlc_clock_main_t of the program
77 */
78vlc_clock_main_t *vlc_clock_main_New(struct vlc_logger *parent_logger, struct vlc_tracer *parent_tracer);
79
80/**
81 * Destroy the clock main
82 *
83 * @param main_clock the unlocked main_clock
84 */
86
87/**
88 * Lock the main_clock mutex
89 *
90 * All vlc_clock_main_t functions must be called with the lock held, except
91 * vlc_clock_main_Delete()
92 *
93 * @param main_clock the unlocked main_clock
94 */
96
97/**
98 * Unlock the main_clock mutex
99 *
100 * @param main_clock the locked main_clock
101 */
103
104/**
105 * Reset the vlc_clock_main_t
106 *
107 * @param main_clock the locked main_clock
108 */
109void vlc_clock_main_Reset(vlc_clock_main_t *main_clock);
110
111/**
112 * Set the first PCR point
113 *
114 * @param main_clock the locked main_clock
115 */
117 vlc_tick_t system_now, vlc_tick_t ts);
118
119/**
120 * Set the input dejitter
121 *
122 * @param main_clock the locked main_clock
123 */
125 vlc_tick_t delay);
126
127/**
128 * This function sets the dejitter delay to absorb the clock jitter
129 *
130 * Also used as the maximum delay before the synchro is considered to kick in.
131 *
132 * @param main_clock the locked main_clock
133 */
134void vlc_clock_main_SetDejitter(vlc_clock_main_t *main_clock, vlc_tick_t dejitter);
135
136
137/**
138 * This function allows changing the pause status.
139 *
140 * @param main_clock the locked main_clock
141 */
143 bool paused);
144
145/**
146 * This function creates a new master vlc_clock_t interface
147 *
148 * @warning There can be only one master at a given time.
149 *
150 * You must use vlc_clock_Delete to free it.
151 *
152 * @param main_clock the locked main_clock
153 */
155 const char *track_str_id,
156 const struct vlc_clock_cbs *cbs,
157 void *cbs_data);
158
159/**
160 * This function creates a new input master vlc_clock_t interface
161 *
162 * Once the input master is created, the current or future master clock created
163 * from vlc_clock_main_CreateMaster() will be demoted as slave.
164 *
165 * @warning There can be only one input master at a given time.
166 *
167 * You must use vlc_clock_Delete to free it.
168 *
169 * @param main_clock the locked main_clock
170 */
172
173/**
174 * This function creates a new slave vlc_clock_t interface
175 *
176 * You must use vlc_clock_Delete to free it.
177 *
178 * @param main_clock the locked main_clock
179 */
181 const char *track_str_id,
182 enum es_format_category_e cat,
183 const struct vlc_clock_cbs *cbs,
184 void *cbs_data);
185
186/**
187 * This function creates a new slave vlc_clock_t interface
188 *
189 * You must use vlc_clock_Delete to free it.
190 *
191 * @param main_clock the locked main_clock
192 */
194 enum es_format_category_e cat);
195
196/**
197 * This function free the resources allocated by vlc_clock*Create*()
198 *
199 * @param clock the unlocked clock used by the source
200 */
202
203/**
204 * This function will update the clock drift and returns the drift
205 *
206 * @param clock the locked clock used by the source
207 * @param system_now valid system time or VLC_TICK_MAX is the updated point is
208 * forced (when paused for example)
209 * @param ts the timestamp in media time for the updated point
210 * @param rate the current playback speed
211 *
212 * @return a valid drift relative time, VLC_TICK_INVALID if there is no drift
213 * (clock is master)
214 */
216 vlc_tick_t ts, double rate);
217
218/**
219 * This function will update the video clock drift and returns the drift
220 *
221 * Same behavior than vlc_clock_Update() except that the video is passed to the
222 * clock, this will be used for clock update callbacks.
223 */
225 vlc_tick_t ts, double rate,
226 unsigned frame_rate, unsigned frame_rate_base);
227
228/**
229 * This function resets the clock drift
230 *
231 * @param clock the locked clock used by the source
232 */
234
235/**
236 * This functions change the clock delay
237 *
238 * It returns the amount of time the clock owner need to wait in order to reach
239 * the time introduced by the new positive delay.
240 *
241 * @param clock the locked clock used by the source
242 */
244
245/**
246 * Lock the clock mutex
247 *
248 * @param clock the unlocked clock used by the source
249 */
251
252/**
253 * Unlock the clock mutex
254 *
255 * @param clock the locked clock used by the source
256 */
258
259/**
260 * Indicate if the clock is paused
261 *
262 * The clock mutex must be locked.
263 *
264 * @param clock the locked clock used by the source
265 * @retval true if the clock is paused
266 * @retval false if the clock is not paused
267 */
269
270/**
271 * Wait for a timestamp expressed in system time
272 *
273 * The wait will be interrupted (signaled) on clock state changes which could
274 * invalidate the computed deadline. In that case, the caller must recompute
275 * the new deadline and call it again.
276 *
277 * @param clock the locked clock used by the source
278 * @return 0 if the condition was signaled, an error code in case of timeout
279 */
280int vlc_clock_Wait(vlc_clock_t *clock, vlc_tick_t system_deadline);
281
282/**
283 * Wake up any vlc_clock_Wait()
284 *
285 * @param clock the locked clock used by the source
286 */
288
289/**
290 * Add a listener for events
291 *
292 * @param clock the locked clock used by the source
293 * @param cbs valid pointer to register events
294 * @param data opaque data used by cbs
295 * @return a valid listener id, or NULL in case of allocation error
296 */
299 const struct vlc_clock_event_cbs *cbs,
300 void *data);
301
302/**
303 * Remove a event listener callback
304 *
305 * @param clock the locked clock used by the source
306 * @param listener_id listener id returned by vlc_clock_AddListener()
307 */
308void
310
311/**
312 * This function converts a timestamp from stream to system
313 *
314 * @param clock the locked clock used by the source
315 * @return the valid system time
316 */
318 vlc_tick_t system_now, vlc_tick_t ts,
319 double rate);
320
321#endif /*CLOCK_H*/
void vlc_clock_Unlock(vlc_clock_t *clock)
Unlock the clock mutex.
Definition clock.c:506
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:680
void vlc_clock_main_Delete(vlc_clock_main_t *main_clock)
Destroy the clock main.
Definition clock.c:650
void vlc_clock_main_Reset(vlc_clock_main_t *main_clock)
Reset the vlc_clock_main_t.
Definition clock.c:580
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:794
void vlc_clock_Delete(vlc_clock_t *clock)
This function free the resources allocated by vlc_clock*Create*()
Definition clock.c:836
void vlc_clock_Lock(vlc_clock_t *clock)
Lock the clock mutex.
Definition clock.c:500
bool vlc_clock_IsPaused(vlc_clock_t *clock)
Indicate if the clock is paused.
Definition clock.c:518
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:673
void vlc_clock_Reset(vlc_clock_t *clock)
This function resets the clock drift.
Definition clock.c:688
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:768
void vlc_clock_main_Unlock(vlc_clock_main_t *main_clock)
Unlock the main_clock mutex.
Definition clock.c:667
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:619
int vlc_clock_Wait(vlc_clock_t *clock, vlc_tick_t system_deadline)
Wait for a timestamp expressed in system time.
Definition clock.c:526
vlc_clock_master_source
Definition clock.h:26
@ VLC_CLOCK_MASTER_INPUT
Definition clock.h:29
@ VLC_CLOCK_MASTER_MONOTONIC
Definition clock.h:30
@ VLC_CLOCK_MASTER_AUTO
Definition clock.h:27
@ VLC_CLOCK_MASTER_AUDIO
Definition clock.h:28
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:743
void vlc_clock_main_SetFirstPcr(vlc_clock_main_t *main_clock, vlc_tick_t system_now, vlc_tick_t ts)
Set the first PCR point.
Definition clock.c:589
vlc_tick_t vlc_clock_ConvertToSystem(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:700
void vlc_clock_RemoveListener(vlc_clock_t *clock, vlc_clock_listener_id *listener_id)
Remove a event listener callback.
Definition clock.c:130
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:542
void vlc_clock_Wake(vlc_clock_t *clock)
Wake up any vlc_clock_Wait()
Definition clock.c:534
void vlc_clock_main_Lock(vlc_clock_main_t *main_clock)
Lock the main_clock mutex.
Definition clock.c:662
void vlc_clock_main_SetInputDejitter(vlc_clock_main_t *main_clock, vlc_tick_t delay)
Set the input dejitter.
Definition clock.c:603
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:830
vlc_tick_t vlc_clock_SetDelay(vlc_clock_t *clock, vlc_tick_t ts_delay)
This functions change the clock delay.
Definition clock.c:694
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:611
vlc_clock_listener_id * vlc_clock_AddListener(vlc_clock_t *clock, const struct vlc_clock_event_cbs *cbs, void *data)
Add a listener for events.
Definition clock.c:104
Callbacks for the owner of the main clock.
Definition clock.h:37
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:52
Event callbacks for the user of a vlc_clock_t.
Definition clock.h:61
void(* on_discontinuity)(void *data)
Called when the master source triggered a discontinuity.
Definition clock.h:70
Definition clock.c:40
void * data
Definition clock.c:43
const struct vlc_clock_event_cbs * cbs
Definition clock.c:42
vlc_clock_t * clock
Definition clock.c:41
Definition clock.c:47
Definition clock.c:92
Definition messages.c:85
Definition tracer.c:36
es_format_category_e
ES Categories.
Definition vlc_es.h:616
int64_t vlc_tick_t
High precision date or time interval.
Definition vlc_tick.h:48