avfilter.h 30 KB
Newer Older
Vitor Sessak's avatar
Vitor Sessak committed
1
/*
2
 * filter layer
3
 * Copyright (c) 2007 Bobby Bingham
Vitor Sessak's avatar
Vitor Sessak committed
4
 *
5
 * This file is part of Libav.
Vitor Sessak's avatar
Vitor Sessak committed
6
 *
7
 * Libav is free software; you can redistribute it and/or
Vitor Sessak's avatar
Vitor Sessak committed
8 9 10 11
 * 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.
 *
12
 * Libav is distributed in the hope that it will be useful,
Vitor Sessak's avatar
Vitor Sessak committed
13 14 15 16 17
 * 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
18
 * License along with Libav; if not, write to the Free Software
Vitor Sessak's avatar
Vitor Sessak committed
19 20 21
 * 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
#include "libavutil/avutil.h"
Anton Khirnov's avatar
Anton Khirnov committed
26
#include "libavutil/frame.h"
27
#include "libavutil/log.h"
28
#include "libavutil/samplefmt.h"
29
#include "libavutil/pixfmt.h"
30
#include "libavutil/rational.h"
31
#include "libavcodec/avcodec.h"
32

33
#include <stddef.h>
Vitor Sessak's avatar
Vitor Sessak committed
34

35 36
#include "libavfilter/version.h"

37
/**
38
 * Return the LIBAVFILTER_VERSION_INT constant.
39 40 41
 */
unsigned avfilter_version(void);

42
/**
43
 * Return the libavfilter build-time configuration.
44
 */
45
const char *avfilter_configuration(void);
46 47

/**
48
 * Return the libavfilter license.
49
 */
50
const char *avfilter_license(void);
51 52


Vitor Sessak's avatar
Vitor Sessak committed
53 54 55
typedef struct AVFilterContext AVFilterContext;
typedef struct AVFilterLink    AVFilterLink;
typedef struct AVFilterPad     AVFilterPad;
56
typedef struct AVFilterFormats AVFilterFormats;
Vitor Sessak's avatar
Vitor Sessak committed
57

Anton Khirnov's avatar
Anton Khirnov committed
58
#if FF_API_AVFILTERBUFFER
Vitor Sessak's avatar
Vitor Sessak committed
59
/**
60
 * A reference-counted buffer data type used by the filter system. Filters
Vitor Sessak's avatar
Vitor Sessak committed
61
 * should not store pointers to this structure directly, but instead use the
62
 * AVFilterBufferRef structure below.
Vitor Sessak's avatar
Vitor Sessak committed
63
 */
64
typedef struct AVFilterBuffer {
65
    uint8_t *data[8];           ///< buffer data for each plane/channel
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81

    /**
     * pointers to the data planes/channels.
     *
     * For video, this should simply point to data[].
     *
     * For planar audio, each channel has a separate data pointer, and
     * linesize[0] contains the size of each channel buffer.
     * For packed audio, there is just one data pointer, and linesize[0]
     * contains the total size of the buffer for all channels.
     *
     * Note: Both data and extended_data will always be set, but for planar
     * audio with more channels that can fit in data, extended_data must be used
     * in order to access all channels.
     */
    uint8_t **extended_data;
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96
    int linesize[8];            ///< number of bytes per line

    /** private data to be used by a custom free function */
    void *priv;
    /**
     * A pointer to the function to deallocate this buffer 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.
     */
    void (*free)(struct AVFilterBuffer *buf);

    int format;                 ///< media format
    int w, h;                   ///< width and height of the allocated buffer
    unsigned refcount;          ///< number of references to this buffer
97
} AVFilterBuffer;
Vitor Sessak's avatar
Vitor Sessak committed
98

99 100 101 102 103
#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
#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
104
#define AV_PERM_NEG_LINESIZES 0x20  ///< the buffer requested can have negative linesizes
105

106 107 108 109 110 111
/**
 * Audio specific properties in a reference to an AVFilterBuffer. Since
 * AVFilterBufferRef is common to different media formats, audio specific
 * per reference properties must be separated out.
 */
typedef struct AVFilterBufferRefAudioProps {
112
    uint64_t channel_layout;    ///< channel layout of audio buffer
113
    int nb_samples;             ///< number of audio samples
114
    int sample_rate;            ///< audio buffer sample rate
115 116 117
    int planar;                 ///< audio buffer - planar or packed
} AVFilterBufferRefAudioProps;

