avfilter.h 23.9 KB
Newer Older
Vitor Sessak's avatar
Vitor Sessak committed
1
/*
2
 * filter layer
Vitor Sessak's avatar
Vitor Sessak committed
3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
 * copyright (c) 2007 Bobby Bingham
 *
 * 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
 */

22 23
#ifndef AVFILTER_AVFILTER_H
#define AVFILTER_AVFILTER_H
Vitor Sessak's avatar
Vitor Sessak committed
24

25
#define LIBAVFILTER_VERSION_MAJOR  0
26
#define LIBAVFILTER_VERSION_MINOR  1
27 28 29 30 31 32 33 34 35
#define LIBAVFILTER_VERSION_MICRO  0

#define LIBAVFILTER_VERSION_INT AV_VERSION_INT(LIBAVFILTER_VERSION_MAJOR, \
                                               LIBAVFILTER_VERSION_MINOR, \
                                               LIBAVFILTER_VERSION_MICRO)
#define LIBAVFILTER_VERSION     AV_VERSION(LIBAVFILTER_VERSION_MAJOR,   \
                                           LIBAVFILTER_VERSION_MINOR,   \
                                           LIBAVFILTER_VERSION_MICRO)
#define LIBAVFILTER_BUILD       LIBAVFILTER_VERSION_INT
Víctor Paesa's avatar
Víctor Paesa committed
36

37
#include <stddef.h>
38
#include "libavcodec/avcodec.h"
Vitor Sessak's avatar
Vitor Sessak committed
39

40 41 42 43 44
/**
 * Returns the LIBAVFILTER_VERSION_INT constant.
 */
unsigned avfilter_version(void);

Vitor Sessak's avatar
Vitor Sessak committed
45 46 47 48 49 50 51 52 53 54
typedef struct AVFilterContext AVFilterContext;
typedef struct AVFilterLink    AVFilterLink;
typedef struct AVFilterPad     AVFilterPad;

/* TODO: look for other flags which may be useful in this structure (interlace
 * flags, etc)
 */
/**
 * A reference-counted picture data type used by the filter system.  Filters
 * should not store pointers to this structure directly, but instead use the
55
 * AVFilterPicRef structure below.
Vitor Sessak's avatar
Vitor Sessak committed
56 57 58
 */
typedef struct AVFilterPic
{
59 60 61
    uint8_t *data[4];           ///< picture data for each plane
    int linesize[4];            ///< number of bytes per line
    enum PixelFormat format;    ///< colorspace
Vitor Sessak's avatar
Vitor Sessak committed
62

63 64 65
    unsigned refcount;          ///< number of references to this image

    /** private data to be used by a custom free function */
Vitor Sessak's avatar
Vitor Sessak committed
66
    void *priv;
67 68 69 70 71 72
    /**
     * A pointer to the function to deallocate this image if the default
     * function is not sufficient.  This could, for example, add the memory
     * back into a memory pool to be reused later without the overhead of
     * reallocating it from scratch.
     */
Vitor Sessak's avatar
Vitor Sessak committed
73 74 75 76 77 78
    void (*free)(struct AVFilterPic *pic);
} AVFilterPic;

/**
 * A reference to an AVFilterPic.  Since filters can manipulate the origin of
 * a picture to, for example, crop image without any memcpy, the picture origin
79 80
 * and dimensions are per-reference properties.  Linesize is also useful for
 * image flipping, frame to field filters, etc, and so is also per-reference.
Vitor Sessak's avatar
Vitor Sessak committed
81
 *
Vitor Sessak's avatar
Vitor Sessak committed
82
 * TODO: add anything necessary for frame reordering
Vitor Sessak's avatar
Vitor Sessak committed
83 84 85
 */
