filter.h

   1 /* Copyright (C) 2005 Andre Noll <maan@tuebingen.mpg.de>, see file COPYING. */
   2
   3 /** \file filter.h Filter-related structures and exported symbols from filter_common.c. */
   4
   5 /**
   6  * Describes one running instance of a filter.
   7 */
   8 struct filter_node {
   9         /** The number in the array of available filters. */
  10         unsigned filter_num;
  11         /**
  12          * Each filter may store any filter-specific information about the particular
  13          * instance of the filter here.
  14          */
  15         void *private_data;
  16         /** The list of registered callbacks. */
  17         struct list_head callbacks;
  18         /** A pointer to the configuration of this instance. */
  19         void *conf;
  20         /** The parsed command line, merged with options given in the config file. */
  21         struct lls_parse_result *lpr;
  22         /** The buffer tree node. */
  23         struct btr_node *btrn;
  24         /** The task corresponding to this filter node. */
  25         struct task *task;
  26         /** The minimal input queue size, see \ref btr_node_status(). */
  27         size_t min_iqs;
  28 };
  29
  30 /**
  31  * Describes a method to convert audio data.
  32  *
  33  * Paraslash filters are "modules" which transform the data of an audio stream.
  34  * This structure contains the methods which have to be implemented by each
  35  * filter.
  36  *
  37  * As several instances of the same filter may be running at the same time, all
  38  * filter methods must be reentrant and no static non-constant variables must
  39  * be used.
  40  *
  41  * \sa \ref filter_node, struct \ref receiver, struct \ref writer, struct \ref
  42  * sched.
  43  */
  44 struct filter {
  45         /**
  46          * Open one instance of this filter.
  47          *
  48          * This should allocate the output buffer of the given filter node and
  49          * do any other filter-specific preparations like initializing the
  50          * private_data member of \a fn suitably. The open function is
  51          * optional, If it is provided, it is assumed to succeed.
  52          */
  53         void (*open)(struct filter_node *fn);
  54         /**
  55          * Close one instance of this filter.
  56          *
  57          * Free all resources associated with \a fn that were previously
  58          * allocated by the open() function. It's OK to set this to NULL if the
  59          * filter does not need to perform any cleanup operation.
  60          */
  61         void (*close)(struct filter_node *fn);
  62         /**
  63          * Prepare the filter according to command line options.
  64          *
  65          * In addition to the syntactic checks which are automatically performed
  66          * by the lopsub functions, some filters like to also check the command
  67          * line arguments semantically. Moreover, since applications may open
  68          * the filter many times with the same options, filters need a method
  69          * which allows them to precompute once those parts of the setup which
  70          * depend only on the command line options.
  71          *
  72          * If this function pointer is not NULL, the function is called once at
  73          * startup. The returned pointer value is made available to the ->open
  74          * method via the ->conf pointer of struct filter_node.
  75          *
  76          * Filters are supposed to abort if the setup fails. If the function
  77          * returns, it is assumed to have succeeded.
  78          */
  79         void *(*setup)(const struct lls_parse_result *lpr);
  80         /**
  81          * Deallocate precomputed resources.
  82          *
  83          * This should free whatever ->setup() has allocated.
  84          */
  85         void (*teardown)(const struct lls_parse_result *lpr, void *conf);
  86         /** Force a zero timeout if data is available in the buffer tree. */
  87         void (*pre_monitor)(struct sched *s, void *context);
  88         /** Convert (filter) input data into output data. */
  89         int (*post_monitor)(struct sched *s, void *context);
  90         /**
  91          * Answer a buffer tree query.
  92          *
  93          * This optional function pointer is used for inter node communications
  94          * of the buffer tree nodes. See \ref btr_command_handler for details.
  95          */
  96         btr_command_handler execute;
  97 };
  98
  99 void print_filter_helps(bool detailed);
 100 void print_filter_list(void);
 101 int filter_setup(const char *fa, void **conf, struct lls_parse_result **lprp);
 102 #define FILTER_CMD(_num) (lls_cmd(_num, filter_cmd_suite))
 103 #define FILTER_CMD_OPT(_cmd, _opt) (lls_opt( \
 104         LSG_FILTER_CMD_ ## _cmd ## _OPT_ ## _opt, \
 105         FILTER_CMD(LSG_FILTER_CMD_CMD_ ## _cmd)))
 106 #define FILTER_CMD_OPT_RESULT(_cmd, _opt, _lpr) \
 107         (lls_opt_result(LSG_FILTER_CMD_ ## _cmd ## _OPT_ ## _opt, _lpr))
 108 #define FILTER_CMD_OPT_GIVEN(_cmd, _opt, _lpr) \
 109         (lls_opt_given(FILTER_CMD_OPT_RESULT(_cmd, _opt, _lpr)))
 110 #define FILTER_CMD_OPT_UINT32_VAL(_cmd, _opt, _lpr) \
 111         (lls_uint32_val(0, FILTER_CMD_OPT_RESULT(_cmd, _opt, _lpr)))
 112 #define FILTER_CMD_OPT_STRING_VAL(_cmd, _opt, _lpr) \
 113         (lls_string_val(0, FILTER_CMD_OPT_RESULT(_cmd, _opt, _lpr)))
 114
 115 void generic_filter_pre_monitor(struct sched *s, void *context);
 116 int decoder_execute(const char *cmd, unsigned sample_rate, unsigned channels,
 117                 char **result);
 118
 119 static inline void write_int16_host_endian(char *buf, int val)
 120 {
 121 #ifdef WORDS_BIGENDIAN
 122         *buf = val >> 8;
 123         *(buf + 1) = val & 0xff;
 124 #else
 125         *buf = val & 0xff;
 126         *(buf + 1) = val >> 8;
 127 #endif
 128 }
 129
 130 const struct filter *filter_get(int filter_num);
 131 const char *filter_name(int filter_num);