aboutsummaryrefslogtreecommitdiffstats
path: root/libavfilter/framesync.h
blob: 233f50a0eb7f6dca03a419c9521281adba130d3c (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
/*
 * Copyright (c) 2013 Nicolas George
 *
 * This file is part of FFmpeg.
 *
 * FFmpeg is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * FFmpeg is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with FFmpeg; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

#ifndef AVFILTER_FRAMESYNC_H
#define AVFILTER_FRAMESYNC_H

#include "bufferqueue.h"

enum EOFAction {
    EOF_ACTION_REPEAT,
    EOF_ACTION_ENDALL,
    EOF_ACTION_PASS
};

/*
 * TODO
 * Export convenient options.
 */

/**
 * This API is intended as a helper for filters that have several video
 * input and need to combine them somehow. If the inputs have different or
 * variable frame rate, getting the input frames to match requires a rather
 * complex logic and a few user-tunable options.
 *
 * In this API, when a set of synchronized input frames is ready to be
 * procesed is called a frame event. Frame event can be generated in
 * response to input frames on any or all inputs and the handling of
 * situations where some stream extend beyond the beginning or the end of
 * others can be configured.
 *
 * The basic working of this API is the following: set the on_event
 * callback, then call ff_framesync_activate() from the filter's activate
 * callback.
 */

/**
 * Stream extrapolation mode
 *
 * Describe how the frames of a stream are extrapolated before the first one
 * and after EOF to keep sync with possibly longer other streams.
 */
enum FFFrameSyncExtMode {

    /**
     * Completely stop all streams with this one.
     */
    EXT_STOP,

    /**
     * Ignore this stream and continue processing the other ones.
     */
    EXT_NULL,

    /**
     * Extend the frame to infinity.
     */
    EXT_INFINITY,
};

/**
 * Timestamp syncronization mode
 *
 * Describe how the frames of a stream are syncronized based on timestamp
 * distance.
 */
enum FFFrameTSSyncMode {

    /**
     * Sync to frames from secondary input with the nearest, lower or equal
     * timestamp to the frame event one.
     */
    TS_DEFAULT,

    /**
     * Sync to frames from secondary input with the absolute nearest timestamp
     * to the frame event one.
     */
    TS_NEAREST,
};

/**
 * Input stream structure
 */
typedef struct FFFrameSyncIn {

    /**
     * Extrapolation mode for timestamps before the first frame
     */
    enum FFFrameSyncExtMode before;

    /**
     * Extrapolation mode for timestamps after the last frame
     */
    enum FFFrameSyncExtMode after;

    /**
     * Time base for the incoming frames
     */
    AVRational time_base;

    /**
     * Current frame, may be NULL before the first one or after EOF
     */
    AVFrame *frame;

    /**
     * Next frame, for internal use
     */
    AVFrame *frame_next;

    /**
     * PTS of the current frame
     */
    int64_t pts;

    /**
     * PTS of the next frame, for internal use
     */
    int64_t pts_next;

    /**
     * Boolean flagging the next frame, for internal use
     */
    uint8_t have_next;

    /**
     * State: before first, in stream or after EOF, for internal use
     */
    uint8_t state;

    /**
     * Synchronization level: frames on input at the highest sync level will
     * generate output frame events.
     *
     * For example, if inputs #0 and #1 have sync level 2 and input #2 has
     * sync level 1, then a frame on either input #0 or #1 will generate a
     * frame event, but not a frame on input #2 until both inputs #0 and #1
     * have reached EOF.
     *
     * If sync is 0, no frame event will be generated.
     */
    unsigned sync;

    enum FFFrameTSSyncMode ts_mode;
} FFFrameSyncIn;

/**
 * Frame sync structure.
 */
typedef struct FFFrameSync {
    const AVClass *class;

    /**
     * Parent filter context.
     */
    AVFilterContext *parent;

    /**
     * Number of input streams
     */
    unsigned nb_in;

    /**
     * Time base for the output events
     */
    AVRational time_base;

    /**
     * Timestamp of the current event
     */
    int64_t pts;

    /**
     * Callback called when a frame event is ready
     */
    int (*on_event)(struct FFFrameSync *fs);

    /**
     * Opaque pointer, not used by the API
     */
    void *opaque;

    /**
     * Index of the input that requires a request
     */
    unsigned in_request;

    /**
     * Synchronization level: only inputs with the same sync level are sync
     * sources.
     */
    unsigned sync_level;

    /**
     * Flag indicating that a frame event is ready
     */
    uint8_t frame_ready;

    /**
     * Flag indicating that output has reached EOF.
     */
    uint8_t eof;

    /**
     * Pointer to array of inputs.
     */
    FFFrameSyncIn *in;

    int opt_repeatlast;
    int opt_shortest;
    int opt_eof_action;
    int opt_ts_sync_mode;

} FFFrameSync;

/**
 * Pre-initialize a frame sync structure.
 *
 * It sets the class pointer and inits the options to their default values.
 * The entire structure is expected to be already set to 0.
 * This step is optional, but necessary to use the options.
 */
void ff_framesync_preinit(FFFrameSync *fs);

/**
 * Initialize a frame sync structure.
 *
 * The entire structure is expected to be already set to 0 or preinited.
 *
 * @param  fs      frame sync structure to initialize
 * @param  parent  parent AVFilterContext object
 * @param  nb_in   number of inputs
 * @return  >= 0 for success or a negative error code
 */
int ff_framesync_init(FFFrameSync *fs, AVFilterContext *parent, unsigned nb_in);

/**
 * Configure a frame sync structure.
 *
 * Must be called after all options are set but before all use.
 *
 * @return  >= 0 for success or a negative error code
 */
int ff_framesync_configure(FFFrameSync *fs);

/**
 * Free all memory currently allocated.
 */
void ff_framesync_uninit(FFFrameSync *fs);

/**
 * Get the current frame in an input.
 *
 * @param fs      frame sync structure
 * @param in      index of the input
 * @param rframe  used to return the current frame (or NULL)
 * @param get     if not zero, the calling code needs to get ownership of
 *                the returned frame; the current frame will either be
 *                duplicated or removed from the framesync structure
 */
int ff_framesync_get_frame(FFFrameSync *fs, unsigned in, AVFrame **rframe,
                            unsigned get);

/**
 * Examine the frames in the filter's input and try to produce output.
 *
 * This function can be the complete implementation of the activate
 * method of a filter using framesync.
 */
int ff_framesync_activate(FFFrameSync *fs);

/**
 * Initialize a frame sync structure for dualinput.
 *
 * Compared to generic framesync, dualinput assumes the first input is the
 * main one and the filtering is performed on it. The first input will be
 * the only one with sync set and generic timeline support will just pass it
 * unchanged when disabled.
 *
 * Equivalent to ff_framesync_init(fs, parent, 2) then setting the time
 * base, sync and ext modes on the inputs.
 */
int ff_framesync_init_dualinput(FFFrameSync *fs, AVFilterContext *parent);

/**
 * @param f0  used to return the main frame
 * @param f1  used to return the second frame, or NULL if disabled
 * @return  >=0 for success or AVERROR code
 * @note  The frame returned in f0 belongs to the caller (get = 1 in
 * ff_framesync_get_frame()) while the frame returned in f1 is still owned
 * by the framesync structure.
 */
int ff_framesync_dualinput_get(FFFrameSync *fs, AVFrame **f0, AVFrame **f1);

/**
 * Same as ff_framesync_dualinput_get(), but make sure that f0 is writable.
 */
int ff_framesync_dualinput_get_writable(FFFrameSync *fs, AVFrame **f0, AVFrame **f1);

const AVClass *ff_framesync_child_class_iterate(void **iter);

#define FRAMESYNC_DEFINE_PURE_CLASS(name, desc, func_prefix, options) \
static const AVClass name##_class = {                                 \
    .class_name          = desc,                                      \
    .item_name           = av_default_item_name,                      \
    .option              = options,                                   \
    .version             = LIBAVUTIL_VERSION_INT,                     \
    .category            = AV_CLASS_CATEGORY_FILTER,                  \
    .child_class_iterate = ff_framesync_child_class_iterate,          \
    .child_next          = func_prefix##_child_next,                  \
}

/* A filter that uses the *_child_next-function from this macro
 * is required to initialize the FFFrameSync structure in AVFilter.preinit
 * via the *_framesync_preinit function defined alongside it. */
#define FRAMESYNC_AUXILIARY_FUNCS(func_prefix, context, field)        \
static int func_prefix##_framesync_preinit(AVFilterContext *ctx)      \
{                                                                     \
    context *s = ctx->priv; \
    ff_framesync_preinit(&s->field); \
    return 0; \
} \
static void *func_prefix##_child_next(void *obj, void *prev)          \
{                                                                     \
    context *s = obj; \
    return prev ? NULL : &s->field; \
}

#define FRAMESYNC_DEFINE_CLASS_EXT(name, context, field, options)     \
FRAMESYNC_AUXILIARY_FUNCS(name, context, field)                       \
FRAMESYNC_DEFINE_PURE_CLASS(name, #name, name, options)

#define FRAMESYNC_DEFINE_CLASS(name, context, field)                  \
FRAMESYNC_DEFINE_CLASS_EXT(name, context, field, name##_options)

#endif /* AVFILTER_FRAMESYNC_H */