typedef struct AVFilterPicRef
{
86 87 88 89 90
    AVFilterPic *pic;           ///< the picture that this is a reference to
    uint8_t *data[4];           ///< picture data for each plane
    int linesize[4];            ///< number of bytes per line
    int w;                      ///< image width
    int h;                      ///< image height
Vitor Sessak's avatar
Vitor Sessak committed
91

92
    int64_t pts;                ///< presentation timestamp in units of 1/AV_TIME_BASE
Vitor Sessak's avatar
Vitor Sessak committed
93

94 95
    AVRational pixel_aspect;    ///< pixel aspect ratio

Vitor Sessak's avatar
Vitor Sessak committed
96 97 98 99
    int perms;                  ///< permissions
#define AV_PERM_READ     0x01   ///< can read from the buffer
#define AV_PERM_WRITE    0x02   ///< can write to the buffer
#define AV_PERM_PRESERVE 0x04   ///< nobody else can overwrite the buffer
100 101
#define AV_PERM_REUSE    0x08   ///< can output the buffer multiple times, with the same contents each time
#define AV_PERM_REUSE2   0x10   ///< can output the buffer multiple times, modified each time
Vitor Sessak's avatar
Vitor Sessak committed
102 103 104 105
} AVFilterPicRef;

/**
 * Add a new reference to a picture.
106 107
 * @param ref   an existing reference to the picture
 * @param pmask a bitmask containing the allowable permissions in the new
108
 *              reference
109
 * @return      a new reference to the picture with the same properties as the
110
 *              old, excluding any permissions denied by pmask
Vitor Sessak's avatar
Vitor Sessak committed
111
 */
112
AVFilterPicRef *avfilter_ref_pic(AVFilterPicRef *ref, int pmask);
Vitor Sessak's avatar
Vitor Sessak committed
113 114 115 116

/**
 * Remove a reference to a picture.  If this is the last reference to the
 * picture, the picture itself is also automatically freed.
117
 * @param ref reference to the picture
Vitor Sessak's avatar
Vitor Sessak committed
118 119 120
 */
void avfilter_unref_pic(AVFilterPicRef *ref);

Vitor Sessak's avatar
Vitor Sessak committed
121 122 123 124 125 126 127
/**
 * A list of supported formats for one end of a filter link. This is used
 * during the format negotiation process to try to pick the best format to
 * use to minimize the number of necessary conversions. Each filter gives a
 * list of the formats supported by each input and output pad. The list
 * given for each pad need not be distinct - they may be references to the
 * same list of formats, as is often the case when a filter supports multiple
Stefano Sabatini's avatar
Stefano Sabatini committed
128
 * formats, but will always output the same format as it is given in input.
Vitor Sessak's avatar
Vitor Sessak committed
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
 *
 * In this way, a list of possible input formats and a list of possible
 * output formats are associated with each link. When a set of formats is
 * negotiated over a link, the input and output lists are merged to form a
 * new list containing only the common elements of each list. In the case
 * that there were no common elements, a format conversion is necessary.
 * Otherwise, the lists are merged, and all other links which reference
 * either of the format lists involved in the merge are also affected.
 *
 * For example, consider the filter chain:
 * filter (a) --> (b) filter (b) --> (c) filter
 *
 * where the letters in parenthesis indicate a list of formats supported on
 * the input or output of the link. Suppose the lists are as follows:
 * (a) = {A, B}
 * (b) = {A, B, C}
 * (c) = {B, C}
 *
 * First, the first link's lists are merged, yielding:
 * filter (a) --> (a) filter (a) --> (c) filter
 *
 * Notice that format list (b) now refers to the same list as filter list (a).
 * Next, the lists for the second link are merged, yielding:
 * filter (a) --> (a) filter (a) --> (a) filter
 *
 * where (a) = {B}.
 *
 * Unfortunately, when the format lists at the two ends of a link are merged,
 * we must ensure that all links which reference either pre-merge format list
 * get updated as well. Therefore, we have the format list structure store a
 * pointer to each of the pointers to itself.
 */
typedef struct AVFilterFormats AVFilterFormats;
struct AVFilterFormats
{
    unsigned format_count;      ///< number of formats
    int *formats;               ///< list of formats

    unsigned refcount;          ///< number of references to this list
    AVFilterFormats ***refs;    ///< references to this list
};

/**
 * Helper function to create a list of supported formats.  This is intended
 * for use in AVFilter->query_formats().
174 175 176
 * @param len the number of formats supported
 * @param ... a list of the supported formats
 * @return    the format list, with no existing references
Vitor Sessak's avatar
Vitor Sessak committed
177 178 179 180
 */
AVFilterFormats *avfilter_make_format_list(int len, ...);

/**
Vitor Sessak's avatar
Vitor Sessak committed
181
 * Returns a list of all colorspaces supported by FFmpeg.
Vitor Sessak's avatar
Vitor Sessak committed
182 183 184 185
 */
