Initial stab at an API
[libav.git] / libavfilter / avfilter.h
CommitLineData
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
25#include "avcodec.h"
26
27typedef struct AVFilterContext AVFilterContext;
28typedef struct AVFilterLink AVFilterLink;
29typedef 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 */
39typedef 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.
54 *
55 * TODO: add pts, and anything necessary for frame reordering
56 */
57typedef struct AVFilterPicRef
58{
59 AVFilterPic *pic;
60 uint8_t *data[4];
61 int w, h;
62
63 int perms; ///< permissions
64#define AV_PERM_READ 0x01 ///< can read from the buffer
65#define AV_PERM_WRITE 0x02 ///< can write to the buffer
66#define AV_PERM_PRESERVE 0x04 ///< nobody else can overwrite the buffer
67#define AV_PERM_REUSE 0x08 ///< can output the buffer multiple times
68} AVFilterPicRef;
69
70/**
71 * Add a new reference to a picture.
72 * @param ref An existing reference to the picture
73 * @return A new reference to the picture with the same properties as the old
74 */
75AVFilterPicRef *avfilter_ref_pic(AVFilterPicRef *ref);
76
77/**
78 * Remove a reference to a picture. If this is the last reference to the
79 * picture, the picture itself is also automatically freed.
80 * @param ref Reference to the picture.
81 */
82void avfilter_unref_pic(AVFilterPicRef *ref);
83
84struct AVFilterPad
85{
86 /**
87 * Pad name. The name is unique among inputs and among oututs, but an
88 * input may have the same name as an output.
89 */
90 char *name;
91
92 /**
93 * AVFilterPad type. Only video supported now, hopefully someone will
94 * add audio in the future.
95 */
96 int type;
97#define AV_PAD_VIDEO 0
98
99 /**
100 * Callback called before passing the first slice of a new frame. If
101 * NULL, the filter layer will default to storing a reference to the
102 * picture inside the link structure.
103 */
104 void (*start_frame)(AVFilterLink *link, AVFilterPicRef *picref);
105
106 /**
107 * Callback function to get a buffer. If NULL, the filter system will
108 * handle buffer requests. Only required for input video pads.
109 */
110 AVFilterPicRef *(*get_video_buffer)(AVFilterLink *link, int perms);
111
112 /**
113 * Callback called after the slices of a frame are completely sent. If
114 * NULL, the filter layer will default to releasing the reference stored
115 * in the link structure during start_frame().
116 */
117 void (*end_frame)(AVFilterLink *link);
118
119 /**
120 * Slice drawing callback. This is where a filter receives video data
121 * and should do its processing. Only required for input video pads.
122 */
123 void (*draw_slice)(AVFilterLink *link, uint8_t *data[4], int y, int height);
124
125 /**
126 * Frame request callback. A call to this should result in at least one
127 * frame being output over the given link. Video output pads only.
128 */
129 void (*request_frame)(AVFilterLink *link);
130
131 /**
132 * Callback to set properties of the link. Only for video output pads.
133 * XXX: this is not acceptable as is. it needs reworked to allow for
134 * negotiation of colorspace, etc.
135 */
136 int (*set_video_props)(AVFilterLink *link);
137};
138
139/* the default implementations of start_frame() and end_frame() */
140void avfilter_default_start_frame(AVFilterLink *link, AVFilterPicRef *picref);
141void avfilter_default_end_frame(AVFilterLink *link);
142
143typedef struct
144{
145 char *name;
146 char *author;
147
148 int priv_size;
149
150 int (*init)(AVFilterContext *ctx);
151 void (*uninit)(AVFilterContext *ctx);
152
153 const AVFilterPad *inputs; /// NULL terminated list of inputs. NULL if none
154 const AVFilterPad *outputs; /// NULL terminated list of outputs. NULL if none
155} AVFilter;
156
157struct AVFilterContext
158{
159 AVClass *av_class;
160
161 AVFilter *filter;
162
163 AVFilterLink **inputs;
164 AVFilterLink **outputs;
165
166 void *priv;
167};
168
169struct AVFilterLink
170{
171 AVFilterContext *src;
172 unsigned int srcpad;
173
174 AVFilterContext *dst;
175 unsigned int dstpad;
176
177 int w, h;
178 enum PixelFormat format;
179
180 AVFilterPicRef *cur_pic;
181};
182
183/** Link two filters together */
184int avfilter_link(AVFilterContext *src, unsigned srcpad,
185 AVFilterContext *dst, unsigned dstpad);
186
187AVFilterPicRef *avfilter_get_video_buffer(AVFilterLink *link, int perms);
188void avfilter_request_frame(AVFilterLink *link);
189void avfilter_start_frame(AVFilterLink *link, AVFilterPicRef *picref);
190void avfilter_end_frame(AVFilterLink *link);
191void avfilter_draw_slice(AVFilterLink *link, uint8_t *data[4], int y, int h);
192
193void avfilter_init(void);
194void avfilter_uninit(void);
195void avfilter_register(AVFilter *filter);
196AVFilter *avfilter_get_by_name(char *name);
197
198AVFilterContext *avfilter_create(AVFilter *filter);
199AVFilterContext *avfilter_create_by_name(char *name);
200int avfilter_init_filter(AVFilterContext *filter);
201void avfilter_destroy(AVFilterContext *filter);
202
203#endif /* FFMPEG_AVFILTER_H */