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