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