AVFilterFormats *avfilter_all_colorspaces(void);

/**
186
 * Returns a format list which contains the intersection of the formats of
187 188
 * a and b. Also, all the references of a, all the references of b, and
 * a and b themselves will be deallocated.
Vitor Sessak's avatar
Vitor Sessak committed
189 190 191 192 193 194
 *
 * If a and b do not share any common formats, neither is modified, and NULL
 * is returned.
 */
AVFilterFormats *avfilter_merge_formats(AVFilterFormats *a, AVFilterFormats *b);

195
/**
196
 * Adds *ref as a new reference to formats.
197 198
 * That is the pointers will point like in the ascii art below:
 *   ________
199 200 201 202
 *  |formats |<--------.
 *  |  ____  |     ____|___________________
 *  | |refs| |    |  __|_
 *  | |* * | |    | |  | |  AVFilterLink
203
 *  | |* *--------->|*ref|
204 205
 *  | |____| |    | |____|
 *  |________|    |________________________
206
 */
207
void avfilter_formats_ref(AVFilterFormats *formats, AVFilterFormats **ref);
Vitor Sessak's avatar
Vitor Sessak committed
208 209 210

/**
 * Remove *ref as a reference to the format list it currently points to,
211
 * deallocate that list if this was the last reference, and set *ref to NULL.
212 213 214 215 216 217 218 219 220 221
 *
 *         Before                                 After
 *   ________                               ________         NULL
 *  |formats |<--------.                   |formats |         ^
 *  |  ____  |     ____|________________   |  ____  |     ____|________________
 *  | |refs| |    |  __|_                  | |refs| |    |  __|_
 *  | |* * | |    | |  | |  AVFilterLink   | |* * | |    | |  | |  AVFilterLink
 *  | |* *--------->|*ref|                 | |*   | |    | |*ref|
 *  | |____| |    | |____|                 | |____| |    | |____|
 *  |________|    |_____________________   |________|    |_____________________
Vitor Sessak's avatar
Vitor Sessak committed
222 223 224
 */
void avfilter_formats_unref(AVFilterFormats **ref);

225 226 227 228
/**
 *
 *         Before                                 After
 *   ________                         ________
229
 *  |formats |<---------.            |formats |<---------.
230 231 232 233 234 235 236 237
 *  |  ____  |       ___|___         |  ____  |       ___|___
 *  | |refs| |      |   |   |        | |refs| |      |   |   |   NULL
 *  | |* *--------->|*oldref|        | |* *--------->|*newref|     ^
 *  | |* * | |      |_______|        | |* * | |      |_______|  ___|___
 *  | |____| |                       | |____| |                |   |   |
 *  |________|                       |________|                |*oldref|
 *                                                             |_______|
 */
Michael Niedermayer's avatar
Michael Niedermayer committed
238 239 240
void avfilter_formats_changeref(AVFilterFormats **oldref,
                                AVFilterFormats **newref);

241
/**
242
 * A filter pad used for either input or output.
243
 */
Vitor Sessak's avatar
Vitor Sessak committed
244 245 246
struct AVFilterPad
{
    /**
247 248 249
     * Pad name.  The name is unique among inputs and among outputs, but an
     * input may have the same name as an output.  This may be NULL if this
     * pad has no need to ever be referenced by name.
Vitor Sessak's avatar
Vitor Sessak committed
250
     */
Vitor Sessak's avatar
Vitor Sessak committed
251
    const char *name;
Vitor Sessak's avatar
Vitor Sessak committed
252 253 254 255 256

    /**
     * AVFilterPad type.  Only video supported now, hopefully someone will
     * add audio in the future.
     */
Vitor Sessak's avatar
Vitor Sessak committed
257
    enum CodecType type;
Vitor Sessak's avatar
Vitor Sessak committed
258

259
    /**
Stefano Sabatini's avatar
Stefano Sabatini committed
260
     * Minimum required permissions on incoming buffers.  Any buffer with
261 262 263 264 265 266 267 268 269
     * insufficient permissions will be automatically copied by the filter
     * system to a new buffer which provides the needed access permissions.
     *
     * Input pads only.
     */
    int min_perms;

