/*
* 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"
/*
* TODO
* Callback-based API similar to dualinput.
* 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:
*
* - When a frame is available on any input, add it using
* ff_framesync_add_frame().
*
* - When a frame event is ready to be processed (i.e. after adding a frame
* or when requested on input):
* - call ff_framesync_next();
* - if fs->frame_ready is true, process the frames;
* - call ff_framesync_drop().
*/
/**
* 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,
};
/**
* Input stream structure
*/
typedef struct FFFrameSyncIn {
/**
* Queue of incoming AVFrame, and NULL to mark EOF
*/
struct FFBufQueue queue;
/**
* 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;
} FFFrameSyncIn;
/**
* Frame sync structure.
*/
typedef struct FFFrameSync {
const AVClass *class;
void *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;
/**
* Array of inputs; all inputs must be in consecutive memory
*/
FFFrameSyncIn in[1]; /* must be the last field */
} FFFrameSync;
/**
* Initialize a frame sync structure.
*
* The entire structure is expected to be already set to 0.
*
* @param fs frame sync structure to initialize
* @param parent parent object, used for logging
* @param nb_in number of inputs
*/
void ff_framesync_init(FFFrameSync *fs, void *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);
/**
* Add a frame to an input
*
* Typically called from the filter_frame() method.
*
* @param fs frame sync structure
* @param in index of the input
* @param frame input frame, or NULL for EOF
*/
int ff_framesync_add_frame(FFFrameSync *fs, unsigned in, AVFrame *frame);
/**
* Prepare the next frame event.
*
* The status of the operation can be found in fs->frame_ready and fs->eof.
*/
void ff_framesync_next(FFFrameSync *fs);
/**
* Drop the current frame event.
*/
void ff_framesync_drop(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);
/**
* Process one or several frame using the on_event callback.
*
* @return number of frames processed or negative error code
*/
int ff_framesync_process_frame(FFFrameSync *fs, unsigned all);
/**
* Accept a frame on a filter input.
*
* This function can be the complete implementation of all filter_frame
* methods of a filter using framesync.
*/
int ff_framesync_filter_frame(FFFrameSync *fs, AVFilterLink *inlink,
AVFrame *in);
/**
* Request a frame on the filter output.
*
* This function can be the complete implementation of all filter_frame
* methods of a filter using framesync if it has only one output.
*/
int ff_framesync_request_frame(FFFrameSync *fs, AVFilterLink *outlink);
#endif /* AVFILTER_FRAMESYNC_H */