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 *reader_eof;
  82         /** the task associated with the filter chain */
  83         struct task task;
  84 };
  85
  86 /**
  87  * describes one running instance of a filter
  88 */
  89 struct filter_node {
  90 /**
  91  *
  92  *
  93  * a pointer to the corresponding filter struct
  94  */
  95         struct filter *filter;
  96 /**
  97  *
  98  *
  99  * the filter chain this filter node belongs to
 100  */
 101         struct filter_chain *fc;
 102 /**
 103  *
 104  *
 105  * the position of the filter in the corresponding filter chain
 106  *
 107  * all filters that make up the filter chains are organized in a doubly
 108  * linked list.
 109  */
 110         struct list_head node;
 111 /**
 112  *
 113  *
 114  * each filter may store any filter-specific information about the particular
 115  * instance of the filter here.
 116  */
 117         void *private_data;
 118 /**
 119  *
 120  *
 121  * the output buffer
 122  */
 123         char *buf;
 124 /**
 125  * the size of the output buffer
 126  */
 127         size_t bufsize;
 128 /**
 129  *
 130  *
 131  * the number of bytes currently loaded in \a buf
 132  */
 133         size_t loaded;
 134 /**
 135  *
 136  *
 137  * the list of registered callbacks
 138  */
 139         struct list_head callbacks;
 140 /**
 141  *
 142  * a pointer to the configuration of this instance
 143  */
 144         void *conf;
 145 };
 146
 147 /**
 148  * used to manage grab clients
 149  *
 150  * An application using paraslash's filter subsystem may register any number of
 151  * callbacks for each filter_node. It is possible to attach a filter callback
 152  * while the filter is running. This is used for stream grabbing in
 153  * para_audiod: Whenever a client sends the 'grab' command, para_audiod adds a
 154  * filter callback to the list of callbacks for the filter node specified in
 155  * the grab command.
 156  */
 157 struct filter_callback {
 158 /**
 159  *
 160  *
 161  * all callbacks are organized in a doubly linked list
 162  */
 163         struct list_head node;
 164 /**
 165  *
 166  *
 167  * private data
 168  *
 169  * May be initialized by the application before registering the callback. This
 170  * pointer is not used by the filter subsystem. It is provided for use within
 171  * the input/ouput/close callback functions.
 172  */
 173         void *data;
 174 /**
 175  *
 176  *
 177  * the input callback
 178  *
 179  * In not \p NULL, the filter subsystem calls this function whenever the filter
 180  * consumed some or all of its input buffer. A pointer to the buffer of consumed
 181  * data, its length and a pointer to the own \a filter_callback structure are passed
 182  * to \a input_cb. The input callback is expected to return a negative value on errors.
 183  */
 184         int (*input_cb)(char *buf, size_t len, struct filter_callback *fc);
 185 /**
 186  *
 187  *
 188  * the output callback
 189  *
 190  * If not NULL, this is called whenever the filter produces output. A pointer
 191  * to the output data, its length and a pointer to the own \a filter_callback
 192  * structure are passed to \a output_cb. Like the input callback, the output
 193  * callback is expected to return a negative value on errors.
 194  */
 195         int (*output_cb)(char *buf, size_t len, struct filter_callback *fc);
 196 /**
 197  *
 198  *
 199  * the callback close function
 200  *
 201  * This gets called whenever the input/ouput callback returned an error, or if
 202  * the filter chain is going to be destroyed, e.g. because the end of the
 203  * stream was encounterd. It is assumed to succeed.
 204  */
 205         void (*close)(struct filter_callback *fc);
 206 };
 207
 208
 209 void close_filters(struct filter_chain *fc);
 210 int filter_io(struct filter_chain *fc);
 211 void filter_init(struct filter *all_filters);
 212 int check_filter_arg(char *filter_arg, void **conf);
 213 int del_filter_callback(struct filter_callback *fcb);
 214 void filter_pre_select(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
 342 /*
 343  * a macro that defines an array of all available filters
 344  */
 345 #define DEFINE_FILTER_ARRAY(fa) struct filter fa[] = { \
 346         FILTER_INIT(wav) \
 347         FILTER_INIT(compress) \
 348         MP3DEC_FILTER \
 349         AACDEC_FILTER \
 350         OGGDEC_FILTER \
 351         { .name = NULL } };
 352 /** \endcond */