FFmpeg coverage

Line	Branch	Exec	Source
1			/*
2			* Filters implementation helper functions
3			*
4			* This file is part of FFmpeg.
5			*
6			* FFmpeg is free software; you can redistribute it and/or
7			* modify it under the terms of the GNU Lesser General Public License
8			* as published by the Free Software Foundation; either
9			* version 2.1 of the License, or (at your option) any later version.
10			*
11			* FFmpeg is distributed in the hope that it will be useful,
12			* but WITHOUT ANY WARRANTY; without even the implied warranty of
13			* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14			* GNU Lesser General Public License for more details.
15			*
16			* You should have received a copy of the GNU Lesser General Public License
17			* along with FFmpeg; if not, write to the Free Software Foundation, Inc.,
18			* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19			*/
20
21			#ifndef AVFILTER_FILTERS_H
22			#define AVFILTER_FILTERS_H
23
24			/**
25			* Filters implementation helper functions and internal structures
26			*/
27
28			#include "avfilter.h"
29			#include "libavutil/pixfmt.h"
30
31			/**
32			* Special return code when activate() did not do anything.
33			*/
34			#define FFERROR_NOT_READY FFERRTAG('N','R','D','Y')
35			#define FFERROR_BUFFERSRC_EMPTY FFERRTAG('M','P','T','Y')
36
37			/**
38			* A filter pad used for either input or output.
39			*/
40			struct AVFilterPad {
41			/**
42			* Pad name. The name is unique among inputs and among outputs, but an
43			* input may have the same name as an output. This may be NULL if this
44			* pad has no need to ever be referenced by name.
45			*/
46			const char *name;
47
48			/**
49			* AVFilterPad type.
50			*/
51			enum AVMediaType type;
52
53			/**
54			* The filter expects writable frames from its input link,
55			* duplicating data buffers if needed.
56			*
57			* input pads only.
58			*/
59			#define AVFILTERPAD_FLAG_NEEDS_WRITABLE (1 << 0)
60
61			/**
62			* The pad's name is allocated and should be freed generically.
63			*/
64			#define AVFILTERPAD_FLAG_FREE_NAME (1 << 1)
65
66			/**
67			* A combination of AVFILTERPAD_FLAG_* flags.
68			*/
69			int flags;
70
71			/**
72			* Callback functions to get a video/audio buffers. If NULL,
73			* the filter system will use ff_default_get_video_buffer() for video
74			* and ff_default_get_audio_buffer() for audio.
75			*
76			* The state of the union is determined by type.
77			*
78			* Input pads only.
79			*/
80			union {
81			AVFrame *(*video)(AVFilterLink *link, int w, int h);
82			AVFrame *(*audio)(AVFilterLink *link, int nb_samples);
83			} get_buffer;
84
85			/**
86			* Filtering callback. This is where a filter receives a frame with
87			* audio/video data and should do its processing.
88			*
89			* Input pads only.
90			*
91			* @return >= 0 on success, a negative AVERROR on error. This function
92			* must ensure that frame is properly unreferenced on error if it
93			* hasn't been passed on to another filter.
94			*/
95			int (*filter_frame)(AVFilterLink *link, AVFrame *frame);
96
97			/**
98			* Frame request callback. A call to this should result in some progress
99			* towards producing output over the given link. This should return zero
100			* on success, and another value on error.
101			*
102			* Output pads only.
103			*/
104			int (*request_frame)(AVFilterLink *link);
105
106			/**
107			* Link configuration callback.
108			*
109			* For output pads, this should set the link properties such as
110			* width/height. This should NOT set the format property - that is
111			* negotiated between filters by the filter system using the
112			* query_formats() callback before this function is called.
113			*
114			* For input pads, this should check the properties of the link, and update
115			* the filter's internal state as necessary.
116			*
117			* For both input and output filters, this should return zero on success,
118			* and another value on error.
119			*/
120			int (*config_props)(AVFilterLink *link);
121			};
122
123			/**
124			* Link properties exposed to filter code, but not external callers.
125			*
126			* Cf. AVFilterLink for public properties, FilterLinkInternal for
127			* properties private to the generic layer.
128			*/
129			typedef struct FilterLink {
130			AVFilterLink pub;
131
132			/**
133			* Graph the filter belongs to.
134			*/
135			struct AVFilterGraph *graph;
136
137			/**
138			* Current timestamp of the link, as defined by the most recent
139			* frame(s), in link time_base units.
140			*/
141			int64_t current_pts;
142
143			/**
144			* Current timestamp of the link, as defined by the most recent
145			* frame(s), in AV_TIME_BASE units.
146			*/
147			int64_t current_pts_us;
148
149			/**
150			* Minimum number of samples to filter at once.
151			*
152			* May be set by the link destination filter in its config_props().
153			* If 0, all related fields are ignored.
154			*/
155			int min_samples;
156
157			/**
158			* Maximum number of samples to filter at once. If filter_frame() is
159			* called with more samples, it will split them.
160			*
161			* May be set by the link destination filter in its config_props().
162			*/
163			int max_samples;
164
165			/**
166			* Number of past frames sent through the link.
167			*/
168			int64_t frame_count_in, frame_count_out;
169
170			/**
171			* Number of past samples sent through the link.
172			*/
173			int64_t sample_count_in, sample_count_out;
174
175			/**
176			* Frame rate of the stream on the link, or 1/0 if unknown or variable.
177			*
178			* May be set by the link source filter in its config_props(); if left to
179			* 0/0, will be automatically copied from the first input of the source
180			* filter if it exists.
181			*
182			* Sources should set it to the best estimation of the real frame rate.
183			* If the source frame rate is unknown or variable, set this to 1/0.
184			* Filters should update it if necessary depending on their function.
185			* Sinks can use it to set a default output frame rate.
186			* It is similar to the r_frame_rate field in AVStream.
187			*/
188			AVRational frame_rate;
189
190			/**
191			* For hwaccel pixel formats, this should be a reference to the
192			* AVHWFramesContext describing the frames.
193			*
194			* May be set by the link source filter in its config_props().
195			*/
196			AVBufferRef *hw_frames_ctx;
197			} FilterLink;
198
199		4893903	static inline FilterLink* ff_filter_link(AVFilterLink *link)
200			{
201		4893903	return (FilterLink*)link;
202			}
203
204			/**
205			* The filter is aware of hardware frames, and any hardware frame context
206			* should not be automatically propagated through it.
207			*/
208			#define FF_FILTER_FLAG_HWFRAME_AWARE (1 << 0)
209
210			/**
211			* Find the index of a link.
212			*
213			* I.e. find i such that link == ctx->(in|out)puts[i]
214			*/
215			#define FF_INLINK_IDX(link) ((int)((link)->dstpad - (link)->dst->input_pads))
216			#define FF_OUTLINK_IDX(link) ((int)((link)->srcpad - (link)->src->output_pads))
217
218			enum FilterFormatsState {
219			/**
220			* The default value meaning that this filter supports all formats
221			* and (for audio) sample rates and channel layouts/counts as long
222			* as these properties agree for all inputs and outputs.
223			* This state is only allowed in case all inputs and outputs actually
224			* have the same type.
225			* The union is unused in this state.
226			*
227			* This value must always be zero (for default static initialization).
228			*/
229			FF_FILTER_FORMATS_PASSTHROUGH = 0,
230			FF_FILTER_FORMATS_QUERY_FUNC, ///< formats.query active.
231			FF_FILTER_FORMATS_QUERY_FUNC2, ///< formats.query_func2 active.
232			FF_FILTER_FORMATS_PIXFMT_LIST, ///< formats.pixels_list active.
233			FF_FILTER_FORMATS_SAMPLEFMTS_LIST, ///< formats.samples_list active.
234			FF_FILTER_FORMATS_SINGLE_PIXFMT, ///< formats.pix_fmt active
235			FF_FILTER_FORMATS_SINGLE_SAMPLEFMT, ///< formats.sample_fmt active.
236			};
237
238			#define FILTER_QUERY_FUNC(func) \
239			.formats.query_func = func, \
240			.formats_state = FF_FILTER_FORMATS_QUERY_FUNC
241			#define FILTER_QUERY_FUNC2(func) \
242			.formats.query_func2 = func, \
243			.formats_state = FF_FILTER_FORMATS_QUERY_FUNC2
244			#define FILTER_PIXFMTS_ARRAY(array) \
245			.formats.pixels_list = array, \
246			.formats_state = FF_FILTER_FORMATS_PIXFMT_LIST
247			#define FILTER_SAMPLEFMTS_ARRAY(array) \
248			.formats.samples_list = array, \
249			.formats_state = FF_FILTER_FORMATS_SAMPLEFMTS_LIST
250			#define FILTER_PIXFMTS(...) \
251			FILTER_PIXFMTS_ARRAY(((const enum AVPixelFormat []) { __VA_ARGS__, AV_PIX_FMT_NONE }))
252			#define FILTER_SAMPLEFMTS(...) \
253			FILTER_SAMPLEFMTS_ARRAY(((const enum AVSampleFormat[]) { __VA_ARGS__, AV_SAMPLE_FMT_NONE }))
254			#define FILTER_SINGLE_PIXFMT(pix_fmt_) \
255			.formats.pix_fmt = pix_fmt_, \
256			.formats_state = FF_FILTER_FORMATS_SINGLE_PIXFMT
257			#define FILTER_SINGLE_SAMPLEFMT(sample_fmt_) \
258			.formats.sample_fmt = sample_fmt_, \
259			.formats_state = FF_FILTER_FORMATS_SINGLE_SAMPLEFMT
260
261			#define FILTER_INOUTPADS(inout, array) \
262			.p.inout = array, \
263			.nb_ ## inout = FF_ARRAY_ELEMS(array)
264			#define FILTER_INPUTS(array) FILTER_INOUTPADS(inputs, (array))
265			#define FILTER_OUTPUTS(array) FILTER_INOUTPADS(outputs, (array))
266
267			typedef struct FFFilter {
268			/**
269			* The public AVFilter. See avfilter.h for it.
270			*/
271			AVFilter p;
272
273			/**
274			* The number of entries in the list of inputs.
275			*/
276			uint8_t nb_inputs;
277
278			/**
279			* The number of entries in the list of outputs.
280			*/
281			uint8_t nb_outputs;
282
283			/**
284			* This field determines the state of the formats union.
285			* It is an enum FilterFormatsState value.
286			*/
287			uint8_t formats_state;
288
289			/**
290			* Filter pre-initialization function
291			*
292			* This callback will be called immediately after the filter context is
293			* allocated, to allow allocating and initing sub-objects.
294			*
295			* If this callback is not NULL, the uninit callback will be called on
296			* allocation failure.
297			*
298			* @return 0 on success,
299			* AVERROR code on failure (but the code will be
300			* dropped and treated as ENOMEM by the calling code)
301			*/
302			int (*preinit)(AVFilterContext *ctx);
303
304			/**
305			* Filter initialization function.
306			*
307			* This callback will be called only once during the filter lifetime, after
308			* all the options have been set, but before links between filters are
309			* established and format negotiation is done.
310			*
311			* Basic filter initialization should be done here. Filters with dynamic
312			* inputs and/or outputs should create those inputs/outputs here based on
313			* provided options. No more changes to this filter's inputs/outputs can be
314			* done after this callback.
315			*
316			* This callback must not assume that the filter links exist or frame
317			* parameters are known.
318			*
319			* @ref AVFilter.uninit "uninit" is guaranteed to be called even if
320			* initialization fails, so this callback does not have to clean up on
321			* failure.
322			*
323			* @return 0 on success, a negative AVERROR on failure
324			*/
325			int (*init)(AVFilterContext *ctx);
326
327			/**
328			* Filter uninitialization function.
329			*
330			* Called only once right before the filter is freed. Should deallocate any
331			* memory held by the filter, release any buffer references, etc. It does
332			* not need to deallocate the AVFilterContext.priv memory itself.
333			*
334			* This callback may be called even if @ref AVFilter.init "init" was not
335			* called or failed, so it must be prepared to handle such a situation.
336			*/
337			void (*uninit)(AVFilterContext *ctx);
338
339			/**
340			* The state of the following union is determined by formats_state.
341			* See the documentation of enum FilterFormatsState in internal.h.
342			*/
343			union {
344			/**
345			* Query formats supported by the filter on its inputs and outputs.
346			*
347			* This callback is called after the filter is initialized (so the inputs
348			* and outputs are fixed), shortly before the format negotiation. This
349			* callback may be called more than once.
350			*
351			* This callback must set ::AVFilterLink's
352			* @ref AVFilterFormatsConfig.formats "outcfg.formats"
353			* on every input link and
354			* @ref AVFilterFormatsConfig.formats "incfg.formats"
355			* on every output link to a list of pixel/sample formats that the filter
356			* supports on that link.
357			* For video links, this filter may also set
358			* @ref AVFilterFormatsConfig.color_spaces "incfg.color_spaces"
359			* /
360			* @ref AVFilterFormatsConfig.color_spaces "outcfg.color_spaces"
361			* and @ref AVFilterFormatsConfig.color_ranges "incfg.color_ranges"
362			* /
363			* @ref AVFilterFormatsConfig.color_ranges "outcfg.color_ranges"
364			* analogously.
365			* For audio links, this filter must also set
366			* @ref AVFilterFormatsConfig.samplerates "incfg.samplerates"
367			* /
368			* @ref AVFilterFormatsConfig.samplerates "outcfg.samplerates"
369			* and @ref AVFilterFormatsConfig.channel_layouts "incfg.channel_layouts"
370			* /
371			* @ref AVFilterFormatsConfig.channel_layouts "outcfg.channel_layouts"
372			* analogously.
373			*
374			* This callback must never be NULL if the union is in this state.
375			*
376			* @return zero on success, a negative value corresponding to an
377			* AVERROR code otherwise
378			*/
379			int (*query_func)(AVFilterContext *);
380
381			/**
382			* Same as query_func(), except this function writes the results into
383			* provided arrays.
384			*
385			* @param cfg_in array of input format configurations with as many
386			* members as the filters has inputs (NULL when there are
387			* no inputs);
388			* @param cfg_out array of output format configurations with as many
389			* members as the filters has outputs (NULL when there
390			* are no outputs);
391			*/
392			int (*query_func2)(const AVFilterContext *,
393			struct AVFilterFormatsConfig **cfg_in,
394			struct AVFilterFormatsConfig **cfg_out);
395			/**
396			* A pointer to an array of admissible pixel formats delimited
397			* by AV_PIX_FMT_NONE. The generic code will use this list
398			* to indicate that this filter supports each of these pixel formats,
399			* provided that all inputs and outputs use the same pixel format.
400			*
401			* In addition to that the generic code will mark all inputs
402			* and all outputs as supporting all color spaces and ranges, as
403			* long as all inputs and outputs use the same color space/range.
404			*
405			* This list must never be NULL if the union is in this state.
406			* The type of all inputs and outputs of filters using this must
407			* be AVMEDIA_TYPE_VIDEO.
408			*/
409			const enum AVPixelFormat *pixels_list;
410			/**
411			* Analogous to pixels, but delimited by AV_SAMPLE_FMT_NONE
412			* and restricted to filters that only have AVMEDIA_TYPE_AUDIO
413			* inputs and outputs.
414			*
415			* In addition to that the generic code will mark all inputs
416			* and all outputs as supporting all sample rates and every
417			* channel count and channel layout, as long as all inputs
418			* and outputs use the same sample rate and channel count/layout.
419			*/
420			const enum AVSampleFormat *samples_list;
421			/**
422			* Equivalent to { pix_fmt, AV_PIX_FMT_NONE } as pixels_list.
423			*/
424			enum AVPixelFormat pix_fmt;
425			/**
426			* Equivalent to { sample_fmt, AV_SAMPLE_FMT_NONE } as samples_list.
427			*/
428			enum AVSampleFormat sample_fmt;
429			} formats;
430
431			int priv_size; ///< size of private data to allocate for the filter
432
433			int flags_internal; ///< Additional flags for avfilter internal use only.
434
435			/**
436			* Make the filter instance process a command.
437			*
438			* @param cmd the command to process, for handling simplicity all commands must be alphanumeric only
439			* @param arg the argument for the command
440			* @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.
441			* @param flags if AVFILTER_CMD_FLAG_FAST is set and the command would be
442			* time consuming then a filter should treat it like an unsupported command
443			*
444			* @returns >=0 on success otherwise an error code.
445			* AVERROR(ENOSYS) on unsupported commands
446			*/
447			int (*process_command)(AVFilterContext *, const char *cmd, const char *arg, char *res, int res_len, int flags);
448
449			/**
450			* Filter activation function.
451			*
452			* Called when any processing is needed from the filter, instead of any
453			* filter_frame and request_frame on pads.
454			*
455			* The function must examine inlinks and outlinks and perform a single
456			* step of processing. If there is nothing to do, the function must do
457			* nothing and not return an error. If more steps are or may be
458			* possible, it must use ff_filter_set_ready() to schedule another
459			* activation.
460			*/
461			int (*activate)(AVFilterContext *ctx);
462			} FFFilter;
463
464		5635657	static inline const FFFilter *fffilter(const AVFilter *f)
465			{
466		5635657	return (const FFFilter*)f;
467			}
468
469
470			#define AVFILTER_DEFINE_CLASS_EXT(name, desc, options) \
471			static const AVClass name##_class = { \
472			.class_name = desc, \
473			.item_name = av_default_item_name, \
474			.option = options, \
475			.version = LIBAVUTIL_VERSION_INT, \
476			.category = AV_CLASS_CATEGORY_FILTER, \
477			}
478			#define AVFILTER_DEFINE_CLASS(fname) \
479			AVFILTER_DEFINE_CLASS_EXT(fname, #fname, fname##_options)
480
481			#define D2TS(d) (isnan(d) ? AV_NOPTS_VALUE : (int64_t)(d))
482			#define TS2D(ts) ((ts) == AV_NOPTS_VALUE ? NAN : (double)(ts))
483			#define TS2T(ts, tb) ((ts) == AV_NOPTS_VALUE ? NAN : (double)(ts) * av_q2d(tb))
484
485			/**
486			* Mark a filter ready and schedule it for activation.
487			*
488			* This is automatically done when something happens to the filter (queued
489			* frame, status change, request on output).
490			* Filters implementing the activate callback can call it directly to
491			* perform one more round of processing later.
492			* It is also useful for filters reacting to external or asynchronous
493			* events.
494			*/
495			void ff_filter_set_ready(AVFilterContext *filter, unsigned priority);
496
497			/**
498			* Get the number of frames available on the link.
499			* @return the number of frames available in the link fifo.
500			*/
501			size_t ff_inlink_queued_frames(AVFilterLink *link);
502
503			/**
504			* Test if a frame is available on the link.
505			* @return >0 if a frame is available
506			*/
507			int ff_inlink_check_available_frame(AVFilterLink *link);
508
509
510			/***
511			* Get the number of samples available on the link.
512			* @return the number of samples available on the link.
513			*/
514			int ff_inlink_queued_samples(AVFilterLink *link);
515
516			/**
517			* Test if enough samples are available on the link.
518			* @return >0 if enough samples are available
519			* @note on EOF and error, min becomes 1
520			*/
521			int ff_inlink_check_available_samples(AVFilterLink *link, unsigned min);
522
523			/**
524			* Take a frame from the link's FIFO and update the link's stats.
525			*
526			* If ff_inlink_check_available_frame() was previously called, the
527			* preferred way of expressing it is "av_assert1(ret);" immediately after
528			* ff_inlink_consume_frame(). Negative error codes must still be checked.
529			*
530			* @note May trigger process_command() and/or update is_disabled.
531			* @return >0 if a frame is available,
532			* 0 and set rframe to NULL if no frame available,
533			* or AVERROR code
534			*/
535			int ff_inlink_consume_frame(AVFilterLink *link, AVFrame **rframe);
536
537			/**
538			* Take samples from the link's FIFO and update the link's stats.
539			*
540			* If ff_inlink_check_available_samples() was previously called, the
541			* preferred way of expressing it is "av_assert1(ret);" immediately after
542			* ff_inlink_consume_samples(). Negative error codes must still be checked.
543			*
544			* @note May trigger process_command() and/or update is_disabled.
545			* @return >0 if a frame is available,
546			* 0 and set rframe to NULL if no frame available,
547			* or AVERROR code
548			*/
549			int ff_inlink_consume_samples(AVFilterLink *link, unsigned min, unsigned max,
550			AVFrame **rframe);
551
552			/**
553			* Access a frame in the link fifo without consuming it.
554			* The first frame is numbered 0; the designated frame must exist.
555			* @return the frame at idx position in the link fifo.
556			*/
557			AVFrame *ff_inlink_peek_frame(AVFilterLink *link, size_t idx);
558
559			/**
560			* Make sure a frame is writable.
561			* This is similar to av_frame_make_writable() except it uses the link's
562			* buffer allocation callback, and therefore allows direct rendering.
563			*/
564			int ff_inlink_make_frame_writable(AVFilterLink *link, AVFrame **rframe);
565
566			/**
567			* Test and acknowledge the change of status on the link.
568			*
569			* Status means EOF or an error condition; a change from the normal (0)
570			* status to a non-zero status can be queued in a filter's input link, it
571			* becomes relevant after the frames queued in the link's FIFO are
572			* processed. This function tests if frames are still queued and if a queued
573			* status change has not yet been processed. In that case it performs basic
574			* treatment (updating the link's timestamp) and returns a positive value to
575			* let the filter do its own treatments (flushing...).
576			*
577			* Filters implementing the activate callback should call this function when
578			* they think it might succeed (usually after checking unsuccessfully for a
579			* queued frame).
580			* Filters implementing the filter_frame and request_frame callbacks do not
581			* need to call that since the same treatment happens in ff_filter_frame().
582			*
583			* @param[out] rstatus new or current status
584			* @param[out] rpts current timestamp of the link in link time base
585			* @return >0 if status changed, <0 if status already acked, 0 otherwise
586			*/
587			int ff_inlink_acknowledge_status(AVFilterLink *link, int *rstatus, int64_t *rpts);
588
589			/**
590			* Mark that a frame is wanted on the link.
591			* Unlike ff_filter_frame(), it must not be called when the link has a
592			* non-zero status, and thus does not acknowledge it.
593			* Also it cannot fail.
594			*/
595			void ff_inlink_request_frame(AVFilterLink *link);
596
597			/**
598			* Set the status on an input link.
599			* Also discard all frames in the link's FIFO.
600			*/
601			void ff_inlink_set_status(AVFilterLink *link, int status);
602
603			/**
604			* Test if a frame is wanted on an output link.
605			*/
606			int ff_outlink_frame_wanted(AVFilterLink *link);
607
608			/**
609			* Get the status on an output link.
610			*/
611			int ff_outlink_get_status(AVFilterLink *link);
612
613			/**
614			* Set the status field of a link from the source filter.
615			* The pts should reflect the timestamp of the status change,
616			* in link time base and relative to the frames timeline.
617			* In particular, for AVERROR_EOF, it should reflect the
618			* end time of the last frame.
619			*/
620			void ff_avfilter_link_set_in_status(AVFilterLink *link, int status, int64_t pts);
621
622			/**
623			* Set the status field of a link from the source filter.
624			* The pts should reflect the timestamp of the status change,
625			* in link time base and relative to the frames timeline.
626			* In particular, for AVERROR_EOF, it should reflect the
627			* end time of the last frame.
628			*/
629		10251	static inline void ff_outlink_set_status(AVFilterLink *link, int status, int64_t pts)
630			{
631		10251	ff_avfilter_link_set_in_status(link, status, pts);
632		10251	}
633
634			/**
635			* Forward the status on an output link to an input link.
636			* If the status is set, it will discard all queued frames and this macro
637			* will return immediately.
638			*/
639			#define FF_FILTER_FORWARD_STATUS_BACK(outlink, inlink) do { \
640			int ret = ff_outlink_get_status(outlink); \
641			if (ret) { \
642			ff_inlink_set_status(inlink, ret); \
643			return 0; \
644			} \
645			} while (0)
646
647			/**
648			* Forward the status on an output link to all input links.
649			* If the status is set, it will discard all queued frames and this macro
650			* will return immediately.
651			*/
652			#define FF_FILTER_FORWARD_STATUS_BACK_ALL(outlink, filter) do { \
653			int ret = ff_outlink_get_status(outlink); \
654			if (ret) { \
655			unsigned i; \
656			for (i = 0; i < filter->nb_inputs; i++) \
657			ff_inlink_set_status(filter->inputs[i], ret); \
658			return 0; \
659			} \
660			} while (0)
661
662			/**
663			* Acknowledge the status on an input link and forward it to an output link.
664			* If the status is set, this macro will return immediately.
665			*/
666			#define FF_FILTER_FORWARD_STATUS(inlink, outlink) do { \
667			int status; \
668			int64_t pts; \
669			if (ff_inlink_acknowledge_status(inlink, &status, &pts)) { \
670			ff_outlink_set_status(outlink, status, pts); \
671			return 0; \
672			} \
673			} while (0)
674
675			/**
676			* Acknowledge the status on an input link and forward it to an output link.
677			* If the status is set, this macro will return immediately.
678			*/
679			#define FF_FILTER_FORWARD_STATUS_ALL(inlink, filter) do { \
680			int status; \
681			int64_t pts; \
682			if (ff_inlink_acknowledge_status(inlink, &status, &pts)) { \
683			unsigned i; \
684			for (i = 0; i < filter->nb_outputs; i++) \
685			ff_outlink_set_status(filter->outputs[i], status, pts); \
686			return 0; \
687			} \
688			} while (0)
689
690			/**
691			* Forward the frame_wanted_out flag from an output link to an input link.
692			* If the flag is set, this macro will return immediately.
693			*/
694			#define FF_FILTER_FORWARD_WANTED(outlink, inlink) do { \
695			if (ff_outlink_frame_wanted(outlink)) { \
696			ff_inlink_request_frame(inlink); \
697			return 0; \
698			} \
699			} while (0)
700
701			/**
702			* Forward the frame_wanted_out flag from any of the output links to an input link.
703			* If the flag is set on any of the outputs, this macro will return immediately.
704			*/
705			#define FF_FILTER_FORWARD_WANTED_ANY(filter, inlink) do { \
706			for (unsigned i = 0; i < filter->nb_outputs; i++) { \
707			if (ff_outlink_frame_wanted(filter->outputs[i])) { \
708			ff_inlink_request_frame(inlink); \
709			return 0; \
710			} \
711			} \
712			} while (0)
713
714			/**
715			* Check for flow control between input and output.
716			* This is necessary for filters that may produce several output frames for
717			* a single input event, otherwise they may produce them all at once,
718			* causing excessive memory consumption.
719			*/
720			int ff_inoutlink_check_flow(AVFilterLink *inlink, AVFilterLink *outlink);
721
722			/**
723			* Perform any additional setup required for hardware frames.
724			*
725			* link->hw_frames_ctx must be set before calling this function.
726			* Inside link->hw_frames_ctx, the fields format, sw_format, width and
727			* height must be set. If dynamically allocated pools are not supported,
728			* then initial_pool_size must also be set, to the minimum hardware frame
729			* pool size necessary for the filter to work (taking into account any
730			* frames which need to stored for use in operations as appropriate). If
731			* default_pool_size is nonzero, then it will be used as the pool size if
732			* no other modification takes place (this can be used to preserve
733			* compatibility).
734			*/
735			int ff_filter_init_hw_frames(AVFilterContext *avctx, AVFilterLink *link,
736			int default_pool_size);
737
738			/**
739			* Generic processing of user supplied commands that are set
740			* in the same way as the filter options.
741			* NOTE: 'enable' option is handled separately, and not by
742			* this function.
743			*/
744			int ff_filter_process_command(AVFilterContext *ctx, const char *cmd,
745			const char *arg, char *res, int res_len, int flags);
746
747			/**
748			* Get number of threads for current filter instance.
749			* This number is always same or less than graph->nb_threads.
750			*/
751			int ff_filter_get_nb_threads(AVFilterContext *ctx) av_pure;
752
753			/**
754			* Send a frame of data to the next filter.
755			*
756			* @param link the output link over which the data is being sent
757			* @param frame a reference to the buffer of data being sent. The
758			* receiving filter will free this reference when it no longer
759			* needs it or pass it on to the next filter.
760			*
761			* @return >= 0 on success, a negative AVERROR on error. The receiving filter
762			* is responsible for unreferencing frame in case of error.
763			*/
764			int ff_filter_frame(AVFilterLink *link, AVFrame *frame);
765
766			/**
767			* Request an input frame from the filter at the other end of the link.
768			*
769			* This function must not be used by filters using the activate callback,
770			* use ff_link_set_frame_wanted() instead.
771			*
772			* The input filter may pass the request on to its inputs, fulfill the
773			* request from an internal buffer or any other means specific to its function.
774			*
775			* When the end of a stream is reached AVERROR_EOF is returned and no further
776			* frames are returned after that.
777			*
778			* When a filter is unable to output a frame for example due to its sources
779			* being unable to do so or because it depends on external means pushing data
780			* into it then AVERROR(EAGAIN) is returned.
781			* It is important that a AVERROR(EAGAIN) return is returned all the way to the
782			* caller (generally eventually a user application) as this step may (but does
783			* not have to be) necessary to provide the input with the next frame.
784			*
785			* If a request is successful then some progress has been made towards
786			* providing a frame on the link (through ff_filter_frame()). A filter that
787			* needs several frames to produce one is allowed to return success if one
788			* more frame has been processed but no output has been produced yet. A
789			* filter is also allowed to simply forward a success return value.
790			*
791			* @param link the input link
792			* @return zero on success
793			* AVERROR_EOF on end of file
794			* AVERROR(EAGAIN) if the previous filter cannot output a frame
795			* currently and can neither guarantee that EOF has been reached.
796			*/
797			int ff_request_frame(AVFilterLink *link);
798
799			/**
800			* Append a new input/output pad to the filter's list of such pads.
801			*
802			* The *_free_name versions will set the AVFILTERPAD_FLAG_FREE_NAME flag
803			* ensuring that the name will be freed generically (even on insertion error).
804			*/
805			int ff_append_inpad (AVFilterContext *f, AVFilterPad *p);
806			int ff_append_outpad(AVFilterContext *f, AVFilterPad *p);
807			int ff_append_inpad_free_name (AVFilterContext *f, AVFilterPad *p);
808			int ff_append_outpad_free_name(AVFilterContext *f, AVFilterPad *p);
809
810			/**
811			* Tell if a pixel format is contained in the provided AV_PIX_FMT_NONE-terminated list.
812			*
813			* @param fmt provided format
814			* @param fmts AV_PIX_FMT_NONE-terminated list of pixel formats
815			* @return 1 if present, 0 if absent
816			*/
817			int ff_pixfmt_is_in(enum AVPixelFormat fmt, const enum AVPixelFormat *fmts);
818
819			int ff_filter_execute(AVFilterContext *ctx, avfilter_action_func *func,
820			void *arg, int *ret, int nb_jobs);
821
822			#endif /* AVFILTER_FILTERS_H */
823