FFmpeg
avfilter.h
Go to the documentation of this file.
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 /**
26  * @file
27  * @ingroup lavfi
28  * Main libavfilter public API header
29  */
30 
31 /**
32  * @defgroup lavfi libavfilter
33  * Graph-based frame editing library.
34  *
35  * @{
36  */
37 
38 #include <stddef.h>
39 
40 #include "libavutil/attributes.h"
41 #include "libavutil/avutil.h"
42 #include "libavutil/buffer.h"
43 #include "libavutil/dict.h"
44 #include "libavutil/frame.h"
45 #include "libavutil/log.h"
46 #include "libavutil/samplefmt.h"
47 #include "libavutil/pixfmt.h"
48 #include "libavutil/rational.h"
49 
51 #ifndef HAVE_AV_CONFIG_H
52 /* When included as part of the ffmpeg build, only include the major version
53  * to avoid unnecessary rebuilds. When included externally, keep including
54  * the full version information. */
55 #include "libavfilter/version.h"
56 #endif
57 
58 /**
59  * Return the LIBAVFILTER_VERSION_INT constant.
60  */
61 unsigned avfilter_version(void);
62 
63 /**
64  * Return the libavfilter build-time configuration.
65  */
66 const char *avfilter_configuration(void);
67 
68 /**
69  * Return the libavfilter license.
70  */
71 const char *avfilter_license(void);
72 
73 typedef struct AVFilterContext AVFilterContext;
74 typedef struct AVFilterLink AVFilterLink;
75 typedef struct AVFilterPad AVFilterPad;
76 typedef struct AVFilterFormats AVFilterFormats;
78 
79 /**
80  * Get the name of an AVFilterPad.
81  *
82  * @param pads an array of AVFilterPads
83  * @param pad_idx index of the pad in the array; it is the caller's
84  * responsibility to ensure the index is valid
85  *
86  * @return name of the pad_idx'th pad in pads
87  */
88 const char *avfilter_pad_get_name(const AVFilterPad *pads, int pad_idx);
89 
90 /**
91  * Get the type of an AVFilterPad.
92  *
93  * @param pads an array of AVFilterPads
94  * @param pad_idx index of the pad in the array; it is the caller's
95  * responsibility to ensure the index is valid
96  *
97  * @return type of the pad_idx'th pad in pads
98  */
99 enum AVMediaType avfilter_pad_get_type(const AVFilterPad *pads, int pad_idx);
100 
101 /**
102  * The number of the filter inputs is not determined just by AVFilter.inputs.
103  * The filter might add additional inputs during initialization depending on the
104  * options supplied to it.
105  */
106 #define AVFILTER_FLAG_DYNAMIC_INPUTS (1 << 0)
107 /**
108  * The number of the filter outputs is not determined just by AVFilter.outputs.
109  * The filter might add additional outputs during initialization depending on
110  * the options supplied to it.
111  */
112 #define AVFILTER_FLAG_DYNAMIC_OUTPUTS (1 << 1)
113 /**
114  * The filter supports multithreading by splitting frames into multiple parts
115  * and processing them concurrently.
116  */
117 #define AVFILTER_FLAG_SLICE_THREADS (1 << 2)
118 /**
119  * The filter is a "metadata" filter - it does not modify the frame data in any
120  * way. It may only affect the metadata (i.e. those fields copied by
121  * av_frame_copy_props()).
122  *
123  * More precisely, this means:
124  * - video: the data of any frame output by the filter must be exactly equal to
125  * some frame that is received on one of its inputs. Furthermore, all frames
126  * produced on a given output must correspond to frames received on the same
127  * input and their order must be unchanged. Note that the filter may still
128  * drop or duplicate the frames.
129  * - audio: the data produced by the filter on any of its outputs (viewed e.g.
130  * as an array of interleaved samples) must be exactly equal to the data
131  * received by the filter on one of its inputs.
132  */
133 #define AVFILTER_FLAG_METADATA_ONLY (1 << 3)
134 
135 /**
136  * The filter can create hardware frames using AVFilterContext.hw_device_ctx.
137  */
138 #define AVFILTER_FLAG_HWDEVICE (1 << 4)
139 /**
140  * Some filters support a generic "enable" expression option that can be used
141  * to enable or disable a filter in the timeline. Filters supporting this
142  * option have this flag set. When the enable expression is false, the default
143  * no-op filter_frame() function is called in place of the filter_frame()
144  * callback defined on each input pad, thus the frame is passed unchanged to
145  * the next filters.
146  */
147 #define AVFILTER_FLAG_SUPPORT_TIMELINE_GENERIC (1 << 16)
148 /**
149  * Same as AVFILTER_FLAG_SUPPORT_TIMELINE_GENERIC, except that the filter will
150  * have its filter_frame() callback(s) called as usual even when the enable
151  * expression is false. The filter will disable filtering within the
152  * filter_frame() callback(s) itself, for example executing code depending on
153  * the AVFilterContext->is_disabled value.
154  */
155 #define AVFILTER_FLAG_SUPPORT_TIMELINE_INTERNAL (1 << 17)
156 /**
157  * Handy mask to test whether the filter supports or no the timeline feature
158  * (internally or generically).
159  */
160 #define AVFILTER_FLAG_SUPPORT_TIMELINE (AVFILTER_FLAG_SUPPORT_TIMELINE_GENERIC | AVFILTER_FLAG_SUPPORT_TIMELINE_INTERNAL)
161 
162 /**
163  * Filter definition. This defines the pads a filter contains, and all the
164  * callback functions used to interact with the filter.
165  */
166 typedef struct AVFilter {
167  /**
168  * Filter name. Must be non-NULL and unique among filters.
169  */
170  const char *name;
171 
172  /**
173  * A description of the filter. May be NULL.
174  *
175  * You should use the NULL_IF_CONFIG_SMALL() macro to define it.
176  */
177  const char *description;
178 
179  /**
180  * List of static inputs.
181  *
182  * NULL if there are no (static) inputs. Instances of filters with
183  * AVFILTER_FLAG_DYNAMIC_INPUTS set may have more inputs than present in
184  * this list.
185  */
187 
188  /**
189  * List of static outputs.
190  *
191  * NULL if there are no (static) outputs. Instances of filters with
192  * AVFILTER_FLAG_DYNAMIC_OUTPUTS set may have more outputs than present in
193  * this list.
194  */
196 
197  /**
198  * A class for the private data, used to declare filter private AVOptions.
199  * This field is NULL for filters that do not declare any options.
200  *
201  * If this field is non-NULL, the first member of the filter private data
202  * must be a pointer to AVClass, which will be set by libavfilter generic
203  * code to this class.
204  */
206 
207  /**
208  * A combination of AVFILTER_FLAG_*
209  */
210  int flags;
211 
212  /*****************************************************************
213  * All fields below this line are not part of the public API. They
214  * may not be used outside of libavfilter and can be changed and
215  * removed at will.
216  * New public fields should be added right above.
217  *****************************************************************
218  */
219 
220  /**
221  * The number of entries in the list of inputs.
222  */
223  uint8_t nb_inputs;
224 
225  /**
226  * The number of entries in the list of outputs.
227  */
228  uint8_t nb_outputs;
229 
230  /**
231  * This field determines the state of the formats union.
232  * It is an enum FilterFormatsState value.
233  */
234  uint8_t formats_state;
235 
236  /**
237  * Filter pre-initialization function
238  *
239  * This callback will be called immediately after the filter context is
240  * allocated, to allow allocating and initing sub-objects.
241  *
242  * If this callback is not NULL, the uninit callback will be called on
243  * allocation failure.
244  *
245  * @return 0 on success,
246  * AVERROR code on failure (but the code will be
247  * dropped and treated as ENOMEM by the calling code)
248  */
250 
251  /**
252  * Filter initialization function.
253  *
254  * This callback will be called only once during the filter lifetime, after
255  * all the options have been set, but before links between filters are
256  * established and format negotiation is done.
257  *
258  * Basic filter initialization should be done here. Filters with dynamic
259  * inputs and/or outputs should create those inputs/outputs here based on
260  * provided options. No more changes to this filter's inputs/outputs can be
261  * done after this callback.
262  *
263  * This callback must not assume that the filter links exist or frame
264  * parameters are known.
265  *
266  * @ref AVFilter.uninit "uninit" is guaranteed to be called even if
267  * initialization fails, so this callback does not have to clean up on
268  * failure.
269  *
270  * @return 0 on success, a negative AVERROR on failure
271  */
273 
274  /**
275  * Filter uninitialization function.
276  *
277  * Called only once right before the filter is freed. Should deallocate any
278  * memory held by the filter, release any buffer references, etc. It does
279  * not need to deallocate the AVFilterContext.priv memory itself.
280  *
281  * This callback may be called even if @ref AVFilter.init "init" was not
282  * called or failed, so it must be prepared to handle such a situation.
283  */
285 
286  /**
287  * The state of the following union is determined by formats_state.
288  * See the documentation of enum FilterFormatsState in internal.h.
289  */
290  union {
291  /**
292  * Query formats supported by the filter on its inputs and outputs.
293  *
294  * This callback is called after the filter is initialized (so the inputs
295  * and outputs are fixed), shortly before the format negotiation. This
296  * callback may be called more than once.
297  *
298  * This callback must set ::AVFilterLink's
299  * @ref AVFilterFormatsConfig.formats "outcfg.formats"
300  * on every input link and
301  * @ref AVFilterFormatsConfig.formats "incfg.formats"
302  * on every output link to a list of pixel/sample formats that the filter
303  * supports on that link.
304  * For video links, this filter may also set
305  * @ref AVFilterFormatsConfig.color_spaces "incfg.color_spaces"
306  * /
307  * @ref AVFilterFormatsConfig.color_spaces "outcfg.color_spaces"
308  * and @ref AVFilterFormatsConfig.color_ranges "incfg.color_ranges"
309  * /
310  * @ref AVFilterFormatsConfig.color_ranges "outcfg.color_ranges"
311  * analogously.
312  * For audio links, this filter must also set
313  * @ref AVFilterFormatsConfig.samplerates "incfg.samplerates"
314  * /
315  * @ref AVFilterFormatsConfig.samplerates "outcfg.samplerates"
316  * and @ref AVFilterFormatsConfig.channel_layouts "incfg.channel_layouts"
317  * /
318  * @ref AVFilterFormatsConfig.channel_layouts "outcfg.channel_layouts"
319  * analogously.
320  *
321  * This callback must never be NULL if the union is in this state.
322  *
323  * @return zero on success, a negative value corresponding to an
324  * AVERROR code otherwise
325  */
327  /**
328  * A pointer to an array of admissible pixel formats delimited
329  * by AV_PIX_FMT_NONE. The generic code will use this list
330  * to indicate that this filter supports each of these pixel formats,
331  * provided that all inputs and outputs use the same pixel format.
332  *
333  * In addition to that the generic code will mark all inputs
334  * and all outputs as supporting all color spaces and ranges, as
335  * long as all inputs and outputs use the same color space/range.
336  *
337  * This list must never be NULL if the union is in this state.
338  * The type of all inputs and outputs of filters using this must
339  * be AVMEDIA_TYPE_VIDEO.
340  */
342  /**
343  * Analogous to pixels, but delimited by AV_SAMPLE_FMT_NONE
344  * and restricted to filters that only have AVMEDIA_TYPE_AUDIO
345  * inputs and outputs.
346  *
347  * In addition to that the generic code will mark all inputs
348  * and all outputs as supporting all sample rates and every
349  * channel count and channel layout, as long as all inputs
350  * and outputs use the same sample rate and channel count/layout.
351  */
353  /**
354  * Equivalent to { pix_fmt, AV_PIX_FMT_NONE } as pixels_list.
355  */
357  /**
358  * Equivalent to { sample_fmt, AV_SAMPLE_FMT_NONE } as samples_list.
359  */
361  } formats;
362 
363  int priv_size; ///< size of private data to allocate for the filter
364 
365  int flags_internal; ///< Additional flags for avfilter internal use only.
366 
367  /**
368  * Make the filter instance process a command.
369  *
370  * @param cmd the command to process, for handling simplicity all commands must be alphanumeric only
371  * @param arg the argument for the command
372  * @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.
373  * @param flags if AVFILTER_CMD_FLAG_FAST is set and the command would be
374  * time consuming then a filter should treat it like an unsupported command
375  *
376  * @returns >=0 on success otherwise an error code.
377  * AVERROR(ENOSYS) on unsupported commands
378  */
379  int (*process_command)(AVFilterContext *, const char *cmd, const char *arg, char *res, int res_len, int flags);
380 
381  /**
382  * Filter activation function.
383  *
384  * Called when any processing is needed from the filter, instead of any
385  * filter_frame and request_frame on pads.
386  *
387  * The function must examine inlinks and outlinks and perform a single
388  * step of processing. If there is nothing to do, the function must do
389  * nothing and not return an error. If more steps are or may be
390  * possible, it must use ff_filter_set_ready() to schedule another
391  * activation.
392  */
394 } AVFilter;
395 
396 /**
397  * Get the number of elements in an AVFilter's inputs or outputs array.
398  */
399 unsigned avfilter_filter_pad_count(const AVFilter *filter, int is_output);
400 
401 /**
402  * Process multiple parts of the frame concurrently.
403  */
404 #define AVFILTER_THREAD_SLICE (1 << 0)
405 
407 
408 /** An instance of a filter */
410  const AVClass *av_class; ///< needed for av_log() and filters common options
411 
412  const AVFilter *filter; ///< the AVFilter of which this is an instance
413 
414  char *name; ///< name of this filter instance
415 
416  AVFilterPad *input_pads; ///< array of input pads
417  AVFilterLink **inputs; ///< array of pointers to input links
418  unsigned nb_inputs; ///< number of input pads
419 
420  AVFilterPad *output_pads; ///< array of output pads
421  AVFilterLink **outputs; ///< array of pointers to output links
422  unsigned nb_outputs; ///< number of output pads
423 
424  void *priv; ///< private data for use by the filter
425 
426  struct AVFilterGraph *graph; ///< filtergraph this filter belongs to
427 
428  /**
429  * Type of multithreading being allowed/used. A combination of
430  * AVFILTER_THREAD_* flags.
431  *
432  * May be set by the caller before initializing the filter to forbid some
433  * or all kinds of multithreading for this filter. The default is allowing
434  * everything.
435  *
436  * When the filter is initialized, this field is combined using bit AND with
437  * AVFilterGraph.thread_type to get the final mask used for determining
438  * allowed threading types. I.e. a threading type needs to be set in both
439  * to be allowed.
440  *
441  * After the filter is initialized, libavfilter sets this field to the
442  * threading type that is actually used (0 for no multithreading).
443  */
445 
446  /**
447  * An opaque struct for libavfilter internal use.
448  */
449  AVFilterInternal *internal;
450 
452 
453  char *enable_str; ///< enable expression string
454  void *enable; ///< parsed expression (AVExpr*)
455  double *var_values; ///< variable values for the enable expression
456  int is_disabled; ///< the enabled state from the last expression evaluation
457 
458  /**
459  * For filters which will create hardware frames, sets the device the
460  * filter should create them in. All other filters will ignore this field:
461  * in particular, a filter which consumes or processes hardware frames will
462  * instead use the hw_frames_ctx field in AVFilterLink to carry the
463  * hardware context information.
464  *
465  * May be set by the caller on filters flagged with AVFILTER_FLAG_HWDEVICE
466  * before initializing the filter with avfilter_init_str() or
467  * avfilter_init_dict().
468  */
470 
471  /**
472  * Max number of threads allowed in this filter instance.
473  * If <= 0, its value is ignored.
474  * Overrides global number of threads set per filter graph.
475  */
477 
478  /**
479  * Ready status of the filter.
480  * A non-0 value means that the filter needs activating;
481  * a higher value suggests a more urgent activation.
482  */
483  unsigned ready;
484 
485  /**
486  * Sets the number of extra hardware frames which the filter will
487  * allocate on its output links for use in following filters or by
488  * the caller.
489  *
490  * Some hardware filters require all frames that they will use for
491  * output to be defined in advance before filtering starts. For such
492  * filters, any hardware frame pools used for output must therefore be
493  * of fixed size. The extra frames set here are on top of any number
494  * that the filter needs internally in order to operate normally.
495  *
496  * This field must be set before the graph containing this filter is
497  * configured.
498  */
500 };
501 
502 /**
503  * Lists of formats / etc. supported by an end of a link.
504  *
505  * This structure is directly part of AVFilterLink, in two copies:
506  * one for the source filter, one for the destination filter.
507 
508  * These lists are used for negotiating the format to actually be used,
509  * which will be loaded into the format and channel_layout members of
510  * AVFilterLink, when chosen.
511  */
512 typedef struct AVFilterFormatsConfig {
513 
514  /**
515  * List of supported formats (pixel or sample).
516  */
518 
519  /**
520  * Lists of supported sample rates, only for audio.
521  */
523 
524  /**
525  * Lists of supported channel layouts, only for audio.
526  */
528 
529  /**
530  * Lists of supported YUV color metadata, only for YUV video.
531  */
532  AVFilterFormats *color_spaces; ///< AVColorSpace
533  AVFilterFormats *color_ranges; ///< AVColorRange
534 
536 
537 /**
538  * A link between two filters. This contains pointers to the source and
539  * destination filters between which this link exists, and the indexes of
540  * the pads involved. In addition, this link also contains the parameters
541  * which have been negotiated and agreed upon between the filter, such as
542  * image dimensions, format, etc.
543  *
544  * Applications must not normally access the link structure directly.
545  * Use the buffersrc and buffersink API instead.
546  * In the future, access to the header may be reserved for filters
547  * implementation.
548  */
549 struct AVFilterLink {
550  AVFilterContext *src; ///< source filter
551  AVFilterPad *srcpad; ///< output pad on the source filter
552 
553  AVFilterContext *dst; ///< dest filter
554  AVFilterPad *dstpad; ///< input pad on the dest filter
555 
556  enum AVMediaType type; ///< filter media type
557 
558  /* These parameters apply only to video */
559  int w; ///< agreed upon image width
560  int h; ///< agreed upon image height
561  AVRational sample_aspect_ratio; ///< agreed upon sample aspect ratio
562  /* These parameters apply only to audio */
563 #if FF_API_OLD_CHANNEL_LAYOUT
564  /**
565  * channel layout of current buffer (see libavutil/channel_layout.h)
566  * @deprecated use ch_layout
567  */
569  uint64_t channel_layout;
570 #endif
571  int sample_rate; ///< samples per second
572 
573  int format; ///< agreed upon media format
574 
575  /**
576  * Define the time base used by the PTS of the frames/samples
577  * which will pass through this link.
578  * During the configuration stage, each filter is supposed to
579  * change only the output timebase, while the timebase of the
580  * input link is assumed to be an unchangeable property.
581  */
583 
584  AVChannelLayout ch_layout; ///< channel layout of current buffer (see libavutil/channel_layout.h)
585 
586  /**
587  * For non-YUV links, these are respectively set to fallback values (as
588  * appropriate for that colorspace).
589  *
590  * Note: This includes grayscale formats, as these are currently treated
591  * as forced full range always.
592  */
593  enum AVColorSpace colorspace; ///< agreed upon YUV color space
594  enum AVColorRange color_range; ///< agreed upon YUV color range
595 
596  /*****************************************************************
597  * All fields below this line are not part of the public API. They
598  * may not be used outside of libavfilter and can be changed and
599  * removed at will.
600  * New public fields should be added right above.
601  *****************************************************************
602  */
603 
604  /**
605  * Lists of supported formats / etc. supported by the input filter.
606  */
608 
609  /**
610  * Lists of supported formats / etc. supported by the output filter.
611  */
613 
614  /**
615  * Graph the filter belongs to.
616  */
618 
619  /**
620  * Current timestamp of the link, as defined by the most recent
621  * frame(s), in link time_base units.
622  */
623  int64_t current_pts;
624 
625  /**
626  * Current timestamp of the link, as defined by the most recent
627  * frame(s), in AV_TIME_BASE units.
628  */
629  int64_t current_pts_us;
630 
631  /**
632  * Frame rate of the stream on the link, or 1/0 if unknown or variable;
633  * if left to 0/0, will be automatically copied from the first input
634  * of the source filter if it exists.
635  *
636  * Sources should set it to the best estimation of the real frame rate.
637  * If the source frame rate is unknown or variable, set this to 1/0.
638  * Filters should update it if necessary depending on their function.
639  * Sinks can use it to set a default output frame rate.
640  * It is similar to the r_frame_rate field in AVStream.
641  */
643 
644  /**
645  * Minimum number of samples to filter at once. If filter_frame() is
646  * called with fewer samples, it will accumulate them in fifo.
647  * This field and the related ones must not be changed after filtering
648  * has started.
649  * If 0, all related fields are ignored.
650  */
652 
653  /**
654  * Maximum number of samples to filter at once. If filter_frame() is
655  * called with more samples, it will split them.
656  */
658 
659  /**
660  * Number of past frames sent through the link.
661  */
663 
664  /**
665  * Number of past samples sent through the link.
666  */
668 
669  /**
670  * True if a frame is currently wanted on the output of this filter.
671  * Set when ff_request_frame() is called by the output,
672  * cleared when a frame is filtered.
673  */
675 
676  /**
677  * For hwaccel pixel formats, this should be a reference to the
678  * AVHWFramesContext describing the frames.
679  */
681 };
682 
683 /**
684  * Link two filters together.
685  *
686  * @param src the source filter
687  * @param srcpad index of the output pad on the source filter
688  * @param dst the destination filter
689  * @param dstpad index of the input pad on the destination filter
690  * @return zero on success
691  */
692 int avfilter_link(AVFilterContext *src, unsigned srcpad,
693  AVFilterContext *dst, unsigned dstpad);
694 
695 /**
696  * Free the link in *link, and set its pointer to NULL.
697  */
699 
700 /**
701  * Negotiate the media format, dimensions, etc of all inputs to a filter.
702  *
703  * @param filter the filter to negotiate the properties for its inputs
704  * @return zero on successful negotiation
705  */
707 
708 #define AVFILTER_CMD_FLAG_ONE 1 ///< Stop once a filter understood the command (for target=all for example), fast filters are favored automatically
709 #define AVFILTER_CMD_FLAG_FAST 2 ///< Only execute command when its fast (like a video out that supports contrast adjustment in hw)
710 
711 /**
712  * Make the filter instance process a command.
713  * It is recommended to use avfilter_graph_send_command().
714  */
715 int avfilter_process_command(AVFilterContext *filter, const char *cmd, const char *arg, char *res, int res_len, int flags);
716 
717 /**
718  * Iterate over all registered filters.
719  *
720  * @param opaque a pointer where libavfilter will store the iteration state. Must
721  * point to NULL to start the iteration.
722  *
723  * @return the next registered filter or NULL when the iteration is
724  * finished
725  */
726 const AVFilter *av_filter_iterate(void **opaque);
727 
728 /**
729  * Get a filter definition matching the given name.
730  *
731  * @param name the filter name to find
732  * @return the filter definition, if any matching one is registered.
733  * NULL if none found.
734  */
735 const AVFilter *avfilter_get_by_name(const char *name);
736 
737 
738 /**
739  * Initialize a filter with the supplied parameters.
740  *
741  * @param ctx uninitialized filter context to initialize
742  * @param args Options to initialize the filter with. This must be a
743  * ':'-separated list of options in the 'key=value' form.
744  * May be NULL if the options have been set directly using the
745  * AVOptions API or there are no options that need to be set.
746  * @return 0 on success, a negative AVERROR on failure
747  */
748 int avfilter_init_str(AVFilterContext *ctx, const char *args);
749 
750 /**
751  * Initialize a filter with the supplied dictionary of options.
752  *
753  * @param ctx uninitialized filter context to initialize
754  * @param options An AVDictionary filled with options for this filter. On
755  * return this parameter will be destroyed and replaced with
756  * a dict containing options that were not found. This dictionary
757  * must be freed by the caller.
758  * May be NULL, then this function is equivalent to
759  * avfilter_init_str() with the second parameter set to NULL.
760  * @return 0 on success, a negative AVERROR on failure
761  *
762  * @note This function and avfilter_init_str() do essentially the same thing,
763  * the difference is in manner in which the options are passed. It is up to the
764  * calling code to choose whichever is more preferable. The two functions also
765  * behave differently when some of the provided options are not declared as
766  * supported by the filter. In such a case, avfilter_init_str() will fail, but
767  * this function will leave those extra options in the options AVDictionary and
768  * continue as usual.
769  */
771 
772 /**
773  * Free a filter context. This will also remove the filter from its
774  * filtergraph's list of filters.
775  *
776  * @param filter the filter to free
777  */
779 
780 /**
781  * Insert a filter in the middle of an existing link.
782  *
783  * @param link the link into which the filter should be inserted
784  * @param filt the filter to be inserted
785  * @param filt_srcpad_idx the input pad on the filter to connect
786  * @param filt_dstpad_idx the output pad on the filter to connect
787  * @return zero on success
788  */
790  unsigned filt_srcpad_idx, unsigned filt_dstpad_idx);
791 
792 /**
793  * @return AVClass for AVFilterContext.
794  *
795  * @see av_opt_find().
796  */
797 const AVClass *avfilter_get_class(void);
798 
800 
801 /**
802  * A function pointer passed to the @ref AVFilterGraph.execute callback to be
803  * executed multiple times, possibly in parallel.
804  *
805  * @param ctx the filter context the job belongs to
806  * @param arg an opaque parameter passed through from @ref
807  * AVFilterGraph.execute
808  * @param jobnr the index of the job being executed
809  * @param nb_jobs the total number of jobs
810  *
811  * @return 0 on success, a negative AVERROR on error
812  */
813 typedef int (avfilter_action_func)(AVFilterContext *ctx, void *arg, int jobnr, int nb_jobs);
814 
815 /**
816  * A function executing multiple jobs, possibly in parallel.
817  *
818  * @param ctx the filter context to which the jobs belong
819  * @param func the function to be called multiple times
820  * @param arg the argument to be passed to func
821  * @param ret a nb_jobs-sized array to be filled with return values from each
822  * invocation of func
823  * @param nb_jobs the number of jobs to execute
824  *
825  * @return 0 on success, a negative AVERROR on error
826  */
828  void *arg, int *ret, int nb_jobs);
829 
830 typedef struct AVFilterGraph {
833  unsigned nb_filters;
834 
835  char *scale_sws_opts; ///< sws options to use for the auto-inserted scale filters
836 
837  /**
838  * Type of multithreading allowed for filters in this graph. A combination
839  * of AVFILTER_THREAD_* flags.
840  *
841  * May be set by the caller at any point, the setting will apply to all
842  * filters initialized after that. The default is allowing everything.
843  *
844  * When a filter in this graph is initialized, this field is combined using
845  * bit AND with AVFilterContext.thread_type to get the final mask used for
846  * determining allowed threading types. I.e. a threading type needs to be
847  * set in both to be allowed.
848  */
850 
851  /**
852  * Maximum number of threads used by filters in this graph. May be set by
853  * the caller before adding any filters to the filtergraph. Zero (the
854  * default) means that the number of threads is determined automatically.
855  */
857 
858  /**
859  * Opaque object for libavfilter internal use.
860  */
862 
863  /**
864  * Opaque user data. May be set by the caller to an arbitrary value, e.g. to
865  * be used from callbacks like @ref AVFilterGraph.execute.
866  * Libavfilter will not touch this field in any way.
867  */
868  void *opaque;
869 
870  /**
871  * This callback may be set by the caller immediately after allocating the
872  * graph and before adding any filters to it, to provide a custom
873  * multithreading implementation.
874  *
875  * If set, filters with slice threading capability will call this callback
876  * to execute multiple jobs in parallel.
877  *
878  * If this field is left unset, libavfilter will use its internal
879  * implementation, which may or may not be multithreaded depending on the
880  * platform and build options.
881  */
883 
884  char *aresample_swr_opts; ///< swr options to use for the auto-inserted aresample filters, Access ONLY through AVOptions
885 } AVFilterGraph;
886 
887 /**
888  * Allocate a filter graph.
889  *
890  * @return the allocated filter graph on success or NULL.
891  */
893 
894 /**
895  * Create a new filter instance in a filter graph.
896  *
897  * @param graph graph in which the new filter will be used
898  * @param filter the filter to create an instance of
899  * @param name Name to give to the new instance (will be copied to
900  * AVFilterContext.name). This may be used by the caller to identify
901  * different filters, libavfilter itself assigns no semantics to
902  * this parameter. May be NULL.
903  *
904  * @return the context of the newly created filter instance (note that it is
905  * also retrievable directly through AVFilterGraph.filters or with
906  * avfilter_graph_get_filter()) on success or NULL on failure.
907  */
909  const AVFilter *filter,
910  const char *name);
911 
912 /**
913  * Get a filter instance identified by instance name from graph.
914  *
915  * @param graph filter graph to search through.
916  * @param name filter instance name (should be unique in the graph).
917  * @return the pointer to the found filter instance or NULL if it
918  * cannot be found.
919  */
921 
922 /**
923  * Create and add a filter instance into an existing graph.
924  * The filter instance is created from the filter filt and inited
925  * with the parameter args. opaque is currently ignored.
926  *
927  * In case of success put in *filt_ctx the pointer to the created
928  * filter instance, otherwise set *filt_ctx to NULL.
929  *
930  * @param name the instance name to give to the created filter instance
931  * @param graph_ctx the filter graph
932  * @return a negative AVERROR error code in case of failure, a non
933  * negative value otherwise
934  */
936  const char *name, const char *args, void *opaque,
937  AVFilterGraph *graph_ctx);
938 
939 /**
940  * Enable or disable automatic format conversion inside the graph.
941  *
942  * Note that format conversion can still happen inside explicitly inserted
943  * scale and aresample filters.
944  *
945  * @param flags any of the AVFILTER_AUTO_CONVERT_* constants
946  */
948 
949 enum {
950  AVFILTER_AUTO_CONVERT_ALL = 0, /**< all automatic conversions enabled */
951  AVFILTER_AUTO_CONVERT_NONE = -1, /**< all automatic conversions disabled */
952 };
953 
954 /**
955  * Check validity and configure all the links and formats in the graph.
956  *
957  * @param graphctx the filter graph
958  * @param log_ctx context used for logging
959  * @return >= 0 in case of success, a negative AVERROR code otherwise
960  */
961 int avfilter_graph_config(AVFilterGraph *graphctx, void *log_ctx);
962 
963 /**
964  * Free a graph, destroy its links, and set *graph to NULL.
965  * If *graph is NULL, do nothing.
966  */
967 void avfilter_graph_free(AVFilterGraph **graph);
968 
969 /**
970  * A linked-list of the inputs/outputs of the filter chain.
971  *
972  * This is mainly useful for avfilter_graph_parse() / avfilter_graph_parse2(),
973  * where it is used to communicate open (unlinked) inputs and outputs from and
974  * to the caller.
975  * This struct specifies, per each not connected pad contained in the graph, the
976  * filter context and the pad index required for establishing a link.
977  */
978 typedef struct AVFilterInOut {
979  /** unique name for this input/output in the list */
980  char *name;
981 
982  /** filter context associated to this input/output */
984 
985  /** index of the filt_ctx pad to use for linking */
986  int pad_idx;
987 
988  /** next input/input in the list, NULL if this is the last */
990 } AVFilterInOut;
991 
992 /**
993  * Allocate a single AVFilterInOut entry.
994  * Must be freed with avfilter_inout_free().
995  * @return allocated AVFilterInOut on success, NULL on failure.
996  */
998 
999 /**
1000  * Free the supplied list of AVFilterInOut and set *inout to NULL.
1001  * If *inout is NULL, do nothing.
1002  */
1003 void avfilter_inout_free(AVFilterInOut **inout);
1004 
1005 /**
1006  * Add a graph described by a string to a graph.
1007  *
1008  * @note The caller must provide the lists of inputs and outputs,
1009  * which therefore must be known before calling the function.
1010  *
1011  * @note The inputs parameter describes inputs of the already existing
1012  * part of the graph; i.e. from the point of view of the newly created
1013  * part, they are outputs. Similarly the outputs parameter describes
1014  * outputs of the already existing filters, which are provided as
1015  * inputs to the parsed filters.
1016  *
1017  * @param graph the filter graph where to link the parsed graph context
1018  * @param filters string to be parsed
1019  * @param inputs linked list to the inputs of the graph
1020  * @param outputs linked list to the outputs of the graph
1021  * @return zero on success, a negative AVERROR code on error
1022  */
1023 int avfilter_graph_parse(AVFilterGraph *graph, const char *filters,
1025  void *log_ctx);
1026 
1027 /**
1028  * Add a graph described by a string to a graph.
1029  *
1030  * In the graph filters description, if the input label of the first
1031  * filter is not specified, "in" is assumed; if the output label of
1032  * the last filter is not specified, "out" is assumed.
1033  *
1034  * @param graph the filter graph where to link the parsed graph context
1035  * @param filters string to be parsed
1036  * @param inputs pointer to a linked list to the inputs of the graph, may be NULL.
1037  * If non-NULL, *inputs is updated to contain the list of open inputs
1038  * after the parsing, should be freed with avfilter_inout_free().
1039  * @param outputs pointer to a linked list to the outputs of the graph, may be NULL.
1040  * If non-NULL, *outputs is updated to contain the list of open outputs
1041  * after the parsing, should be freed with avfilter_inout_free().
1042  * @return non negative on success, a negative AVERROR code on error
1043  */
1044 int avfilter_graph_parse_ptr(AVFilterGraph *graph, const char *filters,
1046  void *log_ctx);
1047 
1048 /**
1049  * Add a graph described by a string to a graph.
1050  *
1051  * @param[in] graph the filter graph where to link the parsed graph context
1052  * @param[in] filters string to be parsed
1053  * @param[out] inputs a linked list of all free (unlinked) inputs of the
1054  * parsed graph will be returned here. It is to be freed
1055  * by the caller using avfilter_inout_free().
1056  * @param[out] outputs a linked list of all free (unlinked) outputs of the
1057  * parsed graph will be returned here. It is to be freed by the
1058  * caller using avfilter_inout_free().
1059  * @return zero on success, a negative AVERROR code on error
1060  *
1061  * @note This function returns the inputs and outputs that are left
1062  * unlinked after parsing the graph and the caller then deals with
1063  * them.
1064  * @note This function makes no reference whatsoever to already
1065  * existing parts of the graph and the inputs parameter will on return
1066  * contain inputs of the newly parsed part of the graph. Analogously
1067  * the outputs parameter will contain outputs of the newly created
1068  * filters.
1069  */
1070 int avfilter_graph_parse2(AVFilterGraph *graph, const char *filters,
1073 
1074 /**
1075  * Parameters of a filter's input or output pad.
1076  *
1077  * Created as a child of AVFilterParams by avfilter_graph_segment_parse().
1078  * Freed in avfilter_graph_segment_free().
1079  */
1080 typedef struct AVFilterPadParams {
1081  /**
1082  * An av_malloc()'ed string containing the pad label.
1083  *
1084  * May be av_free()'d and set to NULL by the caller, in which case this pad
1085  * will be treated as unlabeled for linking.
1086  * May also be replaced by another av_malloc()'ed string.
1087  */
1088  char *label;
1090 
1091 /**
1092  * Parameters describing a filter to be created in a filtergraph.
1093  *
1094  * Created as a child of AVFilterGraphSegment by avfilter_graph_segment_parse().
1095  * Freed in avfilter_graph_segment_free().
1096  */
1097 typedef struct AVFilterParams {
1098  /**
1099  * The filter context.
1100  *
1101  * Created by avfilter_graph_segment_create_filters() based on
1102  * AVFilterParams.filter_name and instance_name.
1103  *
1104  * Callers may also create the filter context manually, then they should
1105  * av_free() filter_name and set it to NULL. Such AVFilterParams instances
1106  * are then skipped by avfilter_graph_segment_create_filters().
1107  */
1109 
1110  /**
1111  * Name of the AVFilter to be used.
1112  *
1113  * An av_malloc()'ed string, set by avfilter_graph_segment_parse(). Will be
1114  * passed to avfilter_get_by_name() by
1115  * avfilter_graph_segment_create_filters().
1116  *
1117  * Callers may av_free() this string and replace it with another one or
1118  * NULL. If the caller creates the filter instance manually, this string
1119  * MUST be set to NULL.
1120  *
1121  * When both AVFilterParams.filter an AVFilterParams.filter_name are NULL,
1122  * this AVFilterParams instance is skipped by avfilter_graph_segment_*()
1123  * functions.
1124  */
1126  /**
1127  * Name to be used for this filter instance.
1128  *
1129  * An av_malloc()'ed string, may be set by avfilter_graph_segment_parse() or
1130  * left NULL. The caller may av_free() this string and replace with another
1131  * one or NULL.
1132  *
1133  * Will be used by avfilter_graph_segment_create_filters() - passed as the
1134  * third argument to avfilter_graph_alloc_filter(), then freed and set to
1135  * NULL.
1136  */
1138 
1139  /**
1140  * Options to be apllied to the filter.
1141  *
1142  * Filled by avfilter_graph_segment_parse(). Afterwards may be freely
1143  * modified by the caller.
1144  *
1145  * Will be applied to the filter by avfilter_graph_segment_apply_opts()
1146  * with an equivalent of av_opt_set_dict2(filter, &opts, AV_OPT_SEARCH_CHILDREN),
1147  * i.e. any unapplied options will be left in this dictionary.
1148  */
1150 
1152  unsigned nb_inputs;
1153 
1155  unsigned nb_outputs;
1156 } AVFilterParams;
1157 
1158 /**
1159  * A filterchain is a list of filter specifications.
1160  *
1161  * Created as a child of AVFilterGraphSegment by avfilter_graph_segment_parse().
1162  * Freed in avfilter_graph_segment_free().
1163  */
1164 typedef struct AVFilterChain {
1166  size_t nb_filters;
1167 } AVFilterChain;
1168 
1169 /**
1170  * A parsed representation of a filtergraph segment.
1171  *
1172  * A filtergraph segment is conceptually a list of filterchains, with some
1173  * supplementary information (e.g. format conversion flags).
1174  *
1175  * Created by avfilter_graph_segment_parse(). Must be freed with
1176  * avfilter_graph_segment_free().
1177  */
1178 typedef struct AVFilterGraphSegment {
1179  /**
1180  * The filtergraph this segment is associated with.
1181  * Set by avfilter_graph_segment_parse().
1182  */
1184 
1185  /**
1186  * A list of filter chain contained in this segment.
1187  * Set in avfilter_graph_segment_parse().
1188  */
1190  size_t nb_chains;
1191 
1192  /**
1193  * A string containing a colon-separated list of key=value options applied
1194  * to all scale filters in this segment.
1195  *
1196  * May be set by avfilter_graph_segment_parse().
1197  * The caller may free this string with av_free() and replace it with a
1198  * different av_malloc()'ed string.
1199  */
1202 
1203 /**
1204  * Parse a textual filtergraph description into an intermediate form.
1205  *
1206  * This intermediate representation is intended to be modified by the caller as
1207  * described in the documentation of AVFilterGraphSegment and its children, and
1208  * then applied to the graph either manually or with other
1209  * avfilter_graph_segment_*() functions. See the documentation for
1210  * avfilter_graph_segment_apply() for the canonical way to apply
1211  * AVFilterGraphSegment.
1212  *
1213  * @param graph Filter graph the parsed segment is associated with. Will only be
1214  * used for logging and similar auxiliary purposes. The graph will
1215  * not be actually modified by this function - the parsing results
1216  * are instead stored in seg for further processing.
1217  * @param graph_str a string describing the filtergraph segment
1218  * @param flags reserved for future use, caller must set to 0 for now
1219  * @param seg A pointer to the newly-created AVFilterGraphSegment is written
1220  * here on success. The graph segment is owned by the caller and must
1221  * be freed with avfilter_graph_segment_free() before graph itself is
1222  * freed.
1223  *
1224  * @retval "non-negative number" success
1225  * @retval "negative error code" failure
1226  */
1227 int avfilter_graph_segment_parse(AVFilterGraph *graph, const char *graph_str,
1228  int flags, AVFilterGraphSegment **seg);
1229 
1230 /**
1231  * Create filters specified in a graph segment.
1232  *
1233  * Walk through the creation-pending AVFilterParams in the segment and create
1234  * new filter instances for them.
1235  * Creation-pending params are those where AVFilterParams.filter_name is
1236  * non-NULL (and hence AVFilterParams.filter is NULL). All other AVFilterParams
1237  * instances are ignored.
1238  *
1239  * For any filter created by this function, the corresponding
1240  * AVFilterParams.filter is set to the newly-created filter context,
1241  * AVFilterParams.filter_name and AVFilterParams.instance_name are freed and set
1242  * to NULL.
1243  *
1244  * @param seg the filtergraph segment to process
1245  * @param flags reserved for future use, caller must set to 0 for now
1246  *
1247  * @retval "non-negative number" Success, all creation-pending filters were
1248  * successfully created
1249  * @retval AVERROR_FILTER_NOT_FOUND some filter's name did not correspond to a
1250  * known filter
1251  * @retval "another negative error code" other failures
1252  *
1253  * @note Calling this function multiple times is safe, as it is idempotent.
1254  */
1256 
1257 /**
1258  * Apply parsed options to filter instances in a graph segment.
1259  *
1260  * Walk through all filter instances in the graph segment that have option
1261  * dictionaries associated with them and apply those options with
1262  * av_opt_set_dict2(..., AV_OPT_SEARCH_CHILDREN). AVFilterParams.opts is
1263  * replaced by the dictionary output by av_opt_set_dict2(), which should be
1264  * empty (NULL) if all options were successfully applied.
1265  *
1266  * If any options could not be found, this function will continue processing all
1267  * other filters and finally return AVERROR_OPTION_NOT_FOUND (unless another
1268  * error happens). The calling program may then deal with unapplied options as
1269  * it wishes.
1270  *
1271  * Any creation-pending filters (see avfilter_graph_segment_create_filters())
1272  * present in the segment will cause this function to fail. AVFilterParams with
1273  * no associated filter context are simply skipped.
1274  *
1275  * @param seg the filtergraph segment to process
1276  * @param flags reserved for future use, caller must set to 0 for now
1277  *
1278  * @retval "non-negative number" Success, all options were successfully applied.
1279  * @retval AVERROR_OPTION_NOT_FOUND some options were not found in a filter
1280  * @retval "another negative error code" other failures
1281  *
1282  * @note Calling this function multiple times is safe, as it is idempotent.
1283  */
1285 
1286 /**
1287  * Initialize all filter instances in a graph segment.
1288  *
1289  * Walk through all filter instances in the graph segment and call
1290  * avfilter_init_dict(..., NULL) on those that have not been initialized yet.
1291  *
1292  * Any creation-pending filters (see avfilter_graph_segment_create_filters())
1293  * present in the segment will cause this function to fail. AVFilterParams with
1294  * no associated filter context or whose filter context is already initialized,
1295  * are simply skipped.
1296  *
1297  * @param seg the filtergraph segment to process
1298  * @param flags reserved for future use, caller must set to 0 for now
1299  *
1300  * @retval "non-negative number" Success, all filter instances were successfully
1301  * initialized
1302  * @retval "negative error code" failure
1303  *
1304  * @note Calling this function multiple times is safe, as it is idempotent.
1305  */
1307 
1308 /**
1309  * Link filters in a graph segment.
1310  *
1311  * Walk through all filter instances in the graph segment and try to link all
1312  * unlinked input and output pads. Any creation-pending filters (see
1313  * avfilter_graph_segment_create_filters()) present in the segment will cause
1314  * this function to fail. Disabled filters and already linked pads are skipped.
1315  *
1316  * Every filter output pad that has a corresponding AVFilterPadParams with a
1317  * non-NULL label is
1318  * - linked to the input with the matching label, if one exists;
1319  * - exported in the outputs linked list otherwise, with the label preserved.
1320  * Unlabeled outputs are
1321  * - linked to the first unlinked unlabeled input in the next non-disabled
1322  * filter in the chain, if one exists
1323  * - exported in the ouputs linked list otherwise, with NULL label
1324  *
1325  * Similarly, unlinked input pads are exported in the inputs linked list.
1326  *
1327  * @param seg the filtergraph segment to process
1328  * @param flags reserved for future use, caller must set to 0 for now
1329  * @param[out] inputs a linked list of all free (unlinked) inputs of the
1330  * filters in this graph segment will be returned here. It
1331  * is to be freed by the caller using avfilter_inout_free().
1332  * @param[out] outputs a linked list of all free (unlinked) outputs of the
1333  * filters in this graph segment will be returned here. It
1334  * is to be freed by the caller using avfilter_inout_free().
1335  *
1336  * @retval "non-negative number" success
1337  * @retval "negative error code" failure
1338  *
1339  * @note Calling this function multiple times is safe, as it is idempotent.
1340  */
1344 
1345 /**
1346  * Apply all filter/link descriptions from a graph segment to the associated filtergraph.
1347  *
1348  * This functions is currently equivalent to calling the following in sequence:
1349  * - avfilter_graph_segment_create_filters();
1350  * - avfilter_graph_segment_apply_opts();
1351  * - avfilter_graph_segment_init();
1352  * - avfilter_graph_segment_link();
1353  * failing if any of them fails. This list may be extended in the future.
1354  *
1355  * Since the above functions are idempotent, the caller may call some of them
1356  * manually, then do some custom processing on the filtergraph, then call this
1357  * function to do the rest.
1358  *
1359  * @param seg the filtergraph segment to process
1360  * @param flags reserved for future use, caller must set to 0 for now
1361  * @param[out] inputs passed to avfilter_graph_segment_link()
1362  * @param[out] outputs passed to avfilter_graph_segment_link()
1363  *
1364  * @retval "non-negative number" success
1365  * @retval "negative error code" failure
1366  *
1367  * @note Calling this function multiple times is safe, as it is idempotent.
1368  */
1372 
1373 /**
1374  * Free the provided AVFilterGraphSegment and everything associated with it.
1375  *
1376  * @param seg double pointer to the AVFilterGraphSegment to be freed. NULL will
1377  * be written to this pointer on exit from this function.
1378  *
1379  * @note
1380  * The filter contexts (AVFilterParams.filter) are owned by AVFilterGraph rather
1381  * than AVFilterGraphSegment, so they are not freed.
1382  */
1384 
1385 /**
1386  * Send a command to one or more filter instances.
1387  *
1388  * @param graph the filter graph
1389  * @param target the filter(s) to which the command should be sent
1390  * "all" sends to all filters
1391  * otherwise it can be a filter or filter instance name
1392  * which will send the command to all matching filters.
1393  * @param cmd the command to send, for handling simplicity all commands must be alphanumeric only
1394  * @param arg the argument for the command
1395  * @param res a buffer with size res_size where the filter(s) can return a response.
1396  *
1397  * @returns >=0 on success otherwise an error code.
1398  * AVERROR(ENOSYS) on unsupported commands
1399  */
1400 int avfilter_graph_send_command(AVFilterGraph *graph, const char *target, const char *cmd, const char *arg, char *res, int res_len, int flags);
1401 
1402 /**
1403  * Queue a command for one or more filter instances.
1404  *
1405  * @param graph the filter graph
1406  * @param target the filter(s) to which the command should be sent
1407  * "all" sends to all filters
1408  * otherwise it can be a filter or filter instance name
1409  * which will send the command to all matching filters.
1410  * @param cmd the command to sent, for handling simplicity all commands must be alphanumeric only
1411  * @param arg the argument for the command
1412  * @param ts time at which the command should be sent to the filter
1413  *
1414  * @note As this executes commands after this function returns, no return code
1415  * from the filter is provided, also AVFILTER_CMD_FLAG_ONE is not supported.
1416  */
1417 int avfilter_graph_queue_command(AVFilterGraph *graph, const char *target, const char *cmd, const char *arg, int flags, double ts);
1418 
1419 
1420 /**
1421  * Dump a graph into a human-readable string representation.
1422  *
1423  * @param graph the graph to dump
1424  * @param options formatting options; currently ignored
1425  * @return a string, or NULL in case of memory allocation failure;
1426  * the string must be freed using av_free
1427  */
1428 char *avfilter_graph_dump(AVFilterGraph *graph, const char *options);
1429 
1430 /**
1431  * Request a frame on the oldest sink link.
1432  *
1433  * If the request returns AVERROR_EOF, try the next.
1434  *
1435  * Note that this function is not meant to be the sole scheduling mechanism
1436  * of a filtergraph, only a convenience function to help drain a filtergraph
1437  * in a balanced way under normal circumstances.
1438  *
1439  * Also note that AVERROR_EOF does not mean that frames did not arrive on
1440  * some of the sinks during the process.
1441  * When there are multiple sink links, in case the requested link
1442  * returns an EOF, this may cause a filter to flush pending frames
1443  * which are sent to another sink link, although unrequested.
1444  *
1445  * @return the return value of ff_request_frame(),
1446  * or AVERROR_EOF if all links returned AVERROR_EOF
1447  */
1449 
1450 /**
1451  * @}
1452  */
1453 
1454 #endif /* AVFILTER_AVFILTER_H */
func
int(* func)(AVBPrint *dst, const char *in, const char *arg)
Definition: jacosubdec.c:68
AVFilterGraph::execute
avfilter_execute_func * execute
This callback may be set by the caller immediately after allocating the graph and before adding any f...
Definition: avfilter.h:882
AVFilterChannelLayouts
A list of supported channel layouts.
Definition: formats.h:85
AVFilterContext::nb_threads
int nb_threads
Max number of threads allowed in this filter instance.
Definition: avfilter.h:476
AVPixelFormat
AVPixelFormat
Pixel format.
Definition: pixfmt.h:71
AVFilterFormatsConfig::samplerates
AVFilterFormats * samplerates
Lists of supported sample rates, only for audio.
Definition: avfilter.h:522
name
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf default minimum maximum flags name is the option name
Definition: writing_filters.txt:88
avfilter_filter_pad_count
unsigned avfilter_filter_pad_count(const AVFilter *filter, int is_output)
Get the number of elements in an AVFilter's inputs or outputs array.
Definition: avfilter.c:604
AVFilterGraph::nb_threads
int nb_threads
Maximum number of threads used by filters in this graph.
Definition: avfilter.h:856
avfilter_pad_get_name
const char * avfilter_pad_get_name(const AVFilterPad *pads, int pad_idx)
Get the name of an AVFilterPad.
Definition: avfilter.c:961
AVFilterFormatsConfig::channel_layouts
AVFilterChannelLayouts * channel_layouts
Lists of supported channel layouts, only for audio.
Definition: avfilter.h:527
AVFilterParams::instance_name
char * instance_name
Name to be used for this filter instance.
Definition: avfilter.h:1137
avfilter_graph_segment_create_filters
int avfilter_graph_segment_create_filters(AVFilterGraphSegment *seg, int flags)
Create filters specified in a graph segment.
Definition: graphparser.c:516
AVFilter::pixels_list
enum AVPixelFormat * pixels_list
A pointer to an array of admissible pixel formats delimited by AV_PIX_FMT_NONE.
Definition: avfilter.h:341
AVFilter::priv_class
const AVClass * priv_class
A class for the private data, used to declare filter private AVOptions.
Definition: avfilter.h:205
avfilter_action_func
int() avfilter_action_func(AVFilterContext *ctx, void *arg, int jobnr, int nb_jobs)
A function pointer passed to the AVFilterGraph::execute callback to be executed multiple times,...
Definition: avfilter.h:813
AVFilterContext::var_values
double * var_values
variable values for the enable expression
Definition: avfilter.h:455
AVFilter::pix_fmt
enum AVPixelFormat pix_fmt
Equivalent to { pix_fmt, AV_PIX_FMT_NONE } as pixels_list.
Definition: avfilter.h:356
rational.h
AVFilterContext::is_disabled
int is_disabled
the enabled state from the last expression evaluation
Definition: avfilter.h:456
AVFilter::process_command
int(* process_command)(AVFilterContext *, const char *cmd, const char *arg, char *res, int res_len, int flags)
Make the filter instance process a command.
Definition: avfilter.h:379
AVFilterInOut::next
struct AVFilterInOut * next
next input/input in the list, NULL if this is the last
Definition: avfilter.h:989
AVFILTER_AUTO_CONVERT_ALL
@ AVFILTER_AUTO_CONVERT_ALL
all automatic conversions enabled
Definition: avfilter.h:950
AVFilterContext::nb_outputs
unsigned nb_outputs
number of output pads
Definition: avfilter.h:422
AVFilterContext::av_class
const AVClass * av_class
needed for av_log() and filters common options
Definition: avfilter.h:410
AVFilterContext::hw_device_ctx
AVBufferRef * hw_device_ctx
For filters which will create hardware frames, sets the device the filter should create them in.
Definition: avfilter.h:469
filter
filter_frame For filters that do not use the this method is called when a frame is pushed to the filter s input It can be called at any time except in a reentrant way If the input frame is enough to produce then the filter should push the output frames on the output link immediately As an exception to the previous rule if the input frame is enough to produce several output frames then the filter needs output only at least one per link The additional frames can be left buffered in the filter
Definition: filter_design.txt:228
AVDictionary
Definition: dict.c:34
AVFilterContext::output_pads
AVFilterPad * output_pads
array of output pads
Definition: avfilter.h:420
AVFilter::name
const char * name
Filter name.
Definition: avfilter.h:170
AVFilterParams::inputs
AVFilterPadParams ** inputs
Definition: avfilter.h:1151
avfilter_graph_free
void avfilter_graph_free(AVFilterGraph **graph)
Free a graph, destroy its links, and set *graph to NULL.
Definition: avfiltergraph.c:116
AVFilterFormats
A list of supported formats for one end of a filter link.
Definition: formats.h:64
AVFilterParams::outputs
AVFilterPadParams ** outputs
Definition: avfilter.h:1154
avfilter_graph_create_filter
int avfilter_graph_create_filter(AVFilterContext **filt_ctx, const AVFilter *filt, const char *name, const char *args, void *opaque, AVFilterGraph *graph_ctx)
Create and add a filter instance into an existing graph.
Definition: avfiltergraph.c:137
avfilter_graph_alloc_filter
AVFilterContext * avfilter_graph_alloc_filter(AVFilterGraph *graph, const AVFilter *filter, const char *name)
Create a new filter instance in a filter graph.
Definition: avfiltergraph.c:164
avfilter_graph_segment_link
int avfilter_graph_segment_link(AVFilterGraphSegment *seg, int flags, AVFilterInOut **inputs, AVFilterInOut **outputs)
Link filters in a graph segment.
Definition: graphparser.c:813
AVFilterContext::priv
void * priv
private data for use by the filter
Definition: avfilter.h:424
AVFilterContext::graph
struct AVFilterGraph * graph
filtergraph this filter belongs to
Definition: avfilter.h:426
AVFilterContext::enable_str
char * enable_str
enable expression string
Definition: avfilter.h:453
avfilter_graph_alloc
AVFilterGraph * avfilter_graph_alloc(void)
Allocate a filter graph.
Definition: avfiltergraph.c:82
AVFilter::formats_state
uint8_t formats_state
This field determines the state of the formats union.
Definition: avfilter.h:234
avfilter_insert_filter
int avfilter_insert_filter(AVFilterLink *link, AVFilterContext *filt, unsigned filt_srcpad_idx, unsigned filt_dstpad_idx)
Insert a filter in the middle of an existing link.
Definition: avfilter.c:275
av_filter_iterate
const AVFilter * av_filter_iterate(void **opaque)
Iterate over all registered filters.
Definition: allfilters.c:618
samplefmt.h
AVFilterContext::extra_hw_frames
int extra_hw_frames
Sets the number of extra hardware frames which the filter will allocate on its output links for use i...
Definition: avfilter.h:499
avfilter_config_links
int avfilter_config_links(AVFilterContext *filter)
Negotiate the media format, dimensions, etc of all inputs to a filter.
Definition: avfilter.c:318
avfilter_graph_segment_free
void avfilter_graph_segment_free(AVFilterGraphSegment **seg)
Free the provided AVFilterGraphSegment and everything associated with it.
Definition: graphparser.c:276
AVFilterGraph::opaque
void * opaque
Opaque user data.
Definition: avfilter.h:868
avfilter_graph_segment_parse
int avfilter_graph_segment_parse(AVFilterGraph *graph, const char *graph_str, int flags, AVFilterGraphSegment **seg)
Parse a textual filtergraph description into an intermediate form.
Definition: graphparser.c:460
AVFilter::flags_internal
int flags_internal
Additional flags for avfilter internal use only.
Definition: avfilter.h:365
AVFilterPad
A filter pad used for either input or output.
Definition: internal.h:33
avfilter_license
const char * avfilter_license(void)
Return the libavfilter license.
Definition: version.c:40
AVFilterContext::input_pads
AVFilterPad * input_pads
array of input pads
Definition: avfilter.h:416
avfilter_inout_free
void avfilter_inout_free(AVFilterInOut **inout)
Free the supplied list of AVFilterInOut and set *inout to NULL.
Definition: graphparser.c:76
AVFilterChain::filters
AVFilterParams ** filters
Definition: avfilter.h:1165
AVFilter::samples_list
enum AVSampleFormat * samples_list
Analogous to pixels, but delimited by AV_SAMPLE_FMT_NONE and restricted to filters that only have AVM...
Definition: avfilter.h:352
avfilter_process_command
int avfilter_process_command(AVFilterContext *filter, const char *cmd, const char *arg, char *res, int res_len, int flags)
Make the filter instance process a command.
Definition: avfilter.c:583
filters
#define filters(fmt, type, inverse, clp, inverset, clip, one, clip_fn, packed)
Definition: af_crystalizer.c:54
avfilter_graph_segment_init
int avfilter_graph_segment_init(AVFilterGraphSegment *seg, int flags)
Initialize all filter instances in a graph segment.
Definition: graphparser.c:616
AVFilter::flags
int flags
A combination of AVFILTER_FLAG_*.
Definition: avfilter.h:210
ctx
AVFormatContext * ctx
Definition: movenc.c:48
AVFilterGraph::aresample_swr_opts
char * aresample_swr_opts
swr options to use for the auto-inserted aresample filters, Access ONLY through AVOptions
Definition: avfilter.h:884
AVFilterFormatsConfig::color_spaces
AVFilterFormats * color_spaces
Lists of supported YUV color metadata, only for YUV video.
Definition: avfilter.h:532
AVFilterPadParams::label
char * label
An av_malloc()'ed string containing the pad label.
Definition: avfilter.h:1088
link
Filter the word “frame” indicates either a video frame or a group of audio as stored in an AVFrame structure Format for each input and each output the list of supported formats For video that means pixel format For audio that means channel sample they are references to shared objects When the negotiation mechanism computes the intersection of the formats supported at each end of a link
Definition: filter_design.txt:23
arg
const char * arg
Definition: jacosubdec.c:67
AVFilter::activate
int(* activate)(AVFilterContext *ctx)
Filter activation function.
Definition: avfilter.h:393
avfilter_get_by_name
const AVFilter * avfilter_get_by_name(const char *name)
Get a filter definition matching the given name.
Definition: allfilters.c:629
AVClass
Describe the class of an AVClass context structure.
Definition: log.h:66
AVFilterContext::thread_type
int thread_type
Type of multithreading being allowed/used.
Definition: avfilter.h:444
avfilter_graph_config
int avfilter_graph_config(AVFilterGraph *graphctx, void *log_ctx)
Check validity and configure all the links and formats in the graph.
Definition: avfiltergraph.c:1325
avfilter_graph_segment_apply
int avfilter_graph_segment_apply(AVFilterGraphSegment *seg, int flags, AVFilterInOut **inputs, AVFilterInOut **outputs)
Apply all filter/link descriptions from a graph segment to the associated filtergraph.
Definition: graphparser.c:881
AVFilterParams
Parameters describing a filter to be created in a filtergraph.
Definition: avfilter.h:1097
AVFilter::outputs
const AVFilterPad * outputs
List of static outputs.
Definition: avfilter.h:195
avfilter_graph_set_auto_convert
void avfilter_graph_set_auto_convert(AVFilterGraph *graph, unsigned flags)
Enable or disable automatic format conversion inside the graph.
Definition: avfiltergraph.c:159
AVFilterParams::filter
AVFilterContext * filter
The filter context.
Definition: avfilter.h:1108
AVRational
Rational number (pair of numerator and denominator).
Definition: rational.h:58
AVFilterChain::nb_filters
size_t nb_filters
Definition: avfilter.h:1166
AVFilterParams::filter_name
char * filter_name
Name of the AVFilter to be used.
Definition: avfilter.h:1125
AVFilterGraph::filters
AVFilterContext ** filters
Definition: avfilter.h:832
AVFilterContext::inputs
AVFilterLink ** inputs
array of pointers to input links
Definition: avfilter.h:417
AVFilterContext::name
char * name
name of this filter instance
Definition: avfilter.h:414
avfilter_inout_alloc
AVFilterInOut * avfilter_inout_alloc(void)
Allocate a single AVFilterInOut entry.
Definition: graphparser.c:71
avfilter_graph_get_filter
AVFilterContext * avfilter_graph_get_filter(AVFilterGraph *graph, const char *name)
Get a filter instance identified by instance name from graph.
Definition: avfiltergraph.c:283
avfilter_graph_request_oldest
int avfilter_graph_request_oldest(AVFilterGraph *graph)
Request a frame on the oldest sink link.
Definition: avfiltergraph.c:1455
AVFilterGraphSegment::chains
AVFilterChain ** chains
A list of filter chain contained in this segment.
Definition: avfilter.h:1189
AVFilterGraph
Definition: avfilter.h:830
inputs
these buffered frames must be flushed immediately if a new input produces new the filter must not call request_frame to get more It must just process the frame or queue it The task of requesting more frames is left to the filter s request_frame method or the application If a filter has several inputs
Definition: filter_design.txt:243
avfilter_graph_parse2
int avfilter_graph_parse2(AVFilterGraph *graph, const char *filters, AVFilterInOut **inputs, AVFilterInOut **outputs)
Add a graph described by a string to a graph.
Definition: graphparser.c:138
AVFilterParams::nb_outputs
unsigned nb_outputs
Definition: avfilter.h:1155
AVFilterFormatsConfig
Lists of formats / etc.
Definition: avfilter.h:512
AVFilterGraphSegment
A parsed representation of a filtergraph segment.
Definition: avfilter.h:1178
AVFilterInOut::pad_idx
int pad_idx
index of the filt_ctx pad to use for linking
Definition: avfilter.h:986
AVFilterGraph::scale_sws_opts
char * scale_sws_opts
sws options to use for the auto-inserted scale filters
Definition: avfilter.h:835
options
const OptionDef options[]
AVFilterContext::nb_inputs
unsigned nb_inputs
number of input pads
Definition: avfilter.h:418
AVFilterGraph::av_class
const AVClass * av_class
Definition: avfilter.h:831
AVMediaType
AVMediaType
Definition: avutil.h:199
AVFilterContext::command_queue
struct AVFilterCommand * command_queue
Definition: avfilter.h:451
AVChannelLayout
An AVChannelLayout holds information about the channel layout of audio data.
Definition: channel_layout.h:313
AVFilterInOut::filter_ctx
AVFilterContext * filter_ctx
filter context associated to this input/output
Definition: avfilter.h:983
avfilter_execute_func
int() avfilter_execute_func(AVFilterContext *ctx, avfilter_action_func *func, void *arg, int *ret, int nb_jobs)
A function executing multiple jobs, possibly in parallel.
Definition: avfilter.h:827
AVFilter::preinit
int(* preinit)(AVFilterContext *ctx)
Filter pre-initialization function.
Definition: avfilter.h:249
avfilter_link
int avfilter_link(AVFilterContext *src, unsigned srcpad, AVFilterContext *dst, unsigned dstpad)
Link two filters together.
Definition: avfilter.c:148
avfilter_graph_queue_command
int avfilter_graph_queue_command(AVFilterGraph *graph, const char *target, const char *cmd, const char *arg, int flags, double ts)
Queue a command for one or more filter instances.
Definition: avfiltergraph.c:1373
AVFilterGraphSegment::scale_sws_opts
char * scale_sws_opts
A string containing a colon-separated list of key=value options applied to all scale filters in this ...
Definition: avfilter.h:1200
frame.h
AVFilter::description
const char * description
A description of the filter.
Definition: avfilter.h:177
avfilter_link_free
void avfilter_link_free(AVFilterLink **link)
Free the link in *link, and set its pointer to NULL.
Definition: avfilter.c:195
buffer.h
attribute_deprecated
#define attribute_deprecated
Definition: attributes.h:104
attributes.h
AVFilterFormatsConfig::color_ranges
AVFilterFormats * color_ranges
AVColorRange.
Definition: avfilter.h:533
AVFilter::nb_inputs
uint8_t nb_inputs
The number of entries in the list of inputs.
Definition: avfilter.h:223
AVFilter::init
int(* init)(AVFilterContext *ctx)
Filter initialization function.
Definition: avfilter.h:272
avfilter_init_str
int avfilter_init_str(AVFilterContext *ctx, const char *args)
Initialize a filter with the supplied parameters.
Definition: avfilter.c:933
AVFilterParams::nb_inputs
unsigned nb_inputs
Definition: avfilter.h:1152
AVFILTER_AUTO_CONVERT_NONE
@ AVFILTER_AUTO_CONVERT_NONE
all automatic conversions disabled
Definition: avfilter.h:951
AVFilter::query_func
int(* query_func)(AVFilterContext *)
Query formats supported by the filter on its inputs and outputs.
Definition: avfilter.h:326
AVFilter::formats
union AVFilter::@240 formats
The state of the following union is determined by formats_state.
log.h
AVFilterGraphSegment::graph
AVFilterGraph * graph
The filtergraph this segment is associated with.
Definition: avfilter.h:1183
avfilter_graph_parse_ptr
int avfilter_graph_parse_ptr(AVFilterGraph *graph, const char *filters, AVFilterInOut **inputs, AVFilterInOut **outputs, void *log_ctx)
Add a graph described by a string to a graph.
Definition: graphparser.c:919
AVFilterCommand
Definition: avfilter_internal.h:87
AVColorSpace
AVColorSpace
YUV colorspace type.
Definition: pixfmt.h:613
version_major.h
AVSampleFormat
AVSampleFormat
Audio sample formats.
Definition: samplefmt.h:55
AVFilterGraph::thread_type
int thread_type
Type of multithreading allowed for filters in this graph.
Definition: avfilter.h:849
filt
static const int8_t filt[NUMTAPS *2]
Definition: af_earwax.c:39
outputs
static const AVFilterPad outputs[]
Definition: af_aap.c:310
AVFilter::priv_size
int priv_size
size of private data to allocate for the filter
Definition: avfilter.h:363
AVFilter
Filter definition.
Definition: avfilter.h:166
ret
ret
Definition: filter_design.txt:187
pixfmt.h
avfilter_configuration
const char * avfilter_configuration(void)
Return the libavfilter build-time configuration.
Definition: version.c:35
AVFilterParams::opts
AVDictionary * opts
Options to be apllied to the filter.
Definition: avfilter.h:1149
avfilter_graph_dump
char * avfilter_graph_dump(AVFilterGraph *graph, const char *options)
Dump a graph into a human-readable string representation.
Definition: graphdump.c:155
dict.h
AVFilter::nb_outputs
uint8_t nb_outputs
The number of entries in the list of outputs.
Definition: avfilter.h:228
avfilter_pad_get_type
enum AVMediaType avfilter_pad_get_type(const AVFilterPad *pads, int pad_idx)
Get the type of an AVFilterPad.
Definition: avfilter.c:966
avfilter_init_dict
int avfilter_init_dict(AVFilterContext *ctx, AVDictionary **options)
Initialize a filter with the supplied dictionary of options.
Definition: avfilter.c:892
AVFilterChain
A filterchain is a list of filter specifications.
Definition: avfilter.h:1164
version.h
AVFilterContext::enable
void * enable
parsed expression (AVExpr*)
Definition: avfilter.h:454
AVFilterGraphSegment::nb_chains
size_t nb_chains
Definition: avfilter.h:1190
AVFilterContext
An instance of a filter.
Definition: avfilter.h:409
avfilter_graph_parse
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.
Definition: graphparser.c:164
avutil.h
AVBufferRef
A reference to a data buffer.
Definition: buffer.h:82
AVFilterFormatsConfig::formats
AVFilterFormats * formats
List of supported formats (pixel or sample).
Definition: avfilter.h:517
AVFilter::inputs
const AVFilterPad * inputs
List of static inputs.
Definition: avfilter.h:186
AVFilter::uninit
void(* uninit)(AVFilterContext *ctx)
Filter uninitialization function.
Definition: avfilter.h:284
avfilter_free
void avfilter_free(AVFilterContext *filter)
Free a filter context.
Definition: avfilter.c:769
AVFilter::sample_fmt
enum AVSampleFormat sample_fmt
Equivalent to { sample_fmt, AV_SAMPLE_FMT_NONE } as samples_list.
Definition: avfilter.h:360
src
INIT_CLIP pixel * src
Definition: h264pred_template.c:418
AVFilterInOut::name
char * name
unique name for this input/output in the list
Definition: avfilter.h:980
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:474
avfilter_graph_send_command
int avfilter_graph_send_command(AVFilterGraph *graph, const char *target, const char *cmd, const char *arg, char *res, int res_len, int flags)
Send a command to one or more filter instances.
Definition: avfiltergraph.c:1343
AVFilterGraphInternal
struct AVFilterGraphInternal AVFilterGraphInternal
Definition: avfilter.h:799
avfilter_graph_segment_apply_opts
int avfilter_graph_segment_apply_opts(AVFilterGraphSegment *seg, int flags)
Apply parsed options to filter instances in a graph segment.
Definition: graphparser.c:586
AVFilterGraph::nb_filters
unsigned nb_filters
Definition: avfilter.h:833
AVFilterContext::filter
const AVFilter * filter
the AVFilter of which this is an instance
Definition: avfilter.h:412
AVColorRange
AVColorRange
Visual content value range.
Definition: pixfmt.h:652
int
int
Definition: ffmpeg_filter.c:424
avfilter_version
unsigned avfilter_version(void)
Return the LIBAVFILTER_VERSION_INT constant.
Definition: version.c:29
avfilter_get_class
const AVClass * avfilter_get_class(void)
Definition: avfilter.c:1604
AVFilterInOut
A linked-list of the inputs/outputs of the filter chain.
Definition: avfilter.h:978
AVFilterContext::ready
unsigned ready
Ready status of the filter.
Definition: avfilter.h:483
AVFilterInternal
struct AVFilterInternal AVFilterInternal
Definition: avfilter.h:406
AVFilterPadParams
Parameters of a filter's input or output pad.
Definition: avfilter.h:1080
AVFilterContext::outputs
AVFilterLink ** outputs
array of pointers to output links
Definition: avfilter.h:421