paraslash 0.2.12
[paraslash.git] / filter.h
1 /*
2  * Copyright (C) 2005-2006 Andre Noll <maan@systemlinux.org>
3  *
4  *     This program is free software; you can redistribute it and/or modify
5  *     it under the terms of the GNU General Public License as published by
6  *     the Free Software Foundation; either version 2 of the License, or
7  *     (at your option) any later version.
8  *
9  *     This program is distributed in the hope that it will be useful,
10  *     but WITHOUT ANY WARRANTY; without even the implied warranty of
11  *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  *     GNU General Public License for more details.
13  *
14  *     You should have received a copy of the GNU General Public License
15  *     along with this program; if not, write to the Free Software
16  *     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111, USA.
17  */
18
19 /** \file filter.h filter-related structures and exported symbols from filter_chain.c */
20
21 /**
22  * describes one running instance of a chain of filters
23  *
24  */
25 struct filter_chain_info {
26 /**
27  *
28  *
29  * the number of channels of the current stream
30  *
31  * Set by the decoding filter
32  */
33         unsigned int channels;
34 /**
35  *
36  *
37  * current samplerate in Hz
38  *
39  * Set by the decoding filter
40  */
41         unsigned int samplerate;
42 /**
43  *
44  *
45  * the list containing all filter nodes in this filter chain
46  */
47         struct list_head filters;
48 /**
49  *
50  *
51  * the input buffer of the filter chain
52  *
53  * This is set to point to the output buffer of the receiving application (the
54  * buffer used to read from stdin for para_filter; the output buffer of the
55  * current receiver for para_audiod)
56  */
57         char *inbuf;
58 /**
59  *
60  *
61  * the output buffer of the filter chain
62  *
63  * Points to the output buffer of the last filter in the filter chain
64 **/
65         char *outbuf;
66 /**
67  *
68  *
69  * pointer to variable containing the number of bytes loaded in the input buffer
70  */
71         size_t *in_loaded;
72 /**
73  *
74  *
75  * pointer to variable containing the number of bytes loaded in the output buffer
76  */
77         size_t *out_loaded;
78 /**
79  *
80  *
81  * non-zero if end of file was encountered
82  */
83         int *eof;
84 /**
85  *
86  *
87  * non-zero if an error occured
88  */
89         int error;
90 };
91
92 /**
93  * describes one running instance of a filter
94 */
95 struct filter_node {
96 /**
97  *
98  *
99  * a pointer to the corresponding filter struct
100  */
101         struct filter *filter;
102 /**
103  *
104  *
105  * the filter chain this filter node belongs to
106  */
107         struct filter_chain_info *fci;
108 /**
109  *
110  *
111  * the position of the filter in the corresponding filter chain
112  *
113  * all filters that make up the filter chains are organized in a doubly
114  * linked list.
115  */
116         struct list_head node;
117 /**
118  *
119  *
120  * each filter may store any filter-specific information about the particular
121  * instance of the filter here.
122  */
123         void *private_data;
124 /**
125  *
126  *
127  * the output buffer
128  */
129         char *buf;
130 /**
131  * the size of the output buffer
132  */
133         size_t bufsize;
134 /**
135  *
136  *
137  * the number of bytes currently loaded in \a buf
138  */
139         size_t loaded;
140 /**
141  *
142  *
143  * the list of registered callbacks
144  */
145         struct list_head callbacks;
146 /**
147  *
148  * a pointer to the configuration of this instance
149  */
150         void *conf;
151 };
152
153 /**
154  * used to manage grab clients
155  *
156  * An application using paraslash's filter subsystem may register any number of
157  * callbacks for each filter_node. It is possible to attach a filter callback
158  * while the filter is running. This is used for stream grabbing in
159  * para_audiod: Whenever a client sends the 'grab' command, para_audiod adds a
160  * filter callback to the list of callbacks for the filter node specified in
161  * the grab command.
162  */
163 struct filter_callback {
164 /**
165  *
166  *
167  * all callbacks are organized in a doubly linked list
168  */
169         struct list_head node;
170 /**
171  *
172  *
173  * private data
174  *
175  * May be initialized by the application before registering the callback. This
176  * pointer is not used by the filter subsystem. It is provided for use within
177  * the input/ouput/close callback functions.
178  */
179         void *data;
180 /**
181  *
182  *
183  * the input callback
184  *
185  * In not \p NULL, the filter subsystem calls this function whenever the filter
186  * consumed some or all of its input buffer. A pointer to the buffer of consumed
187  * data, its length and a pointer to the own \a filter_callback structure are passed
188  * to \a input_cb. The input callback is expected to return a negative value on errors.
189  */
190         int (*input_cb)(char *buf, size_t len, struct filter_callback *fc);
191 /**
192  *
193  *
194  * the output callback
195  *
196  * If not NULL, this is called whenever the filter produces output. A pointer
197  * to the output data, its length and a pointer to the own \a filter_callback
198  * structure are passed to \a output_cb. Like the input callback, the output
199  * callback is expected to return a negative value on errors.
200  */
201         int (*output_cb)(char *buf, size_t len, struct filter_callback *fc);
202 /**
203  *
204  *
205  * the callback close function
206  *
207  * This gets called whenever the input/ouput callback returned an error, or if
208  * the filter chain is going to be destroyed, e.g. because the end of the
209  * stream was encounterd. It is assumed to succeed.
210  */
211         void (*close)(struct filter_callback *fc);
212 };
213
214
215 void close_filters(struct filter_chain_info *fci);
216 int filter_io(struct filter_chain_info *fci);
217 void filter_init(struct filter *all_filters);
218 int check_filter_arg(char *filter_arg, void **conf);
219 int del_filter_callback(struct filter_callback *fcb);
220
221 /**
222  * the structure associated with a paraslash filter
223  *
224  * Paraslash filters are "modules" which are used to transform an audio stream.
225  * struct filter contains pointers to functions that must be supplied by the
226  * filter code in order to be used by the driving application (currently
227  * para_audiod and para_filter).
228  *
229  * Note: As several instances of the same filter may be running at the same
230  * time, all these filter functions must be reentrant; no static non-constant
231  * variables may be used.
232  * \sa mp3dec.c, oggdec.c, wav.c, compress.c, filter_node
233  */
234 struct filter {
235 /**
236  *
237  *
238  * the name of the filter
239  */
240 const char *name;
241 /**
242  *
243  *
244  * pointer to the filter init routine
245  *
246  * This function is only called once at startup. It must initialize the
247  * other non-optional function pointers of \a f.
248  */
249 void (*init)(struct filter *f);
250 /**
251  *
252  *
253  * open one instance of this filter
254  *
255  * This should allocate the output buffer of the given filter node and do any
256  * other filter-specific preparations like initializing the private_data member
257  * of \a fn suitably. The open function is assumed to succeed.
258  */
259 void (*open)(struct filter_node *fn);
260 /**
261  *
262  *
263  * convert (filter) the given data
264  *
265  * Pointer to the converting function of the filter. It should convert the
266  * given input buffer \a inbuf which is of length \a len to the previoulsy
267  * reserved output buffer of \a fn. On success, it must return the number of
268  * bytes it consumed from \a inbuf. On errors, a negative number indicating the
269  * kind of the error must be returned.
270  *
271  * A zero return value just means that nothing was converted (probably because
272  * the input buffer was too small). This is not interpreted as an error.
273  */
274 ssize_t (*convert)(char *inbuf, size_t len, struct filter_node *fn);
275 /**
276  *
277  *
278  * close one instance of this filter
279  *
280  * Free all resources of associated with \a fn that were previously allocated
281  * by the open() function.
282  */
283 void (*close)(struct filter_node *fn);
284 /**
285  *
286  *
287  * print the help text for this filter and exit
288  *
289  * This is optional and it is not necessary to initialize this pointer if
290  * the filter does not have a help text.
291  */
292 void (*print_help)(void);
293 /**
294  *
295  *
296  * a pointer to the filter's command line parser
297  *
298  * If this optional function pointer is not NULL, any filter options are passed
299  * from the main propgram to this command line parser once at application
300  * startup. The command line parser should check its command line options given
301  * by \a argc and \a argv and abort on errors. On success, it should return a
302  * pointer to the filter-specific configuration data determined by \a argc and
303  * \a argv.
304  */
305 void *(*parse_config)(int argc, char **argv);
306 };
307 /** \cond */
308 extern struct filter filters[];
309 #define DECLARE_EXTERN_FILTER_INIT(name) \
310         extern void name ## _init(struct filter *f)
311
312 #define FILTER_INIT(filter) { \
313         .name = #filter, \
314         .init = filter ## _init, \
315         .parse_config = NULL, \
316         .print_help = NULL \
317 },
318
319 /* filters that are always present */
320 DECLARE_EXTERN_FILTER_INIT(wav);
321 /* wav is always the first filter */
322 #define WAV_FILTER_NUM 0
323 DECLARE_EXTERN_FILTER_INIT(compress);
324
325 /* next the optional filters */
326 #ifdef HAVE_MAD
327 DECLARE_EXTERN_FILTER_INIT(mp3dec);
328 #define MP3DEC_FILTER FILTER_INIT(mp3dec)
329 #else
330 #define MP3DEC_FILTER
331 #endif
332
333 #ifdef HAVE_OGGVORBIS
334 DECLARE_EXTERN_FILTER_INIT(oggdec);
335 #define OGGDEC_FILTER FILTER_INIT(oggdec)
336 #else
337 #define OGGDEC_FILTER
338 #endif
339
340 /*
341  * a macro that defines an array of all available filters
342  */
343 #define DEFINE_FILTER_ARRAY(fa) struct filter fa[] = { \
344         FILTER_INIT(wav) \
345         FILTER_INIT(compress) \
346         MP3DEC_FILTER \
347         OGGDEC_FILTER \
348         { .name = NULL } };
349 /** \endcond */