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 "avcodec.h"
  26
  27 typedef struct AVFilterContext AVFilterContext;
  28 typedef struct AVFilterLink    AVFilterLink;
  29 typedef struct AVFilterPad     AVFilterPad;
  30
  31 /* TODO: look for other flags which may be useful in this structure (interlace
  32  * flags, etc)
  33  */
  34 /**
  35  * A reference-counted picture data type used by the filter system.  Filters
  36  * should not store pointers to this structure directly, but instead use the
  37  * AVFilterPicRef structure below
  38  */
  39 typedef struct AVFilterPic
  40 {
  41     uint8_t *data[4];
  42     int linesize[4];    ///< number of bytes per line
  43     enum PixelFormat format;
  44
  45     unsigned refcount;
  46     void *priv;
  47     void (*free)(struct AVFilterPic *pic);
  48 } AVFilterPic;
  49
  50 /**
  51  * A reference to an AVFilterPic.  Since filters can manipulate the origin of
  52  * a picture to, for example, crop image without any memcpy, the picture origin
  53  * and dimensions are per-reference properties.  Linesize is also useful for
  54  * image flipping, frame to field filters, etc, and so is also per-reference.
  55  *
  56  * TODO: add anything necessary for frame reordering
  57  */
  58 typedef struct AVFilterPicRef
  59 {
  60     AVFilterPic *pic;
  61     uint8_t *data[4];
  62     int linesize[4];
  63     int w, h;
  64
  65     int64_t pts;                ///< presentation timestamp in milliseconds
  66
  67     int perms;                  ///< permissions
  68 #define AV_PERM_READ     0x01   ///< can read from the buffer
  69 #define AV_PERM_WRITE    0x02   ///< can write to the buffer
  70 #define AV_PERM_PRESERVE 0x04   ///< nobody else can overwrite the buffer
  71 #define AV_PERM_REUSE    0x08   ///< can output the buffer multiple times
  72 } AVFilterPicRef;
  73
  74 /**
  75  * Add a new reference to a picture.
  76  * @param ref An existing reference to the picture
  77  * @param pmask A bitmask containing the allowable permissions in the new reference
  78  * @return A new reference to the picture with the same properties as the old
  79  */
  80 AVFilterPicRef *avfilter_ref_pic(AVFilterPicRef *ref, int pmask);
  81
  82 /**
  83  * Remove a reference to a picture.  If this is the last reference to the
  84  * picture, the picture itself is also automatically freed.
  85  * @param ref Reference to the picture.
  86  */
  87 void avfilter_unref_pic(AVFilterPicRef *ref);
  88
  89 struct AVFilterPad
  90 {
  91     /**
  92      * Pad name.  The name is unique among inputs and among oututs, but an
  93      * input may have the same name as an output.
  94      */
  95     char *name;
  96
  97     /**
  98      * AVFilterPad type.  Only video supported now, hopefully someone will
  99      * add audio in the future.
 100      */
 101     int type;
 102 #define AV_PAD_VIDEO 0
 103
 104     /**
 105      * Callback to get a list of supported formats.  The returned list should
 106      * be terminated by -1.  This is used for both input and output pads and
 107      * is required for both.
 108      */
 109     int *(*query_formats)(AVFilterLink *link);
 110
 111     /**
 112      * Callback called before passing the first slice of a new frame.  If
 113      * NULL, the filter layer will default to storing a reference to the
 114      * picture inside the link structure.
 115      */
 116     void (*start_frame)(AVFilterLink *link, AVFilterPicRef *picref);
 117
 118     /**
 119      * Callback function to get a buffer.  If NULL, the filter system will
 120      * handle buffer requests.  Only required for input video pads.
 121      */
 122     AVFilterPicRef *(*get_video_buffer)(AVFilterLink *link, int perms);
 123
 124     /**
 125      * Callback called after the slices of a frame are completely sent.  If
 126      * NULL, the filter layer will default to releasing the reference stored
 127      * in the link structure during start_frame().
 128      */
 129     void (*end_frame)(AVFilterLink *link);
 130
 131     /**
 132      * Slice drawing callback.  This is where a filter receives video data
 133      * and should do its processing.  Only required for input video pads.
 134      */
 135     void (*draw_slice)(AVFilterLink *link, uint8_t *data[4], int y, int height);
 136
 137     /**
 138      * Frame request callback.  A call to this should result in at least one
 139      * frame being output over the given link.  Video output pads only.
 140      */
 141     void (*request_frame)(AVFilterLink *link);
 142
 143     /**
 144      * Link configuration callback.  For output pads, this should set the link
 145      * properties such as width/height.  NOTE: this should not set the format
 146      * property - that is negotiated between filters by the filter system using
 147      * the query_formats() callback.
 148      *
 149      * For input pads, this should check the properties of the link, and update
 150      * the filter's internal state as necessary.
 151      */
 152     int (*config_props)(AVFilterLink *link);
 153 };
 154
 155 /* the default implementations of start_frame() and end_frame() */
 156 void avfilter_default_start_frame(AVFilterLink *link, AVFilterPicRef *picref);
 157 void avfilter_default_end_frame(AVFilterLink *link);
 158
 159 typedef struct
 160 {
 161     char *name;
 162     char *author;
 163
 164     int priv_size;
 165
 166     /**
 167      * Filter initialization function.  Args contains the user-supplied
 168      * parameters.  FIXME: maybe an AVOption-based system would be better?
 169      * opaque is data provided by the code requesting creation of the filter,
 170      * and is used to pass data to the filter.
 171      */
 172     int (*init)(AVFilterContext *ctx, const char *args, const void *opaque);
 173     void (*uninit)(AVFilterContext *ctx);
 174
 175     const AVFilterPad *inputs;  /// NULL terminated list of inputs. NULL if none
 176     const AVFilterPad *outputs; /// NULL terminated list of outputs. NULL if none
 177 } AVFilter;
 178
 179 struct AVFilterContext
 180 {
 181     AVClass *av_class;
 182
 183     AVFilter *filter;
 184
 185     char *name;
 186
 187     AVFilterLink **inputs;
 188     AVFilterLink **outputs;
 189
 190     void *priv;
 191 };
 192
 193 struct AVFilterLink
 194 {
 195     AVFilterContext *src;
 196     unsigned int srcpad;
 197
 198     AVFilterContext *dst;
 199     unsigned int dstpad;
 200
 201     int w, h;
 202     enum PixelFormat format;
 203
 204     AVFilterPicRef *cur_pic;
 205     AVFilterPicRef *outpic;
 206 };
 207
 208 /** Link two filters together */
 209 int avfilter_link(AVFilterContext *src, unsigned srcpad,
 210                   AVFilterContext *dst, unsigned dstpad);
 211
 212 AVFilterPicRef *avfilter_get_video_buffer(AVFilterLink *link, int perms);
 213 void avfilter_request_frame(AVFilterLink *link);
 214 void avfilter_start_frame(AVFilterLink *link, AVFilterPicRef *picref);
 215 void avfilter_end_frame(AVFilterLink *link);
 216 void avfilter_draw_slice(AVFilterLink *link, uint8_t *data[4], int y, int h);
 217
 218 void avfilter_init(void);
 219 void avfilter_uninit(void);
 220 void avfilter_register(AVFilter *filter);
 221 AVFilter *avfilter_get_by_name(char *name);
 222
 223 AVFilterContext *avfilter_create(AVFilter *filter, char *inst_name);
 224 AVFilterContext *avfilter_create_by_name(char *name, char *inst_name);
 225 int avfilter_init_filter(AVFilterContext *filter, const char *args, void *opaque);
 226 void avfilter_destroy(AVFilterContext *filter);
 227
 228 int *avfilter_make_format_list(int len, ...);
 229
 230 #endif  /* FFMPEG_AVFILTER_H */