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 /*
  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 */