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