    /**
     * Permissions which are not accepted on incoming buffers.  Any buffer
270 271 272 273
     * which has any of these permissions set will be automatically copied
     * by the filter system to a new buffer which does not have those
     * permissions.  This can be used to easily disallow buffers with
     * AV_PERM_REUSE.
274 275 276 277 278
     *
     * Input pads only.
     */
    int rej_perms;

Vitor Sessak's avatar
Vitor Sessak committed
279 280 281 282
    /**
     * Callback called before passing the first slice of a new frame.  If
     * NULL, the filter layer will default to storing a reference to the
     * picture inside the link structure.
283 284
     *
     * Input video pads only.
Vitor Sessak's avatar
Vitor Sessak committed
285 286 287 288 289
     */
    void (*start_frame)(AVFilterLink *link, AVFilterPicRef *picref);

    /**
     * Callback function to get a buffer.  If NULL, the filter system will
290 291 292
     * handle buffer requests.
     *
     * Input video pads only.
Vitor Sessak's avatar
Vitor Sessak committed
293 294 295 296 297 298 299
     */
    AVFilterPicRef *(*get_video_buffer)(AVFilterLink *link, int perms);

    /**
     * Callback called after the slices of a frame are completely sent.  If
     * NULL, the filter layer will default to releasing the reference stored
     * in the link structure during start_frame().
300 301
     *
     * Input video pads only.
Vitor Sessak's avatar
Vitor Sessak committed
302 303 304 305 306
     */
    void (*end_frame)(AVFilterLink *link);

    /**
     * Slice drawing callback.  This is where a filter receives video data
307 308 309
     * and should do its processing.
     *
     * Input video pads only.
Vitor Sessak's avatar
Vitor Sessak committed
310
     */
311
    void (*draw_slice)(AVFilterLink *link, int y, int height);
Vitor Sessak's avatar
Vitor Sessak committed
312

313 314 315 316 317 318 319 320 321 322 323
    /**
     * Frame poll callback.  This returns the number of immediately available
     * frames. It should return a positive value if the next request_frame()
     * is guaranteed to return one frame (with no delay).
     *
     * Defaults to just calling the source poll_frame() method.
     *
     * Output video pads only.
     */
    int (*poll_frame)(AVFilterLink *link);

Vitor Sessak's avatar
Vitor Sessak committed
324 325
    /**
     * Frame request callback.  A call to this should result in at least one
326 327 328 329
     * frame being output over the given link.  This should return zero on
     * success, and another value on error.
     *
     * Output video pads only.
Vitor Sessak's avatar
Vitor Sessak committed
330
     */
331
    int (*request_frame)(AVFilterLink *link);
Vitor Sessak's avatar
Vitor Sessak committed
332 333

    /**
334 335 336 337 338 339
     * Link configuration callback.
     *
     * For output pads, this should set the link properties such as
     * width/height.  This should NOT set the format property - that is
     * negotiated between filters by the filter system using the
     * query_formats() callback before this function is called.
340 341 342
     *
     * For input pads, this should check the properties of the link, and update
     * the filter's internal state as necessary.
343 344 345
     *
     * For both input and output filters, this should return zero on success,
     * and another value on error.
Vitor Sessak's avatar
Vitor Sessak committed
346
     */
347
    int (*config_props)(AVFilterLink *link);
Vitor Sessak's avatar
Vitor Sessak committed
348 349
};

350
/** default handler for start_frame() for video inputs */
Vitor Sessak's avatar
Vitor Sessak committed
351
void avfilter_default_start_frame(AVFilterLink *link, AVFilterPicRef *picref);
352
/** default handler for end_frame() for video inputs */
Vitor Sessak's avatar
Vitor Sessak committed
353
void avfilter_default_end_frame(AVFilterLink *link);
354
/** default handler for config_props() for video outputs */
355
int avfilter_default_config_output_link(AVFilterLink *link);
356
/** default handler for config_props() for video inputs */
357
int avfilter_default_config_input_link (AVFilterLink *link);
358
/** default handler for get_video_buffer() for video inputs */
359 360
AVFilterPicRef *avfilter_default_get_video_buffer(AVFilterLink *link,
                                                  int perms);
Vitor Sessak's avatar
Vitor Sessak committed
361 362 363 364 365 366 367 368
/**
 * A helper for query_formats() which sets all links to the same list of
 * formats. If there are no links hooked to this filter, the list of formats is
 * freed.
 */
