framesync.h

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