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 CLOCK_H
21#define CLOCK_H
22
23#include <vlc_clock.h>
24
26{
31};
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 * This function creates the vlc_clock_main_t of the program
59 */
60vlc_clock_main_t *vlc_clock_main_New(struct vlc_logger *parent_logger, struct vlc_tracer *parent_tracer);
61
62/**
63 * Destroy the clock main
64 */
66
67/**
68 * Reset the vlc_clock_main_t
69 */
71
73 vlc_tick_t system_now, vlc_tick_t ts);
75 vlc_tick_t delay);
76
77/**
78 * This function sets the dejitter delay to absorb the clock jitter
79 *
80 * Also used as the maximum delay before the synchro is considered to kick in.
81 */
83
84
85/**
86 * This function allows changing the pause status.
87 */
89 bool paused);
90
91/**
92 * This function creates a new master vlc_clock_t interface
93 *
94 * @warning There can be only one master at a given time.
95 *
96 * You must use vlc_clock_Delete to free it.
97 */
99 const char *track_str_id,
100 const struct vlc_clock_cbs *cbs,
101 void *cbs_data);
102
103/**
104 * This function creates a new input master vlc_clock_t interface
105 *
106 * Once the input master is created, the current or future master clock created
107 * from vlc_clock_main_CreateMaster() will be demoted as slave.
108 *
109 * @warning There can be only one input master at a given time.
110 *
111 * You must use vlc_clock_Delete to free it.
112 */
114
115/**
116 * This function creates a new slave vlc_clock_t interface
117 *
118 * You must use vlc_clock_Delete to free it.
119 */
121 const char *track_str_id,
122 enum es_format_category_e cat,
123 const struct vlc_clock_cbs *cbs,
124 void *cbs_data);
125
126/**
127 * This function creates a new slave vlc_clock_t interface
128 *
129 * You must use vlc_clock_Delete to free it.
130 */
132 enum es_format_category_e cat);
133
134/**
135 * This function free the resources allocated by vlc_clock*Create*()
136 */
137void vlc_clock_Delete(vlc_clock_t *clock);
138
139/**
140 * This function will update the clock drift and returns the drift
141 *
142 * @param clock the clock setter to update
143 * @param system_now valid system time or VLC_TICK_MAX is the updated point is
144 * forced (when paused for example)
145 * @param ts the timestamp in media time for the updated point
146 * @param rate the current playback speed
147 *
148 * @return a valid drift relative time, VLC_TICK_INVALID if there is no drift
149 * (clock is master) or VLC_TICK_MAX if the clock is paused
150 */
152 vlc_tick_t ts, double rate);
153
154/**
155 * This function will update the video clock drift and returns the drift
156 *
157 * Same behavior than vlc_clock_Update() except that the video is passed to the
158 * clock, this will be used for clock update callbacks.
159 */
161 vlc_tick_t ts, double rate,
162 unsigned frame_rate, unsigned frame_rate_base);
163
164/**
165 * This function resets the clock drift
166 */
167void vlc_clock_Reset(vlc_clock_t *clock);
168
169/**
170 * This functions change the clock delay
171 *
172 * It returns the amount of time the clock owner need to wait in order to reach
173 * the time introduced by the new positive delay.
174 */
176
177/**
178 * Lock the clock mutex
179 */
180void vlc_clock_Lock(vlc_clock_t *clock);
181
182/**
183 * Unlock the clock mutex
184 */
185void vlc_clock_Unlock(vlc_clock_t *clock);
186
187/**
188 * Indicate if the clock is paused
189 *
190 * The clock mutex must be locked.
191 *
192 * @retval true if the clock is paused
193 * @retval false if the clock is not paused
194 */
196
197/**
198 * Wait for a timestamp expressed in system time
199 *
200 * The wait will be interrupted (signaled) on clock state changes which could
201 * invalidate the computed deadline. In that case, the caller must recompute
202 * the new deadline and call it again.
203 *
204 * The clock mutex must be locked.
205 *
206 * @return 0 if the condition was signaled, an error code in case of timeout
207 */
208int vlc_clock_Wait(vlc_clock_t *clock, vlc_tick_t system_deadline);
209
210/**
211 * Wake up any vlc_clock_Wait()
212 */
213void vlc_clock_Wake(vlc_clock_t *clock);
214
215/**
216 * This function converts a timestamp from stream to system
217 *
218 * The clock mutex must be locked.
219 *
220 * @return the valid system time or VLC_TICK_MAX when the clock is paused
221 */
223 vlc_tick_t system_now, vlc_tick_t ts,
224 double rate);
225
226static inline vlc_tick_t
228 vlc_tick_t ts, double rate)
229{
230 vlc_clock_Lock(clock);
231 vlc_tick_t system =
232 vlc_clock_ConvertToSystemLocked(clock, system_now, ts, rate);
233 vlc_clock_Unlock(clock);
234 return system;
235}
236
237#endif /*CLOCK_H*/
void vlc_clock_Unlock(vlc_clock_t *clock)
Unlock the clock mutex.
Definition: clock.c:399
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:552
void vlc_clock_main_Delete(vlc_clock_main_t *main_clock)
Destroy the clock main.
Definition: clock.c:538
void vlc_clock_main_Reset(vlc_clock_main_t *main_clock)
Reset the vlc_clock_main_t.
Definition: clock.c:469
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:664
void vlc_clock_Delete(vlc_clock_t *clock)
This function free the resources allocated by vlc_clock*Create*()
Definition: clock.c:706
void vlc_clock_Lock(vlc_clock_t *clock)
Lock the clock mutex.
Definition: clock.c:393
bool vlc_clock_IsPaused(vlc_clock_t *clock)
Indicate if the clock is paused.
Definition: clock.c:411
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:546
void vlc_clock_Reset(vlc_clock_t *clock)
This function resets the clock drift.
Definition: clock.c:559
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:569
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:638
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:508
int vlc_clock_Wait(vlc_clock_t *clock, vlc_tick_t system_deadline)
Wait for a timestamp expressed in system time.
Definition: clock.c:419
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:613
void vlc_clock_main_SetFirstPcr(vlc_clock_main_t *main_clock, vlc_tick_t system_now, vlc_tick_t ts)
Definition: clock.c:478
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:433
void vlc_clock_Wake(vlc_clock_t *clock)
Wake up any vlc_clock_Wait()
Definition: clock.c:427
void vlc_clock_main_SetInputDejitter(vlc_clock_main_t *main_clock, vlc_tick_t delay)
Definition: clock.c:492
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:700
vlc_tick_t vlc_clock_SetDelay(vlc_clock_t *clock, vlc_tick_t ts_delay)
This functions change the clock delay.
Definition: clock.c:564
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:500
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:227
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
Definition: clock.c:35
Definition: clock.c:67
Definition: messages.c:85
Definition: tracer.c:36
es_format_category_e
ES Categories.
Definition: vlc_es.h:617
int64_t vlc_tick_t
High precision date or time interval.
Definition: vlc_tick.h:47