filter.h

   1 /*
   2  * Copyright (C) 2005-2007 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 void filter_init(struct filter *all_filters);
 213 int check_filter_arg(char *filter_arg, void **conf);
 214 void filter_pre_select(__a_unused struct sched *s, struct task *t);
 215
 216 /**
 217  * the structure associated with a paraslash filter
 218  *
 219  * Paraslash filters are "modules" which are used to transform an audio stream.
 220  * struct filter contains pointers to functions that must be supplied by the
 221  * filter code in order to be used by the driving application (currently
 222  * para_audiod and para_filter).
 223  *
 224  * Note: As several instances of the same filter may be running at the same
 225  * time, all these filter functions must be reentrant; no static non-constant
 226  * variables may be used.
 227  * \sa mp3dec.c, oggdec.c, wav.c, compress.c, filter_node
 228  */
 229 struct filter {
 230 /**
 231  *
 232  *
 233  * the name of the filter
 234  */
 235 const char *name;
 236 /**
 237  *
 238  *
 239  * pointer to the filter init routine
 240  *
 241  * This function is only called once at startup. It must initialize the
 242  * other non-optional function pointers of \a f.
 243  */
 244 void (*init)(struct filter *f);
 245 /**
 246  *
 247  *
 248  * open one instance of this filter
 249  *
 250  * This should allocate the output buffer of the given filter node and do any
 251  * other filter-specific preparations like initializing the private_data member
 252  * of \a fn suitably. The open function is assumed to succeed.
 253  */
 254 void (*open)(struct filter_node *fn);
 255 /**
 256  *
 257  *
 258  * convert (filter) the given data
 259  *
 260  * Pointer to the converting function of the filter. It should convert the
 261  * given input buffer \a inbuf which is of length \a len to the previoulsy
 262  * reserved output buffer of \a fn. On success, it must return the number of
 263  * bytes it consumed from \a inbuf. On errors, a negative number indicating the
 264  * kind of the error must be returned.
 265  *
 266  * A zero return value just means that nothing was converted (probably because
 267  * the input buffer was too small). This is not interpreted as an error.
 268  */
 269 ssize_t (*convert)(char *inbuf, size_t len, struct filter_node *fn);
 270 /**
 271  *
 272  *
 273  * close one instance of this filter
 274  *
 275  * Free all resources of associated with \a fn that were previously allocated
 276  * by the open() function.
 277  */
 278 void (*close)(struct filter_node *fn);
 279 /**
 280  *
 281  *
 282  * print the help text for this filter and exit
 283  *
 284  * This is optional and it is not necessary to initialize this pointer if
 285  * the filter does not have a help text.
 286  */
 287 void (*print_help)(void);
 288 /**
 289  *
 290  *
 291  * a pointer to the filter's command line parser
 292  *
 293  * If this optional function pointer is not NULL, any filter options are passed
 294  * from the main propgram to this command line parser once at application
 295  * startup. The command line parser should check its command line options given
 296  * by \a argc and \a argv and abort on errors. On success, it should return a
 297  * pointer to the filter-specific configuration data determined by \a argc and
 298  * \a argv.
 299  */
 300 void *(*parse_config)(int argc, char **argv);
 301 };
 302 /** \cond */
 303 extern struct filter filters[];
 304 #define DECLARE_EXTERN_FILTER_INIT(name) \
 305         extern void name ## _init(struct filter *f)
 306
 307 #define FILTER_INIT(filter) { \
 308         .name = #filter, \
 309         .init = filter ## _init, \
 310         .parse_config = NULL, \
 311         .print_help = NULL \
 312 },
 313
 314 /* filters that are always present */
 315 DECLARE_EXTERN_FILTER_INIT(wav);
 316 /* wav is always the first filter */
 317 #define WAV_FILTER_NUM 0
 318 DECLARE_EXTERN_FILTER_INIT(compress);
 319
 320 /* next the optional filters */
 321 #ifdef HAVE_MAD
 322 DECLARE_EXTERN_FILTER_INIT(mp3dec);
 323 #define MP3DEC_FILTER FILTER_INIT(mp3dec)
 324 #else
 325 #define MP3DEC_FILTER
 326 #endif
 327
 328 #ifdef HAVE_FAAD
 329 DECLARE_EXTERN_FILTER_INIT(aacdec);
 330 #define AACDEC_FILTER FILTER_INIT(aacdec)
 331 #else
 332 #define AACDEC_FILTER
 333 #endif
 334
 335 #ifdef HAVE_OGGVORBIS
 336 DECLARE_EXTERN_FILTER_INIT(oggdec);
 337 #define OGGDEC_FILTER FILTER_INIT(oggdec)
 338 #else
 339 #define OGGDEC_FILTER
 340 #endif
 341 /** \endcond */
 342
 343 /** define an array of all available filters */
 344 #define DEFINE_FILTER_ARRAY(filters) struct filter filters[] = { \
 345         FILTER_INIT(wav) \
 346         FILTER_INIT(compress) \
 347         MP3DEC_FILTER \
 348         AACDEC_FILTER \
 349         OGGDEC_FILTER \
 350         { .name = NULL } };