FFmpeg
filters.h
Go to the documentation of this file.
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
26  */
27 
28 #include "avfilter.h"
29 #include "internal.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 
36 /**
37  * Mark a filter ready and schedule it for activation.
38  *
39  * This is automatically done when something happens to the filter (queued
40  * frame, status change, request on output).
41  * Filters implementing the activate callback can call it directly to
42  * perform one more round of processing later.
43  * It is also useful for filters reacting to external or asynchronous
44  * events.
45  */
46 void ff_filter_set_ready(AVFilterContext *filter, unsigned priority);
47 
48 /**
49  * Process the commands queued in the link up to the time of the frame.
50  * Commands will trigger the process_command() callback.
51  * @return >= 0 or AVERROR code.
52  */
54 
55 /**
56  * Evaluate the timeline expression of the link for the time and properties
57  * of the frame.
58  * @return >0 if enabled, 0 if disabled
59  * @note It does not update link->dst->is_disabled.
60  */
62 
63 /**
64  * Get the number of frames available on the link.
65  * @return the number of frames available in the link fifo.
66  */
68 
69 /**
70  * Test if a frame is available on the link.
71  * @return >0 if a frame is available
72  */
74 
75 
76 /***
77  * Get the number of samples available on the link.
78  * @return the numer of samples available on the link.
79  */
81 
82 /**
83  * Test if enough samples are available on the link.
84  * @return >0 if enough samples are available
85  * @note on EOF and error, min becomes 1
86  */
88 
89 /**
90  * Take a frame from the link's FIFO and update the link's stats.
91  *
92  * If ff_inlink_check_available_frame() was previously called, the
93  * preferred way of expressing it is "av_assert1(ret);" immediately after
94  * ff_inlink_consume_frame(). Negative error codes must still be checked.
95  *
96  * @note May trigger process_command() and/or update is_disabled.
97  * @return >0 if a frame is available,
98  * 0 and set rframe to NULL if no frame available,
99  * or AVERROR code
100  */
102 
103 /**
104  * Take samples from the link's FIFO and update the link's stats.
105  *
106  * If ff_inlink_check_available_samples() was previously called, the
107  * preferred way of expressing it is "av_assert1(ret);" immediately after
108  * ff_inlink_consume_samples(). Negative error codes must still be checked.
109  *
110  * @note May trigger process_command() and/or update is_disabled.
111  * @return >0 if a frame is available,
112  * 0 and set rframe to NULL if no frame available,
113  * or AVERROR code
114  */
115 int ff_inlink_consume_samples(AVFilterLink *link, unsigned min, unsigned max,
116  AVFrame **rframe);
117 
118 /**
119  * Access a frame in the link fifo without consuming it.
120  * The first frame is numbered 0; the designated frame must exist.
121  * @return the frame at idx position in the link fifo.
122  */
124 
125 /**
126  * Make sure a frame is writable.
127  * This is similar to av_frame_make_writable() except it uses the link's
128  * buffer allocation callback, and therefore allows direct rendering.
129  */
131 
132 /**
133  * Test and acknowledge the change of status on the link.
134  *
135  * Status means EOF or an error condition; a change from the normal (0)
136  * status to a non-zero status can be queued in a filter's input link, it
137  * becomes relevant after the frames queued in the link's FIFO are
138  * processed. This function tests if frames are still queued and if a queued
139  * status change has not yet been processed. In that case it performs basic
140  * treatment (updating the link's timestamp) and returns a positive value to
141  * let the filter do its own treatments (flushing...).
142  *
143  * Filters implementing the activate callback should call this function when
144  * they think it might succeed (usually after checking unsuccessfully for a
145  * queued frame).
146  * Filters implementing the filter_frame and request_frame callbacks do not
147  * need to call that since the same treatment happens in ff_filter_frame().
148  *
149  * @param[out] rstatus new or current status
150  * @param[out] rpts current timestamp of the link in link time base
151  * @return >0 if status changed, <0 if status already acked, 0 otherwise
152  */
153 int ff_inlink_acknowledge_status(AVFilterLink *link, int *rstatus, int64_t *rpts);
154 
155 /**
156  * Mark that a frame is wanted on the link.
157  * Unlike ff_filter_frame(), it must not be called when the link has a
158  * non-zero status, and thus does not acknowledge it.
159  * Also it cannot fail.
160  */
162 
163 /**
164  * Set the status on an input link.
165  * Also discard all frames in the link's FIFO.
166  */
168 
169 /**
170  * Test if a frame is wanted on an output link.
171  */
173 {
174  return link->frame_wanted_out;
175 }
176 
177 /**
178  * Get the status on an output link.
179  */
181 
182 /**
183  * Set the status field of a link from the source filter.
184  * The pts should reflect the timestamp of the status change,
185  * in link time base and relative to the frames timeline.
186  * In particular, for AVERROR_EOF, it should reflect the
187  * end time of the last frame.
188  */
189 static inline void ff_outlink_set_status(AVFilterLink *link, int status, int64_t pts)
190 {
192 }
193 
194 /**
195  * Forward the status on an output link to an input link.
196  * If the status is set, it will discard all queued frames and this macro
197  * will return immediately.
198  */
199 #define FF_FILTER_FORWARD_STATUS_BACK(outlink, inlink) do { \
200  int ret = ff_outlink_get_status(outlink); \
201  if (ret) { \
202  ff_inlink_set_status(inlink, ret); \
203  return 0; \
204  } \
205 } while (0)
206 
207 /**
208  * Forward the status on an output link to all input links.
209  * If the status is set, it will discard all queued frames and this macro
210  * will return immediately.
211  */
212 #define FF_FILTER_FORWARD_STATUS_BACK_ALL(outlink, filter) do { \
213  int ret = ff_outlink_get_status(outlink); \
214  if (ret) { \
215  unsigned i; \
216  for (i = 0; i < filter->nb_inputs; i++) \
217  ff_inlink_set_status(filter->inputs[i], ret); \
218  return 0; \
219  } \
220 } while (0)
221 
222 /**
223  * Acknowledge the status on an input link and forward it to an output link.
224  * If the status is set, this macro will return immediately.
225  */
226 #define FF_FILTER_FORWARD_STATUS(inlink, outlink) do { \
227  int status; \
228  int64_t pts; \
229  if (ff_inlink_acknowledge_status(inlink, &status, &pts)) { \
230  ff_outlink_set_status(outlink, status, pts); \
231  return 0; \
232  } \
233 } while (0)
234 
235 /**
236  * Acknowledge the status on an input link and forward it to an output link.
237  * If the status is set, this macro will return immediately.
238  */
239 #define FF_FILTER_FORWARD_STATUS_ALL(inlink, filter) do { \
240  int status; \
241  int64_t pts; \
242  if (ff_inlink_acknowledge_status(inlink, &status, &pts)) { \
243  unsigned i; \
244  for (i = 0; i < filter->nb_outputs; i++) \
245  ff_outlink_set_status(filter->outputs[i], status, pts); \
246  return 0; \
247  } \
248 } while (0)
249 
250 /**
251  * Forward the frame_wanted_out flag from an output link to an input link.
252  * If the flag is set, this macro will return immediately.
253  */
254 #define FF_FILTER_FORWARD_WANTED(outlink, inlink) do { \
255  if (ff_outlink_frame_wanted(outlink)) { \
256  ff_inlink_request_frame(inlink); \
257  return 0; \
258  } \
259 } while (0)
260 
261 /**
262  * Check for flow control between input and output.
263  * This is necessary for filters that may produce several output frames for
264  * a single input event, otherwise they may produce them all at once,
265  * causing excessive memory consumption.
266  */
268 
269 #endif /* AVFILTER_FILTERS_H */
ff_inlink_evaluate_timeline_at_frame
int ff_inlink_evaluate_timeline_at_frame(AVFilterLink *link, const AVFrame *frame)
Evaluate the timeline expression of the link for the time and properties of the frame.
Definition: avfilter.c:1493
status
they must not be accessed directly The fifo field contains the frames that are queued in the input for processing by the filter The status_in and status_out fields contains the queued status(EOF or error) of the link
ff_inlink_make_frame_writable
int ff_inlink_make_frame_writable(AVFilterLink *link, AVFrame **rframe)
Make sure a frame is writable.
Definition: avfilter.c:1438
ff_filter_set_ready
void ff_filter_set_ready(AVFilterContext *filter, unsigned priority)
Mark a filter ready and schedule it for activation.
Definition: avfilter.c:191
ff_inlink_check_available_samples
int ff_inlink_check_available_samples(AVFilterLink *link, unsigned min)
Test if enough samples are available on the link.
Definition: avfilter.c:1378
ff_inoutlink_check_flow
int ff_inoutlink_check_flow(AVFilterLink *inlink, AVFilterLink *outlink)
Check for flow control between input and output.
Definition: avfilter.c:1539
inlink
The exact code depends on how similar the blocks are and how related they are to the and needs to apply these operations to the correct inlink or outlink if there are several Macros are available to factor that when no extra processing is inlink
Definition: filter_design.txt:212
AVFrame
This structure describes decoded (raw) audio or video data.
Definition: frame.h:325
max
#define max(a, b)
Definition: cuda_runtime.h:33
filter
filter_frame For filters that do not use the this method is called when a frame is pushed to the filter s input It can be called at any time except in a reentrant way If the input frame is enough to produce then the filter should push the output frames on the output link immediately As an exception to the previous rule if the input frame is enough to produce several output frames then the filter needs output only at least one per link The additional frames can be left buffered in the filter
Definition: filter_design.txt:228
ff_inlink_peek_frame
AVFrame * ff_inlink_peek_frame(AVFilterLink *link, size_t idx)
Access a frame in the link fifo without consuming it.
Definition: avfilter.c:1433
ff_outlink_frame_wanted
static int ff_outlink_frame_wanted(AVFilterLink *link)
Test if a frame is wanted on an output link.
Definition: filters.h:172
pts
static int64_t pts
Definition: transcode_aac.c:654
ff_outlink_set_status
static void ff_outlink_set_status(AVFilterLink *link, int status, int64_t pts)
Set the status field of a link from the source filter.
Definition: filters.h:189
link
Filter the word “frame” indicates either a video frame or a group of audio as stored in an AVFrame structure Format for each input and each output the list of supported formats For video that means pixel format For audio that means channel sample they are references to shared objects When the negotiation mechanism computes the intersection of the formats supported at each end of a link
Definition: filter_design.txt:23
ff_inlink_acknowledge_status
int ff_inlink_acknowledge_status(AVFilterLink *link, int *rstatus, int64_t *rpts)
Test and acknowledge the change of status on the link.
Definition: avfilter.c:1348
ff_inlink_queued_samples
int ff_inlink_queued_samples(AVFilterLink *link)
Definition: avfilter.c:1373
ff_inlink_consume_frame
int ff_inlink_consume_frame(AVFilterLink *link, AVFrame **rframe)
Take a frame from the link's FIFO and update the link's stats.
Definition: avfilter.c:1394
internal.h
ff_avfilter_link_set_in_status
void ff_avfilter_link_set_in_status(AVFilterLink *link, int status, int64_t pts)
Set the status field of a link from the source filter.
Definition: avfilter.c:209
frame
these buffered frames must be flushed immediately if a new input produces new the filter must not call request_frame to get more It must just process the frame or queue it The task of requesting more frames is left to the filter s request_frame method or the application If a filter has several the filter must be ready for frames arriving randomly on any input any filter with several inputs will most likely require some kind of queuing mechanism It is perfectly acceptable to have a limited queue and to drop frames when the inputs are too unbalanced request_frame For filters that do not use the this method is called when a frame is wanted on an output For a it should directly call filter_frame on the corresponding output For a if there are queued frames already one of these frames should be pushed If the filter should request a frame on one of its repeatedly until at least one frame has been pushed Return or at least make progress towards producing a frame
Definition: filter_design.txt:264
ff_inlink_check_available_frame
int ff_inlink_check_available_frame(AVFilterLink *link)
Test if a frame is available on the link.
Definition: avfilter.c:1368
ff_inlink_queued_frames
size_t ff_inlink_queued_frames(AVFilterLink *link)
Get the number of frames available on the link.
Definition: avfilter.c:1363
ff_outlink_get_status
int ff_outlink_get_status(AVFilterLink *link)
Get the status on an output link.
Definition: avfilter.c:1534
ff_inlink_request_frame
void ff_inlink_request_frame(AVFilterLink *link)
Mark that a frame is wanted on the link.
Definition: avfilter.c:1511
avfilter.h
ff_inlink_set_status
void ff_inlink_set_status(AVFilterLink *link, int status)
Set the status on an input link.
Definition: avfilter.c:1519
AVFilterContext
An instance of a filter.
Definition: avfilter.h:408
ff_inlink_process_commands
int ff_inlink_process_commands(AVFilterLink *link, const AVFrame *frame)
Process the commands queued in the link up to the time of the frame.
Definition: avfilter.c:1478
ff_inlink_consume_samples
int ff_inlink_consume_samples(AVFilterLink *link, unsigned min, unsigned max, AVFrame **rframe)
Take samples from the link's FIFO and update the link's stats.
Definition: avfilter.c:1413
min
float min
Definition: vorbis_enc_data.h:429