Merge branch 'maint'
[paraslash.git] / 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);