avfilter: add setrange filter
[ffmpeg.git] / libavfilter / framesync.h
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 enum EOFAction {
27     EOF_ACTION_REPEAT,
28     EOF_ACTION_ENDALL,
29     EOF_ACTION_PASS
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  */
60 enum FFFrameSyncExtMode {
61
62     /**
63      * Completely stop all streams with this one.
64      */
65     EXT_STOP,
66
67     /**
68      * Ignore this stream and continue processing the other ones.
69      */
70     EXT_NULL,
71
72     /**
73      * Extend the frame to infinity.
74      */
75     EXT_INFINITY,
76 };
77
78 /**
79  * Input stream structure
80  */
81 typedef struct FFFrameSyncIn {
82
83     /**
84      * Extrapolation mode for timestamps before the first frame
85      */
86     enum FFFrameSyncExtMode before;
87
88     /**
89      * Extrapolation mode for timestamps after the last frame
90      */
91     enum FFFrameSyncExtMode after;
92
93     /**
94      * Time base for the incoming frames
95      */
96     AVRational time_base;
97
98     /**
99      * Current frame, may be NULL before the first one or after EOF
100      */
101     AVFrame *frame;
102
103     /**
104      * Next frame, for internal use
105      */
106     AVFrame *frame_next;
107
108     /**
109      * PTS of the current frame
110      */
111     int64_t pts;
112
113     /**
114      * PTS of the next frame, for internal use
115      */
116     int64_t pts_next;
117
118     /**
119      * Boolean flagging the next frame, for internal use
120      */
121     uint8_t have_next;
122
123     /**
124      * State: before first, in stream or after EOF, for internal use
125      */
126     uint8_t state;
127
128     /**
129      * Synchronization level: frames on input at the highest sync level will
130      * generate output frame events.
131      *
132      * For example, if inputs #0 and #1 have sync level 2 and input #2 has
133      * sync level 1, then a frame on either input #0 or #1 will generate a
134      * frame event, but not a frame on input #2 until both inputs #0 and #1
135      * have reached EOF.
136      *
137      * If sync is 0, no frame event will be generated.
138      */
139     unsigned sync;
140
141 } FFFrameSyncIn;
142
143 /**
144  * Frame sync structure.
145  */
146 typedef struct FFFrameSync {
147     const AVClass *class;
148
149     /**
150      * Parent filter context.
151      */
152     AVFilterContext *parent;
153
154     /**
155      * Number of input streams
156      */
157     unsigned nb_in;
158
159     /**
160      * Time base for the output events
161      */
162     AVRational time_base;
163
164     /**
165      * Timestamp of the current event
166      */
167     int64_t pts;
168
169     /**
170      * Callback called when a frame event is ready
171      */
172     int (*on_event)(struct FFFrameSync *fs);
173
174     /**
175      * Opaque pointer, not used by the API
176      */
177     void *opaque;
178
179     /**
180      * Index of the input that requires a request
181      */
182     unsigned in_request;
183
184     /**
185      * Synchronization level: only inputs with the same sync level are sync
186      * sources.
187      */
188     unsigned sync_level;
189
190     /**
191      * Flag indicating that a frame event is ready
192      */
193     uint8_t frame_ready;
194
195     /**
196      * Flag indicating that output has reached EOF.
197      */
198     uint8_t eof;
199
200     /**
201      * Pointer to array of inputs.
202      */
203     FFFrameSyncIn *in;
204
205     int opt_repeatlast;
206     int opt_shortest;
207     int opt_eof_action;
208
209 } FFFrameSync;
210
211 /**
212  * Get the class for the framesync object.
213  */
214 const AVClass *framesync_get_class(void);
215
216 /**
217  * Pre-initialize a frame sync structure.
218  *
219  * It sets the class pointer and inits the options to their default values.
220  * The entire structure is expected to be already set to 0.
221  * This step is optional, but necessary to use the options.
222  */
223 void ff_framesync_preinit(FFFrameSync *fs);
224
225 /**
226  * Initialize a frame sync structure.
227  *
228  * The entire structure is expected to be already set to 0 or preinited.
229  *
230  * @param  fs      frame sync structure to initialize
231  * @param  parent  parent AVFilterContext object
232  * @param  nb_in   number of inputs
233  * @return  >= 0 for success or a negative error code
234  */
235 int ff_framesync_init(FFFrameSync *fs, AVFilterContext *parent, unsigned nb_in);
236
237 /**
238  * Configure a frame sync structure.
239  *
240  * Must be called after all options are set but before all use.
241  *
242  * @return  >= 0 for success or a negative error code
243  */
244 int ff_framesync_configure(FFFrameSync *fs);
245
246 /**
247  * Free all memory currently allocated.
248  */
249 void ff_framesync_uninit(FFFrameSync *fs);
250
251 /**
252  * Get the current frame in an input.
253  *
254  * @param fs      frame sync structure
255  * @param in      index of the input
256  * @param rframe  used to return the current frame (or NULL)
257  * @param get     if not zero, the calling code needs to get ownership of
258  *                the returned frame; the current frame will either be
259  *                duplicated or removed from the framesync structure
260  */
261 int ff_framesync_get_frame(FFFrameSync *fs, unsigned in, AVFrame **rframe,
262                             unsigned get);
263
264 /**
265  * Examine the frames in the filter's input and try to produce output.
266  *
267  * This function can be the complete implementation of the activate
268  * method of a filter using framesync.
269  */
270 int ff_framesync_activate(FFFrameSync *fs);
271
272 /**
273  * Initialize a frame sync structure for dualinput.
274  *
275  * Compared to generic framesync, dualinput assumes the first input is the
276  * main one and the filtering is performed on it. The first input will be
277  * the only one with sync set and generic timeline support will just pass it
278  * unchanged when disabled.
279  *
280  * Equivalent to ff_framesync_init(fs, parent, 2) then setting the time
281  * base, sync and ext modes on the inputs.
282  */
283 int ff_framesync_init_dualinput(FFFrameSync *fs, AVFilterContext *parent);
284
285 /**
286  * @param f0  used to return the main frame
287  * @param f1  used to return the second frame, or NULL if disabled
288  * @return  >=0 for success or AVERROR code
289  */
290 int ff_framesync_dualinput_get(FFFrameSync *fs, AVFrame **f0, AVFrame **f1);
291
292 /**
293  * Same as ff_framesync_dualinput_get(), but make sure that f0 is writable.
294  */
295 int ff_framesync_dualinput_get_writable(FFFrameSync *fs, AVFrame **f0, AVFrame **f1);
296
297 #define FRAMESYNC_DEFINE_CLASS(name, context, field) \
298 static int name##_framesync_preinit(AVFilterContext *ctx) { \
299     context *s = ctx->priv; \
300     ff_framesync_preinit(&s->field); \
301     return 0; \
302 } \
303 static const AVClass *name##_child_class_next(const AVClass *prev) { \
304     return prev ? NULL : framesync_get_class(); \
305 } \
306 static void *name##_child_next(void *obj, void *prev) { \
307     context *s = obj; \
308     s->fs.class = framesync_get_class(); /* FIXME */ \
309     return prev ? NULL : &s->field; \
310 } \
311 static const AVClass name##_class = { \
312     .class_name       = #name, \
313     .item_name        = av_default_item_name, \
314     .option           = name##_options, \
315     .version          = LIBAVUTIL_VERSION_INT, \
316     .category         = AV_CLASS_CATEGORY_FILTER, \
317     .child_class_next = name##_child_class_next, \
318     .child_next       = name##_child_next, \
319 }
320
321 #endif /* AVFILTER_FRAMESYNC_H */