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