FFmpeg coverage


Directory: ../../../ffmpeg/
File: src/libavfilter/filters.h
Date: 2025-07-28 20:30:09
Exec Total Coverage
Lines: 7 7 100.0%
Functions: 3 3 100.0%
Branches: 0 0 -%

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