Subversion Repositories Kolibri OS

/*

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