libaf/af.h

   1 /*
   2  * This file is part of MPlayer.
   3  *
   4  * MPlayer is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation; either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * MPlayer is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License along
  15  * with MPlayer; if not, write to the Free Software Foundation, Inc.,
  16  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  17  */
  18
  19 #ifndef MPLAYER_AF_H
  20 #define MPLAYER_AF_H
  21
  22 #include <stdio.h>
  23
  24 #include "config.h"
  25 #include "af_mp.h"
  26 #include "control.h"
  27 #include "af_format.h"
  28
  29 struct af_instance_s;
  30
  31 // Number of channels
  32 #ifndef AF_NCH
  33 #define AF_NCH 6
  34 #endif
  35
  36 // Audio data chunk
  37 typedef struct af_data_s
  38 {
  39   void* audio;  // data buffer
  40   int len;      // buffer length
  41   int rate;     // sample rate
  42   int nch;      // number of channels
  43   int format;   // format
  44   int bps;      // bytes per sample
  45 } af_data_t;
  46
  47
  48 // Flags used for defining the behavior of an audio filter
  49 #define AF_FLAGS_REENTRANT      0x00000000
  50 #define AF_FLAGS_NOT_REENTRANT  0x00000001
  51
  52 /* Audio filter information not specific for current instance, but for
  53    a specific filter */
  54 typedef struct af_info_s
  55 {
  56   const char *info;
  57   const char *name;
  58   const char *author;
  59   const char *comment;
  60   const int flags;
  61   int (*open)(struct af_instance_s* vf);
  62 } af_info_t;
  63
  64 // Linked list of audio filters
  65 typedef struct af_instance_s
  66 {
  67   af_info_t* info;
  68   int (*control)(struct af_instance_s* af, int cmd, void* arg);
  69   void (*uninit)(struct af_instance_s* af);
  70   af_data_t* (*play)(struct af_instance_s* af, af_data_t* data);
  71   void* setup;    // setup data for this specific instance and filter
  72   af_data_t* data; // configuration for outgoing data stream
  73   struct af_instance_s* next;
  74   struct af_instance_s* prev;
  75   double delay; /* Delay caused by the filter, in units of bytes read without
  76                  * corresponding output */
  77   double mul; /* length multiplier: how much does this instance change
  78                  the length of the buffer. */
  79 }af_instance_t;
  80
  81 // Initialization flags
  82 extern int* af_cpu_speed;
  83
  84 #define AF_INIT_AUTO            0x00000000
  85 #define AF_INIT_SLOW            0x00000001
  86 #define AF_INIT_FAST            0x00000002
  87 #define AF_INIT_FORCE           0x00000003
  88 #define AF_INIT_TYPE_MASK       0x00000003
  89
  90 #define AF_INIT_INT             0x00000000
  91 #define AF_INIT_FLOAT           0x00000004
  92 #define AF_INIT_FORMAT_MASK     0x00000004
  93
  94 // Default init type
  95 #ifndef AF_INIT_TYPE
  96 #if HAVE_SSE || HAVE_AMD3DNOW
  97 #define AF_INIT_TYPE (af_cpu_speed?*af_cpu_speed:AF_INIT_FAST)
  98 #else
  99 #define AF_INIT_TYPE (af_cpu_speed?*af_cpu_speed:AF_INIT_SLOW)
 100 #endif
 101 #endif
 102
 103 // Configuration switches
 104 typedef struct af_cfg_s{
 105   int force;    // Initialization type
 106   char** list;  /* list of names of filters that are added to filter
 107                    list during first initialization of stream */
 108 }af_cfg_t;
 109
 110 // Current audio stream
 111 typedef struct af_stream_s
 112 {
 113   // The first and last filter in the list
 114   af_instance_t* first;
 115   af_instance_t* last;
 116   // Storage for input and output data formats
 117   af_data_t input;
 118   af_data_t output;
 119   // Configuration for this stream
 120   af_cfg_t cfg;
 121 }af_stream_t;
 122
 123 /*********************************************
 124 // Return values
 125 */
 126
 127 #define AF_DETACH   2
 128 #define AF_OK       1
 129 #define AF_TRUE     1
 130 #define AF_FALSE    0
 131 #define AF_UNKNOWN -1
 132 #define AF_ERROR   -2
 133 #define AF_FATAL   -3
 134
 135
 136
 137 /*********************************************
 138 // Export functions
 139 */
 140
 141 /**
 142  * \defgroup af_chain Audio filter chain functions
 143  * \{
 144  * \param s filter chain
 145  */
 146
 147 /**
 148  * \brief Initialize the stream "s".
 149  * \return 0 on success, -1 on failure
 150  *
 151  * This function creates a new filter list if necessary, according
 152  * to the values set in input and output. Input and output should contain
 153  * the format of the current movie and the format of the preferred output
 154  * respectively.
 155  * Filters to convert to the preferred output format are inserted
 156  * automatically, except when they are set to 0.
 157  * The function is reentrant i.e. if called with an already initialized
 158  * stream the stream will be reinitialized.
 159  */
 160 int af_init(af_stream_t* s);
 161
 162 /**
 163  * \brief Uninit and remove all filters from audio filter chain
 164  */
 165 void af_uninit(af_stream_t* s);
 166
 167 /**
 168  * \brief This function adds the filter "name" to the stream s.
 169  * \param name name of filter to add
 170  * \return pointer to the new filter, NULL if insert failed
 171  *
 172  * The filter will be inserted somewhere nice in the
 173  * list of filters (i.e. at the beginning unless the
 174  * first filter is the format filter (why??).
 175  */
 176 af_instance_t* af_add(af_stream_t* s, char* name);
 177
 178 /**
 179  * \brief Uninit and remove the filter "af"
 180  * \param af filter to remove
 181  */
 182 void af_remove(af_stream_t* s, af_instance_t* af);
 183
 184 /**
 185  * \brief find filter in chain by name
 186  * \param name name of the filter to find
 187  * \return first filter with right name or NULL if not found
 188  *
 189  * This function is used for finding already initialized filters
 190  */
 191 af_instance_t* af_get(af_stream_t* s, char* name);
 192
 193 /**
 194  * \brief filter data chunk through the filters in the list
 195  * \param data data to play
 196  * \return resulting data
 197  * \ingroup af_chain
 198  */
 199 af_data_t* af_play(af_stream_t* s, af_data_t* data);
 200
 201 /**
 202  * \brief send control to all filters, starting with the last until
 203  *        one accepts the command with AF_OK.
 204  * \param cmd filter control command
 205  * \param arg argument for filter command
 206  * \return the accepting filter or NULL if none was found
 207  */
 208 af_instance_t *af_control_any_rev (af_stream_t* s, int cmd, void* arg);
 209
 210 /**
 211  * \brief calculate average ratio of filter output lenth to input length
 212  * \return the ratio
 213  */
 214 double af_calc_filter_multiplier(af_stream_t* s);
 215
 216 /**
 217  * \brief Calculate the total delay caused by the filters
 218  * \return delay in bytes of "missing" output
 219  */
 220 double af_calc_delay(af_stream_t* s);
 221
 222 /** \} */ // end of af_chain group
 223
 224 // Helper functions and macros used inside the audio filters
 225
 226 /**
 227  * \defgroup af_filter Audio filter helper functions
 228  * \{
 229  */
 230
 231 /* Helper function called by the macro with the same name only to be
 232    called from inside filters */
 233 int af_resize_local_buffer(af_instance_t* af, af_data_t* data);
 234
 235 /* Helper function used to calculate the exact buffer length needed
 236    when buffers are resized. The returned length is >= than what is
 237    needed */
 238 int af_lencalc(double mul, af_data_t* data);
 239
 240 /**
 241  * \brief convert dB to gain value
 242  * \param n number of values to convert
 243  * \param in [in] values in dB, <= -200 will become 0 gain
 244  * \param out [out] gain values
 245  * \param k input values are divided by this
 246  * \param mi minimum dB value, input will be clamped to this
 247  * \param ma maximum dB value, input will be clamped to this
 248  * \return AF_ERROR on error, AF_OK otherwise
 249  */
 250 int af_from_dB(int n, float* in, float* out, float k, float mi, float ma);
 251
 252 /**
 253  * \brief convert gain value to dB
 254  * \param n number of values to convert
 255  * \param in [in] gain values, 0 wil become -200 dB
 256  * \param out [out] values in dB
 257  * \param k output values will be multiplied by this
 258  * \return AF_ERROR on error, AF_OK otherwise
 259  */
 260 int af_to_dB(int n, float* in, float* out, float k);
 261
 262 /**
 263  * \brief convert milliseconds to sample time
 264  * \param n number of values to convert
 265  * \param in [in] values in milliseconds
 266  * \param out [out] sample time values
 267  * \param rate sample rate
 268  * \param mi minimum ms value, input will be clamped to this
 269  * \param ma maximum ms value, input will be clamped to this
 270  * \return AF_ERROR on error, AF_OK otherwise
 271  */
 272 int af_from_ms(int n, float* in, int* out, int rate, float mi, float ma);
 273
 274 /**
 275  * \brief convert sample time to milliseconds
 276  * \param n number of values to convert
 277  * \param in [in] sample time values
 278  * \param out [out] values in milliseconds
 279  * \param rate sample rate
 280  * \return AF_ERROR on error, AF_OK otherwise
 281  */
 282 int af_to_ms(int n, int* in, float* out, int rate);
 283
 284 /**
 285  * \brief test if output format matches
 286  * \param af audio filter
 287  * \param out needed format, will be overwritten by available
 288  *            format if they do not match
 289  * \return AF_FALSE if formats do not match, AF_OK if they match
 290  *
 291  * compares the format, bps, rate and nch values of af->data with out
 292  */
 293 int af_test_output(struct af_instance_s* af, af_data_t* out);
 294
 295 /**
 296  * \brief soft clipping function using sin()
 297  * \param a input value
 298  * \return clipped value
 299  */
 300 float af_softclip(float a);
 301
 302 /** \} */ // end of af_filter group, but more functions of this group below
 303
 304 /** Print a list of all available audio filters */
 305 void af_help(void);
 306
 307 /**
 308  * \brief fill the missing parameters in the af_data_t structure
 309  * \param data structure to fill
 310  * \ingroup af_filter
 311  *
 312  * Currently only sets bps based on format
 313  */
 314 void af_fix_parameters(af_data_t *data);
 315
 316 /** Memory reallocation macro: if a local buffer is used (i.e. if the
 317    filter doesn't operate on the incoming buffer this macro must be
 318    called to ensure the buffer is big enough.
 319  * \ingroup af_filter
 320  */
 321 #define RESIZE_LOCAL_BUFFER(a,d)\
 322 ((a->data->len < af_lencalc(a->mul,d))?af_resize_local_buffer(a,d):AF_OK)
 323
 324 /* Some other useful macro definitions*/
 325 #ifndef min
 326 #define min(a,b)(((a)>(b))?(b):(a))
 327 #endif
 328
 329 #ifndef max
 330 #define max(a,b)(((a)>(b))?(a):(b))
 331 #endif
 332
 333 #ifndef clamp
 334 #define clamp(a,min,max) (((a)>(max))?(max):(((a)<(min))?(min):(a)))
 335 #endif
 336
 337 #ifndef sign
 338 #define sign(a) (((a)>0)?(1):(-1))
 339 #endif
 340
 341 #ifndef lrnd
 342 #define lrnd(a,b) ((b)((a)>=0.0?(a)+0.5:(a)-0.5))
 343 #endif
 344
 345 /* Error messages */
 346
 347 typedef struct af_msg_cfg_s
 348 {
 349   int level;    /* Message level for debug and error messages max = 2
 350                    min = -2 default = 0 */
 351   FILE* err;    // Stream to print error messages to
 352   FILE* msg;    // Stream to print information messages to
 353 }af_msg_cfg_t;
 354
 355 extern af_msg_cfg_t af_msg_cfg; // Message
 356
 357 //! \addtogroup af_filter
 358 //! \{
 359 #define AF_MSG_FATAL    -3 ///< Fatal error exit immediately
 360 #define AF_MSG_ERROR    -2 ///< Error return gracefully
 361 #define AF_MSG_WARN     -1 ///< Print warning but do not exit (can be suppressed)
 362 #define AF_MSG_INFO      0 ///< Important information
 363 #define AF_MSG_VERBOSE   1 ///< Print this if verbose is enabled
 364 #define AF_MSG_DEBUG0    2 ///< Print if very verbose
 365 #define AF_MSG_DEBUG1    3 ///< Print if very very verbose
 366
 367 //! Macro for printing error messages
 368 #ifndef af_msg
 369 #define af_msg(lev, args... ) \
 370 (((lev)<AF_MSG_WARN)?(fprintf(af_msg_cfg.err?af_msg_cfg.err:stderr, ## args )): \
 371 (((lev)<=af_msg_cfg.level)?(fprintf(af_msg_cfg.msg?af_msg_cfg.msg:stdout, ## args )):0))
 372 #endif
 373 //! \}
 374
 375 #endif /* MPLAYER_AF_H */