1 /*
2 * This file is part of FFmpeg.
3 *
4 * FFmpeg is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2.1 of the License, or (at your option) any later version.
8 *
9 * FFmpeg is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with FFmpeg; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17 */
18
19 #ifndef AVFILTER_INTERNAL_H
20 #define AVFILTER_INTERNAL_H
21
22 /**
23 * @file
24 * internal API functions
25 */
26
27 #include "libavutil/internal.h"
28 #include "avfilter.h"
29 #include "formats.h"
30 #include "framequeue.h"
31 #include "video.h"
32
33 typedef struct AVFilterCommand {
34 double time; ///< time expressed in seconds
35 char *command; ///< command
36 char *arg; ///< optional argument for the command
37 int flags;
38 struct AVFilterCommand *next;
39 } AVFilterCommand;
40
41 /**
42 * Update the position of a link in the age heap.
43 */
44 void ff_avfilter_graph_update_heap(AVFilterGraph *graph, AVFilterLink *link);
45
46 /**
47 * A filter pad used for either input or output.
48 */
49 struct AVFilterPad {
50 /**
51 * Pad name. The name is unique among inputs and among outputs, but an
52 * input may have the same name as an output. This may be NULL if this
53 * pad has no need to ever be referenced by name.
54 */
55 const char *name;
56
57 /**
58 * AVFilterPad type.
59 */
60 enum AVMediaType type;
61
62 /**
63 * The filter expects writable frames from its input link,
64 * duplicating data buffers if needed.
65 *
66 * input pads only.
67 */
68 #define AVFILTERPAD_FLAG_NEEDS_WRITABLE (1 << 0)
69
70 /**
71 * The pad's name is allocated and should be freed generically.
72 */
73 #define AVFILTERPAD_FLAG_FREE_NAME (1 << 1)
74
75 /**
76 * A combination of AVFILTERPAD_FLAG_* flags.
77 */
78 int flags;
79
80 /**
81 * Callback functions to get a video/audio buffers. If NULL,
82 * the filter system will use ff_default_get_video_buffer() for video
83 * and ff_default_get_audio_buffer() for audio.
84 *
85 * The state of the union is determined by type.
86 *
87 * Input pads only.
88 */
89 union {
90 AVFrame *(*video)(AVFilterLink *link, int w, int h);
91 AVFrame *(*audio)(AVFilterLink *link, int nb_samples);
92 } get_buffer;
93
94 /**
95 * Filtering callback. This is where a filter receives a frame with
96 * audio/video data and should do its processing.
97 *
98 * Input pads only.
99 *
100 * @return >= 0 on success, a negative AVERROR on error. This function
101 * must ensure that frame is properly unreferenced on error if it
102 * hasn't been passed on to another filter.
103 */
104 int (*filter_frame)(AVFilterLink *link, AVFrame *frame);
105
106 /**
107 * Frame request callback. A call to this should result in some progress
108 * towards producing output over the given link. This should return zero
109 * on success, and another value on error.
110 *
111 * Output pads only.
112 */
113 int (*request_frame)(AVFilterLink *link);
114
115 /**
116 * Link configuration callback.
117 *
118 * For output pads, this should set the link properties such as
119 * width/height. This should NOT set the format property - that is
120 * negotiated between filters by the filter system using the
121 * query_formats() callback before this function is called.
122 *
123 * For input pads, this should check the properties of the link, and update
124 * the filter's internal state as necessary.
125 *
126 * For both input and output filters, this should return zero on success,
127 * and another value on error.
128 */
129 int (*config_props)(AVFilterLink *link);
130 };
131
132 struct AVFilterGraphInternal {
133 void *thread;
134 avfilter_execute_func *thread_execute;
135 FFFrameQueueGlobal frame_queues;
136 };
137
138 struct AVFilterInternal {
139 avfilter_execute_func *execute;
140 };
141
ff_filter_execute(AVFilterContext * ctx,avfilter_action_func * func,void * arg,int * ret,int nb_jobs)142 static av_always_inline int ff_filter_execute(AVFilterContext *ctx, avfilter_action_func *func,
143 void *arg, int *ret, int nb_jobs)
144 {
145 return ctx->internal->execute(ctx, func, arg, ret, nb_jobs);
146 }
147
148 enum FilterFormatsState {
149 /**
150 * The default value meaning that this filter supports all formats
151 * and (for audio) sample rates and channel layouts/counts as long
152 * as these properties agree for all inputs and outputs.
153 * This state is only allowed in case all inputs and outputs actually
154 * have the same type.
155 * The union is unused in this state.
156 *
157 * This value must always be zero (for default static initialization).
158 */
159 FF_FILTER_FORMATS_PASSTHROUGH = 0,
160 FF_FILTER_FORMATS_QUERY_FUNC, ///< formats.query active.
161 FF_FILTER_FORMATS_PIXFMT_LIST, ///< formats.pixels_list active.
162 FF_FILTER_FORMATS_SAMPLEFMTS_LIST, ///< formats.samples_list active.
163 FF_FILTER_FORMATS_SINGLE_PIXFMT, ///< formats.pix_fmt active
164 FF_FILTER_FORMATS_SINGLE_SAMPLEFMT, ///< formats.sample_fmt active.
165 };
166
167 #define FILTER_QUERY_FUNC(func) \
168 .formats.query_func = func, \
169 .formats_state = FF_FILTER_FORMATS_QUERY_FUNC
170 #define FILTER_PIXFMTS_ARRAY(array) \
171 .formats.pixels_list = array, \
172 .formats_state = FF_FILTER_FORMATS_PIXFMT_LIST
173 #define FILTER_SAMPLEFMTS_ARRAY(array) \
174 .formats.samples_list = array, \
175 .formats_state = FF_FILTER_FORMATS_SAMPLEFMTS_LIST
176 #define FILTER_PIXFMTS(...) \
177 FILTER_PIXFMTS_ARRAY(((const enum AVPixelFormat []) { __VA_ARGS__, AV_PIX_FMT_NONE }))
178 #define FILTER_SAMPLEFMTS(...) \
179 FILTER_SAMPLEFMTS_ARRAY(((const enum AVSampleFormat[]) { __VA_ARGS__, AV_SAMPLE_FMT_NONE }))
180 #define FILTER_SINGLE_PIXFMT(pix_fmt_) \
181 .formats.pix_fmt = pix_fmt_, \
182 .formats_state = FF_FILTER_FORMATS_SINGLE_PIXFMT
183 #define FILTER_SINGLE_SAMPLEFMT(sample_fmt_) \
184 .formats.sample_fmt = sample_fmt_, \
185 .formats_state = FF_FILTER_FORMATS_SINGLE_SAMPLEFMT
186
187 #define FILTER_INOUTPADS(inout, array) \
188 .inout = array, \
189 .nb_ ## inout = FF_ARRAY_ELEMS(array)
190 #define FILTER_INPUTS(array) FILTER_INOUTPADS(inputs, (array))
191 #define FILTER_OUTPUTS(array) FILTER_INOUTPADS(outputs, (array))
192
193 /**
194 * Tell if an integer is contained in the provided -1-terminated list of integers.
195 * This is useful for determining (for instance) if an AVPixelFormat is in an
196 * array of supported formats.
197 *
198 * @param fmt provided format
199 * @param fmts -1-terminated list of formats
200 * @return 1 if present, 0 if absent
201 */
202 int ff_fmt_is_in(int fmt, const int *fmts);
203
204 /* Functions to parse audio format arguments */
205
206 /**
207 * Parse a pixel format.
208 *
209 * @param ret pixel format pointer to where the value should be written
210 * @param arg string to parse
211 * @param log_ctx log context
212 * @return >= 0 in case of success, a negative AVERROR code on error
213 */
214 av_warn_unused_result
215 int ff_parse_pixel_format(enum AVPixelFormat *ret, const char *arg, void *log_ctx);
216
217 /**
218 * Parse a sample rate.
219 *
220 * @param ret unsigned integer pointer to where the value should be written
221 * @param arg string to parse
222 * @param log_ctx log context
223 * @return >= 0 in case of success, a negative AVERROR code on error
224 */
225 av_warn_unused_result
226 int ff_parse_sample_rate(int *ret, const char *arg, void *log_ctx);
227
228 /**
229 * Parse a channel layout or a corresponding integer representation.
230 *
231 * @param ret 64bit integer pointer to where the value should be written.
232 * @param nret integer pointer to the number of channels;
233 * if not NULL, then unknown channel layouts are accepted
234 * @param arg string to parse
235 * @param log_ctx log context
236 * @return >= 0 in case of success, a negative AVERROR code on error
237 */
238 av_warn_unused_result
239 int ff_parse_channel_layout(AVChannelLayout *ret, int *nret, const char *arg,
240 void *log_ctx);
241
242 void ff_update_link_current_pts(AVFilterLink *link, int64_t pts);
243
244 /**
245 * Set the status field of a link from the source filter.
246 * The pts should reflect the timestamp of the status change,
247 * in link time base and relative to the frames timeline.
248 * In particular, for AVERROR_EOF, it should reflect the
249 * end time of the last frame.
250 */
251 void ff_avfilter_link_set_in_status(AVFilterLink *link, int status, int64_t pts);
252
253 /**
254 * Set the status field of a link from the destination filter.
255 * The pts should probably be left unset (AV_NOPTS_VALUE).
256 */
257 void ff_avfilter_link_set_out_status(AVFilterLink *link, int status, int64_t pts);
258
259 void ff_command_queue_pop(AVFilterContext *filter);
260
261 #define D2TS(d) (isnan(d) ? AV_NOPTS_VALUE : (int64_t)(d))
262 #define TS2D(ts) ((ts) == AV_NOPTS_VALUE ? NAN : (double)(ts))
263 #define TS2T(ts, tb) ((ts) == AV_NOPTS_VALUE ? NAN : (double)(ts) * av_q2d(tb))
264
265 /* misc trace functions */
266
267 #define FF_TPRINTF_START(ctx, func) ff_tlog(NULL, "%-16s: ", #func)
268
269 char *ff_get_ref_perms_string(char *buf, size_t buf_size, int perms);
270
271 void ff_tlog_link(void *ctx, AVFilterLink *link, int end);
272
273 /**
274 * Append a new input/output pad to the filter's list of such pads.
275 *
276 * The *_free_name versions will set the AVFILTERPAD_FLAG_FREE_NAME flag
277 * ensuring that the name will be freed generically (even on insertion error).
278 */
279 int ff_append_inpad (AVFilterContext *f, AVFilterPad *p);
280 int ff_append_outpad(AVFilterContext *f, AVFilterPad *p);
281 int ff_append_inpad_free_name (AVFilterContext *f, AVFilterPad *p);
282 int ff_append_outpad_free_name(AVFilterContext *f, AVFilterPad *p);
283
284 /**
285 * Request an input frame from the filter at the other end of the link.
286 *
287 * This function must not be used by filters using the activate callback,
288 * use ff_link_set_frame_wanted() instead.
289 *
290 * The input filter may pass the request on to its inputs, fulfill the
291 * request from an internal buffer or any other means specific to its function.
292 *
293 * When the end of a stream is reached AVERROR_EOF is returned and no further
294 * frames are returned after that.
295 *
296 * When a filter is unable to output a frame for example due to its sources
297 * being unable to do so or because it depends on external means pushing data
298 * into it then AVERROR(EAGAIN) is returned.
299 * It is important that a AVERROR(EAGAIN) return is returned all the way to the
300 * caller (generally eventually a user application) as this step may (but does
301 * not have to be) necessary to provide the input with the next frame.
302 *
303 * If a request is successful then some progress has been made towards
304 * providing a frame on the link (through ff_filter_frame()). A filter that
305 * needs several frames to produce one is allowed to return success if one
306 * more frame has been processed but no output has been produced yet. A
307 * filter is also allowed to simply forward a success return value.
308 *
309 * @param link the input link
310 * @return zero on success
311 * AVERROR_EOF on end of file
312 * AVERROR(EAGAIN) if the previous filter cannot output a frame
313 * currently and can neither guarantee that EOF has been reached.
314 */
315 int ff_request_frame(AVFilterLink *link);
316
317 #define AVFILTER_DEFINE_CLASS_EXT(name, desc, options) \
318 static const AVClass name##_class = { \
319 .class_name = desc, \
320 .item_name = av_default_item_name, \
321 .option = options, \
322 .version = LIBAVUTIL_VERSION_INT, \
323 .category = AV_CLASS_CATEGORY_FILTER, \
324 }
325 #define AVFILTER_DEFINE_CLASS(fname) \
326 AVFILTER_DEFINE_CLASS_EXT(fname, #fname, fname##_options)
327
328 /**
329 * Find the index of a link.
330 *
331 * I.e. find i such that link == ctx->(in|out)puts[i]
332 */
333 #define FF_INLINK_IDX(link) ((int)((link)->dstpad - (link)->dst->input_pads))
334 #define FF_OUTLINK_IDX(link) ((int)((link)->srcpad - (link)->src->output_pads))
335
336 /**
337 * Send a frame of data to the next filter.
338 *
339 * @param link the output link over which the data is being sent
340 * @param frame a reference to the buffer of data being sent. The
341 * receiving filter will free this reference when it no longer
342 * needs it or pass it on to the next filter.
343 *
344 * @return >= 0 on success, a negative AVERROR on error. The receiving filter
345 * is responsible for unreferencing frame in case of error.
346 */
347 int ff_filter_frame(AVFilterLink *link, AVFrame *frame);
348
349 /**
350 * Allocate a new filter context and return it.
351 *
352 * @param filter what filter to create an instance of
353 * @param inst_name name to give to the new filter context
354 *
355 * @return newly created filter context or NULL on failure
356 */
357 AVFilterContext *ff_filter_alloc(const AVFilter *filter, const char *inst_name);
358
359 int ff_filter_activate(AVFilterContext *filter);
360
361 /**
362 * Remove a filter from a graph;
363 */
364 void ff_filter_graph_remove_filter(AVFilterGraph *graph, AVFilterContext *filter);
365
366 /**
367 * The filter is aware of hardware frames, and any hardware frame context
368 * should not be automatically propagated through it.
369 */
370 #define FF_FILTER_FLAG_HWFRAME_AWARE (1 << 0)
371
372 /**
373 * Run one round of processing on a filter graph.
374 */
375 int ff_filter_graph_run_once(AVFilterGraph *graph);
376
377 /**
378 * Get number of threads for current filter instance.
379 * This number is always same or less than graph->nb_threads.
380 */
381 int ff_filter_get_nb_threads(AVFilterContext *ctx) av_pure;
382
383 /**
384 * Generic processing of user supplied commands that are set
385 * in the same way as the filter options.
386 * NOTE: 'enable' option is handled separately, and not by
387 * this function.
388 */
389 int ff_filter_process_command(AVFilterContext *ctx, const char *cmd,
390 const char *arg, char *res, int res_len, int flags);
391
392 /**
393 * Perform any additional setup required for hardware frames.
394 *
395 * link->hw_frames_ctx must be set before calling this function.
396 * Inside link->hw_frames_ctx, the fields format, sw_format, width and
397 * height must be set. If dynamically allocated pools are not supported,
398 * then initial_pool_size must also be set, to the minimum hardware frame
399 * pool size necessary for the filter to work (taking into account any
400 * frames which need to stored for use in operations as appropriate). If
401 * default_pool_size is nonzero, then it will be used as the pool size if
402 * no other modification takes place (this can be used to preserve
403 * compatibility).
404 */
405 int ff_filter_init_hw_frames(AVFilterContext *avctx, AVFilterLink *link,
406 int default_pool_size);
407
408 #endif /* AVFILTER_INTERNAL_H */
409