Commit | Line | Data |
---|---|---|
a5cbb2f4 | 1 | /* |
664f6595 | 2 | * filter layer |
3fa77bde | 3 | * Copyright (c) 2007 Bobby Bingham |
a5cbb2f4 VS |
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 | ||
98790382 SS |
22 | #ifndef AVFILTER_AVFILTER_H |
23 | #define AVFILTER_AVFILTER_H | |
a5cbb2f4 | 24 | |
1f20782c DB |
25 | #include "libavutil/avutil.h" |
26 | ||
0eb4ff9e | 27 | #define LIBAVFILTER_VERSION_MAJOR 1 |
a4dc7aa5 BC |
28 | #define LIBAVFILTER_VERSION_MINOR 68 |
29 | #define LIBAVFILTER_VERSION_MICRO 0 | |
be19d752 VS |
30 | |
31 | #define LIBAVFILTER_VERSION_INT AV_VERSION_INT(LIBAVFILTER_VERSION_MAJOR, \ | |
32 | LIBAVFILTER_VERSION_MINOR, \ | |
33 | LIBAVFILTER_VERSION_MICRO) | |
34 | #define LIBAVFILTER_VERSION AV_VERSION(LIBAVFILTER_VERSION_MAJOR, \ | |
35 | LIBAVFILTER_VERSION_MINOR, \ | |
36 | LIBAVFILTER_VERSION_MICRO) | |
37 | #define LIBAVFILTER_BUILD LIBAVFILTER_VERSION_INT | |
a7d46657 | 38 | |
a9c81431 | 39 | #include <stddef.h> |
245976da | 40 | #include "libavcodec/avcodec.h" |
a5cbb2f4 | 41 | |
540f1c7b | 42 | /** |
49bd8e4b | 43 | * Return the LIBAVFILTER_VERSION_INT constant. |
540f1c7b SS |
44 | */ |
45 | unsigned avfilter_version(void); | |
46 | ||
c1736936 | 47 | /** |
49bd8e4b | 48 | * Return the libavfilter build-time configuration. |
c1736936 | 49 | */ |
41600690 | 50 | const char *avfilter_configuration(void); |
c1736936 DB |
51 | |
52 | /** | |
49bd8e4b | 53 | * Return the libavfilter license. |
c1736936 | 54 | */ |
41600690 | 55 | const char *avfilter_license(void); |
c1736936 DB |
56 | |
57 | ||
a5cbb2f4 VS |
58 | typedef struct AVFilterContext AVFilterContext; |
59 | typedef struct AVFilterLink AVFilterLink; | |
60 | typedef struct AVFilterPad AVFilterPad; | |
61 | ||
a5cbb2f4 | 62 | /** |
32d7bcd4 | 63 | * A reference-counted buffer data type used by the filter system. Filters |
a5cbb2f4 | 64 | * should not store pointers to this structure directly, but instead use the |
ecc8dada | 65 | * AVFilterBufferRef structure below. |
a5cbb2f4 | 66 | */ |
f607cc18 | 67 | typedef struct AVFilterBuffer { |
56b5e9d5 HM |
68 | uint8_t *data[8]; ///< buffer data for each plane/channel |
69 | int linesize[8]; ///< number of bytes per line | |
a5cbb2f4 | 70 | |
32d7bcd4 | 71 | unsigned refcount; ///< number of references to this buffer |
13ff8fd0 VS |
72 | |
73 | /** private data to be used by a custom free function */ | |
a5cbb2f4 | 74 | void *priv; |
13ff8fd0 | 75 | /** |
32d7bcd4 | 76 | * A pointer to the function to deallocate this buffer if the default |
38efe768 | 77 | * function is not sufficient. This could, for example, add the memory |
13ff8fd0 VS |
78 | * back into a memory pool to be reused later without the overhead of |
79 | * reallocating it from scratch. | |
80 | */ | |
32d7bcd4 | 81 | void (*free)(struct AVFilterBuffer *buf); |
f0d77b20 | 82 | } AVFilterBuffer; |
a5cbb2f4 | 83 | |
ff5f1be0 HM |
84 | #define AV_PERM_READ 0x01 ///< can read from the buffer |
85 | #define AV_PERM_WRITE 0x02 ///< can write to the buffer | |
86 | #define AV_PERM_PRESERVE 0x04 ///< nobody else can overwrite the buffer | |
87 | #define AV_PERM_REUSE 0x08 ///< can output the buffer multiple times, with the same contents each time | |
88 | #define AV_PERM_REUSE2 0x10 ///< can output the buffer multiple times, modified each time | |
89 | ||
a5cbb2f4 | 90 | /** |
ad2c9501 HM |
91 | * Audio specific properties in a reference to an AVFilterBuffer. Since |
92 | * AVFilterBufferRef is common to different media formats, audio specific | |
93 | * per reference properties must be separated out. | |
94 | */ | |
95 | typedef struct AVFilterBufferRefAudioProps { | |
96 | int64_t channel_layout; ///< channel layout of audio buffer | |
97 | int samples_nb; ///< number of audio samples | |
98 | int size; ///< audio buffer size | |
99 | uint32_t sample_rate; ///< audio buffer sample rate | |
100 | int planar; ///< audio buffer - planar or packed | |
101 | } AVFilterBufferRefAudioProps; | |
102 | ||
103 | /** | |
cc80caff HM |
104 | * Video specific properties in a reference to an AVFilterBuffer. Since |
105 | * AVFilterBufferRef is common to different media formats, video specific | |
106 | * per reference properties must be separated out. | |
107 | */ | |
f607cc18 | 108 | typedef struct AVFilterBufferRefVideoProps { |
cc80caff HM |
109 | int w; ///< image width |
110 | int h; ///< image height | |
111 | AVRational pixel_aspect; ///< pixel aspect ratio | |
112 | int interlaced; ///< is frame interlaced | |
113 | int top_field_first; ///< field order | |
114 | } AVFilterBufferRefVideoProps; | |
115 | ||
116 | /** | |
f0d77b20 | 117 | * A reference to an AVFilterBuffer. Since filters can manipulate the origin of |
7fce481a | 118 | * a buffer to, for example, crop image without any memcpy, the buffer origin |
38efe768 | 119 | * and dimensions are per-reference properties. Linesize is also useful for |
bbf42679 | 120 | * image flipping, frame to field filters, etc, and so is also per-reference. |
a5cbb2f4 | 121 | * |
1a18860a | 122 | * TODO: add anything necessary for frame reordering |
a5cbb2f4 | 123 | */ |
f607cc18 | 124 | typedef struct AVFilterBufferRef { |
7fce481a | 125 | AVFilterBuffer *buf; ///< the buffer that this is a reference to |
ad2c9501 | 126 | uint8_t *data[8]; ///< picture/audio data for each plane |
c1db7bff | 127 | int linesize[8]; ///< number of bytes per line |
d54e0948 | 128 | int format; ///< media format |
a5cbb2f4 | 129 | |
867ae7aa SS |
130 | /** |
131 | * presentation timestamp. The time unit may change during | |
132 | * filtering, as it is specified in the link and the filter code | |
133 | * may need to rescale the PTS accordingly. | |
134 | */ | |
135 | int64_t pts; | |
5bb5c1dc | 136 | int64_t pos; ///< byte position in stream, -1 if unknown |
1a18860a | 137 | |
ff5f1be0 | 138 | int perms; ///< permissions, see the AV_PERM_* flags |
efdc74ef | 139 | |
cc80caff HM |
140 | enum AVMediaType type; ///< media type of buffer data |
141 | AVFilterBufferRefVideoProps *video; ///< video buffer specific properties | |
ad2c9501 | 142 | AVFilterBufferRefAudioProps *audio; ///< audio buffer specific properties |
ecc8dada | 143 | } AVFilterBufferRef; |
a5cbb2f4 VS |
144 | |
145 | /** | |
ad2c9501 | 146 | * Copy properties of src to dst, without copying the actual data |
4d508e4d | 147 | */ |
7fce481a | 148 | static inline void avfilter_copy_buffer_ref_props(AVFilterBufferRef *dst, AVFilterBufferRef *src) |
4d508e4d | 149 | { |
cc80caff | 150 | // copy common properties |
4d508e4d SS |
151 | dst->pts = src->pts; |
152 | dst->pos = src->pos; | |
cc80caff HM |
153 | |
154 | switch (src->type) { | |
155 | case AVMEDIA_TYPE_VIDEO: *dst->video = *src->video; break; | |
ad2c9501 | 156 | case AVMEDIA_TYPE_AUDIO: *dst->audio = *src->audio; break; |
cc80caff | 157 | } |
4d508e4d SS |
158 | } |
159 | ||
160 | /** | |
7fce481a | 161 | * Add a new reference to a buffer. |
3fa3e4f4 | 162 | * |
7fce481a | 163 | * @param ref an existing reference to the buffer |
664f6595 | 164 | * @param pmask a bitmask containing the allowable permissions in the new |
13ff8fd0 | 165 | * reference |
7fce481a | 166 | * @return a new reference to the buffer with the same properties as the |
13ff8fd0 | 167 | * old, excluding any permissions denied by pmask |
a5cbb2f4 | 168 | */ |
7fce481a | 169 | AVFilterBufferRef *avfilter_ref_buffer(AVFilterBufferRef *ref, int pmask); |
a5cbb2f4 VS |
170 | |
171 | /** | |
7fce481a HM |
172 | * Remove a reference to a buffer. If this is the last reference to the |
173 | * buffer, the buffer itself is also automatically freed. | |
3fa3e4f4 | 174 | * |
7fce481a | 175 | * @param ref reference to the buffer |
a5cbb2f4 | 176 | */ |
7fce481a | 177 | void avfilter_unref_buffer(AVFilterBufferRef *ref); |
a5cbb2f4 | 178 | |
13ff8fd0 | 179 | /** |
35f3fdf4 VS |
180 | * A list of supported formats for one end of a filter link. This is used |
181 | * during the format negotiation process to try to pick the best format to | |
182 | * use to minimize the number of necessary conversions. Each filter gives a | |
183 | * list of the formats supported by each input and output pad. The list | |
184 | * given for each pad need not be distinct - they may be references to the | |
185 | * same list of formats, as is often the case when a filter supports multiple | |
42f72a3a | 186 | * formats, but will always output the same format as it is given in input. |
35f3fdf4 VS |
187 | * |
188 | * In this way, a list of possible input formats and a list of possible | |
189 | * output formats are associated with each link. When a set of formats is | |
190 | * negotiated over a link, the input and output lists are merged to form a | |
191 | * new list containing only the common elements of each list. In the case | |
192 | * that there were no common elements, a format conversion is necessary. | |
193 | * Otherwise, the lists are merged, and all other links which reference | |
194 | * either of the format lists involved in the merge are also affected. | |
195 | * | |
196 | * For example, consider the filter chain: | |
197 | * filter (a) --> (b) filter (b) --> (c) filter | |
198 | * | |
199 | * where the letters in parenthesis indicate a list of formats supported on | |
200 | * the input or output of the link. Suppose the lists are as follows: | |
201 | * (a) = {A, B} | |
202 | * (b) = {A, B, C} | |
203 | * (c) = {B, C} | |
204 | * | |
205 | * First, the first link's lists are merged, yielding: | |
206 | * filter (a) --> (a) filter (a) --> (c) filter | |
207 | * | |
208 | * Notice that format list (b) now refers to the same list as filter list (a). | |
209 | * Next, the lists for the second link are merged, yielding: | |
210 | * filter (a) --> (a) filter (a) --> (a) filter | |
211 | * | |
212 | * where (a) = {B}. | |
213 | * | |
214 | * Unfortunately, when the format lists at the two ends of a link are merged, | |
215 | * we must ensure that all links which reference either pre-merge format list | |
216 | * get updated as well. Therefore, we have the format list structure store a | |
217 | * pointer to each of the pointers to itself. | |
218 | */ | |
f607cc18 | 219 | typedef struct AVFilterFormats { |
35f3fdf4 | 220 | unsigned format_count; ///< number of formats |
bdab614b | 221 | int *formats; ///< list of media formats |
35f3fdf4 VS |
222 | |
223 | unsigned refcount; ///< number of references to this list | |
f607cc18 SS |
224 | struct AVFilterFormats ***refs; ///< references to this list |
225 | } AVFilterFormats;; | |
35f3fdf4 VS |
226 | |
227 | /** | |
49bd8e4b | 228 | * Create a list of supported formats. This is intended for use in |
f6a1fa85 | 229 | * AVFilter->query_formats(). |
3fa3e4f4 | 230 | * |
bdab614b | 231 | * @param fmts list of media formats, terminated by -1 |
f6a1fa85 SS |
232 | * @return the format list, with no existing references |
233 | */ | |
bdab614b | 234 | AVFilterFormats *avfilter_make_format_list(const int *fmts); |
f6a1fa85 SS |
235 | |
236 | /** | |
bdab614b | 237 | * Add fmt to the list of media formats contained in *avff. |
c1d662fd SS |
238 | * If *avff is NULL the function allocates the filter formats struct |
239 | * and puts its pointer in *avff. | |
4fd1f187 SS |
240 | * |
241 | * @return a non negative value in case of success, or a negative | |
242 | * value corresponding to an AVERROR code in case of error | |
243 | */ | |
bdab614b | 244 | int avfilter_add_format(AVFilterFormats **avff, int fmt); |
4fd1f187 SS |
245 | |
246 | /** | |
bdab614b | 247 | * Return a list of all formats supported by FFmpeg for the given media type. |
35f3fdf4 | 248 | */ |
bdab614b | 249 | AVFilterFormats *avfilter_all_formats(enum AVMediaType type); |
35f3fdf4 VS |
250 | |
251 | /** | |
49bd8e4b | 252 | * Return a format list which contains the intersection of the formats of |
39981f53 SS |
253 | * a and b. Also, all the references of a, all the references of b, and |
254 | * a and b themselves will be deallocated. | |
35f3fdf4 VS |
255 | * |
256 | * If a and b do not share any common formats, neither is modified, and NULL | |
257 | * is returned. | |
258 | */ | |
259 | AVFilterFormats *avfilter_merge_formats(AVFilterFormats *a, AVFilterFormats *b); | |
260 | ||
09b63a42 | 261 | /** |
49bd8e4b | 262 | * Add *ref as a new reference to formats. |
09b63a42 MN |
263 | * That is the pointers will point like in the ascii art below: |
264 | * ________ | |
a27c8d5f MN |
265 | * |formats |<--------. |
266 | * | ____ | ____|___________________ | |
267 | * | |refs| | | __|_ | |
268 | * | |* * | | | | | | AVFilterLink | |
09b63a42 | 269 | * | |* *--------->|*ref| |
a27c8d5f MN |
270 | * | |____| | | |____| |
271 | * |________| |________________________ | |
09b63a42 | 272 | */ |
a27c8d5f | 273 | void avfilter_formats_ref(AVFilterFormats *formats, AVFilterFormats **ref); |
35f3fdf4 VS |
274 | |
275 | /** | |
49bd8e4b | 276 | * If *ref is non-NULL, remove *ref as a reference to the format list |
063e7692 SS |
277 | * it currently points to, deallocates that list if this was the last |
278 | * reference, and sets *ref to NULL. | |
a27c8d5f MN |
279 | * |
280 | * Before After | |
281 | * ________ ________ NULL | |
282 | * |formats |<--------. |formats | ^ | |
283 | * | ____ | ____|________________ | ____ | ____|________________ | |
284 | * | |refs| | | __|_ | |refs| | | __|_ | |
285 | * | |* * | | | | | | AVFilterLink | |* * | | | | | | AVFilterLink | |
286 | * | |* *--------->|*ref| | |* | | | |*ref| | |
287 | * | |____| | | |____| | |____| | | |____| | |
288 | * |________| |_____________________ |________| |_____________________ | |
35f3fdf4 VS |
289 | */ |
290 | void avfilter_formats_unref(AVFilterFormats **ref); | |
291 | ||
b9c2fb34 MN |
292 | /** |
293 | * | |
294 | * Before After | |
295 | * ________ ________ | |
a27c8d5f | 296 | * |formats |<---------. |formats |<---------. |
b9c2fb34 MN |
297 | * | ____ | ___|___ | ____ | ___|___ |
298 | * | |refs| | | | | | |refs| | | | | NULL | |
299 | * | |* *--------->|*oldref| | |* *--------->|*newref| ^ | |
300 | * | |* * | | |_______| | |* * | | |_______| ___|___ | |
301 | * | |____| | | |____| | | | | | |
302 | * |________| |________| |*oldref| | |
303 | * |_______| | |
304 | */ | |
eb30e86c MN |
305 | void avfilter_formats_changeref(AVFilterFormats **oldref, |
306 | AVFilterFormats **newref); | |
307 | ||
35f3fdf4 | 308 | /** |
664f6595 | 309 | * A filter pad used for either input or output. |
13ff8fd0 | 310 | */ |
f607cc18 | 311 | struct AVFilterPad { |
a5cbb2f4 | 312 | /** |
38efe768 SS |
313 | * Pad name. The name is unique among inputs and among outputs, but an |
314 | * input may have the same name as an output. This may be NULL if this | |
13ff8fd0 | 315 | * pad has no need to ever be referenced by name. |
a5cbb2f4 | 316 | */ |
2844dd39 | 317 | const char *name; |
a5cbb2f4 VS |
318 | |
319 | /** | |
38efe768 | 320 | * AVFilterPad type. Only video supported now, hopefully someone will |
a5cbb2f4 VS |
321 | * add audio in the future. |
322 | */ | |
72415b2a | 323 | enum AVMediaType type; |
a5cbb2f4 VS |
324 | |
325 | /** | |
38efe768 | 326 | * Minimum required permissions on incoming buffers. Any buffer with |
60bf6ce3 VS |
327 | * insufficient permissions will be automatically copied by the filter |
328 | * system to a new buffer which provides the needed access permissions. | |
329 | * | |
330 | * Input pads only. | |
331 | */ | |
332 | int min_perms; | |
333 | ||
334 | /** | |
38efe768 | 335 | * Permissions which are not accepted on incoming buffers. Any buffer |
9ce95f27 SS |
336 | * which has any of these permissions set will be automatically copied |
337 | * by the filter system to a new buffer which does not have those | |
38efe768 | 338 | * permissions. This can be used to easily disallow buffers with |
9ce95f27 | 339 | * AV_PERM_REUSE. |
60bf6ce3 VS |
340 | * |
341 | * Input pads only. | |
342 | */ | |
343 | int rej_perms; | |
344 | ||
345 | /** | |
38efe768 | 346 | * Callback called before passing the first slice of a new frame. If |
a5cbb2f4 VS |
347 | * NULL, the filter layer will default to storing a reference to the |
348 | * picture inside the link structure. | |
13ff8fd0 VS |
349 | * |
350 | * Input video pads only. | |
a5cbb2f4 | 351 | */ |
ecc8dada | 352 | void (*start_frame)(AVFilterLink *link, AVFilterBufferRef *picref); |
a5cbb2f4 VS |
353 | |
354 | /** | |
ad2c9501 | 355 | * Callback function to get a video buffer. If NULL, the filter system will |
da23d424 | 356 | * use avfilter_default_get_video_buffer(). |
13ff8fd0 VS |
357 | * |
358 | * Input video pads only. | |
a5cbb2f4 | 359 | */ |
ecc8dada | 360 | AVFilterBufferRef *(*get_video_buffer)(AVFilterLink *link, int perms, int w, int h); |
a5cbb2f4 VS |
361 | |
362 | /** | |
ad2c9501 HM |
363 | * Callback function to get an audio buffer. If NULL, the filter system will |
364 | * use avfilter_default_get_audio_buffer(). | |
365 | * | |
366 | * Input audio pads only. | |
367 | */ | |
368 | AVFilterBufferRef *(*get_audio_buffer)(AVFilterLink *link, int perms, | |
5d6e4c16 | 369 | enum AVSampleFormat sample_fmt, int size, |
ad2c9501 HM |
370 | int64_t channel_layout, int planar); |
371 | ||
372 | /** | |
38efe768 | 373 | * Callback called after the slices of a frame are completely sent. If |
a5cbb2f4 VS |
374 | * NULL, the filter layer will default to releasing the reference stored |
375 | * in the link structure during start_frame(). | |
13ff8fd0 VS |
376 | * |
377 | * Input video pads only. | |
a5cbb2f4 VS |
378 | */ |
379 | void (*end_frame)(AVFilterLink *link); | |
380 | ||
381 | /** | |
38efe768 | 382 | * Slice drawing callback. This is where a filter receives video data |
13ff8fd0 VS |
383 | * and should do its processing. |
384 | * | |
385 | * Input video pads only. | |
a5cbb2f4 | 386 | */ |
a13a5437 | 387 | void (*draw_slice)(AVFilterLink *link, int y, int height, int slice_dir); |
a5cbb2f4 VS |
388 | |
389 | /** | |
ad2c9501 HM |
390 | * Samples filtering callback. This is where a filter receives audio data |
391 | * and should do its processing. | |
392 | * | |
393 | * Input audio pads only. | |
394 | */ | |
395 | void (*filter_samples)(AVFilterLink *link, AVFilterBufferRef *samplesref); | |
396 | ||
397 | /** | |
38efe768 | 398 | * Frame poll callback. This returns the number of immediately available |
177477f5 | 399 | * samples. It should return a positive value if the next request_frame() |
d224d73a VS |
400 | * is guaranteed to return one frame (with no delay). |
401 | * | |
402 | * Defaults to just calling the source poll_frame() method. | |
403 | * | |
404 | * Output video pads only. | |
405 | */ | |
406 | int (*poll_frame)(AVFilterLink *link); | |
407 | ||
408 | /** | |
38efe768 SS |
409 | * Frame request callback. A call to this should result in at least one |
410 | * frame being output over the given link. This should return zero on | |
13ff8fd0 VS |
411 | * success, and another value on error. |
412 | * | |
413 | * Output video pads only. | |
a5cbb2f4 | 414 | */ |
63f64e6f | 415 | int (*request_frame)(AVFilterLink *link); |
a5cbb2f4 VS |
416 | |
417 | /** | |
13ff8fd0 VS |
418 | * Link configuration callback. |
419 | * | |
420 | * For output pads, this should set the link properties such as | |
38efe768 | 421 | * width/height. This should NOT set the format property - that is |
13ff8fd0 VS |
422 | * negotiated between filters by the filter system using the |
423 | * query_formats() callback before this function is called. | |
d3e57c15 VS |
424 | * |
425 | * For input pads, this should check the properties of the link, and update | |
426 | * the filter's internal state as necessary. | |
13ff8fd0 VS |
427 | * |
428 | * For both input and output filters, this should return zero on success, | |
429 | * and another value on error. | |
a5cbb2f4 | 430 | */ |
d3e57c15 | 431 | int (*config_props)(AVFilterLink *link); |
a5cbb2f4 VS |
432 | }; |
433 | ||
2b187df9 | 434 | /** default handler for start_frame() for video inputs */ |
ecc8dada | 435 | void avfilter_default_start_frame(AVFilterLink *link, AVFilterBufferRef *picref); |
a4fb0ada | 436 | |
b9609848 | 437 | /** default handler for draw_slice() for video inputs */ |
a13a5437 | 438 | void avfilter_default_draw_slice(AVFilterLink *link, int y, int h, int slice_dir); |
a4fb0ada | 439 | |
2b187df9 | 440 | /** default handler for end_frame() for video inputs */ |
a5cbb2f4 | 441 | void avfilter_default_end_frame(AVFilterLink *link); |
a4fb0ada | 442 | |
ad2c9501 HM |
443 | /** default handler for filter_samples() for audio inputs */ |
444 | void avfilter_default_filter_samples(AVFilterLink *link, AVFilterBufferRef *samplesref); | |
445 | ||
446 | /** default handler for config_props() for audio/video outputs */ | |
901e6b39 | 447 | int avfilter_default_config_output_link(AVFilterLink *link); |
a4fb0ada | 448 | |
ad2c9501 | 449 | /** default handler for config_props() for audio/video inputs */ |
85322466 | 450 | int avfilter_default_config_input_link (AVFilterLink *link); |
a4fb0ada | 451 | |
2b187df9 | 452 | /** default handler for get_video_buffer() for video inputs */ |
ecc8dada | 453 | AVFilterBufferRef *avfilter_default_get_video_buffer(AVFilterLink *link, |
a4fb0ada | 454 | int perms, int w, int h); |
ad2c9501 HM |
455 | |
456 | /** default handler for get_audio_buffer() for audio inputs */ | |
457 | AVFilterBufferRef *avfilter_default_get_audio_buffer(AVFilterLink *link, int perms, | |
5d6e4c16 | 458 | enum AVSampleFormat sample_fmt, int size, |
ad2c9501 HM |
459 | int64_t channel_layout, int planar); |
460 | ||
35f3fdf4 VS |
461 | /** |
462 | * A helper for query_formats() which sets all links to the same list of | |
463 | * formats. If there are no links hooked to this filter, the list of formats is | |
464 | * freed. | |
465 | */ | |
466 | void avfilter_set_common_formats(AVFilterContext *ctx, AVFilterFormats *formats); | |
a4fb0ada | 467 | |
35f3fdf4 VS |
468 | /** Default handler for query_formats() */ |
469 | int avfilter_default_query_formats(AVFilterContext *ctx); | |
a5cbb2f4 | 470 | |
91d1c741 | 471 | /** start_frame() handler for filters which simply pass video along */ |
ecc8dada | 472 | void avfilter_null_start_frame(AVFilterLink *link, AVFilterBufferRef *picref); |
91d1c741 BB |
473 | |
474 | /** draw_slice() handler for filters which simply pass video along */ | |
475 | void avfilter_null_draw_slice(AVFilterLink *link, int y, int h, int slice_dir); | |
476 | ||
477 | /** end_frame() handler for filters which simply pass video along */ | |
478 | void avfilter_null_end_frame(AVFilterLink *link); | |
479 | ||
ad2c9501 HM |
480 | /** filter_samples() handler for filters which simply pass audio along */ |
481 | void avfilter_null_filter_samples(AVFilterLink *link, AVFilterBufferRef *samplesref); | |
482 | ||
91d1c741 | 483 | /** get_video_buffer() handler for filters which simply pass video along */ |
ecc8dada | 484 | AVFilterBufferRef *avfilter_null_get_video_buffer(AVFilterLink *link, |
91d1c741 BB |
485 | int perms, int w, int h); |
486 | ||
ad2c9501 HM |
487 | /** get_audio_buffer() handler for filters which simply pass audio along */ |
488 | AVFilterBufferRef *avfilter_null_get_audio_buffer(AVFilterLink *link, int perms, | |
5d6e4c16 | 489 | enum AVSampleFormat sample_fmt, int size, |
ad2c9501 HM |
490 | int64_t channel_layout, int planar); |
491 | ||
13ff8fd0 | 492 | /** |
38efe768 | 493 | * Filter definition. This defines the pads a filter contains, and all the |
13ff8fd0 VS |
494 | * callback functions used to interact with the filter. |
495 | */ | |
f607cc18 | 496 | typedef struct AVFilter { |
2844dd39 | 497 | const char *name; ///< filter name |
a5cbb2f4 | 498 | |
13ff8fd0 | 499 | int priv_size; ///< size of private data to allocate for the filter |
a5cbb2f4 | 500 | |
4d96a914 | 501 | /** |
38efe768 SS |
502 | * Filter initialization function. Args contains the user-supplied |
503 | * parameters. FIXME: maybe an AVOption-based system would be better? | |
6e365c57 VS |
504 | * opaque is data provided by the code requesting creation of the filter, |
505 | * and is used to pass data to the filter. | |
4d96a914 | 506 | */ |
95bcf498 | 507 | int (*init)(AVFilterContext *ctx, const char *args, void *opaque); |
13ff8fd0 VS |
508 | |
509 | /** | |
38efe768 | 510 | * Filter uninitialization function. Should deallocate any memory held |
7fce481a | 511 | * by the filter, release any buffer references, etc. This does not need |
13ff8fd0 VS |
512 | * to deallocate the AVFilterContext->priv memory itself. |
513 | */ | |
a5cbb2f4 VS |
514 | void (*uninit)(AVFilterContext *ctx); |
515 | ||
35f3fdf4 | 516 | /** |
c4d2e41c | 517 | * Queries formats supported by the filter and its pads, and sets the |
35f3fdf4 VS |
518 | * in_formats for links connected to its output pads, and out_formats |
519 | * for links connected to its input pads. | |
520 | * | |
fe592585 SS |
521 | * @return zero on success, a negative value corresponding to an |
522 | * AVERROR code otherwise | |
35f3fdf4 VS |
523 | */ |
524 | int (*query_formats)(AVFilterContext *); | |
525 | ||
13ff8fd0 VS |
526 | const AVFilterPad *inputs; ///< NULL terminated list of inputs. NULL if none |
527 | const AVFilterPad *outputs; ///< NULL terminated list of outputs. NULL if none | |
cccd292a SS |
528 | |
529 | /** | |
530 | * A description for the filter. You should use the | |
531 | * NULL_IF_CONFIG_SMALL() macro to define it. | |
532 | */ | |
533 | const char *description; | |
a5cbb2f4 VS |
534 | } AVFilter; |
535 | ||
13ff8fd0 | 536 | /** An instance of a filter */ |
f607cc18 | 537 | struct AVFilterContext { |
d42a814e | 538 | const AVClass *av_class; ///< needed for av_log() |
a5cbb2f4 | 539 | |
664f6595 | 540 | AVFilter *filter; ///< the AVFilter of which this is an instance |
a5cbb2f4 | 541 | |
13ff8fd0 | 542 | char *name; ///< name of this filter instance |
dcea2482 | 543 | |
13ff8fd0 VS |
544 | unsigned input_count; ///< number of input pads |
545 | AVFilterPad *input_pads; ///< array of input pads | |
546 | AVFilterLink **inputs; ///< array of pointers to input links | |
25f8e601 | 547 | |
13ff8fd0 VS |
548 | unsigned output_count; ///< number of output pads |
549 | AVFilterPad *output_pads; ///< array of output pads | |
550 | AVFilterLink **outputs; ///< array of pointers to output links | |
a5cbb2f4 | 551 | |
13ff8fd0 | 552 | void *priv; ///< private data for use by the filter |
a5cbb2f4 VS |
553 | }; |
554 | ||
13ff8fd0 | 555 | /** |
38efe768 | 556 | * A link between two filters. This contains pointers to the source and |
f4433de9 | 557 | * destination filters between which this link exists, and the indexes of |
38efe768 | 558 | * the pads involved. In addition, this link also contains the parameters |
13ff8fd0 | 559 | * which have been negotiated and agreed upon between the filter, such as |
2b187df9 | 560 | * image dimensions, format, etc. |
13ff8fd0 | 561 | */ |
f607cc18 | 562 | struct AVFilterLink { |
13ff8fd0 | 563 | AVFilterContext *src; ///< source filter |
acc0490f | 564 | AVFilterPad *srcpad; ///< output pad on the source filter |
a5cbb2f4 | 565 | |
13ff8fd0 | 566 | AVFilterContext *dst; ///< dest filter |
acc0490f | 567 | AVFilterPad *dstpad; ///< input pad on the dest filter |
a5cbb2f4 | 568 | |
24c4eff6 VS |
569 | /** stage of the initialization of the link properties (dimensions, etc) */ |
570 | enum { | |
571 | AVLINK_UNINIT = 0, ///< not started | |
572 | AVLINK_STARTINIT, ///< started, but incomplete | |
573 | AVLINK_INIT ///< complete | |
574 | } init_state; | |
575 | ||
bdab614b HM |
576 | enum AVMediaType type; ///< filter media type |
577 | ||
ad2c9501 | 578 | /* These two parameters apply only to video */ |
13ff8fd0 VS |
579 | int w; ///< agreed upon image width |
580 | int h; ///< agreed upon image height | |
ad2c9501 | 581 | /* These two parameters apply only to audio */ |
63e8d976 | 582 | int64_t channel_layout; ///< channel layout of current buffer (see libavcore/audioconvert.h) |
ad2c9501 HM |
583 | int64_t sample_rate; ///< samples per second |
584 | ||
bdab614b | 585 | int format; ///< agreed upon media format |
a5cbb2f4 | 586 | |
60bf6ce3 | 587 | /** |
35f3fdf4 VS |
588 | * Lists of formats supported by the input and output filters respectively. |
589 | * These lists are used for negotiating the format to actually be used, | |
590 | * which will be loaded into the format member, above, when chosen. | |
591 | */ | |
592 | AVFilterFormats *in_formats; | |
593 | AVFilterFormats *out_formats; | |
594 | ||
595 | /** | |
7fce481a | 596 | * The buffer reference currently being sent across the link by the source |
38efe768 | 597 | * filter. This is used internally by the filter system to allow |
7fce481a | 598 | * automatic copying of buffers which do not have sufficient permissions |
38efe768 | 599 | * for the destination. This should not be accessed directly by the |
60bf6ce3 VS |
600 | * filters. |
601 | */ | |
5d4890d7 | 602 | AVFilterBufferRef *src_buf; |
60bf6ce3 | 603 | |
5d4890d7 HM |
604 | AVFilterBufferRef *cur_buf; |
605 | AVFilterBufferRef *out_buf; | |
867ae7aa SS |
606 | |
607 | /** | |
608 | * Define the time base used by the PTS of the frames/samples | |
609 | * which will pass through this link. | |
610 | * During the configuration stage, each filter is supposed to | |
611 | * change only the output timebase, while the timebase of the | |
612 | * input link is assumed to be an unchangeable property. | |
613 | */ | |
614 | AVRational time_base; | |
a5cbb2f4 VS |
615 | }; |
616 | ||
13ff8fd0 | 617 | /** |
49bd8e4b | 618 | * Link two filters together. |
3fa3e4f4 | 619 | * |
664f6595 VS |
620 | * @param src the source filter |
621 | * @param srcpad index of the output pad on the source filter | |
622 | * @param dst the destination filter | |
623 | * @param dstpad index of the input pad on the destination filter | |
624 | * @return zero on success | |
13ff8fd0 | 625 | */ |
a5cbb2f4 VS |
626 | int avfilter_link(AVFilterContext *src, unsigned srcpad, |
627 | AVFilterContext *dst, unsigned dstpad); | |
628 | ||
13ff8fd0 | 629 | /** |
bdab614b | 630 | * Negotiate the media format, dimensions, etc of all inputs to a filter. |
3fa3e4f4 | 631 | * |
664f6595 VS |
632 | * @param filter the filter to negotiate the properties for its inputs |
633 | * @return zero on successful negotiation | |
13ff8fd0 | 634 | */ |
24c4eff6 | 635 | int avfilter_config_links(AVFilterContext *filter); |
85322466 | 636 | |
13ff8fd0 | 637 | /** |
49bd8e4b | 638 | * Request a picture buffer with a specific set of permissions. |
3fa3e4f4 | 639 | * |
7fce481a | 640 | * @param link the output link to the filter from which the buffer will |
13ff8fd0 | 641 | * be requested |
664f6595 | 642 | * @param perms the required access permissions |
0eb4ff9e SS |
643 | * @param w the minimum width of the buffer to allocate |
644 | * @param h the minimum height of the buffer to allocate | |
7fce481a HM |
645 | * @return A reference to the buffer. This must be unreferenced with |
646 | * avfilter_unref_buffer when you are finished with it. | |
13ff8fd0 | 647 | */ |
ecc8dada | 648 | AVFilterBufferRef *avfilter_get_video_buffer(AVFilterLink *link, int perms, |
0eb4ff9e | 649 | int w, int h); |
13ff8fd0 VS |
650 | |
651 | /** | |
d38c340f SS |
652 | * Create a buffer reference wrapped around an already allocated image |
653 | * buffer. | |
654 | * | |
655 | * @param data pointers to the planes of the image to reference | |
656 | * @param linesize linesizes for the planes of the image to reference | |
657 | * @param perms the required access permissions | |
658 | * @param w the width of the image specified by the data and linesize arrays | |
659 | * @param h the height of the image specified by the data and linesize arrays | |
660 | * @param format the pixel format of the image specified by the data and linesize arrays | |
661 | */ | |
662 | AVFilterBufferRef * | |
663 | avfilter_get_video_buffer_ref_from_arrays(uint8_t *data[4], int linesize[4], int perms, | |
664 | int w, int h, enum PixelFormat format); | |
665 | ||
666 | /** | |
ad2c9501 HM |
667 | * Request an audio samples buffer with a specific set of permissions. |
668 | * | |
669 | * @param link the output link to the filter from which the buffer will | |
670 | * be requested | |
671 | * @param perms the required access permissions | |
672 | * @param sample_fmt the format of each sample in the buffer to allocate | |
673 | * @param size the buffer size in bytes | |
674 | * @param channel_layout the number and type of channels per sample in the buffer to allocate | |
675 | * @param planar audio data layout - planar or packed | |
676 | * @return A reference to the samples. This must be unreferenced with | |
33377121 | 677 | * avfilter_unref_buffer when you are finished with it. |
ad2c9501 HM |
678 | */ |
679 | AVFilterBufferRef *avfilter_get_audio_buffer(AVFilterLink *link, int perms, | |
5d6e4c16 | 680 | enum AVSampleFormat sample_fmt, int size, |
ad2c9501 HM |
681 | int64_t channel_layout, int planar); |
682 | ||
683 | /** | |
49bd8e4b | 684 | * Request an input frame from the filter at the other end of the link. |
3fa3e4f4 | 685 | * |
664f6595 VS |
686 | * @param link the input link |
687 | * @return zero on success | |
13ff8fd0 | 688 | */ |
0155b1a1 | 689 | int avfilter_request_frame(AVFilterLink *link); |
13ff8fd0 VS |
690 | |
691 | /** | |
49bd8e4b | 692 | * Poll a frame from the filter chain. |
3fa3e4f4 | 693 | * |
b04c740a | 694 | * @param link the input link |
055068d0 SS |
695 | * @return the number of immediately available frames, a negative |
696 | * number in case of error | |
b04c740a VS |
697 | */ |
698 | int avfilter_poll_frame(AVFilterLink *link); | |
699 | ||
700 | /** | |
49bd8e4b | 701 | * Notifie the next filter of the start of a frame. |
3fa3e4f4 | 702 | * |
664f6595 | 703 | * @param link the output link the frame will be sent over |
38efe768 | 704 | * @param picref A reference to the frame about to be sent. The data for this |
13ff8fd0 | 705 | * frame need only be valid once draw_slice() is called for that |
38efe768 | 706 | * portion. The receiving filter will free this reference when |
13ff8fd0 VS |
707 | * it no longer needs it. |
708 | */ | |
ecc8dada | 709 | void avfilter_start_frame(AVFilterLink *link, AVFilterBufferRef *picref); |
13ff8fd0 VS |
710 | |
711 | /** | |
49bd8e4b | 712 | * Notifie the next filter that the current frame has finished. |
3fa3e4f4 | 713 | * |
664f6595 | 714 | * @param link the output link the frame was sent over |
13ff8fd0 | 715 | */ |
a5cbb2f4 | 716 | void avfilter_end_frame(AVFilterLink *link); |
13ff8fd0 VS |
717 | |
718 | /** | |
49bd8e4b | 719 | * Send a slice to the next filter. |
bd283738 SS |
720 | * |
721 | * Slices have to be provided in sequential order, either in | |
722 | * top-bottom or bottom-top order. If slices are provided in | |
723 | * non-sequential order the behavior of the function is undefined. | |
724 | * | |
664f6595 VS |
725 | * @param link the output link over which the frame is being sent |
726 | * @param y offset in pixels from the top of the image for this slice | |
727 | * @param h height of this slice in pixels | |
a13a5437 SS |
728 | * @param slice_dir the assumed direction for sending slices, |
729 | * from the top slice to the bottom slice if the value is 1, | |
730 | * from the bottom slice to the top slice if the value is -1, | |
731 | * for other values the behavior of the function is undefined. | |
13ff8fd0 | 732 | */ |
a13a5437 | 733 | void avfilter_draw_slice(AVFilterLink *link, int y, int h, int slice_dir); |
a5cbb2f4 | 734 | |
ad2c9501 HM |
735 | /** |
736 | * Send a buffer of audio samples to the next filter. | |
737 | * | |
738 | * @param link the output link over which the audio samples are being sent | |
739 | * @param samplesref a reference to the buffer of audio samples being sent. The | |
740 | * receiving filter will free this reference when it no longer | |
741 | * needs it or pass it on to the next filter. | |
742 | */ | |
743 | void avfilter_filter_samples(AVFilterLink *link, AVFilterBufferRef *samplesref); | |
744 | ||
49bd8e4b | 745 | /** Initialize the filter system. Register all builtin filters. */ |
11de6cac | 746 | void avfilter_register_all(void); |
e4152452 | 747 | |
49bd8e4b | 748 | /** Uninitialize the filter system. Unregister all filters. */ |
a5cbb2f4 | 749 | void avfilter_uninit(void); |
13ff8fd0 VS |
750 | |
751 | /** | |
49bd8e4b | 752 | * Register a filter. This is only needed if you plan to use |
fc815c56 VS |
753 | * avfilter_get_by_name later to lookup the AVFilter structure by name. A |
754 | * filter can still by instantiated with avfilter_open even if it is not | |
755 | * registered. | |
3fa3e4f4 | 756 | * |
664f6595 | 757 | * @param filter the filter to register |
86a60fa1 SS |
758 | * @return 0 if the registration was succesfull, a negative value |
759 | * otherwise | |
13ff8fd0 | 760 | */ |
86a60fa1 | 761 | int avfilter_register(AVFilter *filter); |
13ff8fd0 VS |
762 | |
763 | /** | |
49bd8e4b | 764 | * Get a filter definition matching the given name. |
3fa3e4f4 | 765 | * |
664f6595 VS |
766 | * @param name the filter name to find |
767 | * @return the filter definition, if any matching one is registered. | |
13ff8fd0 VS |
768 | * NULL if none found. |
769 | */ | |
2844dd39 | 770 | AVFilter *avfilter_get_by_name(const char *name); |
a5cbb2f4 | 771 | |
13ff8fd0 | 772 | /** |
1433c4ab SS |
773 | * If filter is NULL, returns a pointer to the first registered filter pointer, |
774 | * if filter is non-NULL, returns the next pointer after filter. | |
775 | * If the returned pointer points to NULL, the last registered filter | |
776 | * was already reached. | |
777 | */ | |
778 | AVFilter **av_filter_next(AVFilter **filter); | |
779 | ||
780 | /** | |
49bd8e4b | 781 | * Create a filter instance. |
84c03869 SS |
782 | * |
783 | * @param filter_ctx put here a pointer to the created filter context | |
784 | * on success, NULL on failure | |
664f6595 | 785 | * @param filter the filter to create an instance of |
38efe768 | 786 | * @param inst_name Name to give to the new instance. Can be NULL for none. |
84c03869 | 787 | * @return >= 0 in case of success, a negative error code otherwise |
13ff8fd0 | 788 | */ |
84c03869 | 789 | int avfilter_open(AVFilterContext **filter_ctx, AVFilter *filter, const char *inst_name); |
13ff8fd0 VS |
790 | |
791 | /** | |
49bd8e4b | 792 | * Initialize a filter. |
3fa3e4f4 | 793 | * |
664f6595 | 794 | * @param filter the filter to initialize |
13ff8fd0 VS |
795 | * @param args A string of parameters to use when initializing the filter. |
796 | * The format and meaning of this string varies by filter. | |
38efe768 | 797 | * @param opaque Any extra non-string data needed by the filter. The meaning |
13ff8fd0 | 798 | * of this parameter varies by filter. |
664f6595 | 799 | * @return zero on success |
13ff8fd0 | 800 | */ |
6e365c57 | 801 | int avfilter_init_filter(AVFilterContext *filter, const char *args, void *opaque); |
13ff8fd0 VS |
802 | |
803 | /** | |
24de0edb | 804 | * Free a filter context. |
3fa3e4f4 | 805 | * |
24de0edb | 806 | * @param filter the filter to free |
13ff8fd0 | 807 | */ |
24de0edb | 808 | void avfilter_free(AVFilterContext *filter); |
a5cbb2f4 | 809 | |
13ff8fd0 | 810 | /** |
49bd8e4b | 811 | * Insert a filter in the middle of an existing link. |
3fa3e4f4 | 812 | * |
664f6595 VS |
813 | * @param link the link into which the filter should be inserted |
814 | * @param filt the filter to be inserted | |
486adc55 SS |
815 | * @param filt_srcpad_idx the input pad on the filter to connect |
816 | * @param filt_dstpad_idx the output pad on the filter to connect | |
664f6595 | 817 | * @return zero on success |
13ff8fd0 | 818 | */ |
35f3fdf4 | 819 | int avfilter_insert_filter(AVFilterLink *link, AVFilterContext *filt, |
486adc55 | 820 | unsigned filt_srcpad_idx, unsigned filt_dstpad_idx); |
d3e57c15 | 821 | |
a9c81431 | 822 | /** |
49bd8e4b | 823 | * Insert a new pad. |
3fa3e4f4 | 824 | * |
38efe768 | 825 | * @param idx Insertion point. Pad is inserted at the end if this point |
a9c81431 VS |
826 | * is beyond the end of the list of pads. |
827 | * @param count Pointer to the number of pads in the list | |
828 | * @param padidx_off Offset within an AVFilterLink structure to the element | |
829 | * to increment when inserting a new pad causes link | |
830 | * numbering to change | |
831 | * @param pads Pointer to the pointer to the beginning of the list of pads | |
832 | * @param links Pointer to the pointer to the beginning of the list of links | |
833 | * @param newpad The new pad to add. A copy is made when adding. | |
834 | */ | |
835 | void avfilter_insert_pad(unsigned idx, unsigned *count, size_t padidx_off, | |
836 | AVFilterPad **pads, AVFilterLink ***links, | |
837 | AVFilterPad *newpad); | |
838 | ||
49bd8e4b | 839 | /** Insert a new input pad for the filter. */ |
a9c81431 VS |
840 | static inline void avfilter_insert_inpad(AVFilterContext *f, unsigned index, |
841 | AVFilterPad *p) | |
842 | { | |
843 | avfilter_insert_pad(index, &f->input_count, offsetof(AVFilterLink, dstpad), | |
844 | &f->input_pads, &f->inputs, p); | |
845 | } | |
846 | ||
49bd8e4b | 847 | /** Insert a new output pad for the filter. */ |
a9c81431 VS |
848 | static inline void avfilter_insert_outpad(AVFilterContext *f, unsigned index, |
849 | AVFilterPad *p) | |
850 | { | |
851 | avfilter_insert_pad(index, &f->output_count, offsetof(AVFilterLink, srcpad), | |
852 | &f->output_pads, &f->outputs, p); | |
853 | } | |
854 | ||
98790382 | 855 | #endif /* AVFILTER_AVFILTER_H */ |