118 119 120 121 122
/**
 * Video specific properties in a reference to an AVFilterBuffer. Since
 * AVFilterBufferRef is common to different media formats, video specific
 * per reference properties must be separated out.
 */
123
typedef struct AVFilterBufferRefVideoProps {
124 125 126 127 128
    int w;                      ///< image width
    int h;                      ///< image height
    AVRational pixel_aspect;    ///< pixel aspect ratio
    int interlaced;             ///< is frame interlaced
    int top_field_first;        ///< field order
129
    enum AVPictureType pict_type; ///< picture type of the frame
130
    int key_frame;              ///< 1 -> keyframe, 0-> not
131 132
} AVFilterBufferRefVideoProps;

Vitor Sessak's avatar
Vitor Sessak committed
133
/**
134
 * A reference to an AVFilterBuffer. Since filters can manipulate the origin of
135
 * a buffer to, for example, crop image without any memcpy, the buffer origin
136
 * and dimensions are per-reference properties. Linesize is also useful for
137
 * image flipping, frame to field filters, etc, and so is also per-reference.
Vitor Sessak's avatar
Vitor Sessak committed
138
 *
Vitor Sessak's avatar
Vitor Sessak committed
139
 * TODO: add anything necessary for frame reordering
Vitor Sessak's avatar
Vitor Sessak committed
140
 */
141
typedef struct AVFilterBufferRef {
142
    AVFilterBuffer *buf;        ///< the buffer that this is a reference to
143
    uint8_t *data[8];           ///< picture/audio data for each plane
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
    /**
     * pointers to the data planes/channels.
     *
     * For video, this should simply point to data[].
     *
     * For planar audio, each channel has a separate data pointer, and
     * linesize[0] contains the size of each channel buffer.
     * For packed audio, there is just one data pointer, and linesize[0]
     * contains the total size of the buffer for all channels.
     *
     * Note: Both data and extended_data will always be set, but for planar
     * audio with more channels that can fit in data, extended_data must be used
     * in order to access all channels.
     */
    uint8_t **extended_data;
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176
    int linesize[8];            ///< number of bytes per line

    AVFilterBufferRefVideoProps *video; ///< video buffer specific properties
    AVFilterBufferRefAudioProps *audio; ///< audio buffer specific properties

    /**
     * presentation timestamp. The time unit may change during
     * filtering, as it is specified in the link and the filter code
     * may need to rescale the PTS accordingly.
     */
    int64_t pts;
    int64_t pos;                ///< byte position in stream, -1 if unknown

    int format;                 ///< media format

    int perms;                  ///< permissions, see the AV_PERM_* flags

    enum AVMediaType type;      ///< media type of buffer data
177
} AVFilterBufferRef;
Vitor Sessak's avatar
Vitor Sessak committed
178

179
/**
180
 * Copy properties of src to dst, without copying the actual data
181
 */
Anton Khirnov's avatar
Anton Khirnov committed
182
attribute_deprecated
183
void avfilter_copy_buffer_ref_props(AVFilterBufferRef *dst, AVFilterBufferRef *src);
184

Vitor Sessak's avatar
Vitor Sessak committed
185
/**
186
 * Add a new reference to a buffer.
187
 *
188
 * @param ref   an existing reference to the buffer
189
 * @param pmask a bitmask containing the allowable permissions in the new
190
 *              reference
191
 * @return      a new reference to the buffer with the same properties as the
192
 *              old, excluding any permissions denied by pmask
Vitor Sessak's avatar
Vitor Sessak committed
193
 */
Anton Khirnov's avatar
Anton Khirnov committed
194
attribute_deprecated
195
AVFilterBufferRef *avfilter_ref_buffer(AVFilterBufferRef *ref, int pmask);
Vitor Sessak's avatar
Vitor Sessak committed
196 197

/**
198 199
 * Remove a reference to a buffer. If this is the last reference to the
 * buffer, the buffer itself is also automatically freed.
200
 *
201
 * @param ref reference to the buffer, may be NULL
202 203 204
 *
 * @note it is recommended to use avfilter_unref_bufferp() instead of this
 * function
Vitor Sessak's avatar
Vitor Sessak committed
205
 */
