filter.h

   1 /*
   2  * Copyright (C) 2005 Andre Noll <maan@tuebingen.mpg.de>
   3  *
   4  * Licensed under the GPL v2. For licencing details see COPYING.
   5  */
   6
   7 /** \file filter.h Filter-related structures and exported symbols from filter_common.c. */
   8
   9 /** The list of supported filters. */
  10 enum filter_enum {FILTER_ENUM};
  11
  12 /**
  13  * Describes one running instance of a filter.
  14 */
  15 struct filter_node {
  16         /** The number in the array of available filters. */
  17         unsigned filter_num;
  18         /**
  19          * Each filter may store any filter-specific information about the particular
  20          * instance of the filter here.
  21          */
  22         void *private_data;
  23         /** The list of registered callbacks. */
  24         struct list_head callbacks;
  25         /** A pointer to the configuration of this instance. */
  26         void *conf;
  27         /** The buffer tree node. */
  28         struct btr_node *btrn;
  29         /** The task corresponding to this filter node. */
  30         struct task *task;
  31         /** The minimal input queue size, see \ref btr_node_status(). */
  32         size_t min_iqs;
  33 };
  34
  35 /**
  36  * The structure associated with a paraslash filter.
  37  *
  38  * Paraslash filters are "modules" which are used to transform an audio stream.
  39  * struct filter contains pointers to functions that must be supplied by the
  40  * filter code in order to be used by the driving application (currently
  41  * para_audiod and para_filter).
  42  *
  43  * Note: As several instances of the same filter may be running at the same
  44  * time, all these filter functions must be reentrant; no static non-constant
  45  * variables may be used.
  46  * \sa mp3dec_filter.c, oggdec_filter.c, wav_filter.c, compress_filter.c, filter_node
  47  */
  48 struct filter {
  49         /** The name of the filter. */
  50         const char *name;
  51         /**
  52          * Pointer to the filter init routine.
  53          *
  54          * This function is only called once at startup. It must initialize the
  55          * other non-optional function pointers of this structure.
  56          */
  57         void (*init)(struct filter *f);
  58         /**
  59          * Open one instance of this filter.
  60          *
  61          * This should allocate the output buffer of the given filter node and
  62          * do any other filter-specific preparations like initializing the
  63          * private_data member of \a fn suitably. The open function is
  64          * optional, If it is provided, it is assumed to succeed.
  65          */
  66         void (*open)(struct filter_node *fn);
  67         /**
  68          * Close one instance of this filter.
  69          *
  70          * Free all resources associated with \a fn that were previously
  71          * allocated by the open() function. It's OK to set this to NULL if the
  72          * filter does not need to perform any cleanup operation.
  73          */
  74         void (*close)(struct filter_node *fn);
  75         /**
  76          * A pointer to the filter's command line parser.
  77          *
  78          * If this optional function pointer is not NULL, any filter options
  79          * are passed from the main program to this command line parser once at
  80          * application startup. The command line parser should check its
  81          * command line options given by \a argc and \a argv and abort on
  82          * errors. Success must be indicated by a non-negative return value. In
  83          * this case the function should return a pointer to the
  84          * filter-specific configuration data determined by \a argc and \a
  85          * argv. On failure, a negative paraslash error code must be returned.
  86          */
  87         int (*parse_config)(int argc, char **argv, void **config);
  88         /**
  89          * Deallocate the memory for the configuration.
  90          *
  91          * This is called to free whatever ->parse_config() has allocated.
  92          */
  93         void (*free_config)(void *conf);
  94
  95         /** The help texts for this filter. */
  96         struct ggo_help help;
  97         /**
  98          * Set scheduler timeout and add file descriptors to fd sets.
  99          *
 100          * This function controls the timeout value for the next call to
 101          * select(2). It may decrease the current timeout but shall never
 102          * increase it. The second purpose of this function is to add file
 103          * descriptors to the two fd sets of the sched structure. The
 104          * descriptors in these sets will be watched by the subsequent
 105          * select(2) call.
 106          */
 107         void (*pre_select)(struct sched *s, void *context);
 108         /**
 109          * Convert (filter) the given data.
 110          *
 111          * Pointer to the converting function of the filter. On errors, the
 112          * post_select function is supposed to return a negative error code.
 113          */
 114         int (*post_select)(struct sched *s, void *context);
 115         /**
 116          * Answer a buffer tree query.
 117          *
 118          * This optional function pointer is used for inter node communications
 119          * of the buffer tree nodes. See \ref btr_command_handler for details.
 120          */
 121         btr_command_handler execute;
 122 };
 123
 124 void filter_init(void);
 125 int check_filter_arg(const char *fa, void **conf);
 126 void print_filter_helps(unsigned flags);
 127 void generic_filter_pre_select(struct sched *s, void *context);
 128 int decoder_execute(const char *cmd, unsigned sample_rate, unsigned channels,
 129                 char **result);
 130
 131 static inline void write_int16_host_endian(char *buf, int val)
 132 {
 133 #ifdef WORDS_BIGENDIAN
 134         *buf = val >> 8;
 135         *(buf + 1) = val & 0xff;
 136 #else
 137         *buf = val & 0xff;
 138         *(buf + 1) = val >> 8;
 139 #endif
 140 }
 141
 142 DECLARE_FILTER_INITS
 143
 144 const struct filter *filter_get(int filter_num);