gc/samplerate.h

   1 /*
   2 ** Copyright (C) 2002-2004 Erik de Castro Lopo <erikd@mega-nerd.com>
   3 **
   4 ** This program 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 ** This program 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
  15 ** along with this program; if not, write to the Free Software
  16 ** Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
  17 */
  18
  19 /*
  20 ** API documentation is available here:
  21 **     http://www.mega-nerd.com/SRC/api.html
  22 */
  23
  24 #ifndef SAMPLERATE_H
  25 #define SAMPLERATE_H
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif  /* __cplusplus */
  30
  31
  32 /* Opaque data type SRC_STATE. */
  33 typedef struct SRC_STATE_tag SRC_STATE ;
  34
  35 /* SRC_DATA is used to pass data to src_simple() and src_process(). */
  36 typedef struct
  37 {       float   *data_in, *data_out ;
  38
  39         long    input_frames, output_frames ;
  40         long    input_frames_used, output_frames_gen ;
  41
  42         int             end_of_input ;
  43
  44         double  src_ratio ;
  45 } SRC_DATA ;
  46
  47 /* SRC_CB_DATA is used with callback based API. */
  48 typedef struct
  49 {       long    frames ;
  50         float   *data_in ;
  51 } SRC_CB_DATA ;
  52
  53 /*
  54 ** User supplied callback function type for use with src_callback_new()
  55 ** and src_callback_read(). First parameter is the same pointer that was
  56 ** passed into src_callback_new(). Second parameter is pointer to a
  57 ** pointer. The user supplied callback function must modify *data to
  58 ** point to the start of the user supplied float array. The user supplied
  59 ** function must return the number of frames that **data points to.
  60 */
  61
  62 typedef long (*src_callback_t) (void *cb_data, float **data) ;
  63
  64 /*
  65 **      Standard initialisation function : return an anonymous pointer to the
  66 **      internal state of the converter. Choose a converter from the enums below.
  67 **      Error returned in *error.
  68 */
  69
  70 SRC_STATE* src_new (int converter_type, int channels, int *error) ;
  71
  72 /*
  73 **      Initilisation for callback based API : return an anonymous pointer to the
  74 **      internal state of the converter. Choose a converter from the enums below.
  75 **      The cb_data pointer can point to any data or be set to NULL. Whatever the
  76 **      value, when processing, user supplied function "func" gets called with
  77 **      cb_data as first parameter.
  78 */
  79
  80 SRC_STATE* src_callback_new (src_callback_t func, int converter_type, int channels,
  81                                 int *error, void* cb_data) ;
  82
  83 /*
  84 **      Cleanup all internal allocations.
  85 **      Always returns NULL.
  86 */
  87
  88 SRC_STATE* src_delete (SRC_STATE *state) ;
  89
  90 /*
  91 **      Standard processing function.
  92 **      Returns non zero on error.
  93 */
  94
  95 int src_process (SRC_STATE *state, SRC_DATA *data) ;
  96
  97 /*
  98 **      Callback based processing function. Read up to frames worth of data from
  99 **      the converter int *data and return frames read or -1 on error.
 100 */
 101 long src_callback_read (SRC_STATE *state, double src_ratio, long frames, float *data) ;
 102
 103 /*
 104 **      Simple interface for performing a single conversion from input buffer to
 105 **      output buffer at a fixed conversion ratio.
 106 **      Simple interface does not require initialisation as it can only operate on
 107 **      a single buffer worth of audio.
 108 */
 109
 110 int src_simple (SRC_DATA *data, int converter_type, int channels) ;
 111
 112 /*
 113 ** This library contains a number of different sample rate converters,
 114 ** numbered 0 through N.
 115 **
 116 ** Return a string giving either a name or a more full description of each
 117 ** sample rate converter or NULL if no sample rate converter exists for
 118 ** the given value. The converters are sequentially numbered from 0 to N.
 119 */
 120
 121 const char *src_get_name (int converter_type) ;
 122 const char *src_get_description (int converter_type) ;
 123 const char *src_get_version (void) ;
 124
 125 /*
 126 **      Set a new SRC ratio. This allows step responses
 127 **      in the conversion ratio.
 128 **      Returns non zero on error.
 129 */
 130
 131 int src_set_ratio (SRC_STATE *state, double new_ratio) ;
 132
 133 /*
 134 **      Reset the internal SRC state.
 135 **      Does not modify the quality settings.
 136 **      Does not free any memory allocations.
 137 **      Returns non zero on error.
 138 */
 139
 140 int src_reset (SRC_STATE *state) ;
 141
 142 /*
 143 ** Return TRUE if ratio is a valid conversion ratio, FALSE
 144 ** otherwise.
 145 */
 146
 147 int src_is_valid_ratio (double ratio) ;
 148
 149 /*
 150 **      Return an error number.
 151 */
 152
 153 int src_error (SRC_STATE *state) ;
 154
 155 /*
 156 **      Convert the error number into a string.
 157 */
 158 const char* src_strerror (int error) ;
 159
 160 /*
 161 ** The following enums can be used to set the interpolator type
 162 ** using the function src_set_converter().
 163 */
 164
 165 enum
 166 {
 167         SRC_SINC_BEST_QUALITY           = 0,
 168         SRC_SINC_MEDIUM_QUALITY         = 1,
 169         SRC_SINC_FASTEST                        = 2,
 170         SRC_ZERO_ORDER_HOLD                     = 3,
 171         SRC_LINEAR                                      = 4
 172 } ;
 173
 174 /*
 175 ** Extra helper functions for converting from short to float and
 176 ** back again.
 177 */
 178
 179 void src_short_to_float_array (const short *in, float *out, int len) ;
 180 void src_float_to_short_array (const float *in, short *out, int len) ;
 181
 182
 183 #ifdef __cplusplus
 184 }               /* extern "C" */
 185 #endif  /* __cplusplus */
 186
 187 #endif  /* SAMPLERATE_H */
 188
 189 /*
 190 ** Do not edit or modify anything in this comment block.
 191 ** The arch-tag line is a file identity tag for the GNU Arch
 192 ** revision control system.
 193 **
 194 ** arch-tag: 5421ef3e-c898-4ec3-8671-ea03d943ee00
 195 */
 196