Anton Khirnov's avatar
Anton Khirnov committed
206
attribute_deprecated
207
void avfilter_unref_buffer(AVFilterBufferRef *ref);
Vitor Sessak's avatar
Vitor Sessak committed
208

209 210 211 212 213 214 215
/**
 * Remove a reference to a buffer and set the pointer to NULL.
 * If this is the last reference to the buffer, the buffer itself
 * is also automatically freed.
 *
 * @param ref pointer to the buffer reference
 */
Anton Khirnov's avatar
Anton Khirnov committed
216
attribute_deprecated
217
void avfilter_unref_bufferp(AVFilterBufferRef **ref);
Anton Khirnov's avatar
Anton Khirnov committed
218
#endif
219

220
#if FF_API_AVFILTERPAD_PUBLIC
221
/**
222
 * A filter pad used for either input or output.
223 224 225 226 227
 *
 * @warning this struct will be removed from public API.
 * users should call avfilter_pad_get_name() and avfilter_pad_get_type()
 * to access the name and type fields; there should be no need to access
 * any other fields from outside of libavfilter.
228
 */
229
struct AVFilterPad {
Vitor Sessak's avatar
Vitor Sessak committed
230
    /**
231 232
     * 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
233
     * pad has no need to ever be referenced by name.
Vitor Sessak's avatar
Vitor Sessak committed
234
     */
Vitor Sessak's avatar
Vitor Sessak committed
235
    const char *name;
Vitor Sessak's avatar
Vitor Sessak committed
236 237

    /**
238
     * AVFilterPad type.
Vitor Sessak's avatar
Vitor Sessak committed
239
     */
240
    enum AVMediaType type;
Vitor Sessak's avatar
Vitor Sessak committed
241

242
    /**
243
     * Minimum required permissions on incoming buffers. Any buffer with
244 245 246 247 248
     * insufficient permissions will be automatically copied by the filter
     * system to a new buffer which provides the needed access permissions.
     *
     * Input pads only.
     */
Anton Khirnov's avatar
Anton Khirnov committed
249
    attribute_deprecated int min_perms;
250 251

    /**
252
     * Permissions which are not accepted on incoming buffers. Any buffer
253 254
     * which has any of these permissions set will be automatically copied
     * by the filter system to a new buffer which does not have those
255
     * permissions. This can be used to easily disallow buffers with
256
     * AV_PERM_REUSE.
257 258 259
     *
     * Input pads only.
     */
Anton Khirnov's avatar
Anton Khirnov committed
260
    attribute_deprecated int rej_perms;
261

Vitor Sessak's avatar
Vitor Sessak committed
262
    /**
263
     * @deprecated unused
Vitor Sessak's avatar
Vitor Sessak committed
264
     */
265
    int (*start_frame)(AVFilterLink *link, AVFilterBufferRef *picref);
Vitor Sessak's avatar
Vitor Sessak committed
266 267

    /**
268
     * Callback function to get a video buffer. If NULL, the filter system will
269
     * use avfilter_default_get_video_buffer().
270 271
     *
     * Input video pads only.
Vitor Sessak's avatar
Vitor Sessak committed
272
     */
Anton Khirnov's avatar
Anton Khirnov committed
273
    AVFrame *(*get_video_buffer)(AVFilterLink *link, int w, int h);
Vitor Sessak's avatar
Vitor Sessak committed
274

275 276 277 278 279 280
    /**
     * Callback function to get an audio buffer. If NULL, the filter system will
     * use avfilter_default_get_audio_buffer().
     *
     * Input audio pads only.
     */
Anton Khirnov's avatar
Anton Khirnov committed
281
    AVFrame *(*get_audio_buffer)(AVFilterLink *link, int nb_samples);
282

Vitor Sessak's avatar
Vitor Sessak committed
283
    /**
284
     * @deprecated unused
Vitor Sessak's avatar
Vitor Sessak committed
285
     */
286
    int (*end_frame)(AVFilterLink *link);
Vitor Sessak's avatar
Vitor Sessak committed
287 288

