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
25
30 };
31
32 /*
33 * TODO
34 * Export convenient options.
35 */
36
37 /**
38 * This API is intended as a helper for filters that have several video
39 * input and need to combine them somehow. If the inputs have different or
40 * variable frame rate, getting the input frames to match requires a rather
41 * complex logic and a few user-tunable options.
42 *
43 * In this API, when a set of synchronized input frames is ready to be
44 * procesed is called a frame event. Frame event can be generated in
45 * response to input frames on any or all inputs and the handling of
46 * situations where some stream extend beyond the beginning or the end of
47 * others can be configured.
48 *
49 * The basic working of this API is the following: set the on_event
50 * callback, then call ff_framesync_activate() from the filter's activate
51 * callback.
52 */
53
54 /**
55 * Stream extrapolation mode
56 *
57 * Describe how the frames of a stream are extrapolated before the first one
58 * and after EOF to keep sync with possibly longer other streams.
59 */
61
62 /**
63 * Completely stop all streams with this one.
64 */
66
67 /**
68 * Ignore this stream and continue processing the other ones.
69 */
71
72 /**
73 * Extend the frame to infinity.
74 */
76 };
77
78 /**
79 * Timestamp syncronization mode
80 *
81 * Describe how the frames of a stream are syncronized based on timestamp
82 * distance.
83 */
85
86 /**
87 * Sync to frames from secondary input with the nearest, lower or equal
88 * timestamp to the frame event one.
89 */
91
92 /**
93 * Sync to frames from secondary input with the absolute nearest timestamp
94 * to the frame event one.
95 */
97 };
98
99 /**
100 * Input stream structure
101 */
103
104 /**
105 * Extrapolation mode for timestamps before the first frame
106 */
108
109 /**
110 * Extrapolation mode for timestamps after the last frame
111 */
113
114 /**
115 * Time base for the incoming frames
116 */
118
119 /**
120 * Current frame, may be NULL before the first one or after EOF
121 */
123
124 /**
125 * Next frame, for internal use
126 */
128
129 /**
130 * PTS of the current frame
131 */
133
134 /**
135 * PTS of the next frame, for internal use
136 */
138
139 /**
140 * Boolean flagging the next frame, for internal use
141 */
143
144 /**
145 * State: before first, in stream or after EOF, for internal use
146 */
148
149 /**
150 * Synchronization level: frames on input at the highest sync level will
151 * generate output frame events.
152 *
153 * For example, if inputs #0 and #1 have sync level 2 and input #2 has
154 * sync level 1, then a frame on either input #0 or #1 will generate a
155 * frame event, but not a frame on input #2 until both inputs #0 and #1
156 * have reached EOF.
157 *
158 * If sync is 0, no frame event will be generated.
159 */
161
164
165 /**
166 * Frame sync structure.
167 */
170
171 /**
172 * Parent filter context.
173 */
175
176 /**
177 * Number of input streams
178 */
180
181 /**
182 * Time base for the output events
183 */
185
186 /**
187 * Timestamp of the current event
188 */
190
191 /**
192 * Callback called when a frame event is ready
193 */
195
196 /**
197 * Opaque pointer, not used by the API
198 */
200
201 /**
202 * Index of the input that requires a request
203 */
205
206 /**
207 * Synchronization level: only inputs with the same sync level are sync
208 * sources.
209 */
211
212 /**
213 * Flag indicating that a frame event is ready
214 */
216
217 /**
218 * Flag indicating that output has reached EOF.
219 */
221
222 /**
223 * Pointer to array of inputs.
224 */
226
231
233
234 /**
235 * Pre-initialize a frame sync structure.
236 *
237 * It sets the class pointer and inits the options to their default values.
238 * The entire structure is expected to be already set to 0.
239 * This step is optional, but necessary to use the options.
240 */
242
243 /**
244 * Initialize a frame sync structure.
245 *
246 * The entire structure is expected to be already set to 0 or preinited.
247 *
248 * @param fs frame sync structure to initialize
249 * @param parent parent AVFilterContext object
250 * @param nb_in number of inputs
251 * @return >= 0 for success or a negative error code
252 */
254
255 /**
256 * Configure a frame sync structure.
257 *
258 * Must be called after all options are set but before all use.
259 *
260 * @return >= 0 for success or a negative error code
261 */
263
264 /**
265 * Free all memory currently allocated.
266 */
268
269 /**
270 * Get the current frame in an input.
271 *
272 * @param fs frame sync structure
273 * @param in index of the input
274 * @param rframe used to return the current frame (or NULL)
275 * @param get if not zero, the calling code needs to get ownership of
276 * the returned frame; the current frame will either be
277 * duplicated or removed from the framesync structure
278 */
281
282 /**
283 * Examine the frames in the filter's input and try to produce output.
284 *
285 * This function can be the complete implementation of the activate
286 * method of a filter using framesync.
287 */
289
290 /**
291 * Initialize a frame sync structure for dualinput.
292 *
293 * Compared to generic framesync, dualinput assumes the first input is the
294 * main one and the filtering is performed on it. The first input will be
295 * the only one with sync set and generic timeline support will just pass it
296 * unchanged when disabled.
297 *
298 * Equivalent to ff_framesync_init(fs, parent, 2) then setting the time
299 * base, sync and ext modes on the inputs.
300 */
302
303 /**
304 * @param f0 used to return the main frame
305 * @param f1 used to return the second frame, or NULL if disabled
306 * @return >=0 for success or AVERROR code
307 * @note The frame returned in f0 belongs to the caller (get = 1 in
308 * ff_framesync_get_frame()) while the frame returned in f1 is still owned
309 * by the framesync structure.
310 */
312
313 /**
314 * Same as ff_framesync_dualinput_get(), but make sure that f0 is writable.
315 */
317
319
320 #define FRAMESYNC_DEFINE_PURE_CLASS(name, desc, func_prefix, options) \
321 static const AVClass name##_class = { \
322 .class_name = desc, \
323 .item_name = av_default_item_name, \
324 .option = options, \
325 .version = LIBAVUTIL_VERSION_INT, \
326 .category = AV_CLASS_CATEGORY_FILTER, \
327 .child_class_iterate = ff_framesync_child_class_iterate, \
328 .child_next = func_prefix##_child_next, \
329 }
330
331 /* A filter that uses the *_child_next-function from this macro
332 * is required to initialize the FFFrameSync structure in AVFilter.preinit
333 * via the *_framesync_preinit function defined alongside it. */
334 #define FRAMESYNC_AUXILIARY_FUNCS(func_prefix, context, field) \
335 static int func_prefix##_framesync_preinit(AVFilterContext *ctx) \
336 { \
337 context *s = ctx->priv; \
338 ff_framesync_preinit(&s->field); \
339 return 0; \
340 } \
341 static void *func_prefix##_child_next(void *obj, void *prev) \
342 { \
343 context *s = obj; \
344 return prev ? NULL : &s->field; \
345 }
346
347 #define FRAMESYNC_DEFINE_CLASS_EXT(name, context, field, options) \
348 FRAMESYNC_AUXILIARY_FUNCS(name, context, field) \
349 FRAMESYNC_DEFINE_PURE_CLASS(name, #name, name, options)
350
351 #define FRAMESYNC_DEFINE_CLASS(name, context, field) \
352 FRAMESYNC_DEFINE_CLASS_EXT(name, context, field, name##_options)
353
354 #endif /* AVFILTER_FRAMESYNC_H */