Commit | Line | Data |
---|---|---|
a5cbb2f4 VS |
1 | /* |
2 | * Filter layer | |
3 | * copyright (c) 2007 Bobby Bingham | |
4 | * | |
5 | * This file is part of FFmpeg. | |
6 | * | |
7 | * FFmpeg is free software; you can redistribute it and/or | |
8 | * modify it under the terms of the GNU Lesser General Public | |
9 | * License as published by the Free Software Foundation; either | |
10 | * version 2.1 of the License, or (at your option) any later version. | |
11 | * | |
12 | * FFmpeg is distributed in the hope that it will be useful, | |
13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
15 | * Lesser General Public License for more details. | |
16 | * | |
17 | * You should have received a copy of the GNU Lesser General Public | |
18 | * License along with FFmpeg; if not, write to the Free Software | |
19 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA | |
20 | */ | |
21 | ||
22 | #ifndef FFMPEG_AVFILTER_H | |
23 | #define FFMPEG_AVFILTER_H | |
24 | ||
a9c81431 | 25 | #include <stddef.h> |
a5cbb2f4 VS |
26 | #include "avcodec.h" |
27 | ||
28 | typedef struct AVFilterContext AVFilterContext; | |
29 | typedef struct AVFilterLink AVFilterLink; | |
30 | typedef struct AVFilterPad AVFilterPad; | |
31 | ||
32 | /* TODO: look for other flags which may be useful in this structure (interlace | |
33 | * flags, etc) | |
34 | */ | |
35 | /** | |
36 | * A reference-counted picture data type used by the filter system. Filters | |
37 | * should not store pointers to this structure directly, but instead use the | |
38 | * AVFilterPicRef structure below | |
39 | */ | |
40 | typedef struct AVFilterPic | |
41 | { | |
13ff8fd0 VS |
42 | uint8_t *data[4]; ///< picture data for each plane |
43 | int linesize[4]; ///< number of bytes per line | |
44 | enum PixelFormat format; ///< colorspace | |
a5cbb2f4 | 45 | |
13ff8fd0 VS |
46 | unsigned refcount; ///< number of references to this image |
47 | ||
48 | /** private data to be used by a custom free function */ | |
a5cbb2f4 | 49 | void *priv; |
13ff8fd0 VS |
50 | /** |
51 | * A pointer to the function to deallocate this image if the default | |
52 | * function is not sufficient. This could, for example, add the memory | |
53 | * back into a memory pool to be reused later without the overhead of | |
54 | * reallocating it from scratch. | |
55 | */ | |
a5cbb2f4 VS |
56 | void (*free)(struct AVFilterPic *pic); |
57 | } AVFilterPic; | |
58 | ||
59 | /** | |
60 | * A reference to an AVFilterPic. Since filters can manipulate the origin of | |
61 | * a picture to, for example, crop image without any memcpy, the picture origin | |
bbf42679 VS |
62 | * and dimensions are per-reference properties. Linesize is also useful for |
63 | * image flipping, frame to field filters, etc, and so is also per-reference. | |
a5cbb2f4 | 64 | * |
1a18860a | 65 | * TODO: add anything necessary for frame reordering |
a5cbb2f4 VS |
66 | */ |
67 | typedef struct AVFilterPicRef | |
68 | { | |
13ff8fd0 VS |
69 | AVFilterPic *pic; ///< the picture that this is a reference to |
70 | uint8_t *data[4]; ///< picture data for each plane | |
71 | int linesize[4]; ///< number of bytes per line | |
72 | int w; ///< image width | |
73 | int h; ///< image height | |
a5cbb2f4 | 74 | |
056f0431 | 75 | int64_t pts; ///< presentation timestamp in units of 1/AV_TIME_BASE |
1a18860a | 76 | |
2621f4a3 VS |
77 | AVRational pixel_aspect; ///< pixel aspect ratio |
78 | ||
a5cbb2f4 VS |
79 | int perms; ///< permissions |
80 | #define AV_PERM_READ 0x01 ///< can read from the buffer | |
81 | #define AV_PERM_WRITE 0x02 ///< can write to the buffer | |
82 | #define AV_PERM_PRESERVE 0x04 ///< nobody else can overwrite the buffer | |
b3ab2f7e VS |
83 | #define AV_PERM_REUSE 0x08 ///< can output the buffer multiple times, with the same contents each time |
84 | #define AV_PERM_REUSE2 0x10 ///< can output the buffer multiple times, modified each time | |
a5cbb2f4 VS |
85 | } AVFilterPicRef; |
86 | ||
87 | /** | |
88 | * Add a new reference to a picture. | |
13ff8fd0 VS |
89 | * @param ref An existing reference to the picture |
90 | * @param pmask A bitmask containing the allowable permissions in the new | |
91 | * reference | |
92 | * @return A new reference to the picture with the same properties as the | |
93 | * old, excluding any permissions denied by pmask | |
a5cbb2f4 | 94 | */ |
16415eaf | 95 | AVFilterPicRef *avfilter_ref_pic(AVFilterPicRef *ref, int pmask); |
a5cbb2f4 VS |
96 | |
97 | /** | |
98 | * Remove a reference to a picture. If this is the last reference to the | |
99 | * picture, the picture itself is also automatically freed. | |
100 | * @param ref Reference to the picture. | |
101 | */ | |
102 | void avfilter_unref_pic(AVFilterPicRef *ref); | |
103 | ||
13ff8fd0 VS |
104 | /** |
105 | * A filter pad used for either input or output | |
106 | */ | |
a5cbb2f4 VS |
107 | struct AVFilterPad |
108 | { | |
109 | /** | |
13ff8fd0 VS |
110 | * Pad name. The name is unique among inputs and among outputs, but an |
111 | * input may have the same name as an output. This may be NULL if this | |
112 | * pad has no need to ever be referenced by name. | |
a5cbb2f4 VS |
113 | */ |
114 | char *name; | |
115 | ||
116 | /** | |
117 | * AVFilterPad type. Only video supported now, hopefully someone will | |
118 | * add audio in the future. | |
119 | */ | |
120 | int type; | |
13ff8fd0 | 121 | #define AV_PAD_VIDEO 0 ///< video pad |
a5cbb2f4 VS |
122 | |
123 | /** | |
60bf6ce3 VS |
124 | * Minimum required permissions on incoming buffers. Any buffers with |
125 | * insufficient permissions will be automatically copied by the filter | |
126 | * system to a new buffer which provides the needed access permissions. | |
127 | * | |
128 | * Input pads only. | |
129 | */ | |
130 | int min_perms; | |
131 | ||
132 | /** | |
133 | * Permissions which are not accepted on incoming buffers. Any buffer | |
134 | * which has any of these permissions set be automatically copied by the | |
135 | * filter system to a new buffer which does not have those permissions. | |
136 | * This can be used to easily disallow buffers with AV_PERM_REUSE. | |
137 | * | |
138 | * Input pads only. | |
139 | */ | |
140 | int rej_perms; | |
141 | ||
142 | /** | |
d3e57c15 | 143 | * Callback to get a list of supported formats. The returned list should |
13ff8fd0 VS |
144 | * be terminated by -1 (see avfilter_make_format_list for an easy way to |
145 | * create such a list). | |
146 | * | |
147 | * This is used for both input and output pads. If ommitted from an output | |
148 | * pad, it is assumed that the only format supported is the same format | |
149 | * that is being used for the filter's first input. If the filter has no | |
150 | * inputs, then this may not be ommitted for its output pads. | |
d3e57c15 VS |
151 | */ |
152 | int *(*query_formats)(AVFilterLink *link); | |
153 | ||
154 | /** | |
a5cbb2f4 VS |
155 | * Callback called before passing the first slice of a new frame. If |
156 | * NULL, the filter layer will default to storing a reference to the | |
157 | * picture inside the link structure. | |
13ff8fd0 VS |
158 | * |
159 | * Input video pads only. | |
a5cbb2f4 VS |
160 | */ |
161 | void (*start_frame)(AVFilterLink *link, AVFilterPicRef *picref); | |
162 | ||
163 | /** | |
164 | * Callback function to get a buffer. If NULL, the filter system will | |
13ff8fd0 VS |
165 | * handle buffer requests. |
166 | * | |
167 | * Input video pads only. | |
a5cbb2f4 VS |
168 | */ |
169 | AVFilterPicRef *(*get_video_buffer)(AVFilterLink *link, int perms); | |
170 | ||
171 | /** | |
172 | * Callback called after the slices of a frame are completely sent. If | |
173 | * NULL, the filter layer will default to releasing the reference stored | |
174 | * in the link structure during start_frame(). | |
13ff8fd0 VS |
175 | * |
176 | * Input video pads only. | |
a5cbb2f4 VS |
177 | */ |
178 | void (*end_frame)(AVFilterLink *link); | |
179 | ||
180 | /** | |
181 | * Slice drawing callback. This is where a filter receives video data | |
13ff8fd0 VS |
182 | * and should do its processing. |
183 | * | |
184 | * Input video pads only. | |
a5cbb2f4 | 185 | */ |
72f6d631 | 186 | void (*draw_slice)(AVFilterLink *link, int y, int height); |
a5cbb2f4 VS |
187 | |
188 | /** | |
189 | * Frame request callback. A call to this should result in at least one | |
13ff8fd0 VS |
190 | * frame being output over the given link. This should return zero on |
191 | * success, and another value on error. | |
192 | * | |
193 | * Output video pads only. | |
a5cbb2f4 | 194 | */ |
63f64e6f | 195 | int (*request_frame)(AVFilterLink *link); |
a5cbb2f4 VS |
196 | |
197 | /** | |
13ff8fd0 VS |
198 | * Link configuration callback. |
199 | * | |
200 | * For output pads, this should set the link properties such as | |
201 | * width/height. This should NOT set the format property - that is | |
202 | * negotiated between filters by the filter system using the | |
203 | * query_formats() callback before this function is called. | |
d3e57c15 VS |
204 | * |
205 | * For input pads, this should check the properties of the link, and update | |
206 | * the filter's internal state as necessary. | |
13ff8fd0 VS |
207 | * |
208 | * For both input and output filters, this should return zero on success, | |
209 | * and another value on error. | |
a5cbb2f4 | 210 | */ |
d3e57c15 | 211 | int (*config_props)(AVFilterLink *link); |
a5cbb2f4 VS |
212 | }; |
213 | ||
13ff8fd0 | 214 | /** Default handler for start_frame() for video inputs */ |
a5cbb2f4 | 215 | void avfilter_default_start_frame(AVFilterLink *link, AVFilterPicRef *picref); |
13ff8fd0 | 216 | /** Default handler for end_frame() for video inputs */ |
a5cbb2f4 | 217 | void avfilter_default_end_frame(AVFilterLink *link); |
13ff8fd0 | 218 | /** Default handler for config_props() for video outputs */ |
901e6b39 | 219 | int avfilter_default_config_output_link(AVFilterLink *link); |
13ff8fd0 | 220 | /** Default handler for config_props() for video inputs */ |
85322466 | 221 | int avfilter_default_config_input_link (AVFilterLink *link); |
13ff8fd0 | 222 | /** Default handler for query_formats() for video outputs */ |
901e6b39 | 223 | int *avfilter_default_query_output_formats(AVFilterLink *link); |
13ff8fd0 | 224 | /** Default handler for get_video_buffer() for video inputs */ |
901e6b39 VS |
225 | AVFilterPicRef *avfilter_default_get_video_buffer(AVFilterLink *link, |
226 | int perms); | |
a5cbb2f4 | 227 | |
13ff8fd0 VS |
228 | /** |
229 | * Filter definition. This defines the pads a filter contains, and all the | |
230 | * callback functions used to interact with the filter. | |
231 | */ | |
a5cbb2f4 VS |
232 | typedef struct |
233 | { | |
13ff8fd0 VS |
234 | char *name; ///< filter name |
235 | char *author; ///< filter author | |
a5cbb2f4 | 236 | |
13ff8fd0 | 237 | int priv_size; ///< size of private data to allocate for the filter |
a5cbb2f4 | 238 | |
4d96a914 VS |
239 | /** |
240 | * Filter initialization function. Args contains the user-supplied | |
241 | * parameters. FIXME: maybe an AVOption-based system would be better? | |
6e365c57 VS |
242 | * opaque is data provided by the code requesting creation of the filter, |
243 | * and is used to pass data to the filter. | |
4d96a914 | 244 | */ |
95bcf498 | 245 | int (*init)(AVFilterContext *ctx, const char *args, void *opaque); |
13ff8fd0 VS |
246 | |
247 | /** | |
248 | * Filter uninitialization function. Should deallocate any memory held | |
249 | * by the filter, release any picture references, etc. This does not need | |
250 | * to deallocate the AVFilterContext->priv memory itself. | |
251 | */ | |
a5cbb2f4 VS |
252 | void (*uninit)(AVFilterContext *ctx); |
253 | ||
13ff8fd0 VS |
254 | const AVFilterPad *inputs; ///< NULL terminated list of inputs. NULL if none |
255 | const AVFilterPad *outputs; ///< NULL terminated list of outputs. NULL if none | |
a5cbb2f4 VS |
256 | } AVFilter; |
257 | ||
13ff8fd0 | 258 | /** An instance of a filter */ |
a5cbb2f4 VS |
259 | struct AVFilterContext |
260 | { | |
13ff8fd0 | 261 | AVClass *av_class; ///< Needed for av_log() |
a5cbb2f4 | 262 | |
13ff8fd0 | 263 | AVFilter *filter; ///< The AVFilter of which this is an instance |
a5cbb2f4 | 264 | |
13ff8fd0 | 265 | char *name; ///< name of this filter instance |
dcea2482 | 266 | |
13ff8fd0 VS |
267 | unsigned input_count; ///< number of input pads |
268 | AVFilterPad *input_pads; ///< array of input pads | |
269 | AVFilterLink **inputs; ///< array of pointers to input links | |
25f8e601 | 270 | |
13ff8fd0 VS |
271 | unsigned output_count; ///< number of output pads |
272 | AVFilterPad *output_pads; ///< array of output pads | |
273 | AVFilterLink **outputs; ///< array of pointers to output links | |
a5cbb2f4 | 274 | |
13ff8fd0 | 275 | void *priv; ///< private data for use by the filter |
a5cbb2f4 VS |
276 | }; |
277 | ||
13ff8fd0 VS |
278 | /** |
279 | * A links between two filters. This contains pointers to the source and | |
280 | * destination filters between which this link exists, and the indices of | |
281 | * the pads involved. In addition, this link also contains the parameters | |
282 | * which have been negotiated and agreed upon between the filter, such as | |
283 | * image dimensions, format, etc | |
284 | */ | |
a5cbb2f4 VS |
285 | struct AVFilterLink |
286 | { | |
13ff8fd0 VS |
287 | AVFilterContext *src; ///< source filter |
288 | unsigned int srcpad; ///< index of the output pad on the source filter | |
a5cbb2f4 | 289 | |
13ff8fd0 VS |
290 | AVFilterContext *dst; ///< dest filter |
291 | unsigned int dstpad; ///< index of the input pad on the dest filter | |
a5cbb2f4 | 292 | |
13ff8fd0 VS |
293 | int w; ///< agreed upon image width |
294 | int h; ///< agreed upon image height | |
295 | enum PixelFormat format; ///< agreed upon image colorspace | |
a5cbb2f4 | 296 | |
60bf6ce3 VS |
297 | /** |
298 | * The picture reference currently being sent across the link by the source | |
299 | * filter. This is used internally by the filter system to allow | |
300 | * automatic copying of pictures which d not have sufficient permissions | |
301 | * for the destination. This should not be accessed directly by the | |
302 | * filters. | |
303 | */ | |
304 | AVFilterPicRef *srcpic; | |
305 | ||
a5cbb2f4 | 306 | AVFilterPicRef *cur_pic; |
462f57db | 307 | AVFilterPicRef *outpic; |
a5cbb2f4 VS |
308 | }; |
309 | ||
13ff8fd0 VS |
310 | /** |
311 | * Link two filters together | |
312 | * @param src The source filter | |
313 | * @param srcpad Index of the output pad on the source filter | |
314 | * @param dst The destination filter | |
315 | * @param dstpad Index of the input pad on the destination filter | |
316 | * @return Zero on success | |
317 | */ | |
a5cbb2f4 VS |
318 | int avfilter_link(AVFilterContext *src, unsigned srcpad, |
319 | AVFilterContext *dst, unsigned dstpad); | |
320 | ||
13ff8fd0 VS |
321 | /** |
322 | * Negotiate the colorspace, dimensions, etc of a link | |
323 | * @param link The link to negotiate the properties of | |
324 | * @return Zero on successful negotiation | |
325 | */ | |
85322466 VS |
326 | int avfilter_config_link(AVFilterLink *link); |
327 | ||
13ff8fd0 VS |
328 | /** |
329 | * Request a picture buffer with a specific set of permissions | |
330 | * @param link The output link to the filter from which the picture will | |
331 | * be requested | |
332 | * @param perms The required access permissions | |
333 | * @return A reference to the picture. This must be unreferenced with | |
334 | * avfilter_unref_pic when you are finished with it. | |
335 | */ | |
a5cbb2f4 | 336 | AVFilterPicRef *avfilter_get_video_buffer(AVFilterLink *link, int perms); |
13ff8fd0 VS |
337 | |
338 | /** | |
339 | * Request an input frame from the filter at the other end of the link. | |
340 | * @param link The input link | |
341 | * @return Zero on success | |
342 | */ | |
63f64e6f | 343 | int avfilter_request_frame(AVFilterLink *link); |
13ff8fd0 VS |
344 | |
345 | /** | |
b42a6a92 | 346 | * Notify the next filter of the start of a frame. |
13ff8fd0 VS |
347 | * @param link The output link the frame will be sent over |
348 | * @param picref A reference to the frame about to be sent. The data for this | |
349 | * frame need only be valid once draw_slice() is called for that | |
350 | * portion. The receiving filter will free this reference when | |
351 | * it no longer needs it. | |
352 | */ | |
a5cbb2f4 | 353 | void avfilter_start_frame(AVFilterLink *link, AVFilterPicRef *picref); |
13ff8fd0 VS |
354 | |
355 | /** | |
356 | * Notify the next filter that the current frame has finished | |
357 | * @param link The output link the frame was sent over | |
358 | */ | |
a5cbb2f4 | 359 | void avfilter_end_frame(AVFilterLink *link); |
13ff8fd0 VS |
360 | |
361 | /** | |
362 | * Send a slice to the next filter | |
363 | * @param link The output link over which the frame is being sent | |
13ff8fd0 VS |
364 | * @param y Offset in pixels from the top of the image for this slice |
365 | * @param h Height of this slice in pixels | |
366 | */ | |
72f6d631 | 367 | void avfilter_draw_slice(AVFilterLink *link, int y, int h); |
a5cbb2f4 | 368 | |
13ff8fd0 | 369 | /** Initialize the filter system. Registers all builtin filters */ |
a5cbb2f4 | 370 | void avfilter_init(void); |
13ff8fd0 VS |
371 | |
372 | /** Uninitialize the filter system. Unregisters all filters */ | |
a5cbb2f4 | 373 | void avfilter_uninit(void); |
13ff8fd0 VS |
374 | |
375 | /** | |
fc815c56 VS |
376 | * Register a filter. This is only needed if you plan to use |
377 | * avfilter_get_by_name later to lookup the AVFilter structure by name. A | |
378 | * filter can still by instantiated with avfilter_open even if it is not | |
379 | * registered. | |
13ff8fd0 VS |
380 | * @param filter The filter to register |
381 | */ | |
a5cbb2f4 | 382 | void avfilter_register(AVFilter *filter); |
13ff8fd0 VS |
383 | |
384 | /** | |
385 | * Gets a filter definition matching the given name | |
386 | * @param name The filter name to find | |
387 | * @return The filter definition, if any matching one is registered. | |
388 | * NULL if none found. | |
389 | */ | |
a5cbb2f4 VS |
390 | AVFilter *avfilter_get_by_name(char *name); |
391 | ||
13ff8fd0 VS |
392 | /** |
393 | * Create a filter instance | |
394 | * @param filter The filter to create an instance of | |
395 | * @param inst_name Name to give to the new instance. Can be NULL for none. | |
396 | * @return Pointer to the new instance on success. NULL on failure. | |
397 | */ | |
fc815c56 | 398 | AVFilterContext *avfilter_open(AVFilter *filter, char *inst_name); |
13ff8fd0 VS |
399 | |
400 | /** | |
401 | * Initialize a filter | |
402 | * @param filter The filter to initialize | |
403 | * @param args A string of parameters to use when initializing the filter. | |
404 | * The format and meaning of this string varies by filter. | |
405 | * @param opaque Any extra non-string data needed by the filter. The meaning | |
406 | * of this parameter varies by filter. | |
407 | * @return Zero on success | |
408 | */ | |
6e365c57 | 409 | int avfilter_init_filter(AVFilterContext *filter, const char *args, void *opaque); |
13ff8fd0 VS |
410 | |
411 | /** | |
412 | * Destroy a filter | |
413 | * @param filter The filter to destroy | |
414 | */ | |
a5cbb2f4 VS |
415 | void avfilter_destroy(AVFilterContext *filter); |
416 | ||
13ff8fd0 VS |
417 | /** |
418 | * Helper function to create a list of supported formats. This is intended | |
419 | * for use in AVFilterPad->query_formats(). | |
420 | * @param len The number of formats supported | |
421 | * @param ... A list of the supported formats | |
422 | * @return The format list in a form suitable for returning from | |
423 | * AVFilterPad->query_formats() | |
424 | */ | |
d3e57c15 VS |
425 | int *avfilter_make_format_list(int len, ...); |
426 | ||
a9c81431 VS |
427 | /** |
428 | * Insert a new pad | |
429 | * @param idx Insertion point. Pad is inserted at the end if this point | |
430 | * is beyond the end of the list of pads. | |
431 | * @param count Pointer to the number of pads in the list | |
432 | * @param padidx_off Offset within an AVFilterLink structure to the element | |
433 | * to increment when inserting a new pad causes link | |
434 | * numbering to change | |
435 | * @param pads Pointer to the pointer to the beginning of the list of pads | |
436 | * @param links Pointer to the pointer to the beginning of the list of links | |
437 | * @param newpad The new pad to add. A copy is made when adding. | |
438 | */ | |
439 | void avfilter_insert_pad(unsigned idx, unsigned *count, size_t padidx_off, | |
440 | AVFilterPad **pads, AVFilterLink ***links, | |
441 | AVFilterPad *newpad); | |
442 | ||
443 | /** insert a new input pad for the filter */ | |
444 | static inline void avfilter_insert_inpad(AVFilterContext *f, unsigned index, | |
445 | AVFilterPad *p) | |
446 | { | |
447 | avfilter_insert_pad(index, &f->input_count, offsetof(AVFilterLink, dstpad), | |
448 | &f->input_pads, &f->inputs, p); | |
449 | } | |
450 | ||
451 | /** insert a new output pad for the filter */ | |
452 | static inline void avfilter_insert_outpad(AVFilterContext *f, unsigned index, | |
453 | AVFilterPad *p) | |
454 | { | |
455 | avfilter_insert_pad(index, &f->output_count, offsetof(AVFilterLink, srcpad), | |
456 | &f->output_pads, &f->outputs, p); | |
457 | } | |
458 | ||
a5cbb2f4 | 459 | #endif /* FFMPEG_AVFILTER_H */ |