    /**
289
     * @deprecated unused
Vitor Sessak's avatar
Vitor Sessak committed
290
     */
291
    int (*draw_slice)(AVFilterLink *link, int y, int height, int slice_dir);
Vitor Sessak's avatar
Vitor Sessak committed
292

293
    /**
294 295
     * Filtering callback. This is where a filter receives a frame with
     * audio/video data and should do its processing.
296
     *
297
     * Input pads only.
298 299 300 301
     *
     * @return >= 0 on success, a negative AVERROR on error. This function
     * must ensure that samplesref is properly unreferenced on error if it
     * hasn't been passed on to another filter.
302
     */
Anton Khirnov's avatar
Anton Khirnov committed
303
    int (*filter_frame)(AVFilterLink *link, AVFrame *frame);
304

305
    /**
306
     * Frame poll callback. This returns the number of immediately available
307
     * samples. It should return a positive value if the next request_frame()
308 309 310 311
     * is guaranteed to return one frame (with no delay).
     *
     * Defaults to just calling the source poll_frame() method.
     *
Anton Khirnov's avatar
Anton Khirnov committed
312
     * Output pads only.
313 314 315
     */
    int (*poll_frame)(AVFilterLink *link);

Vitor Sessak's avatar
Vitor Sessak committed
316
    /**
317 318
     * Frame request callback. A call to this should result in at least one
     * frame being output over the given link. This should return zero on
319 320
     * success, and another value on error.
     *
Anton Khirnov's avatar
Anton Khirnov committed
321
     * Output pads only.
Vitor Sessak's avatar
Vitor Sessak committed
322
     */
323
    int (*request_frame)(AVFilterLink *link);
Vitor Sessak's avatar
Vitor Sessak committed
324 325

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

    /**
     * The filter expects a fifo to be inserted on its input link,
     * typically because it has a delay.
     *
     * input pads only.
     */
    int needs_fifo;
Anton Khirnov's avatar
Anton Khirnov committed
348 349

    int needs_writable;
Vitor Sessak's avatar
Vitor Sessak committed
350
};
351
#endif
Vitor Sessak's avatar
Vitor Sessak committed
352

353 354 355 356 357 358 359 360 361
/**
 * Get the name of an AVFilterPad.
 *
 * @param pads an array of AVFilterPads
 * @param pad_idx index of the pad in the array it; is the caller's
 *                responsibility to ensure the index is valid
 *
 * @return name of the pad_idx'th pad in pads
 */
362
const char *avfilter_pad_get_name(const AVFilterPad *pads, int pad_idx);
363 364 365 366 367 368 369 370 371 372

/**
 * Get the type of an AVFilterPad.
 *
 * @param pads an array of AVFilterPads
 * @param pad_idx index of the pad in the array; it is the caller's
 *                responsibility to ensure the index is valid
 *
 * @return type of the pad_idx'th pad in pads
 */
373
enum AVMediaType avfilter_pad_get_type(const AVFilterPad *pads, int pad_idx);
374

375
/**
376
 * Filter definition. This defines the pads a filter contains, and all the
377 378
 * callback functions used to interact with the filter.
 */
379
typedef struct AVFilter {
Vitor Sessak's avatar
Vitor Sessak committed
380
    const char *name;         ///< filter name
Vitor Sessak's avatar
Vitor Sessak committed
381

382 383 384 385 386 387 388 389 390
    /**
     * A description for the filter. You should use the
     * NULL_IF_CONFIG_SMALL() macro to define it.
     */
    const char *description;

    const AVFilterPad *inputs;  ///< NULL terminated list of inputs. NULL if none
    const AVFilterPad *outputs; ///< NULL terminated list of outputs. NULL if none

391 392 393 394 395 396
    /**
     * A class for the private data, used to access filter private
     * AVOptions.
     */
    const AVClass *priv_class;

397 398 399 400 401 402 403
    /*****************************************************************
     * All fields below this line are not part of the public API. They
     * may not be used outside of libavfilter and can be changed and
     * removed at will.
     * New public fields should be added right above.
     *****************************************************************
     */
Vitor Sessak's avatar
Vitor Sessak committed
404

405
    /**
406 407
     * Filter initialization function. Called when all the options have been
     * set.
408
     */
409
    int (*init)(AVFilterContext *ctx);
410

411 412 413 414 415 416 417
    /**
     * Should be set instead of init by the filters that want to pass a
     * dictionary of AVOptions to nested contexts that are allocated in
     * init.
     */
    int (*init_dict)(AVFilterContext *ctx, AVDictionary **options);

418
    /**
419
     * Filter uninitialization function. Should deallocate any memory held
420
     * by the filter, release any buffer references, etc. This does not need
421 422
     * to deallocate the AVFilterContext->priv memory itself.
     */
Vitor Sessak's avatar
Vitor Sessak committed
423 424
    void (*uninit)(AVFilterContext *ctx);

Vitor Sessak's avatar
Vitor Sessak committed
425
    /**
426
     * Queries formats supported by the filter and its pads, and sets the
Vitor Sessak's avatar
Vitor Sessak committed
427 428 429
     * in_formats for links connected to its output pads, and out_formats
     * for links connected to its input pads.
     *
430 431
     * @return zero on success, a negative value corresponding to an
     * AVERROR code otherwise
Vitor Sessak's avatar
Vitor Sessak committed
432 433 434
     */
    int (*query_formats)(AVFilterContext *);

435
    int priv_size;      ///< size of private data to allocate for the filter
Vitor Sessak's avatar
Vitor Sessak committed
436 437
} AVFilter;