void avfilter_set_common_formats(AVFilterContext *ctx, AVFilterFormats *formats);
/** Default handler for query_formats() */
int avfilter_default_query_formats(AVFilterContext *ctx);
Vitor Sessak's avatar
Vitor Sessak committed
369

370 371 372 373
/**
 * Filter definition.  This defines the pads a filter contains, and all the
 * callback functions used to interact with the filter.
 */
Vitor Sessak's avatar
Vitor Sessak committed
374 375
typedef struct
{
Vitor Sessak's avatar
Vitor Sessak committed
376
    const char *name;         ///< filter name
Vitor Sessak's avatar
Vitor Sessak committed
377

378
    int priv_size;      ///< size of private data to allocate for the filter
Vitor Sessak's avatar
Vitor Sessak committed
379

380 381 382
    /**
     * Filter initialization function.  Args contains the user-supplied
     * parameters.  FIXME: maybe an AVOption-based system would be better?
383 384
     * opaque is data provided by the code requesting creation of the filter,
     * and is used to pass data to the filter.
385
     */
386
    int (*init)(AVFilterContext *ctx, const char *args, void *opaque);
387 388 389 390 391 392

    /**
     * Filter uninitialization function.  Should deallocate any memory held
     * by the filter, release any picture references, etc.  This does not need
     * to deallocate the AVFilterContext->priv memory itself.
     */
Vitor Sessak's avatar
Vitor Sessak committed
393 394
    void (*uninit)(AVFilterContext *ctx);

Vitor Sessak's avatar
Vitor Sessak committed
395 396 397 398 399 400 401 402 403
    /**
     * Query formats supported by the filter and its pads. Should set the
     * in_formats for links connected to its output pads, and out_formats
     * for links connected to its input pads.
     *
     * Should return zero on success.
     */
    int (*query_formats)(AVFilterContext *);

404 405
    const AVFilterPad *inputs;  ///< NULL terminated list of inputs. NULL if none
    const AVFilterPad *outputs; ///< NULL terminated list of outputs. NULL if none
Vitor Sessak's avatar
Vitor Sessak committed
406 407
} AVFilter;

408
/** An instance of a filter */
Vitor Sessak's avatar
Vitor Sessak committed
409 410
struct AVFilterContext
{
411
    const AVClass *av_class;              ///< needed for av_log()
Vitor Sessak's avatar
Vitor Sessak committed
412

413
    AVFilter *filter;               ///< the AVFilter of which this is an instance
Vitor Sessak's avatar
Vitor Sessak committed
414

415
    char *name;                     ///< name of this filter instance
416

417 418 419
    unsigned input_count;           ///< number of input pads
    AVFilterPad   *input_pads;      ///< array of input pads
    AVFilterLink **inputs;          ///< array of pointers to input links
Vitor Sessak's avatar
Vitor Sessak committed
420

421 422 423
    unsigned output_count;          ///< number of output pads
    AVFilterPad   *output_pads;     ///< array of output pads
    AVFilterLink **outputs;         ///< array of pointers to output links
Vitor Sessak's avatar
Vitor Sessak committed
424

425
    void *priv;                     ///< private data for use by the filter
Vitor Sessak's avatar
Vitor Sessak committed
426 427
};

428
/**
429
 * A link between two filters.  This contains pointers to the source and
430
 * destination filters between which this link exists, and the indexes of
431 432
 * the pads involved.  In addition, this link also contains the parameters
 * which have been negotiated and agreed upon between the filter, such as
433
 * image dimensions, format, etc.
434
 */
