lavfi: add avfilter_get_class() and iteration callbacks
[ffmpeg.git] / libavfilter / avfilter.h
1 /*
2  * filter layer
3  * Copyright (c) 2007 Bobby Bingham
4  *
5  * This file is part of FFmpeg.
6  *
7  * FFmpeg is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License as published by the Free Software Foundation; either
10  * version 2.1 of the License, or (at your option) any later version.
11  *
12  * FFmpeg is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with FFmpeg; if not, write to the Free Software
19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20  */
21
22 #ifndef AVFILTER_AVFILTER_H
23 #define AVFILTER_AVFILTER_H
24
25 #include <stddef.h>
26
27 #include "libavutil/avutil.h"
28 #include "libavutil/log.h"
29 #include "libavutil/samplefmt.h"
30 #include "libavutil/pixfmt.h"
31 #include "libavutil/rational.h"
32
33 #include "libavfilter/version.h"
34
35 /**
36  * Return the LIBAVFILTER_VERSION_INT constant.
37  */
38 unsigned avfilter_version(void);
39
40 /**
41  * Return the libavfilter build-time configuration.
42  */
43 const char *avfilter_configuration(void);
44
45 /**
46  * Return the libavfilter license.
47  */
48 const char *avfilter_license(void);
49
50 /**
51  * Get the class for the AVFilterContext struct.
52  */
53 const AVClass *avfilter_get_class(void);
54
55 typedef struct AVFilterContext AVFilterContext;
56 typedef struct AVFilterLink    AVFilterLink;
57 typedef struct AVFilterPad     AVFilterPad;
58 typedef struct AVFilterFormats AVFilterFormats;
59
60 /**
61  * A reference-counted buffer data type used by the filter system. Filters
62  * should not store pointers to this structure directly, but instead use the
63  * AVFilterBufferRef structure below.
64  */
65 typedef struct AVFilterBuffer {
66     uint8_t *data[8];           ///< buffer data for each plane/channel
67
68     /**
69      * pointers to the data planes/channels.
70      *
71      * For video, this should simply point to data[].
72      *
73      * For planar audio, each channel has a separate data pointer, and
74      * linesize[0] contains the size of each channel buffer.
75      * For packed audio, there is just one data pointer, and linesize[0]
76      * contains the total size of the buffer for all channels.
77      *
78      * Note: Both data and extended_data will always be set, but for planar
79      * audio with more channels that can fit in data, extended_data must be used
80      * in order to access all channels.
81      */
82     uint8_t **extended_data;
83     int linesize[8];            ///< number of bytes per line
84
85     /** private data to be used by a custom free function */
86     void *priv;
87     /**
88      * A pointer to the function to deallocate this buffer if the default
89      * function is not sufficient. This could, for example, add the memory
90      * back into a memory pool to be reused later without the overhead of
91      * reallocating it from scratch.
92      */
93     void (*free)(struct AVFilterBuffer *buf);
94
95     int format;                 ///< media format
96     int w, h;                   ///< width and height of the allocated buffer
97     unsigned refcount;          ///< number of references to this buffer
98 } AVFilterBuffer;
99
100 #define AV_PERM_READ     0x01   ///< can read from the buffer
101 #define AV_PERM_WRITE    0x02   ///< can write to the buffer
102 #define AV_PERM_PRESERVE 0x04   ///< nobody else can overwrite the buffer
103 #define AV_PERM_REUSE    0x08   ///< can output the buffer multiple times, with the same contents each time
104 #define AV_PERM_REUSE2   0x10   ///< can output the buffer multiple times, modified each time
105 #define AV_PERM_NEG_LINESIZES 0x20  ///< the buffer requested can have negative linesizes
106 #define AV_PERM_ALIGN    0x40   ///< the buffer must be aligned
107
108 #define AVFILTER_ALIGN 16 //not part of ABI
109
110 /**
111  * Audio specific properties in a reference to an AVFilterBuffer. Since
112  * AVFilterBufferRef is common to different media formats, audio specific
113  * per reference properties must be separated out.
114  */
115 typedef struct AVFilterBufferRefAudioProps {
116     uint64_t channel_layout;    ///< channel layout of audio buffer
117     int nb_samples;             ///< number of audio samples per channel
118     int sample_rate;            ///< audio buffer sample rate
119 } AVFilterBufferRefAudioProps;
120
121 /**
122  * Video specific properties in a reference to an AVFilterBuffer. Since
123  * AVFilterBufferRef is common to different media formats, video specific
124  * per reference properties must be separated out.
125  */
126 typedef struct AVFilterBufferRefVideoProps {
127     int w;                      ///< image width
128     int h;                      ///< image height
129     AVRational sample_aspect_ratio; ///< sample aspect ratio
130     int interlaced;             ///< is frame interlaced
131     int top_field_first;        ///< field order
132     enum AVPictureType pict_type; ///< picture type of the frame
133     int key_frame;              ///< 1 -> keyframe, 0-> not
134 } AVFilterBufferRefVideoProps;
135
136 /**
137  * A reference to an AVFilterBuffer. Since filters can manipulate the origin of
138  * a buffer to, for example, crop image without any memcpy, the buffer origin
139  * and dimensions are per-reference properties. Linesize is also useful for
140  * image flipping, frame to field filters, etc, and so is also per-reference.
141  *
142  * TODO: add anything necessary for frame reordering
143  */
144 typedef struct AVFilterBufferRef {
145     AVFilterBuffer *buf;        ///< the buffer that this is a reference to
146     uint8_t *data[8];           ///< picture/audio data for each plane
147     /**
148      * pointers to the data planes/channels.
149      *
150      * For video, this should simply point to data[].
151      *
152      * For planar audio, each channel has a separate data pointer, and
153      * linesize[0] contains the size of each channel buffer.
154      * For packed audio, there is just one data pointer, and linesize[0]
155      * contains the total size of the buffer for all channels.
156      *
157      * Note: Both data and extended_data will always be set, but for planar
158      * audio with more channels that can fit in data, extended_data must be used
159      * in order to access all channels.
160      */
161     uint8_t **extended_data;
162     int linesize[8];            ///< number of bytes per line
163
164     AVFilterBufferRefVideoProps *video; ///< video buffer specific properties
165     AVFilterBufferRefAudioProps *audio; ///< audio buffer specific properties
166
167     /**
168      * presentation timestamp. The time unit may change during
169      * filtering, as it is specified in the link and the filter code
170      * may need to rescale the PTS accordingly.
171      */
172     int64_t pts;
173     int64_t pos;                ///< byte position in stream, -1 if unknown
174
175     int format;                 ///< media format
176
177     int perms;                  ///< permissions, see the AV_PERM_* flags
178
179     enum AVMediaType type;      ///< media type of buffer data
180 } AVFilterBufferRef;
181
182 /**
183  * Copy properties of src to dst, without copying the actual data
184  */
185 void avfilter_copy_buffer_ref_props(AVFilterBufferRef *dst, AVFilterBufferRef *src);
186
187 /**
188  * Add a new reference to a buffer.
189  *
190  * @param ref   an existing reference to the buffer
191  * @param pmask a bitmask containing the allowable permissions in the new
192  *              reference
193  * @return      a new reference to the buffer with the same properties as the
194  *              old, excluding any permissions denied by pmask
195  */
196 AVFilterBufferRef *avfilter_ref_buffer(AVFilterBufferRef *ref, int pmask);
197
198 /**
199  * Remove a reference to a buffer. If this is the last reference to the
200  * buffer, the buffer itself is also automatically freed.
201  *
202  * @param ref reference to the buffer, may be NULL
203  *
204  * @note it is recommended to use avfilter_unref_bufferp() instead of this
205  * function
206  */
207 void avfilter_unref_buffer(AVFilterBufferRef *ref);
208
209 /**
210  * Remove a reference to a buffer and set the pointer to NULL.
211  * If this is the last reference to the buffer, the buffer itself
212  * is also automatically freed.
213  *
214  * @param ref pointer to the buffer reference
215  */
216 void avfilter_unref_bufferp(AVFilterBufferRef **ref);
217
218 #if FF_API_AVFILTERPAD_PUBLIC
219 /**
220  * A filter pad used for either input or output.
221  *
222  * See doc/filter_design.txt for details on how to implement the methods.
223  *
224  * @warning this struct might be removed from public API.
225  * users should call avfilter_pad_get_name() and avfilter_pad_get_type()
226  * to access the name and type fields; there should be no need to access
227  * any other fields from outside of libavfilter.
228  */
229 struct AVFilterPad {
230     /**
231      * Pad name. The name is unique among inputs and among outputs, but an
232      * 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.
234      */
235     const char *name;
236
237     /**
238      * AVFilterPad type.
239      */
240     enum AVMediaType type;
241
242     /**
243      * Minimum required permissions on incoming buffers. Any buffer with
244      * insufficient permissions will be automatically copied by the filter
245      * system to a new buffer which provides the needed access permissions.
246      *
247      * Input pads only.
248      */
249     int min_perms;
250
251     /**
252      * Permissions which are not accepted on incoming buffers. Any buffer
253      * which has any of these permissions set will be automatically copied
254      * 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      * Input pads only.
259      */
260     int rej_perms;
261
262     /**
263      * Callback called before passing the first slice of a new frame. If
264      * NULL, the filter layer will default to storing a reference to the
265      * picture inside the link structure.
266      *
267      * The reference given as argument is also available in link->cur_buf.
268      * It can be stored elsewhere or given away, but then clearing
269      * link->cur_buf is advised, as it is automatically unreferenced.
270      * The reference must not be unreferenced before end_frame(), as it may
271      * still be in use by the automatic copy mechanism.
272      *
273      * Input video pads only.
274      *
275      * @return >= 0 on success, a negative AVERROR on error. picref will be
276      * unreferenced by the caller in case of error.
277      */
278     int (*start_frame)(AVFilterLink *link, AVFilterBufferRef *picref);
279
280     /**
281      * Callback function to get a video buffer. If NULL, the filter system will
282      * use avfilter_default_get_video_buffer().
283      *
284      * Input video pads only.
285      */
286     AVFilterBufferRef *(*get_video_buffer)(AVFilterLink *link, int perms, int w, int h);
287
288     /**
289      * Callback function to get an audio buffer. If NULL, the filter system will
290      * use avfilter_default_get_audio_buffer().
291      *
292      * Input audio pads only.
293      */
294     AVFilterBufferRef *(*get_audio_buffer)(AVFilterLink *link, int perms,
295                                            int nb_samples);
296
297     /**
298      * Callback called after the slices of a frame are completely sent. If
299      * NULL, the filter layer will default to releasing the reference stored
300      * in the link structure during start_frame().
301      *
302      * Input video pads only.
303      *
304      * @return >= 0 on success, a negative AVERROR on error.
305      */
306     int (*end_frame)(AVFilterLink *link);
307
308     /**
309      * Slice drawing callback. This is where a filter receives video data
310      * and should do its processing.
311      *
312      * Input video pads only.
313      *
314      * @return >= 0 on success, a negative AVERROR on error.
315      */
316     int (*draw_slice)(AVFilterLink *link, int y, int height, int slice_dir);
317
318     /**
319      * Samples filtering callback. This is where a filter receives audio data
320      * and should do its processing.
321      *
322      * Input audio pads only.
323      *
324      * @return >= 0 on success, a negative AVERROR on error. This function
325      * must ensure that samplesref is properly unreferenced on error if it
326      * hasn't been passed on to another filter.
327      */
328     int (*filter_samples)(AVFilterLink *link, AVFilterBufferRef *samplesref);
329
330     /**
331      * Frame poll callback. This returns the number of immediately available
332      * samples. It should return a positive value if the next request_frame()
333      * is guaranteed to return one frame (with no delay).
334      *
335      * Defaults to just calling the source poll_frame() method.
336      *
337      * Output pads only.
338      */
339     int (*poll_frame)(AVFilterLink *link);
340
341     /**
342      * Frame request callback. A call to this should result in at least one
343      * frame being output over the given link. This should return zero on
344      * success, and another value on error.
345      * See ff_request_frame() for the error codes with a specific
346      * meaning.
347      *
348      * Output pads only.
349      */
350     int (*request_frame)(AVFilterLink *link);
351
352     /**
353      * Link configuration callback.
354      *
355      * For output pads, this should set the following link properties:
356      * video: width, height, sample_aspect_ratio, time_base
357      * audio: sample_rate.
358      *
359      * This should NOT set properties such as format, channel_layout, etc which
360      * are negotiated between filters by the filter system using the
361      * query_formats() callback before this function is called.
362      *
363      * For input pads, this should check the properties of the link, and update
364      * the filter's internal state as necessary.
365      *
366      * For both input and output pads, this should return zero on success,
367      * and another value on error.
368      */
369     int (*config_props)(AVFilterLink *link);
370
371     /**
372      * The filter expects a fifo to be inserted on its input link,
373      * typically because it has a delay.
374      *
375      * input pads only.
376      */
377     int needs_fifo;
378 };
379 #endif
380
381 /**
382  * Get the name of an AVFilterPad.
383  *
384  * @param pads an array of AVFilterPads
385  * @param pad_idx index of the pad in the array it; is the caller's
386  *                responsibility to ensure the index is valid
387  *
388  * @return name of the pad_idx'th pad in pads
389  */
390 const char *avfilter_pad_get_name(AVFilterPad *pads, int pad_idx);
391
392 /**
393  * Get the type of an AVFilterPad.
394  *
395  * @param pads an array of AVFilterPads
396  * @param pad_idx index of the pad in the array; it is the caller's
397  *                responsibility to ensure the index is valid
398  *
399  * @return type of the pad_idx'th pad in pads
400  */
401 enum AVMediaType avfilter_pad_get_type(AVFilterPad *pads, int pad_idx);
402
403 /** default handler for end_frame() for video inputs */
404 attribute_deprecated
405 int  avfilter_default_end_frame(AVFilterLink *link);
406
407 /**
408  * Filter definition. This defines the pads a filter contains, and all the
409  * callback functions used to interact with the filter.
410  */
411 typedef struct AVFilter {
412     const char *name;         ///< filter name
413
414     /**
415      * A description for the filter. You should use the
416      * NULL_IF_CONFIG_SMALL() macro to define it.
417      */
418     const char *description;
419
420     const AVFilterPad *inputs;  ///< NULL terminated list of inputs. NULL if none
421     const AVFilterPad *outputs; ///< NULL terminated list of outputs. NULL if none
422
423     /*****************************************************************
424      * All fields below this line are not part of the public API. They
425      * may not be used outside of libavfilter and can be changed and
426      * removed at will.
427      * New public fields should be added right above.
428      *****************************************************************
429      */
430
431     /**
432      * Filter initialization function. Args contains the user-supplied
433      * parameters. FIXME: maybe an AVOption-based system would be better?
434      */
435     int (*init)(AVFilterContext *ctx, const char *args);
436
437     /**
438      * Filter uninitialization function. Should deallocate any memory held
439      * by the filter, release any buffer references, etc. This does not need
440      * to deallocate the AVFilterContext->priv memory itself.
441      */
442     void (*uninit)(AVFilterContext *ctx);
443
444     /**
445      * Queries formats/layouts supported by the filter and its pads, and sets
446      * the in_formats/in_chlayouts for links connected to its output pads,
447      * and out_formats/out_chlayouts for links connected to its input pads.
448      *
449      * @return zero on success, a negative value corresponding to an
450      * AVERROR code otherwise
451      */
452     int (*query_formats)(AVFilterContext *);
453
454     int priv_size;      ///< size of private data to allocate for the filter
455
456     /**
457      * Make the filter instance process a command.
458      *
459      * @param cmd    the command to process, for handling simplicity all commands must be alphanumeric only
460      * @param arg    the argument for the command
461      * @param res    a buffer with size res_size where the filter(s) can return a response. This must not change when the command is not supported.
462      * @param flags  if AVFILTER_CMD_FLAG_FAST is set and the command would be
463      *               time consuming then a filter should treat it like an unsupported command
464      *
465      * @returns >=0 on success otherwise an error code.
466      *          AVERROR(ENOSYS) on unsupported commands
467      */
468     int (*process_command)(AVFilterContext *, const char *cmd, const char *arg, char *res, int res_len, int flags);
469
470     /**
471      * Filter initialization function, alternative to the init()
472      * callback. Args contains the user-supplied parameters, opaque is
473      * used for providing binary data.
474      */
475     int (*init_opaque)(AVFilterContext *ctx, const char *args, void *opaque);
476
477     const AVClass *priv_class;      ///< private class, containing filter specific options
478 } AVFilter;
479
480 /** An instance of a filter */
481 struct AVFilterContext {
482     const AVClass *av_class;        ///< needed for av_log()
483
484     AVFilter *filter;               ///< the AVFilter of which this is an instance
485
486     char *name;                     ///< name of this filter instance
487
488     AVFilterPad   *input_pads;      ///< array of input pads
489     AVFilterLink **inputs;          ///< array of pointers to input links
490 #if FF_API_FOO_COUNT
491     unsigned input_count;           ///< @deprecated use nb_inputs
492 #endif
493     unsigned    nb_inputs;          ///< number of input pads
494
495     AVFilterPad   *output_pads;     ///< array of output pads
496     AVFilterLink **outputs;         ///< array of pointers to output links
497 #if FF_API_FOO_COUNT
498     unsigned output_count;          ///< @deprecated use nb_outputs
499 #endif
500     unsigned    nb_outputs;         ///< number of output pads
501
502     void *priv;                     ///< private data for use by the filter
503
504     struct AVFilterCommand *command_queue;
505 };
506
507 /**
508  * A link between two filters. This contains pointers to the source and
509  * destination filters between which this link exists, and the indexes of
510  * the pads involved. In addition, this link also contains the parameters
511  * which have been negotiated and agreed upon between the filter, such as
512  * image dimensions, format, etc.
513  */
514 struct AVFilterLink {
515     AVFilterContext *src;       ///< source filter
516     AVFilterPad *srcpad;        ///< output pad on the source filter
517
518     AVFilterContext *dst;       ///< dest filter
519     AVFilterPad *dstpad;        ///< input pad on the dest filter
520
521     enum AVMediaType type;      ///< filter media type
522
523     /* These parameters apply only to video */
524     int w;                      ///< agreed upon image width
525     int h;                      ///< agreed upon image height
526     AVRational sample_aspect_ratio; ///< agreed upon sample aspect ratio
527     /* These parameters apply only to audio */
528     uint64_t channel_layout;    ///< channel layout of current buffer (see libavutil/audioconvert.h)
529     int sample_rate;            ///< samples per second
530
531     int format;                 ///< agreed upon media format
532
533     /**
534      * Define the time base used by the PTS of the frames/samples
535      * which will pass through this link.
536      * During the configuration stage, each filter is supposed to
537      * change only the output timebase, while the timebase of the
538      * input link is assumed to be an unchangeable property.
539      */
540     AVRational time_base;
541
542     /*****************************************************************
543      * All fields below this line are not part of the public API. They
544      * may not be used outside of libavfilter and can be changed and
545      * removed at will.
546      * New public fields should be added right above.
547      *****************************************************************
548      */
549     /**
550      * Lists of formats and channel layouts supported by the input and output
551      * filters respectively. These lists are used for negotiating the format
552      * to actually be used, which will be loaded into the format and
553      * channel_layout members, above, when chosen.
554      *
555      */
556     AVFilterFormats *in_formats;
557     AVFilterFormats *out_formats;
558
559     /**
560      * Lists of channel layouts and sample rates used for automatic
561      * negotiation.
562      */
563     AVFilterFormats  *in_samplerates;
564     AVFilterFormats *out_samplerates;
565     struct AVFilterChannelLayouts  *in_channel_layouts;
566     struct AVFilterChannelLayouts *out_channel_layouts;
567
568     /**
569      * Audio only, the destination filter sets this to a non-zero value to
570      * request that buffers with the given number of samples should be sent to
571      * it. AVFilterPad.needs_fifo must also be set on the corresponding input
572      * pad.
573      * Last buffer before EOF will be padded with silence.
574      */
575     int request_samples;
576
577     /** stage of the initialization of the link properties (dimensions, etc) */
578     enum {
579         AVLINK_UNINIT = 0,      ///< not started
580         AVLINK_STARTINIT,       ///< started, but incomplete
581         AVLINK_INIT             ///< complete
582     } init_state;
583
584     /**
585      * The buffer reference currently being sent across the link by the source
586      * filter. This is used internally by the filter system to allow
587      * automatic copying of buffers which do not have sufficient permissions
588      * for the destination. This should not be accessed directly by the
589      * filters.
590      */
591     AVFilterBufferRef *src_buf;
592
593     /**
594      * The buffer reference to the frame sent across the link by the
595      * source filter, which is read by the destination filter. It is
596      * automatically set up by ff_start_frame().
597      *
598      * Depending on the permissions, it may either be the same as
599      * src_buf or an automatic copy of it.
600      *
601      * It is automatically freed by the filter system when calling
602      * ff_end_frame(). In case you save the buffer reference
603      * internally (e.g. if you cache it for later reuse), or give it
604      * away (e.g. if you pass the reference to the next filter) it
605      * must be set to NULL before calling ff_end_frame().
606      */
607     AVFilterBufferRef *cur_buf;
608
609     /**
610      * The buffer reference to the frame which is sent to output by
611      * the source filter.
612      *
613      * If no start_frame callback is defined on a link,
614      * ff_start_frame() will automatically request a new buffer on the
615      * first output link of the destination filter. The reference to
616      * the buffer so obtained is stored in the out_buf field on the
617      * output link.
618      *
619      * It can also be set by the filter code in case the filter needs
620      * to access the output buffer later. For example the filter code
621      * may set it in a custom start_frame, and access it in
622      * draw_slice.
623      *
624      * It is automatically freed by the filter system in
625      * ff_end_frame().
626      */
627     AVFilterBufferRef *out_buf;
628
629     struct AVFilterPool *pool;
630
631     /**
632      * Graph the filter belongs to.
633      */
634     struct AVFilterGraph *graph;
635
636     /**
637      * Current timestamp of the link, as defined by the most recent
638      * frame(s), in AV_TIME_BASE units.
639      */
640     int64_t current_pts;
641
642     /**
643      * Index in the age array.
644      */
645     int age_index;
646
647     /**
648      * Frame rate of the stream on the link, or 1/0 if unknown;
649      * if left to 0/0, will be automatically be copied from the first input
650      * of the source filter if it exists.
651      *
652      * Sources should set it to the best estimation of the real frame rate.
653      * Filters should update it if necessary depending on their function.
654      * Sinks can use it to set a default output frame rate.
655      * It is similar to the r_frame_rate field in AVStream.
656      */
657     AVRational frame_rate;
658
659     /**
660      * Buffer partially filled with samples to achieve a fixed/minimum size.
661      */
662     AVFilterBufferRef *partial_buf;
663
664     /**
665      * Size of the partial buffer to allocate.
666      * Must be between min_samples and max_samples.
667      */
668     int partial_buf_size;
669
670     /**
671      * Minimum number of samples to filter at once. If filter_samples() is
672      * called with fewer samples, it will accumulate them in partial_buf.
673      * This field and the related ones must not be changed after filtering
674      * has started.
675      * If 0, all related fields are ignored.
676      */
677     int min_samples;
678
679     /**
680      * Maximum number of samples to filter at once. If filter_samples() is
681      * called with more samples, it will split them.
682      */
683     int max_samples;
684
685     /**
686      * The buffer reference currently being received across the link by the
687      * destination filter. This is used internally by the filter system to
688      * allow automatic copying of buffers which do not have sufficient
689      * permissions for the destination. This should not be accessed directly
690      * by the filters.
691      */
692     AVFilterBufferRef *cur_buf_copy;
693 };
694
695 /**
696  * Link two filters together.
697  *
698  * @param src    the source filter
699  * @param srcpad index of the output pad on the source filter
700  * @param dst    the destination filter
701  * @param dstpad index of the input pad on the destination filter
702  * @return       zero on success
703  */
704 int avfilter_link(AVFilterContext *src, unsigned srcpad,
705                   AVFilterContext *dst, unsigned dstpad);
706
707 /**
708  * Free the link in *link, and set its pointer to NULL.
709  */
710 void avfilter_link_free(AVFilterLink **link);
711
712 /**
713  * Negotiate the media format, dimensions, etc of all inputs to a filter.
714  *
715  * @param filter the filter to negotiate the properties for its inputs
716  * @return       zero on successful negotiation
717  */
718 int avfilter_config_links(AVFilterContext *filter);
719
720 /**
721  * Create a buffer reference wrapped around an already allocated image
722  * buffer.
723  *
724  * @param data pointers to the planes of the image to reference
725  * @param linesize linesizes for the planes of the image to reference
726  * @param perms the required access permissions
727  * @param w the width of the image specified by the data and linesize arrays
728  * @param h the height of the image specified by the data and linesize arrays
729  * @param format the pixel format of the image specified by the data and linesize arrays
730  */
731 AVFilterBufferRef *
732 avfilter_get_video_buffer_ref_from_arrays(uint8_t * const data[4], const int linesize[4], int perms,
733                                           int w, int h, enum PixelFormat format);
734
735 /**
736  * Create an audio buffer reference wrapped around an already
737  * allocated samples buffer.
738  *
739  * @param data           pointers to the samples plane buffers
740  * @param linesize       linesize for the samples plane buffers
741  * @param perms          the required access permissions
742  * @param nb_samples     number of samples per channel
743  * @param sample_fmt     the format of each sample in the buffer to allocate
744  * @param channel_layout the channel layout of the buffer
745  */
746 AVFilterBufferRef *avfilter_get_audio_buffer_ref_from_arrays(uint8_t **data,
747                                                              int linesize,
748                                                              int perms,
749                                                              int nb_samples,
750                                                              enum AVSampleFormat sample_fmt,
751                                                              uint64_t channel_layout);
752
753
754 #define AVFILTER_CMD_FLAG_ONE   1 ///< Stop once a filter understood the command (for target=all for example), fast filters are favored automatically
755 #define AVFILTER_CMD_FLAG_FAST  2 ///< Only execute command when its fast (like a video out that supports contrast adjustment in hw)
756
757 /**
758  * Make the filter instance process a command.
759  * It is recommended to use avfilter_graph_send_command().
760  */
761 int avfilter_process_command(AVFilterContext *filter, const char *cmd, const char *arg, char *res, int res_len, int flags);
762
763 /** Initialize the filter system. Register all builtin filters. */
764 void avfilter_register_all(void);
765
766 /** Uninitialize the filter system. Unregister all filters. */
767 void avfilter_uninit(void);
768
769 /**
770  * Register a filter. This is only needed if you plan to use
771  * avfilter_get_by_name later to lookup the AVFilter structure by name. A
772  * filter can still by instantiated with avfilter_open even if it is not
773  * registered.
774  *
775  * @param filter the filter to register
776  * @return 0 if the registration was successful, a negative value
777  * otherwise
778  */
779 int avfilter_register(AVFilter *filter);
780
781 /**
782  * Get a filter definition matching the given name.
783  *
784  * @param name the filter name to find
785  * @return     the filter definition, if any matching one is registered.
786  *             NULL if none found.
787  */
788 AVFilter *avfilter_get_by_name(const char *name);
789
790 /**
791  * If filter is NULL, returns a pointer to the first registered filter pointer,
792  * if filter is non-NULL, returns the next pointer after filter.
793  * If the returned pointer points to NULL, the last registered filter
794  * was already reached.
795  */
796 AVFilter **av_filter_next(AVFilter **filter);
797
798 /**
799  * Create a filter instance.
800  *
801  * @param filter_ctx put here a pointer to the created filter context
802  * on success, NULL on failure
803  * @param filter    the filter to create an instance of
804  * @param inst_name Name to give to the new instance. Can be NULL for none.
805  * @return >= 0 in case of success, a negative error code otherwise
806  */
807 int avfilter_open(AVFilterContext **filter_ctx, AVFilter *filter, const char *inst_name);
808
809 /**
810  * Initialize a filter.
811  *
812  * @param filter the filter to initialize
813  * @param args   A string of parameters to use when initializing the filter.
814  *               The format and meaning of this string varies by filter.
815  * @param opaque Any extra non-string data needed by the filter. The meaning
816  *               of this parameter varies by filter.
817  * @return       zero on success
818  */
819 int avfilter_init_filter(AVFilterContext *filter, const char *args, void *opaque);
820
821 /**
822  * Free a filter context.
823  *
824  * @param filter the filter to free
825  */
826 void avfilter_free(AVFilterContext *filter);
827
828 /**
829  * Insert a filter in the middle of an existing link.
830  *
831  * @param link the link into which the filter should be inserted
832  * @param filt the filter to be inserted
833  * @param filt_srcpad_idx the input pad on the filter to connect
834  * @param filt_dstpad_idx the output pad on the filter to connect
835  * @return     zero on success
836  */
837 int avfilter_insert_filter(AVFilterLink *link, AVFilterContext *filt,
838                            unsigned filt_srcpad_idx, unsigned filt_dstpad_idx);
839
840 #endif /* AVFILTER_AVFILTER_H */