438
/** An instance of a filter */
439
struct AVFilterContext {
440
    const AVClass *av_class;              ///< needed for av_log()
Vitor Sessak's avatar
Vitor Sessak committed
441

442
    const AVFilter *filter;         ///< the AVFilter of which this is an instance
Vitor Sessak's avatar
Vitor Sessak committed
443

444
    char *name;                     ///< name of this filter instance
445

446 447
    AVFilterPad   *input_pads;      ///< array of input pads
    AVFilterLink **inputs;          ///< array of pointers to input links
448 449 450
#if FF_API_FOO_COUNT
    unsigned input_count;           ///< @deprecated use nb_inputs
#endif
451
    unsigned    nb_inputs;          ///< number of input pads
Vitor Sessak's avatar
Vitor Sessak committed
452

453 454
    AVFilterPad   *output_pads;     ///< array of output pads
    AVFilterLink **outputs;         ///< array of pointers to output links
455 456 457
#if FF_API_FOO_COUNT
    unsigned output_count;          ///< @deprecated use nb_outputs
#endif
458
    unsigned    nb_outputs;         ///< number of output pads
Vitor Sessak's avatar
Vitor Sessak committed
459

460
    void *priv;                     ///< private data for use by the filter
Vitor Sessak's avatar
Vitor Sessak committed
461 462
};

463
/**
464
 * A link between two filters. This contains pointers to the source and
465
 * destination filters between which this link exists, and the indexes of
466
 * the pads involved. In addition, this link also contains the parameters
467
 * which have been negotiated and agreed upon between the filter, such as
468
 * image dimensions, format, etc.
469
 */
470
struct AVFilterLink {
471
    AVFilterContext *src;       ///< source filter
472
    AVFilterPad *srcpad;        ///< output pad on the source filter
Vitor Sessak's avatar
Vitor Sessak committed
473

474
    AVFilterContext *dst;       ///< dest filter
475
    AVFilterPad *dstpad;        ///< input pad on the dest filter
Vitor Sessak's avatar
Vitor Sessak committed
476

477 478
    enum AVMediaType type;      ///< filter media type

479
    /* These parameters apply only to video */
480 481
    int w;                      ///< agreed upon image width
    int h;                      ///< agreed upon image height
482
    AVRational sample_aspect_ratio; ///< agreed upon sample aspect ratio
483
    /* These two parameters apply only to audio */
484
    uint64_t channel_layout;    ///< channel layout of current buffer (see libavutil/channel_layout.h)
485
    int sample_rate;            ///< samples per second
486

487
    int format;                 ///< agreed upon media format
Vitor Sessak's avatar
Vitor Sessak committed
488

489 490 491 492 493 494 495 496
    /**
     * Define the time base used by the PTS of the frames/samples
     * which will pass through this link.
     * During the configuration stage, each filter is supposed to
     * change only the output timebase, while the timebase of the
     * input link is assumed to be an unchangeable property.
     */
    AVRational time_base;
497 498 499 500 501 502 503 504

    /*****************************************************************
     * All fields below this line are not part of the public API. They
     * may not be used outside of libavfilter and can be changed and
     * removed at will.
     * New public fields should be added right above.
     *****************************************************************
     */
505 506 507 508 509 510 511 512
    /**
     * 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;

513 514 515 516 517 518 519 520
    /**
     * Lists of channel layouts and sample rates used for automatic
     * negotiation.
     */
    AVFilterFormats  *in_samplerates;
    AVFilterFormats *out_samplerates;
    struct AVFilterChannelLayouts  *in_channel_layouts;
    struct AVFilterChannelLayouts *out_channel_layouts;
521 522 523 524 525 526 527 528 529

