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 {
  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         /** non-zero if this filter wont' produce any more output */
  79         int eof;
  80         /** pointer to the eof flag of the receiving application */
  81         int *input_eof;
  82         /** pointer to the eof flag of the writing application */
  83         int *output_eof;
  84         /** the task associated with the filter chain */
  85         struct task task;
  86 };
  87
  88 /**
  89  * describes one running instance of a filter
  90 */
  91 struct filter_node {
  92 /**
  93  *
  94  *
  95  * a pointer to the corresponding filter struct
  96  */
  97         struct filter *filter;
  98 /**
  99  *
 100  *
 101  * the filter chain this filter node belongs to
 102  */
 103         struct filter_chain *fc;
 104 /**
 105  *
 106  *
 107  * the position of the filter in the corresponding filter chain
 108  *
 109  * all filters that make up the filter chains are organized in a doubly
 110  * linked list.
 111  */
 112         struct list_head node;
 113 /**
 114  *
 115  *
 116  * each filter may store any filter-specific information about the particular
 117  * instance of the filter here.
 118  */
 119         void *private_data;
 120 /**
 121  *
 122  *
 123  * the output buffer
 124  */
 125         char *buf;
 126 /**
 127  * the size of the output buffer
 128  */
 129         size_t bufsize;
 130 /**
 131  *
 132  *
 133  * the number of bytes currently loaded in \a buf
 134  */
 135         size_t loaded;
 136 /**
 137  *
 138  *
 139  * the list of registered callbacks
 140  */
 141         struct list_head callbacks;
 142 /**
 143  *
 144  * a pointer to the configuration of this instance
 145  */
 146         void *conf;
 147 };
 148
 149 /**
 150  * used to manage grab clients
 151  *
 152  * An application using paraslash's filter subsystem may register any number of
 153  * callbacks for each filter_node. It is possible to attach a filter callback
 154  * while the filter is running. This is used for stream grabbing in
 155  * para_audiod: Whenever a client sends the 'grab' command, para_audiod adds a
 156  * filter callback to the list of callbacks for the filter node specified in
 157  * the grab command.
 158  */
 159 struct filter_callback {
 160 /**
 161  *
 162  *
 163  * all callbacks are organized in a doubly linked list
 164  */
 165         struct list_head node;
 166 /**
 167  *
 168  *
 169  * private data
 170  *
 171  * May be initialized by the application before registering the callback. This
 172  * pointer is not used by the filter subsystem. It is provided for use within
 173  * the input/ouput/close callback functions.
 174  */
 175         void *data;
 176 /**
 177  *
 178  *
 179  * the input callback
 180  *
 181  * In not \p NULL, the filter subsystem calls this function whenever the filter
 182  * consumed some or all of its input buffer. A pointer to the buffer of consumed
 183  * data, its length and a pointer to the own \a filter_callback structure are passed
 184  * to \a input_cb. The input callback is expected to return a negative value on errors.
 185  */
 186         int (*input_cb)(char *buf, size_t len, struct filter_callback *fc);
 187 /**
 188  *
 189  *
 190  * the output callback
 191  *
 192  * If not NULL, this is called whenever the filter produces output. A pointer
 193  * to the output data, its length and a pointer to the own \a filter_callback
 194  * structure are passed to \a output_cb. Like the input callback, the output
 195  * callback is expected to return a negative value on errors.
 196  */
 197         int (*output_cb)(char *buf, size_t len, struct filter_callback *fc);
 198 /**
 199  *
 200  *
 201  * the callback close function
 202  *
 203  * This gets called whenever the input/ouput callback returned an error, or if
 204  * the filter chain is going to be destroyed, e.g. because the end of the
 205  * stream was encounterd. It is assumed to succeed.
 206  */
 207         void (*close)(struct filter_callback *fc);
 208 };
 209
 210
 211 void close_filters(struct filter_chain *fc);
 212 int filter_io(struct filter_chain *fc);
 213 void filter_init(struct filter *all_filters);
 214 int check_filter_arg(char *filter_arg, void **conf);
 215 int del_filter_callback(struct filter_callback *fcb);
 216 void filter_pre_select(struct sched *s, struct task *t);
 217
 218 /**
 219  * the structure associated with a paraslash filter
 220  *
 221  * Paraslash filters are "modules" which are used to transform an audio stream.
 222  * struct filter contains pointers to functions that must be supplied by the
 223  * filter code in order to be used by the driving application (currently
 224  * para_audiod and para_filter).
 225  *
 226  * Note: As several instances of the same filter may be running at the same
 227  * time, all these filter functions must be reentrant; no static non-constant
 228  * variables may be used.
 229  * \sa mp3dec.c, oggdec.c, wav.c, compress.c, filter_node
 230  */
 231 struct filter {
 232 /**
 233  *
 234  *
 235  * the name of the filter
 236  */
 237 const char *name;
 238 /**
 239  *
 240  *
 241  * pointer to the filter init routine
 242  *
 243  * This function is only called once at startup. It must initialize the
 244  * other non-optional function pointers of \a f.
 245  */
 246 void (*init)(struct filter *f);
 247 /**
 248  *
 249  *
 250  * open one instance of this filter
 251  *
 252  * This should allocate the output buffer of the given filter node and do any
 253  * other filter-specific preparations like initializing the private_data member
 254  * of \a fn suitably. The open function is assumed to succeed.
 255  */
 256 void (*open)(struct filter_node *fn);
 257 /**
 258  *
 259  *
 260  * convert (filter) the given data
 261  *
 262  * Pointer to the converting function of the filter. It should convert the
 263  * given input buffer \a inbuf which is of length \a len to the previoulsy
 264  * reserved output buffer of \a fn. On success, it must return the number of
 265  * bytes it consumed from \a inbuf. On errors, a negative number indicating the
 266  * kind of the error must be returned.
 267  *
 268  * A zero return value just means that nothing was converted (probably because
 269  * the input buffer was too small). This is not interpreted as an error.
 270  */
 271 ssize_t (*convert)(char *inbuf, size_t len, struct filter_node *fn);
 272 /**
 273  *
 274  *
 275  * close one instance of this filter
 276  *
 277  * Free all resources of associated with \a fn that were previously allocated
 278  * by the open() function.
 279  */
 280 void (*close)(struct filter_node *fn);
 281 /**
 282  *
 283  *
 284  * print the help text for this filter and exit
 285  *
 286  * This is optional and it is not necessary to initialize this pointer if
 287  * the filter does not have a help text.
 288  */
 289 void (*print_help)(void);
 290 /**
 291  *
 292  *
 293  * a pointer to the filter's command line parser
 294  *
 295  * If this optional function pointer is not NULL, any filter options are passed
 296  * from the main propgram to this command line parser once at application
 297  * startup. The command line parser should check its command line options given
 298  * by \a argc and \a argv and abort on errors. On success, it should return a
 299  * pointer to the filter-specific configuration data determined by \a argc and
 300  * \a argv.
 301  */
 302 void *(*parse_config)(int argc, char **argv);
 303 };
 304 /** \cond */
 305 extern struct filter filters[];
 306 #define DECLARE_EXTERN_FILTER_INIT(name) \
 307         extern void name ## _init(struct filter *f)
 308
 309 #define FILTER_INIT(filter) { \
 310         .name = #filter, \
 311         .init = filter ## _init, \
 312         .parse_config = NULL, \
 313         .print_help = NULL \
 314 },
 315
 316 /* filters that are always present */
 317 DECLARE_EXTERN_FILTER_INIT(wav);
 318 /* wav is always the first filter */
 319 #define WAV_FILTER_NUM 0
 320 DECLARE_EXTERN_FILTER_INIT(compress);
 321
 322 /* next the optional filters */
 323 #ifdef HAVE_MAD
 324 DECLARE_EXTERN_FILTER_INIT(mp3dec);
 325 #define MP3DEC_FILTER FILTER_INIT(mp3dec)
 326 #else
 327 #define MP3DEC_FILTER
 328 #endif
 329
 330 #ifdef HAVE_FAAD
 331 DECLARE_EXTERN_FILTER_INIT(aacdec);
 332 #define AACDEC_FILTER FILTER_INIT(aacdec)
 333 #else
 334 #define AACDEC_FILTER
 335 #endif
 336
 337 #ifdef HAVE_OGGVORBIS
 338 DECLARE_EXTERN_FILTER_INIT(oggdec);
 339 #define OGGDEC_FILTER FILTER_INIT(oggdec)
 340 #else
 341 #define OGGDEC_FILTER
 342 #endif
 343
 344 /*
 345  * a macro that defines an array of all available filters
 346  */
 347 #define DEFINE_FILTER_ARRAY(fa) struct filter fa[] = { \
 348         FILTER_INIT(wav) \
 349         FILTER_INIT(compress) \
 350         MP3DEC_FILTER \
 351         AACDEC_FILTER \
 352         OGGDEC_FILTER \
 353         { .name = NULL } };
 354 /** \endcond */