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  * The structure associated with a paraslash filter.
  32  *
  33  * Paraslash filters are "modules" which transform an audio stream. struct
  34  * filter contains methods which are implemented by each filter.
  35  *
  36  * Note: As several instances of the same filter may be running at the same
  37  * time, all these filter functions must be reentrant; no static non-constant
  38  * variables may be used.
  39  *
  40  * \sa \ref filter_node.
  41  */
  42 struct filter {
  43         /**
  44          * Open one instance of this filter.
  45          *
  46          * This should allocate the output buffer of the given filter node and
  47          * do any other filter-specific preparations like initializing the
  48          * private_data member of \a fn suitably. The open function is
  49          * optional, If it is provided, it is assumed to succeed.
  50          */
  51         void (*open)(struct filter_node *fn);
  52         /**
  53          * Close one instance of this filter.
  54          *
  55          * Free all resources associated with \a fn that were previously
  56          * allocated by the open() function. It's OK to set this to NULL if the
  57          * filter does not need to perform any cleanup operation.
  58          */
  59         void (*close)(struct filter_node *fn);
  60         /**
  61          * Prepare the filter according to command line options.
  62          *
  63          * In addition to the syntactic checks which are automatically performed
  64          * by the lopsub functions, some filters like to also check the command
  65          * line arguments semantically. Moreover, since applications may open
  66          * the filter many times with the same options, filters need a method
  67          * which allows them to precompute once those parts of the setup which
  68          * depend only on the command line options.
  69          *
  70          * If this function pointer is not NULL, the function is called once at
  71          * startup. The returned pointer value is made available to the ->open
  72          * method via the ->conf pointer of struct filter_node.
  73          *
  74          * Filters are supposed to abort if the setup fails. If the function
  75          * returns, it is assumed to have succeeded.
  76          */
  77         void *(*setup)(const struct lls_parse_result *lpr);
  78         /**
  79          * Deallocate precomputed resources.
  80          *
  81          * This should free whatever ->setup() has allocated.
  82          */
  83         void (*teardown)(const struct lls_parse_result *lpr, void *conf);
  84         /**
  85          * Set scheduler timeout and add file descriptors to fd sets.
  86          *
  87          * This function controls the timeout value for the next call to
  88          * select(2). It may decrease the current timeout but shall never
  89          * increase it. The second purpose of this function is to add file
  90          * descriptors to the two fd sets of the sched structure. The
  91          * descriptors in these sets will be watched by the subsequent
  92          * select(2) call.
  93          */
  94         void (*pre_select)(struct sched *s, void *context);
  95         /**
  96          * Convert (filter) the given data.
  97          *
  98          * Pointer to the converting function of the filter. On errors, the
  99          * post_select function is supposed to return a negative error code.
 100          */
 101         int (*post_select)(struct sched *s, void *context);
 102         /**
 103          * Answer a buffer tree query.
 104          *
 105          * This optional function pointer is used for inter node communications
 106          * of the buffer tree nodes. See \ref btr_command_handler for details.
 107          */
 108         btr_command_handler execute;
 109 };
 110
 111 void print_filter_helps(bool detailed);
 112 void print_filter_list(void);
 113 int filter_setup(const char *fa, void **conf, struct lls_parse_result **lprp);
 114 #define FILTER_CMD(_num) (lls_cmd(_num, filter_cmd_suite))
 115 #define FILTER_CMD_OPT(_cmd, _opt) (lls_opt( \
 116         LSG_FILTER_CMD_ ## _cmd ## _OPT_ ## _opt, \
 117         FILTER_CMD(LSG_FILTER_CMD_CMD_ ## _cmd)))
 118 #define FILTER_CMD_OPT_RESULT(_cmd, _opt, _lpr) \
 119         (lls_opt_result(LSG_FILTER_CMD_ ## _cmd ## _OPT_ ## _opt, _lpr))
 120 #define FILTER_CMD_OPT_GIVEN(_cmd, _opt, _lpr) \
 121         (lls_opt_given(FILTER_CMD_OPT_RESULT(_cmd, _opt, _lpr)))
 122 #define FILTER_CMD_OPT_UINT32_VAL(_cmd, _opt, _lpr) \
 123         (lls_uint32_val(0, FILTER_CMD_OPT_RESULT(_cmd, _opt, _lpr)))
 124 #define FILTER_CMD_OPT_STRING_VAL(_cmd, _opt, _lpr) \
 125         (lls_string_val(0, FILTER_CMD_OPT_RESULT(_cmd, _opt, _lpr)))
 126
 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 const struct filter *filter_get(int filter_num);
 143 const char *filter_name(int filter_num);