2 * Copyright (c) 2013 Nicolas George
4 * This file is part of FFmpeg.
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.
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.
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
21 #ifndef AVFILTER_FRAMESYNC_H
22 #define AVFILTER_FRAMESYNC_H
24 #include "bufferqueue.h"
28 * Callback-based API similar to dualinput.
29 * Export convenient options.
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.
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.
44 * The basic working of this API is the following:
46 * - When a frame is available on any input, add it using
47 * ff_framesync_add_frame().
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().
57 * Stream extrapolation mode
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.
62 enum FFFrameSyncExtMode
{
65 * Completely stop all streams with this one.
70 * Ignore this stream and continue processing the other ones.
75 * Extend the frame to infinity.
81 * Input stream structure
83 typedef struct FFFrameSyncIn
{
86 * Queue of incoming AVFrame, and NULL to mark EOF
88 struct FFBufQueue queue
;
91 * Extrapolation mode for timestamps before the first frame
93 enum FFFrameSyncExtMode before
;
96 * Extrapolation mode for timestamps after the last frame
98 enum FFFrameSyncExtMode after
;
101 * Time base for the incoming frames
103 AVRational time_base
;
106 * Current frame, may be NULL before the first one or after EOF
111 * Next frame, for internal use
116 * PTS of the current frame
121 * PTS of the next frame, for internal use
126 * Boolean flagging the next frame, for internal use
131 * State: before first, in stream or after EOF, for internal use
136 * Synchronization level: frames on input at the highest sync level will
137 * generate output frame events.
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
144 * If sync is 0, no frame event will be generated.
151 * Frame sync structure.
153 typedef struct FFFrameSync
{
154 const AVClass
*class;
158 * Number of input streams
163 * Time base for the output events
165 AVRational time_base
;
168 * Timestamp of the current event
173 * Callback called when a frame event is ready
175 int (*on_event
)(struct FFFrameSync
*fs
);
178 * Opaque pointer, not used by the API
183 * Index of the input that requires a request
188 * Synchronization level: only inputs with the same sync level are sync
194 * Flag indicating that a frame event is ready
199 * Flag indicating that output has reached EOF.
204 * Array of inputs; all inputs must be in consecutive memory
206 FFFrameSyncIn in
[1]; /* must be the last field */
211 * Initialize a frame sync structure.
213 * The entire structure is expected to be already set to 0.
215 * @param fs frame sync structure to initialize
216 * @param parent parent object, used for logging
217 * @param nb_in number of inputs
219 void ff_framesync_init(FFFrameSync
*fs
, void *parent
, unsigned nb_in
);
222 * Configure a frame sync structure.
224 * Must be called after all options are set but before all use.
226 * @return >= 0 for success or a negative error code
228 int ff_framesync_configure(FFFrameSync
*fs
);
231 * Free all memory currently allocated.
233 void ff_framesync_uninit(FFFrameSync
*fs
);
236 * Add a frame to an input
238 * Typically called from the filter_frame() method.
240 * @param fs frame sync structure
241 * @param in index of the input
242 * @param frame input frame, or NULL for EOF
244 int ff_framesync_add_frame(FFFrameSync
*fs
, unsigned in
, AVFrame
*frame
);
247 * Prepare the next frame event.
249 * The status of the operation can be found in fs->frame_ready and fs->eof.
251 void ff_framesync_next(FFFrameSync
*fs
);
254 * Drop the current frame event.
256 void ff_framesync_drop(FFFrameSync
*fs
);
259 * Get the current frame in an input.
261 * @param fs frame sync structure
262 * @param in index of the input
263 * @param rframe used to return the current frame (or NULL)
264 * @param get if not zero, the calling code needs to get ownership of
265 * the returned frame; the current frame will either be
266 * duplicated or removed from the framesync structure
268 int ff_framesync_get_frame(FFFrameSync
*fs
, unsigned in
, AVFrame
**rframe
,
272 * Process one or several frame using the on_event callback.
274 * @return number of frames processed or negative error code
276 int ff_framesync_process_frame(FFFrameSync
*fs
, unsigned all
);
280 * Accept a frame on a filter input.
282 * This function can be the complete implementation of all filter_frame
283 * methods of a filter using framesync.
285 int ff_framesync_filter_frame(FFFrameSync
*fs
, AVFilterLink
*inlink
,
289 * Request a frame on the filter output.
291 * This function can be the complete implementation of all filter_frame
292 * methods of a filter using framesync if it has only one output.
294 int ff_framesync_request_frame(FFFrameSync
*fs
, AVFilterLink
*outlink
);
296 #endif /* AVFILTER_FRAMESYNC_H */