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