    /**
     * Audio only, the destination filter sets this to a non-zero value to
     * request that buffers with the given number of samples should be sent to
     * it. AVFilterPad.needs_fifo must also be set on the corresponding input
     * pad.
     * Last buffer before EOF will be padded with silence.
     */
    int request_samples;
530 531 532 533 534 535 536

    /** 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;
Vitor Sessak's avatar
Vitor Sessak committed
537 538
};

539
/**
540
 * Link two filters together.
541
 *
542 543 544 545 546
 * @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
547
 */
Vitor Sessak's avatar
Vitor Sessak committed
548 549 550
int avfilter_link(AVFilterContext *src, unsigned srcpad,
                  AVFilterContext *dst, unsigned dstpad);

551
/**
552
 * Negotiate the media format, dimensions, etc of all inputs to a filter.
553
 *
554 555
 * @param filter the filter to negotiate the properties for its inputs
 * @return       zero on successful negotiation
556
 */
557
int avfilter_config_links(AVFilterContext *filter);
558

Anton Khirnov's avatar
Anton Khirnov committed
559
#if FF_API_AVFILTERBUFFER
560 561 562 563 564 565 566 567 568 569 570
/**
 * Create a buffer reference wrapped around an already allocated image
 * buffer.
 *
 * @param data pointers to the planes of the image to reference
 * @param linesize linesizes for the planes of the image to reference
 * @param perms the required access permissions
 * @param w the width of the image specified by the data and linesize arrays
 * @param h the height of the image specified by the data and linesize arrays
 * @param format the pixel format of the image specified by the data and linesize arrays
 */
Anton Khirnov's avatar
Anton Khirnov committed
571
attribute_deprecated
572 573
AVFilterBufferRef *
avfilter_get_video_buffer_ref_from_arrays(uint8_t *data[4], int linesize[4], int perms,
574
                                          int w, int h, enum AVPixelFormat format);
575

576 577 578 579 580 581 582 583 584 585 586
/**
 * Create an audio buffer reference wrapped around an already
 * allocated samples buffer.
 *
 * @param data           pointers to the samples plane buffers
 * @param linesize       linesize for the samples plane buffers
 * @param perms          the required access permissions
 * @param nb_samples     number of samples per channel
 * @param sample_fmt     the format of each sample in the buffer to allocate
 * @param channel_layout the channel layout of the buffer
 */
Anton Khirnov's avatar
Anton Khirnov committed
587
attribute_deprecated
588 589 590 591 592 593
AVFilterBufferRef *avfilter_get_audio_buffer_ref_from_arrays(uint8_t **data,
                                                             int linesize,
                                                             int perms,
                                                             int nb_samples,
                                                             enum AVSampleFormat sample_fmt,
                                                             uint64_t channel_layout);
Anton Khirnov's avatar
Anton Khirnov committed
594
#endif
595

596
/** Initialize the filter system. Register all builtin filters. */
Vitor Sessak's avatar
Oops  
Vitor Sessak committed
597
void avfilter_register_all(void);
598

599
/** Uninitialize the filter system. Unregister all filters. */
Vitor Sessak's avatar
Vitor Sessak committed
600
void avfilter_uninit(void);
601 602

/**
603
 * Register a filter. This is only needed if you plan to use
604 605 606
 * 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.
607
 *
608
 * @param filter the filter to register
609 610
 * @return 0 if the registration was succesfull, a negative value
 * otherwise
611
 */
612
int avfilter_register(AVFilter *filter);
613 614

/**
615
 * Get a filter definition matching the given name.
616
 *
617 618
 * @param name the filter name to find
 * @return     the filter definition, if any matching one is registered.
619 620
 *             NULL if none found.
 */
Vitor Sessak's avatar
Vitor Sessak committed
621
AVFilter *avfilter_get_by_name(const char *name);
Vitor Sessak's avatar
Vitor Sessak committed
622

Stefano Sabatini's avatar
Stefano Sabatini committed
623 624 625 626 627 628 629 630
/**
 * If filter is NULL, returns a pointer to the first registered filter pointer,
 * if filter is non-NULL, returns the next pointer after filter.
 * If the returned pointer points to NULL, the last registered filter
 * was already reached.
 */
AVFilter **av_filter_next(AVFilter **filter);

631
/**
632
 * Create a filter instance.
633 634 635
 *
 * @param filter_ctx put here a pointer to the created filter context
 * on success, NULL on failure
636
 * @param filter    the filter to create an instance of
637
 * @param inst_name Name to give to the new instance. Can be NULL for none.
638
 * @return >= 0 in case of success, a negative error code otherwise
639
 */
640
int avfilter_open(AVFilterContext **filter_ctx, AVFilter *filter, const char *inst_name);
641 642

/**
643
 * Initialize a filter.
644
 *
645
 * @param filter the filter to initialize
646 647
 * @param args   A string of parameters to use when initializing the filter.
 *               The format and meaning of this string varies by filter.
648
 * @param opaque Any extra non-string data needed by the filter. The meaning
649
 *               of this parameter varies by filter.
650
 * @return       zero on success
651
 */
652
int avfilter_init_filter(AVFilterContext *filter, const char *args, void *opaque);
653 654

/**
655
 * Free a filter context.
656
 *
657
 * @param filter the filter to free
658
 */
659
void avfilter_free(AVFilterContext *filter);
Vitor Sessak's avatar
Vitor Sessak committed
660

661
/**
662
 * Insert a filter in the middle of an existing link.
663
 *
664 665
 * @param link the link into which the filter should be inserted
 * @param filt the filter to be inserted
666 667
 * @param filt_srcpad_idx the input pad on the filter to connect
 * @param filt_dstpad_idx the output pad on the filter to connect
668
 * @return     zero on success
669
 */
Vitor Sessak's avatar
Vitor Sessak committed
670
int avfilter_insert_filter(AVFilterLink *link, AVFilterContext *filt,
671
                           unsigned filt_srcpad_idx, unsigned filt_dstpad_idx);
672

Anton Khirnov's avatar
Anton Khirnov committed
673
#if FF_API_AVFILTERBUFFER
674 675 676 677 678 679
/**
 * Copy the frame properties of src to dst, without copying the actual
 * image data.
 *
 * @return 0 on success, a negative number on error.
 */
Anton Khirnov's avatar
Anton Khirnov committed
680
attribute_deprecated
681 682
int avfilter_copy_frame_props(AVFilterBufferRef *dst, const AVFrame *src);

683 684 685 686 687 688
/**
 * Copy the frame properties and data pointers of src to dst, without copying
 * the actual data.
 *
 * @return 0 on success, a negative number on error.
 */
Anton Khirnov's avatar
Anton Khirnov committed
689
attribute_deprecated
690
int avfilter_copy_buf_props(AVFrame *dst, const AVFilterBufferRef *src);
Anton Khirnov's avatar
Anton Khirnov committed
691
#endif
692

693 694 695 696 697 698 699
/**
 * @return AVClass for AVFilterContext.
 *
 * @see av_opt_find().
 */
const AVClass *avfilter_get_class(void);

700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853
typedef struct AVFilterGraph {
    const AVClass *av_class;
#if FF_API_FOO_COUNT
    attribute_deprecated
    unsigned filter_count;
#endif
    AVFilterContext **filters;
#if !FF_API_FOO_COUNT
    unsigned nb_filters;
#endif

    char *scale_sws_opts; ///< sws options to use for the auto-inserted scale filters
    char *resample_lavr_opts;   ///< libavresample options to use for the auto-inserted resample filters
#if FF_API_FOO_COUNT
    unsigned nb_filters;
#endif
} AVFilterGraph;

/**
 * Allocate a filter graph.
 */
AVFilterGraph *avfilter_graph_alloc(void);

/**
 * Get a filter instance with name name from graph.
 *
 * @return the pointer to the found filter instance or NULL if it
 * cannot be found.
 */
AVFilterContext *avfilter_graph_get_filter(AVFilterGraph *graph, char *name);

/**
 * Add an existing filter instance to a filter graph.
 *
 * @param graphctx  the filter graph
 * @param filter the filter to be added
 */
int avfilter_graph_add_filter(AVFilterGraph *graphctx, AVFilterContext *filter);

/**
 * Create and add a filter instance into an existing graph.
 * The filter instance is created from the filter filt and inited
 * with the parameters args and opaque.
 *
 * In case of success put in *filt_ctx the pointer to the created
 * filter instance, otherwise set *filt_ctx to NULL.
 *
 * @param name the instance name to give to the created filter instance
 * @param graph_ctx the filter graph
 * @return a negative AVERROR error code in case of failure, a non
 * negative value otherwise
 */
int avfilter_graph_create_filter(AVFilterContext **filt_ctx, AVFilter *filt,
                                 const char *name, const char *args, void *opaque,
                                 AVFilterGraph *graph_ctx);

/**
 * Check validity and configure all the links and formats in the graph.
 *
 * @param graphctx the filter graph
 * @param log_ctx context used for logging
 * @return 0 in case of success, a negative AVERROR code otherwise
 */
int avfilter_graph_config(AVFilterGraph *graphctx, void *log_ctx);

/**
 * Free a graph, destroy its links, and set *graph to NULL.
 * If *graph is NULL, do nothing.
 */
void avfilter_graph_free(AVFilterGraph **graph);

/**
 * A linked-list of the inputs/outputs of the filter chain.
 *
 * This is mainly useful for avfilter_graph_parse() / avfilter_graph_parse2(),
 * where it is used to communicate open (unlinked) inputs and outputs from and
 * to the caller.
 * This struct specifies, per each not connected pad contained in the graph, the
 * filter context and the pad index required for establishing a link.
 */
typedef struct AVFilterInOut {
    /** unique name for this input/output in the list */
    char *name;

    /** filter context associated to this input/output */
    AVFilterContext *filter_ctx;

    /** index of the filt_ctx pad to use for linking */
    int pad_idx;

    /** next input/input in the list, NULL if this is the last */
    struct AVFilterInOut *next;
} AVFilterInOut;

/**
 * Allocate a single AVFilterInOut entry.
 * Must be freed with avfilter_inout_free().
 * @return allocated AVFilterInOut on success, NULL on failure.
 */
AVFilterInOut *avfilter_inout_alloc(void);

/**
 * Free the supplied list of AVFilterInOut and set *inout to NULL.
 * If *inout is NULL, do nothing.
 */
void avfilter_inout_free(AVFilterInOut **inout);

/**
 * Add a graph described by a string to a graph.
 *
 * @param graph   the filter graph where to link the parsed graph context
 * @param filters string to be parsed
 * @param inputs  linked list to the inputs of the graph
 * @param outputs linked list to the outputs of the graph
 * @return zero on success, a negative AVERROR code on error
 */
int avfilter_graph_parse(AVFilterGraph *graph, const char *filters,
                         AVFilterInOut *inputs, AVFilterInOut *outputs,
                         void *log_ctx);

/**
 * Add a graph described by a string to a graph.
 *
 * @param[in]  graph   the filter graph where to link the parsed graph context
 * @param[in]  filters string to be parsed
 * @param[out] inputs  a linked list of all free (unlinked) inputs of the
 *                     parsed graph will be returned here. It is to be freed
 *                     by the caller using avfilter_inout_free().
 * @param[out] outputs a linked list of all free (unlinked) outputs of the
 *                     parsed graph will be returned here. It is to be freed by the
 *                     caller using avfilter_inout_free().
 * @return zero on success, a negative AVERROR code on error
 *
 * @note the difference between avfilter_graph_parse2() and
 * avfilter_graph_parse() is that in avfilter_graph_parse(), the caller provides
 * the lists of inputs and outputs, which therefore must be known before calling
 * the function. On the other hand, avfilter_graph_parse2() \em returns the
 * inputs and outputs that are left unlinked after parsing the graph and the
 * caller then deals with them. Another difference is that in
 * avfilter_graph_parse(), the inputs parameter describes inputs of the
 * <em>already existing</em> part of the graph; i.e. from the point of view of
 * the newly created part, they are outputs. Similarly the outputs parameter
 * describes outputs of the already existing filters, which are provided as
 * inputs to the parsed filters.
 * avfilter_graph_parse2() takes the opposite approach -- it makes no reference
 * whatsoever to already existing parts of the graph and the inputs parameter
 * will on return contain inputs of the newly parsed part of the graph.
 * Analogously the outputs parameter will contain outputs of the newly created
 * filters.
 */
int avfilter_graph_parse2(AVFilterGraph *graph, const char *filters,
                          AVFilterInOut **inputs,
                          AVFilterInOut **outputs);

854
#endif /* AVFILTER_AVFILTER_H */