Commit | Line | Data |
---|---|---|
2ba45a60 DM |
1 | /* |
2 | * filter layer | |
3 | * Copyright (c) 2007 Bobby Bingham | |
4 | * | |
5 | * This file is part of FFmpeg. | |
6 | * | |
7 | * FFmpeg is free software; you can redistribute it and/or | |
8 | * modify it under the terms of the GNU Lesser General Public | |
9 | * License as published by the Free Software Foundation; either | |
10 | * version 2.1 of the License, or (at your option) any later version. | |
11 | * | |
12 | * FFmpeg is distributed in the hope that it will be useful, | |
13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
15 | * Lesser General Public License for more details. | |
16 | * | |
17 | * You should have received a copy of the GNU Lesser General Public | |
18 | * License along with FFmpeg; if not, write to the Free Software | |
19 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | |
20 | */ | |
21 | ||
22 | #ifndef AVFILTER_AVFILTER_H | |
23 | #define AVFILTER_AVFILTER_H | |
24 | ||
25 | /** | |
26 | * @file | |
27 | * @ingroup lavfi | |
28 | * Main libavfilter public API header | |
29 | */ | |
30 | ||
31 | /** | |
32 | * @defgroup lavfi Libavfilter - graph-based frame editing library | |
33 | * @{ | |
34 | */ | |
35 | ||
36 | #include <stddef.h> | |
37 | ||
38 | #include "libavutil/attributes.h" | |
39 | #include "libavutil/avutil.h" | |
40 | #include "libavutil/dict.h" | |
41 | #include "libavutil/frame.h" | |
42 | #include "libavutil/log.h" | |
43 | #include "libavutil/samplefmt.h" | |
44 | #include "libavutil/pixfmt.h" | |
45 | #include "libavutil/rational.h" | |
46 | ||
47 | #include "libavfilter/version.h" | |
48 | ||
49 | /** | |
50 | * Return the LIBAVFILTER_VERSION_INT constant. | |
51 | */ | |
52 | unsigned avfilter_version(void); | |
53 | ||
54 | /** | |
55 | * Return the libavfilter build-time configuration. | |
56 | */ | |
57 | const char *avfilter_configuration(void); | |
58 | ||
59 | /** | |
60 | * Return the libavfilter license. | |
61 | */ | |
62 | const char *avfilter_license(void); | |
63 | ||
64 | typedef struct AVFilterContext AVFilterContext; | |
65 | typedef struct AVFilterLink AVFilterLink; | |
66 | typedef struct AVFilterPad AVFilterPad; | |
67 | typedef struct AVFilterFormats AVFilterFormats; | |
68 | ||
69 | #if FF_API_AVFILTERBUFFER | |
70 | /** | |
71 | * A reference-counted buffer data type used by the filter system. Filters | |
72 | * should not store pointers to this structure directly, but instead use the | |
73 | * AVFilterBufferRef structure below. | |
74 | */ | |
75 | typedef struct AVFilterBuffer { | |
76 | uint8_t *data[8]; ///< buffer data for each plane/channel | |
77 | ||
78 | /** | |
79 | * pointers to the data planes/channels. | |
80 | * | |
81 | * For video, this should simply point to data[]. | |
82 | * | |
83 | * For planar audio, each channel has a separate data pointer, and | |
84 | * linesize[0] contains the size of each channel buffer. | |
85 | * For packed audio, there is just one data pointer, and linesize[0] | |
86 | * contains the total size of the buffer for all channels. | |
87 | * | |
88 | * Note: Both data and extended_data will always be set, but for planar | |
89 | * audio with more channels that can fit in data, extended_data must be used | |
90 | * in order to access all channels. | |
91 | */ | |
92 | uint8_t **extended_data; | |
93 | int linesize[8]; ///< number of bytes per line | |
94 | ||
95 | /** private data to be used by a custom free function */ | |
96 | void *priv; | |
97 | /** | |
98 | * A pointer to the function to deallocate this buffer if the default | |
99 | * function is not sufficient. This could, for example, add the memory | |
100 | * back into a memory pool to be reused later without the overhead of | |
101 | * reallocating it from scratch. | |
102 | */ | |
103 | void (*free)(struct AVFilterBuffer *buf); | |
104 | ||
105 | int format; ///< media format | |
106 | int w, h; ///< width and height of the allocated buffer | |
107 | unsigned refcount; ///< number of references to this buffer | |
108 | } AVFilterBuffer; | |
109 | ||
110 | #define AV_PERM_READ 0x01 ///< can read from the buffer | |
111 | #define AV_PERM_WRITE 0x02 ///< can write to the buffer | |
112 | #define AV_PERM_PRESERVE 0x04 ///< nobody else can overwrite the buffer | |
113 | #define AV_PERM_REUSE 0x08 ///< can output the buffer multiple times, with the same contents each time | |
114 | #define AV_PERM_REUSE2 0x10 ///< can output the buffer multiple times, modified each time | |
115 | #define AV_PERM_NEG_LINESIZES 0x20 ///< the buffer requested can have negative linesizes | |
116 | #define AV_PERM_ALIGN 0x40 ///< the buffer must be aligned | |
117 | ||
118 | #define AVFILTER_ALIGN 16 //not part of ABI | |
119 | ||
120 | /** | |
121 | * Audio specific properties in a reference to an AVFilterBuffer. Since | |
122 | * AVFilterBufferRef is common to different media formats, audio specific | |
123 | * per reference properties must be separated out. | |
124 | */ | |
125 | typedef struct AVFilterBufferRefAudioProps { | |
126 | uint64_t channel_layout; ///< channel layout of audio buffer | |
127 | int nb_samples; ///< number of audio samples per channel | |
128 | int sample_rate; ///< audio buffer sample rate | |
129 | int channels; ///< number of channels (do not access directly) | |
130 | } AVFilterBufferRefAudioProps; | |
131 | ||
132 | /** | |
133 | * Video specific properties in a reference to an AVFilterBuffer. Since | |
134 | * AVFilterBufferRef is common to different media formats, video specific | |
135 | * per reference properties must be separated out. | |
136 | */ | |
137 | typedef struct AVFilterBufferRefVideoProps { | |
138 | int w; ///< image width | |
139 | int h; ///< image height | |
140 | AVRational sample_aspect_ratio; ///< sample aspect ratio | |
141 | int interlaced; ///< is frame interlaced | |
142 | int top_field_first; ///< field order | |
143 | enum AVPictureType pict_type; ///< picture type of the frame | |
144 | int key_frame; ///< 1 -> keyframe, 0-> not | |
145 | int qp_table_linesize; ///< qp_table stride | |
146 | int qp_table_size; ///< qp_table size | |
147 | int8_t *qp_table; ///< array of Quantization Parameters | |
148 | } AVFilterBufferRefVideoProps; | |
149 | ||
150 | /** | |
151 | * A reference to an AVFilterBuffer. Since filters can manipulate the origin of | |
152 | * a buffer to, for example, crop image without any memcpy, the buffer origin | |
153 | * and dimensions are per-reference properties. Linesize is also useful for | |
154 | * image flipping, frame to field filters, etc, and so is also per-reference. | |
155 | * | |
156 | * TODO: add anything necessary for frame reordering | |
157 | */ | |
158 | typedef struct AVFilterBufferRef { | |
159 | AVFilterBuffer *buf; ///< the buffer that this is a reference to | |
160 | uint8_t *data[8]; ///< picture/audio data for each plane | |
161 | /** | |
162 | * pointers to the data planes/channels. | |
163 | * | |
164 | * For video, this should simply point to data[]. | |
165 | * | |
166 | * For planar audio, each channel has a separate data pointer, and | |
167 | * linesize[0] contains the size of each channel buffer. | |
168 | * For packed audio, there is just one data pointer, and linesize[0] | |
169 | * contains the total size of the buffer for all channels. | |
170 | * | |
171 | * Note: Both data and extended_data will always be set, but for planar | |
172 | * audio with more channels that can fit in data, extended_data must be used | |
173 | * in order to access all channels. | |
174 | */ | |
175 | uint8_t **extended_data; | |
176 | int linesize[8]; ///< number of bytes per line | |
177 | ||
178 | AVFilterBufferRefVideoProps *video; ///< video buffer specific properties | |
179 | AVFilterBufferRefAudioProps *audio; ///< audio buffer specific properties | |
180 | ||
181 | /** | |
182 | * presentation timestamp. The time unit may change during | |
183 | * filtering, as it is specified in the link and the filter code | |
184 | * may need to rescale the PTS accordingly. | |
185 | */ | |
186 | int64_t pts; | |
187 | int64_t pos; ///< byte position in stream, -1 if unknown | |
188 | ||
189 | int format; ///< media format | |
190 | ||
191 | int perms; ///< permissions, see the AV_PERM_* flags | |
192 | ||
193 | enum AVMediaType type; ///< media type of buffer data | |
194 | ||
195 | AVDictionary *metadata; ///< dictionary containing metadata key=value tags | |
196 | } AVFilterBufferRef; | |
197 | ||
198 | /** | |
199 | * Copy properties of src to dst, without copying the actual data | |
200 | */ | |
201 | attribute_deprecated | |
202 | void avfilter_copy_buffer_ref_props(AVFilterBufferRef *dst, const AVFilterBufferRef *src); | |
203 | ||
204 | /** | |
205 | * Add a new reference to a buffer. | |
206 | * | |
207 | * @param ref an existing reference to the buffer | |
208 | * @param pmask a bitmask containing the allowable permissions in the new | |
209 | * reference | |
210 | * @return a new reference to the buffer with the same properties as the | |
211 | * old, excluding any permissions denied by pmask | |
212 | */ | |
213 | attribute_deprecated | |
214 | AVFilterBufferRef *avfilter_ref_buffer(AVFilterBufferRef *ref, int pmask); | |
215 | ||
216 | /** | |
217 | * Remove a reference to a buffer. If this is the last reference to the | |
218 | * buffer, the buffer itself is also automatically freed. | |
219 | * | |
220 | * @param ref reference to the buffer, may be NULL | |
221 | * | |
222 | * @note it is recommended to use avfilter_unref_bufferp() instead of this | |
223 | * function | |
224 | */ | |
225 | attribute_deprecated | |
226 | void avfilter_unref_buffer(AVFilterBufferRef *ref); | |
227 | ||
228 | /** | |
229 | * Remove a reference to a buffer and set the pointer to NULL. | |
230 | * If this is the last reference to the buffer, the buffer itself | |
231 | * is also automatically freed. | |
232 | * | |
233 | * @param ref pointer to the buffer reference | |
234 | */ | |
235 | attribute_deprecated | |
236 | void avfilter_unref_bufferp(AVFilterBufferRef **ref); | |
237 | #endif | |
238 | ||
239 | /** | |
240 | * Get the number of channels of a buffer reference. | |
241 | */ | |
242 | attribute_deprecated | |
243 | int avfilter_ref_get_channels(AVFilterBufferRef *ref); | |
244 | ||
245 | #if FF_API_AVFILTERPAD_PUBLIC | |
246 | /** | |
247 | * A filter pad used for either input or output. | |
248 | * | |
249 | * See doc/filter_design.txt for details on how to implement the methods. | |
250 | * | |
251 | * @warning this struct might be removed from public API. | |
252 | * users should call avfilter_pad_get_name() and avfilter_pad_get_type() | |
253 | * to access the name and type fields; there should be no need to access | |
254 | * any other fields from outside of libavfilter. | |
255 | */ | |
256 | struct AVFilterPad { | |
257 | /** | |
258 | * Pad name. The name is unique among inputs and among outputs, but an | |
259 | * input may have the same name as an output. This may be NULL if this | |
260 | * pad has no need to ever be referenced by name. | |
261 | */ | |
262 | const char *name; | |
263 | ||
264 | /** | |
265 | * AVFilterPad type. | |
266 | */ | |
267 | enum AVMediaType type; | |
268 | ||
269 | /** | |
270 | * Input pads: | |
271 | * Minimum required permissions on incoming buffers. Any buffer with | |
272 | * insufficient permissions will be automatically copied by the filter | |
273 | * system to a new buffer which provides the needed access permissions. | |
274 | * | |
275 | * Output pads: | |
276 | * Guaranteed permissions on outgoing buffers. Any buffer pushed on the | |
277 | * link must have at least these permissions; this fact is checked by | |
278 | * asserts. It can be used to optimize buffer allocation. | |
279 | */ | |
280 | attribute_deprecated int min_perms; | |
281 | ||
282 | /** | |
283 | * Input pads: | |
284 | * Permissions which are not accepted on incoming buffers. Any buffer | |
285 | * which has any of these permissions set will be automatically copied | |
286 | * by the filter system to a new buffer which does not have those | |
287 | * permissions. This can be used to easily disallow buffers with | |
288 | * AV_PERM_REUSE. | |
289 | * | |
290 | * Output pads: | |
291 | * Permissions which are automatically removed on outgoing buffers. It | |
292 | * can be used to optimize buffer allocation. | |
293 | */ | |
294 | attribute_deprecated int rej_perms; | |
295 | ||
296 | /** | |
297 | * @deprecated unused | |
298 | */ | |
299 | int (*start_frame)(AVFilterLink *link, AVFilterBufferRef *picref); | |
300 | ||
301 | /** | |
302 | * Callback function to get a video buffer. If NULL, the filter system will | |
303 | * use ff_default_get_video_buffer(). | |
304 | * | |
305 | * Input video pads only. | |
306 | */ | |
307 | AVFrame *(*get_video_buffer)(AVFilterLink *link, int w, int h); | |
308 | ||
309 | /** | |
310 | * Callback function to get an audio buffer. If NULL, the filter system will | |
311 | * use ff_default_get_audio_buffer(). | |
312 | * | |
313 | * Input audio pads only. | |
314 | */ | |
315 | AVFrame *(*get_audio_buffer)(AVFilterLink *link, int nb_samples); | |
316 | ||
317 | /** | |
318 | * @deprecated unused | |
319 | */ | |
320 | int (*end_frame)(AVFilterLink *link); | |
321 | ||
322 | /** | |
323 | * @deprecated unused | |
324 | */ | |
325 | int (*draw_slice)(AVFilterLink *link, int y, int height, int slice_dir); | |
326 | ||
327 | /** | |
328 | * Filtering callback. This is where a filter receives a frame with | |
329 | * audio/video data and should do its processing. | |
330 | * | |
331 | * Input pads only. | |
332 | * | |
333 | * @return >= 0 on success, a negative AVERROR on error. This function | |
334 | * must ensure that frame is properly unreferenced on error if it | |
335 | * hasn't been passed on to another filter. | |
336 | */ | |
337 | int (*filter_frame)(AVFilterLink *link, AVFrame *frame); | |
338 | ||
339 | /** | |
340 | * Frame poll callback. This returns the number of immediately available | |
341 | * samples. It should return a positive value if the next request_frame() | |
342 | * is guaranteed to return one frame (with no delay). | |
343 | * | |
344 | * Defaults to just calling the source poll_frame() method. | |
345 | * | |
346 | * Output pads only. | |
347 | */ | |
348 | int (*poll_frame)(AVFilterLink *link); | |
349 | ||
350 | /** | |
351 | * Frame request callback. A call to this should result in at least one | |
352 | * frame being output over the given link. This should return zero on | |
353 | * success, and another value on error. | |
354 | * See ff_request_frame() for the error codes with a specific | |
355 | * meaning. | |
356 | * | |
357 | * Output pads only. | |
358 | */ | |
359 | int (*request_frame)(AVFilterLink *link); | |
360 | ||
361 | /** | |
362 | * Link configuration callback. | |
363 | * | |
364 | * For output pads, this should set the following link properties: | |
365 | * video: width, height, sample_aspect_ratio, time_base | |
366 | * audio: sample_rate. | |
367 | * | |
368 | * This should NOT set properties such as format, channel_layout, etc which | |
369 | * are negotiated between filters by the filter system using the | |
370 | * query_formats() callback before this function is called. | |
371 | * | |
372 | * For input pads, this should check the properties of the link, and update | |
373 | * the filter's internal state as necessary. | |
374 | * | |
375 | * For both input and output pads, this should return zero on success, | |
376 | * and another value on error. | |
377 | */ | |
378 | int (*config_props)(AVFilterLink *link); | |
379 | ||
380 | /** | |
381 | * The filter expects a fifo to be inserted on its input link, | |
382 | * typically because it has a delay. | |
383 | * | |
384 | * input pads only. | |
385 | */ | |
386 | int needs_fifo; | |
387 | ||
388 | /** | |
389 | * The filter expects writable frames from its input link, | |
390 | * duplicating data buffers if needed. | |
391 | * | |
392 | * input pads only. | |
393 | */ | |
394 | int needs_writable; | |
395 | }; | |
396 | #endif | |
397 | ||
398 | /** | |
399 | * Get the number of elements in a NULL-terminated array of AVFilterPads (e.g. | |
400 | * AVFilter.inputs/outputs). | |
401 | */ | |
402 | int avfilter_pad_count(const AVFilterPad *pads); | |
403 | ||
404 | /** | |
405 | * Get the name of an AVFilterPad. | |
406 | * | |
407 | * @param pads an array of AVFilterPads | |
408 | * @param pad_idx index of the pad in the array it; is the caller's | |
409 | * responsibility to ensure the index is valid | |
410 | * | |
411 | * @return name of the pad_idx'th pad in pads | |
412 | */ | |
413 | const char *avfilter_pad_get_name(const AVFilterPad *pads, int pad_idx); | |
414 | ||
415 | /** | |
416 | * Get the type of an AVFilterPad. | |
417 | * | |
418 | * @param pads an array of AVFilterPads | |
419 | * @param pad_idx index of the pad in the array; it is the caller's | |
420 | * responsibility to ensure the index is valid | |
421 | * | |
422 | * @return type of the pad_idx'th pad in pads | |
423 | */ | |
424 | enum AVMediaType avfilter_pad_get_type(const AVFilterPad *pads, int pad_idx); | |
425 | ||
426 | /** | |
427 | * The number of the filter inputs is not determined just by AVFilter.inputs. | |
428 | * The filter might add additional inputs during initialization depending on the | |
429 | * options supplied to it. | |
430 | */ | |
431 | #define AVFILTER_FLAG_DYNAMIC_INPUTS (1 << 0) | |
432 | /** | |
433 | * The number of the filter outputs is not determined just by AVFilter.outputs. | |
434 | * The filter might add additional outputs during initialization depending on | |
435 | * the options supplied to it. | |
436 | */ | |
437 | #define AVFILTER_FLAG_DYNAMIC_OUTPUTS (1 << 1) | |
438 | /** | |
439 | * The filter supports multithreading by splitting frames into multiple parts | |
440 | * and processing them concurrently. | |
441 | */ | |
442 | #define AVFILTER_FLAG_SLICE_THREADS (1 << 2) | |
443 | /** | |
444 | * Some filters support a generic "enable" expression option that can be used | |
445 | * to enable or disable a filter in the timeline. Filters supporting this | |
446 | * option have this flag set. When the enable expression is false, the default | |
447 | * no-op filter_frame() function is called in place of the filter_frame() | |
448 | * callback defined on each input pad, thus the frame is passed unchanged to | |
449 | * the next filters. | |
450 | */ | |
451 | #define AVFILTER_FLAG_SUPPORT_TIMELINE_GENERIC (1 << 16) | |
452 | /** | |
453 | * Same as AVFILTER_FLAG_SUPPORT_TIMELINE_GENERIC, except that the filter will | |
454 | * have its filter_frame() callback(s) called as usual even when the enable | |
455 | * expression is false. The filter will disable filtering within the | |
456 | * filter_frame() callback(s) itself, for example executing code depending on | |
457 | * the AVFilterContext->is_disabled value. | |
458 | */ | |
459 | #define AVFILTER_FLAG_SUPPORT_TIMELINE_INTERNAL (1 << 17) | |
460 | /** | |
461 | * Handy mask to test whether the filter supports or no the timeline feature | |
462 | * (internally or generically). | |
463 | */ | |
464 | #define AVFILTER_FLAG_SUPPORT_TIMELINE (AVFILTER_FLAG_SUPPORT_TIMELINE_GENERIC | AVFILTER_FLAG_SUPPORT_TIMELINE_INTERNAL) | |
465 | ||
466 | /** | |
467 | * Filter definition. This defines the pads a filter contains, and all the | |
468 | * callback functions used to interact with the filter. | |
469 | */ | |
470 | typedef struct AVFilter { | |
471 | /** | |
472 | * Filter name. Must be non-NULL and unique among filters. | |
473 | */ | |
474 | const char *name; | |
475 | ||
476 | /** | |
477 | * A description of the filter. May be NULL. | |
478 | * | |
479 | * You should use the NULL_IF_CONFIG_SMALL() macro to define it. | |
480 | */ | |
481 | const char *description; | |
482 | ||
483 | /** | |
484 | * List of inputs, terminated by a zeroed element. | |
485 | * | |
486 | * NULL if there are no (static) inputs. Instances of filters with | |
487 | * AVFILTER_FLAG_DYNAMIC_INPUTS set may have more inputs than present in | |
488 | * this list. | |
489 | */ | |
490 | const AVFilterPad *inputs; | |
491 | /** | |
492 | * List of outputs, terminated by a zeroed element. | |
493 | * | |
494 | * NULL if there are no (static) outputs. Instances of filters with | |
495 | * AVFILTER_FLAG_DYNAMIC_OUTPUTS set may have more outputs than present in | |
496 | * this list. | |
497 | */ | |
498 | const AVFilterPad *outputs; | |
499 | ||
500 | /** | |
501 | * A class for the private data, used to declare filter private AVOptions. | |
502 | * This field is NULL for filters that do not declare any options. | |
503 | * | |
504 | * If this field is non-NULL, the first member of the filter private data | |
505 | * must be a pointer to AVClass, which will be set by libavfilter generic | |
506 | * code to this class. | |
507 | */ | |
508 | const AVClass *priv_class; | |
509 | ||
510 | /** | |
511 | * A combination of AVFILTER_FLAG_* | |
512 | */ | |
513 | int flags; | |
514 | ||
515 | /***************************************************************** | |
516 | * All fields below this line are not part of the public API. They | |
517 | * may not be used outside of libavfilter and can be changed and | |
518 | * removed at will. | |
519 | * New public fields should be added right above. | |
520 | ***************************************************************** | |
521 | */ | |
522 | ||
523 | /** | |
524 | * Filter initialization function. | |
525 | * | |
526 | * This callback will be called only once during the filter lifetime, after | |
527 | * all the options have been set, but before links between filters are | |
528 | * established and format negotiation is done. | |
529 | * | |
530 | * Basic filter initialization should be done here. Filters with dynamic | |
531 | * inputs and/or outputs should create those inputs/outputs here based on | |
532 | * provided options. No more changes to this filter's inputs/outputs can be | |
533 | * done after this callback. | |
534 | * | |
535 | * This callback must not assume that the filter links exist or frame | |
536 | * parameters are known. | |
537 | * | |
538 | * @ref AVFilter.uninit "uninit" is guaranteed to be called even if | |
539 | * initialization fails, so this callback does not have to clean up on | |
540 | * failure. | |
541 | * | |
542 | * @return 0 on success, a negative AVERROR on failure | |
543 | */ | |
544 | int (*init)(AVFilterContext *ctx); | |
545 | ||
546 | /** | |
547 | * Should be set instead of @ref AVFilter.init "init" by the filters that | |
548 | * want to pass a dictionary of AVOptions to nested contexts that are | |
549 | * allocated during init. | |
550 | * | |
551 | * On return, the options dict should be freed and replaced with one that | |
552 | * contains all the options which could not be processed by this filter (or | |
553 | * with NULL if all the options were processed). | |
554 | * | |
555 | * Otherwise the semantics is the same as for @ref AVFilter.init "init". | |
556 | */ | |
557 | int (*init_dict)(AVFilterContext *ctx, AVDictionary **options); | |
558 | ||
559 | /** | |
560 | * Filter uninitialization function. | |
561 | * | |
562 | * Called only once right before the filter is freed. Should deallocate any | |
563 | * memory held by the filter, release any buffer references, etc. It does | |
564 | * not need to deallocate the AVFilterContext.priv memory itself. | |
565 | * | |
566 | * This callback may be called even if @ref AVFilter.init "init" was not | |
567 | * called or failed, so it must be prepared to handle such a situation. | |
568 | */ | |
569 | void (*uninit)(AVFilterContext *ctx); | |
570 | ||
571 | /** | |
572 | * Query formats supported by the filter on its inputs and outputs. | |
573 | * | |
574 | * This callback is called after the filter is initialized (so the inputs | |
575 | * and outputs are fixed), shortly before the format negotiation. This | |
576 | * callback may be called more than once. | |
577 | * | |
578 | * This callback must set AVFilterLink.out_formats on every input link and | |
579 | * AVFilterLink.in_formats on every output link to a list of pixel/sample | |
580 | * formats that the filter supports on that link. For audio links, this | |
581 | * filter must also set @ref AVFilterLink.in_samplerates "in_samplerates" / | |
582 | * @ref AVFilterLink.out_samplerates "out_samplerates" and | |
583 | * @ref AVFilterLink.in_channel_layouts "in_channel_layouts" / | |
584 | * @ref AVFilterLink.out_channel_layouts "out_channel_layouts" analogously. | |
585 | * | |
586 | * This callback may be NULL for filters with one input, in which case | |
587 | * libavfilter assumes that it supports all input formats and preserves | |
588 | * them on output. | |
589 | * | |
590 | * @return zero on success, a negative value corresponding to an | |
591 | * AVERROR code otherwise | |
592 | */ | |
593 | int (*query_formats)(AVFilterContext *); | |
594 | ||
595 | int priv_size; ///< size of private data to allocate for the filter | |
596 | ||
597 | /** | |
598 | * Used by the filter registration system. Must not be touched by any other | |
599 | * code. | |
600 | */ | |
601 | struct AVFilter *next; | |
602 | ||
603 | /** | |
604 | * Make the filter instance process a command. | |
605 | * | |
606 | * @param cmd the command to process, for handling simplicity all commands must be alphanumeric only | |
607 | * @param arg the argument for the command | |
608 | * @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. | |
609 | * @param flags if AVFILTER_CMD_FLAG_FAST is set and the command would be | |
610 | * time consuming then a filter should treat it like an unsupported command | |
611 | * | |
612 | * @returns >=0 on success otherwise an error code. | |
613 | * AVERROR(ENOSYS) on unsupported commands | |
614 | */ | |
615 | int (*process_command)(AVFilterContext *, const char *cmd, const char *arg, char *res, int res_len, int flags); | |
616 | ||
617 | /** | |
618 | * Filter initialization function, alternative to the init() | |
619 | * callback. Args contains the user-supplied parameters, opaque is | |
620 | * used for providing binary data. | |
621 | */ | |
622 | int (*init_opaque)(AVFilterContext *ctx, void *opaque); | |
623 | } AVFilter; | |
624 | ||
625 | /** | |
626 | * Process multiple parts of the frame concurrently. | |
627 | */ | |
628 | #define AVFILTER_THREAD_SLICE (1 << 0) | |
629 | ||
630 | typedef struct AVFilterInternal AVFilterInternal; | |
631 | ||
632 | /** An instance of a filter */ | |
633 | struct AVFilterContext { | |
634 | const AVClass *av_class; ///< needed for av_log() and filters common options | |
635 | ||
636 | const AVFilter *filter; ///< the AVFilter of which this is an instance | |
637 | ||
638 | char *name; ///< name of this filter instance | |
639 | ||
640 | AVFilterPad *input_pads; ///< array of input pads | |
641 | AVFilterLink **inputs; ///< array of pointers to input links | |
642 | #if FF_API_FOO_COUNT | |
643 | attribute_deprecated unsigned input_count; ///< @deprecated use nb_inputs | |
644 | #endif | |
645 | unsigned nb_inputs; ///< number of input pads | |
646 | ||
647 | AVFilterPad *output_pads; ///< array of output pads | |
648 | AVFilterLink **outputs; ///< array of pointers to output links | |
649 | #if FF_API_FOO_COUNT | |
650 | attribute_deprecated unsigned output_count; ///< @deprecated use nb_outputs | |
651 | #endif | |
652 | unsigned nb_outputs; ///< number of output pads | |
653 | ||
654 | void *priv; ///< private data for use by the filter | |
655 | ||
656 | struct AVFilterGraph *graph; ///< filtergraph this filter belongs to | |
657 | ||
658 | /** | |
659 | * Type of multithreading being allowed/used. A combination of | |
660 | * AVFILTER_THREAD_* flags. | |
661 | * | |
662 | * May be set by the caller before initializing the filter to forbid some | |
663 | * or all kinds of multithreading for this filter. The default is allowing | |
664 | * everything. | |
665 | * | |
666 | * When the filter is initialized, this field is combined using bit AND with | |
667 | * AVFilterGraph.thread_type to get the final mask used for determining | |
668 | * allowed threading types. I.e. a threading type needs to be set in both | |
669 | * to be allowed. | |
670 | * | |
671 | * After the filter is initialized, libavfilter sets this field to the | |
672 | * threading type that is actually used (0 for no multithreading). | |
673 | */ | |
674 | int thread_type; | |
675 | ||
676 | /** | |
677 | * An opaque struct for libavfilter internal use. | |
678 | */ | |
679 | AVFilterInternal *internal; | |
680 | ||
681 | struct AVFilterCommand *command_queue; | |
682 | ||
683 | char *enable_str; ///< enable expression string | |
684 | void *enable; ///< parsed expression (AVExpr*) | |
685 | double *var_values; ///< variable values for the enable expression | |
686 | int is_disabled; ///< the enabled state from the last expression evaluation | |
687 | }; | |
688 | ||
689 | /** | |
690 | * A link between two filters. This contains pointers to the source and | |
691 | * destination filters between which this link exists, and the indexes of | |
692 | * the pads involved. In addition, this link also contains the parameters | |
693 | * which have been negotiated and agreed upon between the filter, such as | |
694 | * image dimensions, format, etc. | |
695 | */ | |
696 | struct AVFilterLink { | |
697 | AVFilterContext *src; ///< source filter | |
698 | AVFilterPad *srcpad; ///< output pad on the source filter | |
699 | ||
700 | AVFilterContext *dst; ///< dest filter | |
701 | AVFilterPad *dstpad; ///< input pad on the dest filter | |
702 | ||
703 | enum AVMediaType type; ///< filter media type | |
704 | ||
705 | /* These parameters apply only to video */ | |
706 | int w; ///< agreed upon image width | |
707 | int h; ///< agreed upon image height | |
708 | AVRational sample_aspect_ratio; ///< agreed upon sample aspect ratio | |
709 | /* These parameters apply only to audio */ | |
710 | uint64_t channel_layout; ///< channel layout of current buffer (see libavutil/channel_layout.h) | |
711 | int sample_rate; ///< samples per second | |
712 | ||
713 | int format; ///< agreed upon media format | |
714 | ||
715 | /** | |
716 | * Define the time base used by the PTS of the frames/samples | |
717 | * which will pass through this link. | |
718 | * During the configuration stage, each filter is supposed to | |
719 | * change only the output timebase, while the timebase of the | |
720 | * input link is assumed to be an unchangeable property. | |
721 | */ | |
722 | AVRational time_base; | |
723 | ||
724 | /***************************************************************** | |
725 | * All fields below this line are not part of the public API. They | |
726 | * may not be used outside of libavfilter and can be changed and | |
727 | * removed at will. | |
728 | * New public fields should be added right above. | |
729 | ***************************************************************** | |
730 | */ | |
731 | /** | |
732 | * Lists of formats and channel layouts supported by the input and output | |
733 | * filters respectively. These lists are used for negotiating the format | |
734 | * to actually be used, which will be loaded into the format and | |
735 | * channel_layout members, above, when chosen. | |
736 | * | |
737 | */ | |
738 | AVFilterFormats *in_formats; | |
739 | AVFilterFormats *out_formats; | |
740 | ||
741 | /** | |
742 | * Lists of channel layouts and sample rates used for automatic | |
743 | * negotiation. | |
744 | */ | |
745 | AVFilterFormats *in_samplerates; | |
746 | AVFilterFormats *out_samplerates; | |
747 | struct AVFilterChannelLayouts *in_channel_layouts; | |
748 | struct AVFilterChannelLayouts *out_channel_layouts; | |
749 | ||
750 | /** | |
751 | * Audio only, the destination filter sets this to a non-zero value to | |
752 | * request that buffers with the given number of samples should be sent to | |
753 | * it. AVFilterPad.needs_fifo must also be set on the corresponding input | |
754 | * pad. | |
755 | * Last buffer before EOF will be padded with silence. | |
756 | */ | |
757 | int request_samples; | |
758 | ||
759 | /** stage of the initialization of the link properties (dimensions, etc) */ | |
760 | enum { | |
761 | AVLINK_UNINIT = 0, ///< not started | |
762 | AVLINK_STARTINIT, ///< started, but incomplete | |
763 | AVLINK_INIT ///< complete | |
764 | } init_state; | |
765 | ||
766 | struct AVFilterPool *pool; | |
767 | ||
768 | /** | |
769 | * Graph the filter belongs to. | |
770 | */ | |
771 | struct AVFilterGraph *graph; | |
772 | ||
773 | /** | |
774 | * Current timestamp of the link, as defined by the most recent | |
775 | * frame(s), in AV_TIME_BASE units. | |
776 | */ | |
777 | int64_t current_pts; | |
778 | ||
779 | /** | |
780 | * Index in the age array. | |
781 | */ | |
782 | int age_index; | |
783 | ||
784 | /** | |
785 | * Frame rate of the stream on the link, or 1/0 if unknown; | |
786 | * if left to 0/0, will be automatically be copied from the first input | |
787 | * of the source filter if it exists. | |
788 | * | |
789 | * Sources should set it to the best estimation of the real frame rate. | |
790 | * Filters should update it if necessary depending on their function. | |
791 | * Sinks can use it to set a default output frame rate. | |
792 | * It is similar to the r_frame_rate field in AVStream. | |
793 | */ | |
794 | AVRational frame_rate; | |
795 | ||
796 | /** | |
797 | * Buffer partially filled with samples to achieve a fixed/minimum size. | |
798 | */ | |
799 | AVFrame *partial_buf; | |
800 | ||
801 | /** | |
802 | * Size of the partial buffer to allocate. | |
803 | * Must be between min_samples and max_samples. | |
804 | */ | |
805 | int partial_buf_size; | |
806 | ||
807 | /** | |
808 | * Minimum number of samples to filter at once. If filter_frame() is | |
809 | * called with fewer samples, it will accumulate them in partial_buf. | |
810 | * This field and the related ones must not be changed after filtering | |
811 | * has started. | |
812 | * If 0, all related fields are ignored. | |
813 | */ | |
814 | int min_samples; | |
815 | ||
816 | /** | |
817 | * Maximum number of samples to filter at once. If filter_frame() is | |
818 | * called with more samples, it will split them. | |
819 | */ | |
820 | int max_samples; | |
821 | ||
822 | /** | |
823 | * The buffer reference currently being received across the link by the | |
824 | * destination filter. This is used internally by the filter system to | |
825 | * allow automatic copying of buffers which do not have sufficient | |
826 | * permissions for the destination. This should not be accessed directly | |
827 | * by the filters. | |
828 | */ | |
829 | AVFilterBufferRef *cur_buf_copy; | |
830 | ||
831 | /** | |
832 | * True if the link is closed. | |
833 | * If set, all attempts of start_frame, filter_frame or request_frame | |
834 | * will fail with AVERROR_EOF, and if necessary the reference will be | |
835 | * destroyed. | |
836 | * If request_frame returns AVERROR_EOF, this flag is set on the | |
837 | * corresponding link. | |
838 | * It can be set also be set by either the source or the destination | |
839 | * filter. | |
840 | */ | |
841 | int closed; | |
842 | ||
843 | /** | |
844 | * Number of channels. | |
845 | */ | |
846 | int channels; | |
847 | ||
848 | /** | |
849 | * True if a frame is being requested on the link. | |
850 | * Used internally by the framework. | |
851 | */ | |
852 | unsigned frame_requested; | |
853 | ||
854 | /** | |
855 | * Link processing flags. | |
856 | */ | |
857 | unsigned flags; | |
858 | ||
859 | /** | |
860 | * Number of past frames sent through the link. | |
861 | */ | |
862 | int64_t frame_count; | |
863 | }; | |
864 | ||
865 | /** | |
866 | * Link two filters together. | |
867 | * | |
868 | * @param src the source filter | |
869 | * @param srcpad index of the output pad on the source filter | |
870 | * @param dst the destination filter | |
871 | * @param dstpad index of the input pad on the destination filter | |
872 | * @return zero on success | |
873 | */ | |
874 | int avfilter_link(AVFilterContext *src, unsigned srcpad, | |
875 | AVFilterContext *dst, unsigned dstpad); | |
876 | ||
877 | /** | |
878 | * Free the link in *link, and set its pointer to NULL. | |
879 | */ | |
880 | void avfilter_link_free(AVFilterLink **link); | |
881 | ||
882 | /** | |
883 | * Get the number of channels of a link. | |
884 | */ | |
885 | int avfilter_link_get_channels(AVFilterLink *link); | |
886 | ||
887 | /** | |
888 | * Set the closed field of a link. | |
889 | */ | |
890 | void avfilter_link_set_closed(AVFilterLink *link, int closed); | |
891 | ||
892 | /** | |
893 | * Negotiate the media format, dimensions, etc of all inputs to a filter. | |
894 | * | |
895 | * @param filter the filter to negotiate the properties for its inputs | |
896 | * @return zero on successful negotiation | |
897 | */ | |
898 | int avfilter_config_links(AVFilterContext *filter); | |
899 | ||
900 | #if FF_API_AVFILTERBUFFER | |
901 | /** | |
902 | * Create a buffer reference wrapped around an already allocated image | |
903 | * buffer. | |
904 | * | |
905 | * @param data pointers to the planes of the image to reference | |
906 | * @param linesize linesizes for the planes of the image to reference | |
907 | * @param perms the required access permissions | |
908 | * @param w the width of the image specified by the data and linesize arrays | |
909 | * @param h the height of the image specified by the data and linesize arrays | |
910 | * @param format the pixel format of the image specified by the data and linesize arrays | |
911 | */ | |
912 | attribute_deprecated | |
913 | AVFilterBufferRef * | |
914 | avfilter_get_video_buffer_ref_from_arrays(uint8_t * const data[4], const int linesize[4], int perms, | |
915 | int w, int h, enum AVPixelFormat format); | |
916 | ||
917 | /** | |
918 | * Create an audio buffer reference wrapped around an already | |
919 | * allocated samples buffer. | |
920 | * | |
921 | * See avfilter_get_audio_buffer_ref_from_arrays_channels() for a version | |
922 | * that can handle unknown channel layouts. | |
923 | * | |
924 | * @param data pointers to the samples plane buffers | |
925 | * @param linesize linesize for the samples plane buffers | |
926 | * @param perms the required access permissions | |
927 | * @param nb_samples number of samples per channel | |
928 | * @param sample_fmt the format of each sample in the buffer to allocate | |
929 | * @param channel_layout the channel layout of the buffer | |
930 | */ | |
931 | attribute_deprecated | |
932 | AVFilterBufferRef *avfilter_get_audio_buffer_ref_from_arrays(uint8_t **data, | |
933 | int linesize, | |
934 | int perms, | |
935 | int nb_samples, | |
936 | enum AVSampleFormat sample_fmt, | |
937 | uint64_t channel_layout); | |
938 | /** | |
939 | * Create an audio buffer reference wrapped around an already | |
940 | * allocated samples buffer. | |
941 | * | |
942 | * @param data pointers to the samples plane buffers | |
943 | * @param linesize linesize for the samples plane buffers | |
944 | * @param perms the required access permissions | |
945 | * @param nb_samples number of samples per channel | |
946 | * @param sample_fmt the format of each sample in the buffer to allocate | |
947 | * @param channels the number of channels of the buffer | |
948 | * @param channel_layout the channel layout of the buffer, | |
949 | * must be either 0 or consistent with channels | |
950 | */ | |
951 | attribute_deprecated | |
952 | AVFilterBufferRef *avfilter_get_audio_buffer_ref_from_arrays_channels(uint8_t **data, | |
953 | int linesize, | |
954 | int perms, | |
955 | int nb_samples, | |
956 | enum AVSampleFormat sample_fmt, | |
957 | int channels, | |
958 | uint64_t channel_layout); | |
959 | ||
960 | #endif | |
961 | ||
962 | ||
963 | #define AVFILTER_CMD_FLAG_ONE 1 ///< Stop once a filter understood the command (for target=all for example), fast filters are favored automatically | |
964 | #define AVFILTER_CMD_FLAG_FAST 2 ///< Only execute command when its fast (like a video out that supports contrast adjustment in hw) | |
965 | ||
966 | /** | |
967 | * Make the filter instance process a command. | |
968 | * It is recommended to use avfilter_graph_send_command(). | |
969 | */ | |
970 | int avfilter_process_command(AVFilterContext *filter, const char *cmd, const char *arg, char *res, int res_len, int flags); | |
971 | ||
972 | /** Initialize the filter system. Register all builtin filters. */ | |
973 | void avfilter_register_all(void); | |
974 | ||
975 | #if FF_API_OLD_FILTER_REGISTER | |
976 | /** Uninitialize the filter system. Unregister all filters. */ | |
977 | attribute_deprecated | |
978 | void avfilter_uninit(void); | |
979 | #endif | |
980 | ||
981 | /** | |
982 | * Register a filter. This is only needed if you plan to use | |
983 | * avfilter_get_by_name later to lookup the AVFilter structure by name. A | |
984 | * filter can still by instantiated with avfilter_graph_alloc_filter even if it | |
985 | * is not registered. | |
986 | * | |
987 | * @param filter the filter to register | |
988 | * @return 0 if the registration was successful, a negative value | |
989 | * otherwise | |
990 | */ | |
991 | int avfilter_register(AVFilter *filter); | |
992 | ||
993 | /** | |
994 | * Get a filter definition matching the given name. | |
995 | * | |
996 | * @param name the filter name to find | |
997 | * @return the filter definition, if any matching one is registered. | |
998 | * NULL if none found. | |
999 | */ | |
1000 | #if !FF_API_NOCONST_GET_NAME | |
1001 | const | |
1002 | #endif | |
1003 | AVFilter *avfilter_get_by_name(const char *name); | |
1004 | ||
1005 | /** | |
1006 | * Iterate over all registered filters. | |
1007 | * @return If prev is non-NULL, next registered filter after prev or NULL if | |
1008 | * prev is the last filter. If prev is NULL, return the first registered filter. | |
1009 | */ | |
1010 | const AVFilter *avfilter_next(const AVFilter *prev); | |
1011 | ||
1012 | #if FF_API_OLD_FILTER_REGISTER | |
1013 | /** | |
1014 | * If filter is NULL, returns a pointer to the first registered filter pointer, | |
1015 | * if filter is non-NULL, returns the next pointer after filter. | |
1016 | * If the returned pointer points to NULL, the last registered filter | |
1017 | * was already reached. | |
1018 | * @deprecated use avfilter_next() | |
1019 | */ | |
1020 | attribute_deprecated | |
1021 | AVFilter **av_filter_next(AVFilter **filter); | |
1022 | #endif | |
1023 | ||
1024 | #if FF_API_AVFILTER_OPEN | |
1025 | /** | |
1026 | * Create a filter instance. | |
1027 | * | |
1028 | * @param filter_ctx put here a pointer to the created filter context | |
1029 | * on success, NULL on failure | |
1030 | * @param filter the filter to create an instance of | |
1031 | * @param inst_name Name to give to the new instance. Can be NULL for none. | |
1032 | * @return >= 0 in case of success, a negative error code otherwise | |
1033 | * @deprecated use avfilter_graph_alloc_filter() instead | |
1034 | */ | |
1035 | attribute_deprecated | |
1036 | int avfilter_open(AVFilterContext **filter_ctx, AVFilter *filter, const char *inst_name); | |
1037 | #endif | |
1038 | ||
1039 | ||
1040 | #if FF_API_AVFILTER_INIT_FILTER | |
1041 | /** | |
1042 | * Initialize a filter. | |
1043 | * | |
1044 | * @param filter the filter to initialize | |
1045 | * @param args A string of parameters to use when initializing the filter. | |
1046 | * The format and meaning of this string varies by filter. | |
1047 | * @param opaque Any extra non-string data needed by the filter. The meaning | |
1048 | * of this parameter varies by filter. | |
1049 | * @return zero on success | |
1050 | */ | |
1051 | attribute_deprecated | |
1052 | int avfilter_init_filter(AVFilterContext *filter, const char *args, void *opaque); | |
1053 | #endif | |
1054 | ||
1055 | /** | |
1056 | * Initialize a filter with the supplied parameters. | |
1057 | * | |
1058 | * @param ctx uninitialized filter context to initialize | |
1059 | * @param args Options to initialize the filter with. This must be a | |
1060 | * ':'-separated list of options in the 'key=value' form. | |
1061 | * May be NULL if the options have been set directly using the | |
1062 | * AVOptions API or there are no options that need to be set. | |
1063 | * @return 0 on success, a negative AVERROR on failure | |
1064 | */ | |
1065 | int avfilter_init_str(AVFilterContext *ctx, const char *args); | |
1066 | ||
1067 | /** | |
1068 | * Initialize a filter with the supplied dictionary of options. | |
1069 | * | |
1070 | * @param ctx uninitialized filter context to initialize | |
1071 | * @param options An AVDictionary filled with options for this filter. On | |
1072 | * return this parameter will be destroyed and replaced with | |
1073 | * a dict containing options that were not found. This dictionary | |
1074 | * must be freed by the caller. | |
1075 | * May be NULL, then this function is equivalent to | |
1076 | * avfilter_init_str() with the second parameter set to NULL. | |
1077 | * @return 0 on success, a negative AVERROR on failure | |
1078 | * | |
1079 | * @note This function and avfilter_init_str() do essentially the same thing, | |
1080 | * the difference is in manner in which the options are passed. It is up to the | |
1081 | * calling code to choose whichever is more preferable. The two functions also | |
1082 | * behave differently when some of the provided options are not declared as | |
1083 | * supported by the filter. In such a case, avfilter_init_str() will fail, but | |
1084 | * this function will leave those extra options in the options AVDictionary and | |
1085 | * continue as usual. | |
1086 | */ | |
1087 | int avfilter_init_dict(AVFilterContext *ctx, AVDictionary **options); | |
1088 | ||
1089 | /** | |
1090 | * Free a filter context. This will also remove the filter from its | |
1091 | * filtergraph's list of filters. | |
1092 | * | |
1093 | * @param filter the filter to free | |
1094 | */ | |
1095 | void avfilter_free(AVFilterContext *filter); | |
1096 | ||
1097 | /** | |
1098 | * Insert a filter in the middle of an existing link. | |
1099 | * | |
1100 | * @param link the link into which the filter should be inserted | |
1101 | * @param filt the filter to be inserted | |
1102 | * @param filt_srcpad_idx the input pad on the filter to connect | |
1103 | * @param filt_dstpad_idx the output pad on the filter to connect | |
1104 | * @return zero on success | |
1105 | */ | |
1106 | int avfilter_insert_filter(AVFilterLink *link, AVFilterContext *filt, | |
1107 | unsigned filt_srcpad_idx, unsigned filt_dstpad_idx); | |
1108 | ||
1109 | #if FF_API_AVFILTERBUFFER | |
1110 | /** | |
1111 | * Copy the frame properties of src to dst, without copying the actual | |
1112 | * image data. | |
1113 | * | |
1114 | * @return 0 on success, a negative number on error. | |
1115 | */ | |
1116 | attribute_deprecated | |
1117 | int avfilter_copy_frame_props(AVFilterBufferRef *dst, const AVFrame *src); | |
1118 | ||
1119 | /** | |
1120 | * Copy the frame properties and data pointers of src to dst, without copying | |
1121 | * the actual data. | |
1122 | * | |
1123 | * @return 0 on success, a negative number on error. | |
1124 | */ | |
1125 | attribute_deprecated | |
1126 | int avfilter_copy_buf_props(AVFrame *dst, const AVFilterBufferRef *src); | |
1127 | #endif | |
1128 | ||
1129 | /** | |
1130 | * @return AVClass for AVFilterContext. | |
1131 | * | |
1132 | * @see av_opt_find(). | |
1133 | */ | |
1134 | const AVClass *avfilter_get_class(void); | |
1135 | ||
1136 | typedef struct AVFilterGraphInternal AVFilterGraphInternal; | |
1137 | ||
1138 | /** | |
1139 | * A function pointer passed to the @ref AVFilterGraph.execute callback to be | |
1140 | * executed multiple times, possibly in parallel. | |
1141 | * | |
1142 | * @param ctx the filter context the job belongs to | |
1143 | * @param arg an opaque parameter passed through from @ref | |
1144 | * AVFilterGraph.execute | |
1145 | * @param jobnr the index of the job being executed | |
1146 | * @param nb_jobs the total number of jobs | |
1147 | * | |
1148 | * @return 0 on success, a negative AVERROR on error | |
1149 | */ | |
1150 | typedef int (avfilter_action_func)(AVFilterContext *ctx, void *arg, int jobnr, int nb_jobs); | |
1151 | ||
1152 | /** | |
1153 | * A function executing multiple jobs, possibly in parallel. | |
1154 | * | |
1155 | * @param ctx the filter context to which the jobs belong | |
1156 | * @param func the function to be called multiple times | |
1157 | * @param arg the argument to be passed to func | |
1158 | * @param ret a nb_jobs-sized array to be filled with return values from each | |
1159 | * invocation of func | |
1160 | * @param nb_jobs the number of jobs to execute | |
1161 | * | |
1162 | * @return 0 on success, a negative AVERROR on error | |
1163 | */ | |
1164 | typedef int (avfilter_execute_func)(AVFilterContext *ctx, avfilter_action_func *func, | |
1165 | void *arg, int *ret, int nb_jobs); | |
1166 | ||
1167 | typedef struct AVFilterGraph { | |
1168 | const AVClass *av_class; | |
1169 | #if FF_API_FOO_COUNT | |
1170 | attribute_deprecated | |
1171 | unsigned filter_count_unused; | |
1172 | #endif | |
1173 | AVFilterContext **filters; | |
1174 | #if !FF_API_FOO_COUNT | |
1175 | unsigned nb_filters; | |
1176 | #endif | |
1177 | ||
1178 | char *scale_sws_opts; ///< sws options to use for the auto-inserted scale filters | |
1179 | char *resample_lavr_opts; ///< libavresample options to use for the auto-inserted resample filters | |
1180 | #if FF_API_FOO_COUNT | |
1181 | unsigned nb_filters; | |
1182 | #endif | |
1183 | ||
1184 | /** | |
1185 | * Type of multithreading allowed for filters in this graph. A combination | |
1186 | * of AVFILTER_THREAD_* flags. | |
1187 | * | |
1188 | * May be set by the caller at any point, the setting will apply to all | |
1189 | * filters initialized after that. The default is allowing everything. | |
1190 | * | |
1191 | * When a filter in this graph is initialized, this field is combined using | |
1192 | * bit AND with AVFilterContext.thread_type to get the final mask used for | |
1193 | * determining allowed threading types. I.e. a threading type needs to be | |
1194 | * set in both to be allowed. | |
1195 | */ | |
1196 | int thread_type; | |
1197 | ||
1198 | /** | |
1199 | * Maximum number of threads used by filters in this graph. May be set by | |
1200 | * the caller before adding any filters to the filtergraph. Zero (the | |
1201 | * default) means that the number of threads is determined automatically. | |
1202 | */ | |
1203 | int nb_threads; | |
1204 | ||
1205 | /** | |
1206 | * Opaque object for libavfilter internal use. | |
1207 | */ | |
1208 | AVFilterGraphInternal *internal; | |
1209 | ||
1210 | /** | |
1211 | * Opaque user data. May be set by the caller to an arbitrary value, e.g. to | |
1212 | * be used from callbacks like @ref AVFilterGraph.execute. | |
1213 | * Libavfilter will not touch this field in any way. | |
1214 | */ | |
1215 | void *opaque; | |
1216 | ||
1217 | /** | |
1218 | * This callback may be set by the caller immediately after allocating the | |
1219 | * graph and before adding any filters to it, to provide a custom | |
1220 | * multithreading implementation. | |
1221 | * | |
1222 | * If set, filters with slice threading capability will call this callback | |
1223 | * to execute multiple jobs in parallel. | |
1224 | * | |
1225 | * If this field is left unset, libavfilter will use its internal | |
1226 | * implementation, which may or may not be multithreaded depending on the | |
1227 | * platform and build options. | |
1228 | */ | |
1229 | avfilter_execute_func *execute; | |
1230 | ||
1231 | char *aresample_swr_opts; ///< swr options to use for the auto-inserted aresample filters, Access ONLY through AVOptions | |
1232 | ||
1233 | /** | |
1234 | * Private fields | |
1235 | * | |
1236 | * The following fields are for internal use only. | |
1237 | * Their type, offset, number and semantic can change without notice. | |
1238 | */ | |
1239 | ||
1240 | AVFilterLink **sink_links; | |
1241 | int sink_links_count; | |
1242 | ||
1243 | unsigned disable_auto_convert; | |
1244 | } AVFilterGraph; | |
1245 | ||
1246 | /** | |
1247 | * Allocate a filter graph. | |
1248 | */ | |
1249 | AVFilterGraph *avfilter_graph_alloc(void); | |
1250 | ||
1251 | /** | |
1252 | * Create a new filter instance in a filter graph. | |
1253 | * | |
1254 | * @param graph graph in which the new filter will be used | |
1255 | * @param filter the filter to create an instance of | |
1256 | * @param name Name to give to the new instance (will be copied to | |
1257 | * AVFilterContext.name). This may be used by the caller to identify | |
1258 | * different filters, libavfilter itself assigns no semantics to | |
1259 | * this parameter. May be NULL. | |
1260 | * | |
1261 | * @return the context of the newly created filter instance (note that it is | |
1262 | * also retrievable directly through AVFilterGraph.filters or with | |
1263 | * avfilter_graph_get_filter()) on success or NULL on failure. | |
1264 | */ | |
1265 | AVFilterContext *avfilter_graph_alloc_filter(AVFilterGraph *graph, | |
1266 | const AVFilter *filter, | |
1267 | const char *name); | |
1268 | ||
1269 | /** | |
1270 | * Get a filter instance identified by instance name from graph. | |
1271 | * | |
1272 | * @param graph filter graph to search through. | |
1273 | * @param name filter instance name (should be unique in the graph). | |
1274 | * @return the pointer to the found filter instance or NULL if it | |
1275 | * cannot be found. | |
1276 | */ | |
1277 | AVFilterContext *avfilter_graph_get_filter(AVFilterGraph *graph, const char *name); | |
1278 | ||
1279 | #if FF_API_AVFILTER_OPEN | |
1280 | /** | |
1281 | * Add an existing filter instance to a filter graph. | |
1282 | * | |
1283 | * @param graphctx the filter graph | |
1284 | * @param filter the filter to be added | |
1285 | * | |
1286 | * @deprecated use avfilter_graph_alloc_filter() to allocate a filter in a | |
1287 | * filter graph | |
1288 | */ | |
1289 | attribute_deprecated | |
1290 | int avfilter_graph_add_filter(AVFilterGraph *graphctx, AVFilterContext *filter); | |
1291 | #endif | |
1292 | ||
1293 | /** | |
1294 | * Create and add a filter instance into an existing graph. | |
1295 | * The filter instance is created from the filter filt and inited | |
1296 | * with the parameters args and opaque. | |
1297 | * | |
1298 | * In case of success put in *filt_ctx the pointer to the created | |
1299 | * filter instance, otherwise set *filt_ctx to NULL. | |
1300 | * | |
1301 | * @param name the instance name to give to the created filter instance | |
1302 | * @param graph_ctx the filter graph | |
1303 | * @return a negative AVERROR error code in case of failure, a non | |
1304 | * negative value otherwise | |
1305 | */ | |
1306 | int avfilter_graph_create_filter(AVFilterContext **filt_ctx, const AVFilter *filt, | |
1307 | const char *name, const char *args, void *opaque, | |
1308 | AVFilterGraph *graph_ctx); | |
1309 | ||
1310 | /** | |
1311 | * Enable or disable automatic format conversion inside the graph. | |
1312 | * | |
1313 | * Note that format conversion can still happen inside explicitly inserted | |
1314 | * scale and aresample filters. | |
1315 | * | |
1316 | * @param flags any of the AVFILTER_AUTO_CONVERT_* constants | |
1317 | */ | |
1318 | void avfilter_graph_set_auto_convert(AVFilterGraph *graph, unsigned flags); | |
1319 | ||
1320 | enum { | |
1321 | AVFILTER_AUTO_CONVERT_ALL = 0, /**< all automatic conversions enabled */ | |
1322 | AVFILTER_AUTO_CONVERT_NONE = -1, /**< all automatic conversions disabled */ | |
1323 | }; | |
1324 | ||
1325 | /** | |
1326 | * Check validity and configure all the links and formats in the graph. | |
1327 | * | |
1328 | * @param graphctx the filter graph | |
1329 | * @param log_ctx context used for logging | |
1330 | * @return >= 0 in case of success, a negative AVERROR code otherwise | |
1331 | */ | |
1332 | int avfilter_graph_config(AVFilterGraph *graphctx, void *log_ctx); | |
1333 | ||
1334 | /** | |
1335 | * Free a graph, destroy its links, and set *graph to NULL. | |
1336 | * If *graph is NULL, do nothing. | |
1337 | */ | |
1338 | void avfilter_graph_free(AVFilterGraph **graph); | |
1339 | ||
1340 | /** | |
1341 | * A linked-list of the inputs/outputs of the filter chain. | |
1342 | * | |
1343 | * This is mainly useful for avfilter_graph_parse() / avfilter_graph_parse2(), | |
1344 | * where it is used to communicate open (unlinked) inputs and outputs from and | |
1345 | * to the caller. | |
1346 | * This struct specifies, per each not connected pad contained in the graph, the | |
1347 | * filter context and the pad index required for establishing a link. | |
1348 | */ | |
1349 | typedef struct AVFilterInOut { | |
1350 | /** unique name for this input/output in the list */ | |
1351 | char *name; | |
1352 | ||
1353 | /** filter context associated to this input/output */ | |
1354 | AVFilterContext *filter_ctx; | |
1355 | ||
1356 | /** index of the filt_ctx pad to use for linking */ | |
1357 | int pad_idx; | |
1358 | ||
1359 | /** next input/input in the list, NULL if this is the last */ | |
1360 | struct AVFilterInOut *next; | |
1361 | } AVFilterInOut; | |
1362 | ||
1363 | /** | |
1364 | * Allocate a single AVFilterInOut entry. | |
1365 | * Must be freed with avfilter_inout_free(). | |
1366 | * @return allocated AVFilterInOut on success, NULL on failure. | |
1367 | */ | |
1368 | AVFilterInOut *avfilter_inout_alloc(void); | |
1369 | ||
1370 | /** | |
1371 | * Free the supplied list of AVFilterInOut and set *inout to NULL. | |
1372 | * If *inout is NULL, do nothing. | |
1373 | */ | |
1374 | void avfilter_inout_free(AVFilterInOut **inout); | |
1375 | ||
1376 | #if AV_HAVE_INCOMPATIBLE_LIBAV_ABI || !FF_API_OLD_GRAPH_PARSE | |
1377 | /** | |
1378 | * Add a graph described by a string to a graph. | |
1379 | * | |
1380 | * @note The caller must provide the lists of inputs and outputs, | |
1381 | * which therefore must be known before calling the function. | |
1382 | * | |
1383 | * @note The inputs parameter describes inputs of the already existing | |
1384 | * part of the graph; i.e. from the point of view of the newly created | |
1385 | * part, they are outputs. Similarly the outputs parameter describes | |
1386 | * outputs of the already existing filters, which are provided as | |
1387 | * inputs to the parsed filters. | |
1388 | * | |
1389 | * @param graph the filter graph where to link the parsed graph context | |
1390 | * @param filters string to be parsed | |
1391 | * @param inputs linked list to the inputs of the graph | |
1392 | * @param outputs linked list to the outputs of the graph | |
1393 | * @return zero on success, a negative AVERROR code on error | |
1394 | */ | |
1395 | int avfilter_graph_parse(AVFilterGraph *graph, const char *filters, | |
1396 | AVFilterInOut *inputs, AVFilterInOut *outputs, | |
1397 | void *log_ctx); | |
1398 | #else | |
1399 | /** | |
1400 | * Add a graph described by a string to a graph. | |
1401 | * | |
1402 | * @param graph the filter graph where to link the parsed graph context | |
1403 | * @param filters string to be parsed | |
1404 | * @param inputs pointer to a linked list to the inputs of the graph, may be NULL. | |
1405 | * If non-NULL, *inputs is updated to contain the list of open inputs | |
1406 | * after the parsing, should be freed with avfilter_inout_free(). | |
1407 | * @param outputs pointer to a linked list to the outputs of the graph, may be NULL. | |
1408 | * If non-NULL, *outputs is updated to contain the list of open outputs | |
1409 | * after the parsing, should be freed with avfilter_inout_free(). | |
1410 | * @return non negative on success, a negative AVERROR code on error | |
1411 | * @deprecated Use avfilter_graph_parse_ptr() instead. | |
1412 | */ | |
1413 | attribute_deprecated | |
1414 | int avfilter_graph_parse(AVFilterGraph *graph, const char *filters, | |
1415 | AVFilterInOut **inputs, AVFilterInOut **outputs, | |
1416 | void *log_ctx); | |
1417 | #endif | |
1418 | ||
1419 | /** | |
1420 | * Add a graph described by a string to a graph. | |
1421 | * | |
1422 | * @param graph the filter graph where to link the parsed graph context | |
1423 | * @param filters string to be parsed | |
1424 | * @param inputs pointer to a linked list to the inputs of the graph, may be NULL. | |
1425 | * If non-NULL, *inputs is updated to contain the list of open inputs | |
1426 | * after the parsing, should be freed with avfilter_inout_free(). | |
1427 | * @param outputs pointer to a linked list to the outputs of the graph, may be NULL. | |
1428 | * If non-NULL, *outputs is updated to contain the list of open outputs | |
1429 | * after the parsing, should be freed with avfilter_inout_free(). | |
1430 | * @return non negative on success, a negative AVERROR code on error | |
1431 | */ | |
1432 | int avfilter_graph_parse_ptr(AVFilterGraph *graph, const char *filters, | |
1433 | AVFilterInOut **inputs, AVFilterInOut **outputs, | |
1434 | void *log_ctx); | |
1435 | ||
1436 | /** | |
1437 | * Add a graph described by a string to a graph. | |
1438 | * | |
1439 | * @param[in] graph the filter graph where to link the parsed graph context | |
1440 | * @param[in] filters string to be parsed | |
1441 | * @param[out] inputs a linked list of all free (unlinked) inputs of the | |
1442 | * parsed graph will be returned here. It is to be freed | |
1443 | * by the caller using avfilter_inout_free(). | |
1444 | * @param[out] outputs a linked list of all free (unlinked) outputs of the | |
1445 | * parsed graph will be returned here. It is to be freed by the | |
1446 | * caller using avfilter_inout_free(). | |
1447 | * @return zero on success, a negative AVERROR code on error | |
1448 | * | |
1449 | * @note This function returns the inputs and outputs that are left | |
1450 | * unlinked after parsing the graph and the caller then deals with | |
1451 | * them. | |
1452 | * @note This function makes no reference whatsoever to already | |
1453 | * existing parts of the graph and the inputs parameter will on return | |
1454 | * contain inputs of the newly parsed part of the graph. Analogously | |
1455 | * the outputs parameter will contain outputs of the newly created | |
1456 | * filters. | |
1457 | */ | |
1458 | int avfilter_graph_parse2(AVFilterGraph *graph, const char *filters, | |
1459 | AVFilterInOut **inputs, | |
1460 | AVFilterInOut **outputs); | |
1461 | ||
1462 | /** | |
1463 | * Send a command to one or more filter instances. | |
1464 | * | |
1465 | * @param graph the filter graph | |
1466 | * @param target the filter(s) to which the command should be sent | |
1467 | * "all" sends to all filters | |
1468 | * otherwise it can be a filter or filter instance name | |
1469 | * which will send the command to all matching filters. | |
1470 | * @param cmd the command to send, for handling simplicity all commands must be alphanumeric only | |
1471 | * @param arg the argument for the command | |
1472 | * @param res a buffer with size res_size where the filter(s) can return a response. | |
1473 | * | |
1474 | * @returns >=0 on success otherwise an error code. | |
1475 | * AVERROR(ENOSYS) on unsupported commands | |
1476 | */ | |
1477 | int avfilter_graph_send_command(AVFilterGraph *graph, const char *target, const char *cmd, const char *arg, char *res, int res_len, int flags); | |
1478 | ||
1479 | /** | |
1480 | * Queue a command for one or more filter instances. | |
1481 | * | |
1482 | * @param graph the filter graph | |
1483 | * @param target the filter(s) to which the command should be sent | |
1484 | * "all" sends to all filters | |
1485 | * otherwise it can be a filter or filter instance name | |
1486 | * which will send the command to all matching filters. | |
1487 | * @param cmd the command to sent, for handling simplicity all commands must be alphanumeric only | |
1488 | * @param arg the argument for the command | |
1489 | * @param ts time at which the command should be sent to the filter | |
1490 | * | |
1491 | * @note As this executes commands after this function returns, no return code | |
1492 | * from the filter is provided, also AVFILTER_CMD_FLAG_ONE is not supported. | |
1493 | */ | |
1494 | int avfilter_graph_queue_command(AVFilterGraph *graph, const char *target, const char *cmd, const char *arg, int flags, double ts); | |
1495 | ||
1496 | ||
1497 | /** | |
1498 | * Dump a graph into a human-readable string representation. | |
1499 | * | |
1500 | * @param graph the graph to dump | |
1501 | * @param options formatting options; currently ignored | |
1502 | * @return a string, or NULL in case of memory allocation failure; | |
1503 | * the string must be freed using av_free | |
1504 | */ | |
1505 | char *avfilter_graph_dump(AVFilterGraph *graph, const char *options); | |
1506 | ||
1507 | /** | |
1508 | * Request a frame on the oldest sink link. | |
1509 | * | |
1510 | * If the request returns AVERROR_EOF, try the next. | |
1511 | * | |
1512 | * Note that this function is not meant to be the sole scheduling mechanism | |
1513 | * of a filtergraph, only a convenience function to help drain a filtergraph | |
1514 | * in a balanced way under normal circumstances. | |
1515 | * | |
1516 | * Also note that AVERROR_EOF does not mean that frames did not arrive on | |
1517 | * some of the sinks during the process. | |
1518 | * When there are multiple sink links, in case the requested link | |
1519 | * returns an EOF, this may cause a filter to flush pending frames | |
1520 | * which are sent to another sink link, although unrequested. | |
1521 | * | |
1522 | * @return the return value of ff_request_frame(), | |
1523 | * or AVERROR_EOF if all links returned AVERROR_EOF | |
1524 | */ | |
1525 | int avfilter_graph_request_oldest(AVFilterGraph *graph); | |
1526 | ||
1527 | /** | |
1528 | * @} | |
1529 | */ | |
1530 | ||
1531 | #endif /* AVFILTER_AVFILTER_H */ |