Vitor Sessak's avatar
Vitor Sessak committed
435 436
struct AVFilterLink
{
437 438
    AVFilterContext *src;       ///< source filter
    unsigned int srcpad;        ///< index of the output pad on the source filter
Vitor Sessak's avatar
Vitor Sessak committed
439

440 441
    AVFilterContext *dst;       ///< dest filter
    unsigned int dstpad;        ///< index of the input pad on the dest filter
Vitor Sessak's avatar
Vitor Sessak committed
442

443 444 445 446 447 448 449
    /** stage of the initialization of the link properties (dimensions, etc) */
    enum {
        AVLINK_UNINIT = 0,      ///< not started
        AVLINK_STARTINIT,       ///< started, but incomplete
        AVLINK_INIT             ///< complete
    } init_state;

450 451 452
    int w;                      ///< agreed upon image width
    int h;                      ///< agreed upon image height
    enum PixelFormat format;    ///< agreed upon image colorspace
Vitor Sessak's avatar
Vitor Sessak committed
453

Vitor Sessak's avatar
Vitor Sessak committed
454 455 456 457 458 459 460 461
    /**
     * Lists of formats supported by the input and output filters respectively.
     * These lists are used for negotiating the format to actually be used,
     * which will be loaded into the format member, above, when chosen.
     */
    AVFilterFormats *in_formats;
    AVFilterFormats *out_formats;

462 463 464
    /**
     * The picture reference currently being sent across the link by the source
     * filter.  This is used internally by the filter system to allow
465
     * automatic copying of pictures which do not have sufficient permissions
466 467 468 469 470
     * for the destination.  This should not be accessed directly by the
     * filters.
     */
    AVFilterPicRef *srcpic;

Vitor Sessak's avatar
Vitor Sessak committed
471
    AVFilterPicRef *cur_pic;
472
    AVFilterPicRef *outpic;
Vitor Sessak's avatar
Vitor Sessak committed
473 474
};

475
/**
476 477 478 479 480 481
 * Link two filters together.
 * @param src    the source filter
 * @param srcpad index of the output pad on the source filter
 * @param dst    the destination filter
 * @param dstpad index of the input pad on the destination filter
 * @return       zero on success
482
 */
Vitor Sessak's avatar
Vitor Sessak committed
483 484 485
int avfilter_link(AVFilterContext *src, unsigned srcpad,
                  AVFilterContext *dst, unsigned dstpad);

486
/**
487
 * Negotiate the colorspace, dimensions, etc of all inputs to a filter.
488 489
 * @param filter the filter to negotiate the properties for its inputs
 * @return       zero on successful negotiation
490
 */
491
int avfilter_config_links(AVFilterContext *filter);
492

493
/**
494
 * Request a picture buffer with a specific set of permissions.
495
 * @param link  the output link to the filter from which the picture will
496
 *              be requested
497
 * @param perms the required access permissions
498 499 500
 * @return      A reference to the picture.  This must be unreferenced with
 *              avfilter_unref_pic when you are finished with it.
 */
Vitor Sessak's avatar
Vitor Sessak committed
501
AVFilterPicRef *avfilter_get_video_buffer(AVFilterLink *link, int perms);
502 503 504

/**
 * Request an input frame from the filter at the other end of the link.
505 506
 * @param link the input link
 * @return     zero on success
507
 */
Vitor Sessak's avatar
Vitor Sessak committed
508
int avfilter_request_frame(AVFilterLink *link);
509

510 511 512
/**
 * Poll a frame from the filter chain.
 * @param  link the input link
513 514
 * @return the number of immediately available frames, a negative
 * number in case of error
515 516 517
 */
int avfilter_poll_frame(AVFilterLink *link);

518
/**
Vitor Sessak's avatar
Vitor Sessak committed
519
 * Notify the next filter of the start of a frame.
520
 * @param link   the output link the frame will be sent over
521 522 523 524 525
 * @param picref A reference to the frame about to be sent.  The data for this
 *               frame need only be valid once draw_slice() is called for that
 *               portion.  The receiving filter will free this reference when
 *               it no longer needs it.
 */
Vitor Sessak's avatar
Vitor Sessak committed
526
void avfilter_start_frame(AVFilterLink *link, AVFilterPicRef *picref);
527 528

/**
529
 * Notify the next filter that the current frame has finished.
530
 * @param link the output link the frame was sent over
531
 */
Vitor Sessak's avatar
Vitor Sessak committed
532
void avfilter_end_frame(AVFilterLink *link);
533 534

/**
535 536 537 538
 * Send a slice to the next filter.
 * @param link the output link over which the frame is being sent
 * @param y    offset in pixels from the top of the image for this slice
 * @param h    height of this slice in pixels
539
 */
540
void avfilter_draw_slice(AVFilterLink *link, int y, int h);
Vitor Sessak's avatar
Vitor Sessak committed
541

542
/** Initialize the filter system.  Registers all builtin filters */
Vitor Sessak's avatar
Oops  
Vitor Sessak committed
543
void avfilter_register_all(void);
544

