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