Mercurial > mplayer.hg
comparison libaf/af.h @ 16627:584bd8980d57
documentation-only patch: make doxygen compatible and create
af_chain and af_filter doxygen modules.
author | reimar |
---|---|
date | Sat, 01 Oct 2005 12:55:34 +0000 |
parents | 9b4bbb6098f6 |
children | 1e188b06ce98 |
comparison
equal
deleted
inserted
replaced
16626:b36b5bb95a9b | 16627:584bd8980d57 |
---|---|
122 | 122 |
123 /********************************************* | 123 /********************************************* |
124 // Export functions | 124 // Export functions |
125 */ | 125 */ |
126 | 126 |
127 /* Initialize the stream "s". This function creates a new filter list | 127 /** |
128 if necessary according to the values set in input and output. Input | 128 * \defgroup af_chain Audio filter chain functions |
129 and output should contain the format of the current movie and the | 129 * \{ |
130 formate of the preferred output respectively. The function is | 130 * \param s filter chain |
131 reentrant i.e. if called with an already initialized stream the | 131 */ |
132 stream will be reinitialized. If the binary parameter | 132 |
133 "force_output" is set, the output format will be converted to the | 133 /** |
134 format given in "s", otherwise the output fromat in the last filter | 134 * \brief Initialize the stream "s". |
135 will be copied "s". The return value is 0 if success and -1 if | 135 * \return 0 on success, -1 on failure |
136 failure */ | 136 * |
137 * This function creates a new filter list if necessary, according | |
138 * to the values set in input and output. Input and output should contain | |
139 * the format of the current movie and the format of the preferred output | |
140 * respectively. | |
141 * Filters to convert to the preferred output format are inserted | |
142 * automatically, except when they are set to 0. | |
143 * The function is reentrant i.e. if called with an already initialized | |
144 * stream the stream will be reinitialized. | |
145 */ | |
137 int af_init(af_stream_t* s); | 146 int af_init(af_stream_t* s); |
138 | 147 |
139 // Uninit and remove all filters | 148 /** |
149 * \brief Uninit and remove all filters from audio filter chain | |
150 */ | |
140 void af_uninit(af_stream_t* s); | 151 void af_uninit(af_stream_t* s); |
141 | 152 |
142 /* Add filter during execution. This function adds the filter "name" | 153 /** |
143 to the stream s. The filter will be inserted somewhere nice in the | 154 * \brief This function adds the filter "name" to the stream s. |
144 list of filters. The return value is a pointer to the new filter, | 155 * \param name name of filter to add |
145 If the filter couldn't be added the return value is NULL. */ | 156 * \return pointer to the new filter, NULL if insert failed |
157 * | |
158 * The filter will be inserted somewhere nice in the | |
159 * list of filters (i.e. at the beginning unless the | |
160 * first filter is the format filter (why??). | |
161 */ | |
146 af_instance_t* af_add(af_stream_t* s, char* name); | 162 af_instance_t* af_add(af_stream_t* s, char* name); |
147 | 163 |
148 // Uninit and remove the filter "af" | 164 /** |
165 * \brief Uninit and remove the filter "af" | |
166 * \param af filter to remove | |
167 */ | |
149 void af_remove(af_stream_t* s, af_instance_t* af); | 168 void af_remove(af_stream_t* s, af_instance_t* af); |
150 | 169 |
151 /* Find filter in the dynamic filter list using it's name This | 170 /** |
152 function is used for finding already initialized filters */ | 171 * \brief find filter in chain by name |
172 * \param name name of the filter to find | |
173 * \return first filter with right name or NULL if not found | |
174 * | |
175 * This function is used for finding already initialized filters | |
176 */ | |
153 af_instance_t* af_get(af_stream_t* s, char* name); | 177 af_instance_t* af_get(af_stream_t* s, char* name); |
154 | 178 |
155 // Filter data chunk through the filters in the list | 179 /** |
180 * \brief filter data chunk through the filters in the list | |
181 * \param data data to play | |
182 * \return resulting data | |
183 * \ingroup af_chain | |
184 */ | |
156 af_data_t* af_play(af_stream_t* s, af_data_t* data); | 185 af_data_t* af_play(af_stream_t* s, af_data_t* data); |
157 | 186 |
158 // send control to all filters, starting with the last until | 187 /** |
159 // one accepts the command with AF_OK. | 188 * \brief send control to all filters, starting with the last until |
160 // Returns the accepting filter or NULL if none was found. | 189 * one accepts the command with AF_OK. |
190 * \param cmd filter control command | |
191 * \param arg argument for filter command | |
192 * \return the accepting filter or NULL if none was found | |
193 */ | |
161 af_instance_t *af_control_any_rev (af_stream_t* s, int cmd, void* arg); | 194 af_instance_t *af_control_any_rev (af_stream_t* s, int cmd, void* arg); |
162 | 195 |
163 /* Calculate how long the output from the filters will be given the | 196 /** |
164 input length "len". The calculated length is >= the actual | 197 * \brief Calculate how long the output from the filters will be for a given |
165 length */ | 198 * input length. |
199 * \param len input lenght for which to calculate output length | |
200 * \return calculated output length, will always be >= the resulting | |
201 * length when actually calling af_play. | |
202 */ | |
166 int af_outputlen(af_stream_t* s, int len); | 203 int af_outputlen(af_stream_t* s, int len); |
167 | 204 |
168 /* Calculate how long the input to the filters should be to produce a | 205 /** |
169 certain output length, i.e. the return value of this function is | 206 * \brief Calculate how long the input to the filters should be to produce a |
170 the input length required to produce the output length "len". The | 207 * certain output length |
171 calculated length is <= the actual length */ | 208 * \param len wanted output length |
209 * \return input length required to produce the output length "len". Possibly | |
210 * smaller to avoid overflow of output buffer | |
211 */ | |
172 int af_inputlen(af_stream_t* s, int len); | 212 int af_inputlen(af_stream_t* s, int len); |
173 | 213 |
174 /* Calculate how long the input IN to the filters should be to produce | 214 /** |
215 * \brief calculate required input length for desired output size | |
216 * \param len desired minimum output length | |
217 * \param max_outsize maximum output length | |
218 * \param max_insize maximum input length | |
219 * \return input length or -1 on error | |
220 * | |
221 Calculate how long the input IN to the filters should be to produce | |
175 a certain output length OUT but with the following three constraints: | 222 a certain output length OUT but with the following three constraints: |
176 1. IN <= max_insize, where max_insize is the maximum possible input | 223 1. IN <= max_insize, where max_insize is the maximum possible input |
177 block length | 224 block length |
178 2. OUT <= max_outsize, where max_outsize is the maximum possible | 225 2. OUT <= max_outsize, where max_outsize is the maximum possible |
179 output block length | 226 output block length |
180 3. If possible OUT >= len. | 227 3. If possible OUT >= len. |
181 Return -1 in case of error */ | 228 */ |
182 int af_calc_insize_constrained(af_stream_t* s, int len, | 229 int af_calc_insize_constrained(af_stream_t* s, int len, |
183 int max_outsize,int max_insize); | 230 int max_outsize,int max_insize); |
184 | 231 |
185 /* Calculate the total delay caused by the filters */ | 232 /** |
233 * \brief Calculate the total delay caused by the filters | |
234 * \return delay in seconds | |
235 */ | |
186 double af_calc_delay(af_stream_t* s); | 236 double af_calc_delay(af_stream_t* s); |
187 | 237 |
238 /** \} */ // end of af_chain group | |
239 | |
188 // Helper functions and macros used inside the audio filters | 240 // Helper functions and macros used inside the audio filters |
241 | |
242 /** | |
243 * \defgroup af_filter Audio filter helper functions | |
244 * \{ | |
245 */ | |
189 | 246 |
190 /* Helper function called by the macro with the same name only to be | 247 /* Helper function called by the macro with the same name only to be |
191 called from inside filters */ | 248 called from inside filters */ |
192 int af_resize_local_buffer(af_instance_t* af, af_data_t* data); | 249 int af_resize_local_buffer(af_instance_t* af, af_data_t* data); |
193 | 250 |
194 /* Helper function used to calculate the exact buffer length needed | 251 /* Helper function used to calculate the exact buffer length needed |
195 when buffers are resized. The returned length is >= than what is | 252 when buffers are resized. The returned length is >= than what is |
196 needed */ | 253 needed */ |
197 int af_lencalc(frac_t mul, af_data_t* data); | 254 int af_lencalc(frac_t mul, af_data_t* data); |
198 | 255 |
199 /* Helper function used to convert to gain value from dB. Returns | 256 /** |
200 AF_OK if of and AF_ERROR if fail */ | 257 * \brief convert dB to gain value |
258 * \param n number of values to convert | |
259 * \param in [in] values in dB, <= -200 will become 0 gain | |
260 * \param out [out] gain values | |
261 * \param k input values are divided by this | |
262 * \param mi minimum dB value, input will be clamped to this | |
263 * \param ma maximum dB value, input will be clamped to this | |
264 * \return AF_ERROR on error, AF_OK otherwise | |
265 */ | |
201 int af_from_dB(int n, float* in, float* out, float k, float mi, float ma); | 266 int af_from_dB(int n, float* in, float* out, float k, float mi, float ma); |
202 /* Helper function used to convert from gain value to dB. Returns | 267 |
203 AF_OK if of and AF_ERROR if fail */ | 268 /** |
269 * \brief convert gain value to dB | |
270 * \param n number of values to convert | |
271 * \param in [in] gain values, 0 wil become -200 dB | |
272 * \param out [out] values in dB | |
273 * \param k output values will be multiplied by this | |
274 * \return AF_ERROR on error, AF_OK otherwise | |
275 */ | |
204 int af_to_dB(int n, float* in, float* out, float k); | 276 int af_to_dB(int n, float* in, float* out, float k); |
205 /* Helper function used to convert from ms to sample time*/ | 277 |
278 /** | |
279 * \brief convert milliseconds to sample time | |
280 * \param n number of values to convert | |
281 * \param in [in] values in milliseconds | |
282 * \param out [out] sample time values | |
283 * \param rate sample rate | |
284 * \param mi minimum ms value, input will be clamped to this | |
285 * \param ma maximum ms value, input will be clamped to this | |
286 * \return AF_ERROR on error, AF_OK otherwise | |
287 */ | |
206 int af_from_ms(int n, float* in, int* out, int rate, float mi, float ma); | 288 int af_from_ms(int n, float* in, int* out, int rate, float mi, float ma); |
207 /* Helper function used to convert from sample time to ms */ | 289 |
290 /** | |
291 * \brief convert sample time to milliseconds | |
292 * \param n number of values to convert | |
293 * \param in [in] sample time values | |
294 * \param out [out] values in milliseconds | |
295 * \param rate sample rate | |
296 * \return AF_ERROR on error, AF_OK otherwise | |
297 */ | |
208 int af_to_ms(int n, int* in, float* out, int rate); | 298 int af_to_ms(int n, int* in, float* out, int rate); |
209 /* Helper function for testing the output format */ | 299 |
300 /** | |
301 * \brief test if output format matches | |
302 * \param af audio filter | |
303 * \param out needed format, will be overwritten by available | |
304 * format if they do not match | |
305 * \return AF_FALSE if formats do not match, AF_OK if they match | |
306 * | |
307 * compares the format, bps, rate and nch values of af->data with out | |
308 */ | |
210 int af_test_output(struct af_instance_s* af, af_data_t* out); | 309 int af_test_output(struct af_instance_s* af, af_data_t* out); |
211 | 310 |
311 /** | |
312 * \brief soft clipping function using sin() | |
313 * \param a input value | |
314 * \return clipped value | |
315 */ | |
212 float af_softclip(float a); | 316 float af_softclip(float a); |
317 | |
318 /** \} */ // end of af_filter group, but more functions of this group below | |
213 | 319 |
214 /** Print a list of all available audio filters */ | 320 /** Print a list of all available audio filters */ |
215 void af_help(void); | 321 void af_help(void); |
216 | 322 |
217 /* Fill the missing parameters in the af_data_t structure. | 323 /** |
218 Used for stuffing bps with a value based on format. */ | 324 * \brief fill the missing parameters in the af_data_t structure |
325 * \param data structure to fill | |
326 * \ingroup af_filter | |
327 * | |
328 * Currently only sets bps based on format | |
329 */ | |
219 void af_fix_parameters(af_data_t *data); | 330 void af_fix_parameters(af_data_t *data); |
220 | 331 |
221 /* Memory reallocation macro: if a local buffer is used (i.e. if the | 332 /** Memory reallocation macro: if a local buffer is used (i.e. if the |
222 filter doesn't operate on the incoming buffer this macro must be | 333 filter doesn't operate on the incoming buffer this macro must be |
223 called to ensure the buffer is big enough. */ | 334 called to ensure the buffer is big enough. |
335 * \ingroup af_filter | |
336 */ | |
224 #define RESIZE_LOCAL_BUFFER(a,d)\ | 337 #define RESIZE_LOCAL_BUFFER(a,d)\ |
225 ((a->data->len < af_lencalc(a->mul,d))?af_resize_local_buffer(a,d):AF_OK) | 338 ((a->data->len < af_lencalc(a->mul,d))?af_resize_local_buffer(a,d):AF_OK) |
226 | 339 |
227 /* Some other useful macro definitions*/ | 340 /* Some other useful macro definitions*/ |
228 #ifndef min | 341 #ifndef min |
255 FILE* msg; // Stream to print information messages to | 368 FILE* msg; // Stream to print information messages to |
256 }af_msg_cfg_t; | 369 }af_msg_cfg_t; |
257 | 370 |
258 extern af_msg_cfg_t af_msg_cfg; // Message | 371 extern af_msg_cfg_t af_msg_cfg; // Message |
259 | 372 |
260 #define AF_MSG_FATAL -3 // Fatal error exit immediately | 373 //! \addtogroup af_filter |
261 #define AF_MSG_ERROR -2 // Error return gracefully | 374 //! \{ |
262 #define AF_MSG_WARN -1 // Print warning but do not exit (can be suppressed) | 375 #define AF_MSG_FATAL -3 ///< Fatal error exit immediately |
263 #define AF_MSG_INFO 0 // Important information | 376 #define AF_MSG_ERROR -2 ///< Error return gracefully |
264 #define AF_MSG_VERBOSE 1 // Print this if verbose is enabled | 377 #define AF_MSG_WARN -1 ///< Print warning but do not exit (can be suppressed) |
265 #define AF_MSG_DEBUG0 2 // Print if very verbose | 378 #define AF_MSG_INFO 0 ///< Important information |
266 #define AF_MSG_DEBUG1 3 // Print if very very verbose | 379 #define AF_MSG_VERBOSE 1 ///< Print this if verbose is enabled |
267 | 380 #define AF_MSG_DEBUG0 2 ///< Print if very verbose |
268 /* Macro for printing error messages */ | 381 #define AF_MSG_DEBUG1 3 ///< Print if very very verbose |
382 | |
383 //! Macro for printing error messages | |
269 #ifndef af_msg | 384 #ifndef af_msg |
270 #define af_msg(lev, args... ) \ | 385 #define af_msg(lev, args... ) \ |
271 (((lev)<AF_MSG_WARN)?(fprintf(af_msg_cfg.err?af_msg_cfg.err:stderr, ## args )): \ | 386 (((lev)<AF_MSG_WARN)?(fprintf(af_msg_cfg.err?af_msg_cfg.err:stderr, ## args )): \ |
272 (((lev)<=af_msg_cfg.level)?(fprintf(af_msg_cfg.msg?af_msg_cfg.msg:stdout, ## args )):0)) | 387 (((lev)<=af_msg_cfg.level)?(fprintf(af_msg_cfg.msg?af_msg_cfg.msg:stdout, ## args )):0)) |
273 #endif | 388 #endif |
389 //! \} | |
274 | 390 |
275 #endif /* __aop_h__ */ | 391 #endif /* __aop_h__ */ |