filter.h

   1 /*
   2  * Copyright (C) 2005-2011 Andre Noll <maan@systemlinux.org>
   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 do any
  62          * other filter-specific preparations like initializing the private_data member
  63          * of \a fn suitably. The open function is assumed to succeed.
  64          */
  65         void (*open)(struct filter_node *fn);
  66         /**
  67          * Close one instance of this filter.
  68          *
  69          * Free all resources of associated with \a fn that were previously allocated
  70          * by the open() function. It's OK to leave this alone if the filter does not
  71          * need any cleanups.
  72          */
  73         void (*close)(struct filter_node *fn);
  74         /**
  75          * A pointer to the filter's command line parser.
  76          *
  77          * If this optional function pointer is not NULL, any filter options
  78          * are passed from the main program to this command line parser once at
  79          * application startup. The command line parser should check its
  80          * command line options given by \a argc and \a argv and abort on
  81          * errors. Success must be indicated by a non-negative return value. In
  82          * this case the function should return a pointer to the
  83          * filter-specific configuration data determined by \a argc and \a
  84          * argv. On failure, a negative paraslash error code must be returned.
  85          */
  86         int (*parse_config)(int argc, char **argv, void **config);
  87         /**
  88          * Deallocate the memory for the configuration.
  89          *
  90          * This is called to free whatever ->parse_config() has allocated.
  91          */
  92         void (*free_config)(void *conf);
  93
  94         /** The help texts for this filter. */
  95         struct ggo_help help;
  96         /**
  97          * Set scheduler timeout and add file descriptors to fd sets.
  98          *
  99          * This function is used to control the timeout value for select. It
 100          * only allowed to decrease the current value. The second purpose of
 101          * this function is to set file descriptors to be watched by the
 102          * subsequent select call to the two fd sets.
 103          */
 104         void (*pre_select)(struct sched *s, struct task *t);
 105         /**
 106          * Convert (filter) the given data.
 107          *
 108          * Pointer to the converting function of the filter. On errors, the
 109          * post_select function is supposed to set t->error to a (negative)
 110          * error code.
 111          */
 112         void (*post_select)(struct sched *s, struct task *t);
 113         /**
 114          * Answer a buffer tree query.
 115          *
 116          * This optional function pointer is used for inter node communications
 117          * of the buffer tree nodes. See \ref btr_command_handler for details.
 118          */
 119         btr_command_handler execute;
 120 };
 121
 122 void filter_init(void);
 123 int check_filter_arg(char *filter_arg, void **conf);
 124 void print_filter_helps(int detailed);
 125 void generic_filter_pre_select(struct sched *s, struct task *t);
 126 int decoder_execute(const char *cmd, unsigned sample_rate, unsigned channels,
 127                 char **result);
 128
 129 static inline void write_int16_host_endian(char *buf, int val)
 130 {
 131 #ifdef WORDS_BIGENDIAN
 132         *buf = val >> 8;
 133         *(buf + 1) = val & 0xff;
 134 #else
 135         *buf = val & 0xff;
 136         *(buf + 1) = val >> 8;
 137 #endif
 138 }
 139
 140 DECLARE_FILTER_INITS
 141
 142 /** Iterate over the array of supported filters. */
 143 #define FOR_EACH_SUPPORTED_FILTER(j)  for (j = 0; j < NUM_SUPPORTED_FILTERS; j++)
 144
 145 /** The filter array, one structure for each supported filter. */
 146 extern struct filter filters[NUM_SUPPORTED_FILTERS];