545
/** Uninitialize the filter system.  Unregisters all filters */
Vitor Sessak's avatar
Vitor Sessak committed
546
void avfilter_uninit(void);
547 548

/**
549 550 551 552
 * Register a filter.  This is only needed if you plan to use
 * avfilter_get_by_name later to lookup the AVFilter structure by name. A
 * filter can still by instantiated with avfilter_open even if it is not
 * registered.
553
 * @param filter the filter to register
554
 */
Vitor Sessak's avatar
Vitor Sessak committed
555
void avfilter_register(AVFilter *filter);
556 557

/**
558 559 560
 * Gets a filter definition matching the given name.
 * @param name the filter name to find
 * @return     the filter definition, if any matching one is registered.
561 562
 *             NULL if none found.
 */
Vitor Sessak's avatar
Vitor Sessak committed
563
AVFilter *avfilter_get_by_name(const char *name);
Vitor Sessak's avatar
Vitor Sessak committed
564

565
/**
566 567
 * Create a filter instance.
 * @param filter    the filter to create an instance of
568 569 570
 * @param inst_name Name to give to the new instance.  Can be NULL for none.
 * @return          Pointer to the new instance on success.  NULL on failure.
 */
Vitor Sessak's avatar
Vitor Sessak committed
571
AVFilterContext *avfilter_open(AVFilter *filter, const char *inst_name);
572 573

/**
574 575
 * Initialize a filter.
 * @param filter the filter to initialize
576 577 578 579
 * @param args   A string of parameters to use when initializing the filter.
 *               The format and meaning of this string varies by filter.
 * @param opaque Any extra non-string data needed by the filter.  The meaning
 *               of this parameter varies by filter.
580
 * @return       zero on success
581
 */
582
int avfilter_init_filter(AVFilterContext *filter, const char *args, void *opaque);
583 584

/**
585 586
 * Destroy a filter.
 * @param filter the filter to destroy
587
 */
Vitor Sessak's avatar
Vitor Sessak committed
588 589
void avfilter_destroy(AVFilterContext *filter);

590
/**
Vitor Sessak's avatar
Vitor Sessak committed
591
 * Insert a filter in the middle of an existing link.
592 593 594 595 596
 * @param link the link into which the filter should be inserted
 * @param filt the filter to be inserted
 * @param in   the input pad on the filter to connect
 * @param out  the output pad on the filter to connect
 * @return     zero on success
597
 */
Vitor Sessak's avatar
Vitor Sessak committed
598 599
int avfilter_insert_filter(AVFilterLink *link, AVFilterContext *filt,
                           unsigned in, unsigned out);
600

601
/**
602
 * Insert a new pad.
603 604 605 606 607 608 609 610 611 612 613 614 615 616
 * @param idx Insertion point.  Pad is inserted at the end if this point
 *            is beyond the end of the list of pads.
 * @param count Pointer to the number of pads in the list
 * @param padidx_off Offset within an AVFilterLink structure to the element
 *                   to increment when inserting a new pad causes link
 *                   numbering to change
 * @param pads Pointer to the pointer to the beginning of the list of pads
 * @param links Pointer to the pointer to the beginning of the list of links
 * @param newpad The new pad to add. A copy is made when adding.
 */
void avfilter_insert_pad(unsigned idx, unsigned *count, size_t padidx_off,
                         AVFilterPad **pads, AVFilterLink ***links,
                         AVFilterPad *newpad);

617
/** Insert a new input pad for the filter. */
618 619 620 621 622 623 624
static inline void avfilter_insert_inpad(AVFilterContext *f, unsigned index,
                                         AVFilterPad *p)
{
    avfilter_insert_pad(index, &f->input_count, offsetof(AVFilterLink, dstpad),
                        &f->input_pads, &f->inputs, p);
}

625
/** Insert a new output pad for the filter. */
626 627 628 629 630 631 632
static inline void avfilter_insert_outpad(AVFilterContext *f, unsigned index,
                                          AVFilterPad *p)
{
    avfilter_insert_pad(index, &f->output_count, offsetof(AVFilterLink, srcpad),
                        &f->output_pads, &f->outputs, p);
}

633
#endif  /* AVFILTER_AVFILTER_H */