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