blob: 7ba99d5d861515cec4b53b370ecd2d558bcc6dda
1 | /* |
2 | * Copyright (c) 2013 Nicolas George |
3 | * |
4 | * This file is part of FFmpeg. |
5 | * |
6 | * FFmpeg is free software; you can redistribute it and/or |
7 | * modify it under the terms of the GNU Lesser General Public License |
8 | * as published by the Free Software Foundation; either |
9 | * version 2.1 of the License, or (at your option) any later version. |
10 | * |
11 | * FFmpeg 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 FFmpeg; if not, write to the Free Software Foundation, Inc., |
18 | * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
19 | */ |
20 | |
21 | #ifndef AVFILTER_FRAMESYNC_H |
22 | #define AVFILTER_FRAMESYNC_H |
23 | |
24 | #include "bufferqueue.h" |
25 | |
26 | /* |
27 | * TODO |
28 | * Callback-based API similar to dualinput. |
29 | * Export convenient options. |
30 | */ |
31 | |
32 | /** |
33 | * This API is intended as a helper for filters that have several video |
34 | * input and need to combine them somehow. If the inputs have different or |
35 | * variable frame rate, getting the input frames to match requires a rather |
36 | * complex logic and a few user-tunable options. |
37 | * |
38 | * In this API, when a set of synchronized input frames is ready to be |
39 | * procesed is called a frame event. Frame event can be generated in |
40 | * response to input frames on any or all inputs and the handling of |
41 | * situations where some stream extend beyond the beginning or the end of |
42 | * others can be configured. |
43 | * |
44 | * The basic working of this API is the following: |
45 | * |
46 | * - When a frame is available on any input, add it using |
47 | * ff_framesync_add_frame(). |
48 | * |
49 | * - When a frame event is ready to be processed (i.e. after adding a frame |
50 | * or when requested on input): |
51 | * - call ff_framesync_next(); |
52 | * - if fs->frame_ready is true, process the frames; |
53 | * - call ff_framesync_drop(). |
54 | */ |
55 | |
56 | /** |
57 | * Stream extrapolation mode |
58 | * |
59 | * Describe how the frames of a stream are extrapolated before the first one |
60 | * and after EOF to keep sync with possibly longer other streams. |
61 | */ |
62 | enum FFFrameSyncExtMode { |
63 | |
64 | /** |
65 | * Completely stop all streams with this one. |
66 | */ |
67 | EXT_STOP, |
68 | |
69 | /** |
70 | * Ignore this stream and continue processing the other ones. |
71 | */ |
72 | EXT_NULL, |
73 | |
74 | /** |
75 | * Extend the frame to infinity. |
76 | */ |
77 | EXT_INFINITY, |
78 | }; |
79 | |
80 | /** |
81 | * Input stream structure |
82 | */ |
83 | typedef struct FFFrameSyncIn { |
84 | |
85 | /** |
86 | * Queue of incoming AVFrame, and NULL to mark EOF |
87 | */ |
88 | struct FFBufQueue queue; |
89 | |
90 | /** |
91 | * Extrapolation mode for timestamps before the first frame |
92 | */ |
93 | enum FFFrameSyncExtMode before; |
94 | |
95 | /** |
96 | * Extrapolation mode for timestamps after the last frame |
97 | */ |
98 | enum FFFrameSyncExtMode after; |
99 | |
100 | /** |
101 | * Time base for the incoming frames |
102 | */ |
103 | AVRational time_base; |
104 | |
105 | /** |
106 | * Current frame, may be NULL before the first one or after EOF |
107 | */ |
108 | AVFrame *frame; |
109 | |
110 | /** |
111 | * Next frame, for internal use |
112 | */ |
113 | AVFrame *frame_next; |
114 | |
115 | /** |
116 | * PTS of the current frame |
117 | */ |
118 | int64_t pts; |
119 | |
120 | /** |
121 | * PTS of the next frame, for internal use |
122 | */ |
123 | int64_t pts_next; |
124 | |
125 | /** |
126 | * Boolean flagging the next frame, for internal use |
127 | */ |
128 | uint8_t have_next; |
129 | |
130 | /** |
131 | * State: before first, in stream or after EOF, for internal use |
132 | */ |
133 | uint8_t state; |
134 | |
135 | /** |
136 | * Synchronization level: frames on input at the highest sync level will |
137 | * generate output frame events. |
138 | * |
139 | * For example, if inputs #0 and #1 have sync level 2 and input #2 has |
140 | * sync level 1, then a frame on either input #0 or #1 will generate a |
141 | * frame event, but not a frame on input #2 until both inputs #0 and #1 |
142 | * have reached EOF. |
143 | * |
144 | * If sync is 0, no frame event will be generated. |
145 | */ |
146 | unsigned sync; |
147 | |
148 | } FFFrameSyncIn; |
149 | |
150 | /** |
151 | * Frame sync structure. |
152 | */ |
153 | typedef struct FFFrameSync { |
154 | const AVClass *class; |
155 | void *parent; |
156 | |
157 | /** |
158 | * Number of input streams |
159 | */ |
160 | unsigned nb_in; |
161 | |
162 | /** |
163 | * Time base for the output events |
164 | */ |
165 | AVRational time_base; |
166 | |
167 | /** |
168 | * Timestamp of the current event |
169 | */ |
170 | int64_t pts; |
171 | |
172 | /** |
173 | * Callback called when a frame event is ready |
174 | */ |
175 | int (*on_event)(struct FFFrameSync *fs); |
176 | |
177 | /** |
178 | * Opaque pointer, not used by the API |
179 | */ |
180 | void *opaque; |
181 | |
182 | /** |
183 | * Index of the input that requires a request |
184 | */ |
185 | unsigned in_request; |
186 | |
187 | /** |
188 | * Synchronization level: only inputs with the same sync level are sync |
189 | * sources. |
190 | */ |
191 | unsigned sync_level; |
192 | |
193 | /** |
194 | * Flag indicating that a frame event is ready |
195 | */ |
196 | uint8_t frame_ready; |
197 | |
198 | /** |
199 | * Flag indicating that output has reached EOF. |
200 | */ |
201 | uint8_t eof; |
202 | |
203 | /** |
204 | * Pointer to array of inputs. |
205 | */ |
206 | FFFrameSyncIn *in; |
207 | |
208 | } FFFrameSync; |
209 | |
210 | /** |
211 | * Initialize a frame sync structure. |
212 | * |
213 | * The entire structure is expected to be already set to 0. |
214 | * |
215 | * @param fs frame sync structure to initialize |
216 | * @param parent parent object, used for logging |
217 | * @param nb_in number of inputs |
218 | * @return >= 0 for success or a negative error code |
219 | */ |
220 | int ff_framesync_init(FFFrameSync *fs, void *parent, unsigned nb_in); |
221 | |
222 | /** |
223 | * Configure a frame sync structure. |
224 | * |
225 | * Must be called after all options are set but before all use. |
226 | * |
227 | * @return >= 0 for success or a negative error code |
228 | */ |
229 | int ff_framesync_configure(FFFrameSync *fs); |
230 | |
231 | /** |
232 | * Free all memory currently allocated. |
233 | */ |
234 | void ff_framesync_uninit(FFFrameSync *fs); |
235 | |
236 | /** |
237 | * Add a frame to an input |
238 | * |
239 | * Typically called from the filter_frame() method. |
240 | * |
241 | * @param fs frame sync structure |
242 | * @param in index of the input |
243 | * @param frame input frame, or NULL for EOF |
244 | */ |
245 | int ff_framesync_add_frame(FFFrameSync *fs, unsigned in, AVFrame *frame); |
246 | |
247 | /** |
248 | * Prepare the next frame event. |
249 | * |
250 | * The status of the operation can be found in fs->frame_ready and fs->eof. |
251 | */ |
252 | void ff_framesync_next(FFFrameSync *fs); |
253 | |
254 | /** |
255 | * Drop the current frame event. |
256 | */ |
257 | void ff_framesync_drop(FFFrameSync *fs); |
258 | |
259 | /** |
260 | * Get the current frame in an input. |
261 | * |
262 | * @param fs frame sync structure |
263 | * @param in index of the input |
264 | * @param rframe used to return the current frame (or NULL) |
265 | * @param get if not zero, the calling code needs to get ownership of |
266 | * the returned frame; the current frame will either be |
267 | * duplicated or removed from the framesync structure |
268 | */ |
269 | int ff_framesync_get_frame(FFFrameSync *fs, unsigned in, AVFrame **rframe, |
270 | unsigned get); |
271 | |
272 | /** |
273 | * Process one or several frame using the on_event callback. |
274 | * |
275 | * @return number of frames processed or negative error code |
276 | */ |
277 | int ff_framesync_process_frame(FFFrameSync *fs, unsigned all); |
278 | |
279 | |
280 | /** |
281 | * Accept a frame on a filter input. |
282 | * |
283 | * This function can be the complete implementation of all filter_frame |
284 | * methods of a filter using framesync. |
285 | */ |
286 | int ff_framesync_filter_frame(FFFrameSync *fs, AVFilterLink *inlink, |
287 | AVFrame *in); |
288 | |
289 | /** |
290 | * Request a frame on the filter output. |
291 | * |
292 | * This function can be the complete implementation of all filter_frame |
293 | * methods of a filter using framesync if it has only one output. |
294 | */ |
295 | int ff_framesync_request_frame(FFFrameSync *fs, AVFilterLink *outlink); |
296 | |
297 | #endif /* AVFILTER_FRAMESYNC_H */ |
298 |