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