libsamplerate/doc/api_full.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2 <HTML>
   3
   4 <HEAD>
   5         <TITLE>
   6         Secret Rabbit Code (aka libsamplerate)
   7         </TITLE>
   8         <META NAME="Author"      CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
   9     <META NAME="Version"     CONTENT="libsamplerate-0.1.8">
  10         <META NAME="Description" CONTENT="The Secret Rabbit Code Home Page">
  11         <META NAME="Keywords"    CONTENT="libsamplerate sound resample audio dsp Linux">
  12         <LINK REL=StyleSheet HREF="SRC.css" TYPE="text/css" MEDIA="all">
  13 </HEAD>
  14
  15 <BODY TEXT="#FFFFFF" BGCOLOR="#000000" LINK="#FB1465" VLINK="#FB1465" ALINK="#FB1465">
  16 <!-- pepper -->
  17 <CENTER>
  18         <IMG SRC="SRC.png" HEIGHT=100 WIDTH=760 ALT="SRC.png">
  19 </CENTER>
  20 <!-- pepper -->
  21 <BR>
  22 <!-- pepper -->
  23 <TABLE ALIGN="center" WIDTH="98%">
  24 <TR>
  25 <TD VALIGN="top">
  26 <BR>
  27 <DIV CLASS="nav">
  28         <BR>
  29         <A HREF="index.html">Home</A><BR>
  30         <BR>
  31         <A HREF="api_simple.html">Simple API</A><BR>
  32         <A HREF="api_full.html">Full API</A><BR>
  33         <A HREF="api_callback.html">Callback API</A><BR>
  34         <A HREF="api_misc.html">Miscellaneous</A><BR>
  35         <A HREF="api_misc.html#ErrorReporting">Error Handling</A><BR>
  36 <BR>
  37 <DIV CLASS="block">
  38 Author :<BR>Erik de Castro Lopo
  39 <!-- pepper -->
  40 <BR><BR>
  41 <!-- pepper -->
  42
  43 </DIV>
  44         <IMG SRC=
  45         "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_api.dat"
  46         HEIGHT=30 WIDTH=100 ALT="counter.gif">
  47 </DIV>
  48
  49 </TD>
  50 <!-- pepper -->
  51 <!-- ######################################################################## -->
  52 <!-- pepper -->
  53 <TD VALIGN="top">
  54 <DIV CLASS="block">
  55
  56 <H1><B>Full API</B></H1>
  57 <P>
  58 The full API consists of the following functions :
  59 </P>
  60 <PRE>
  61       SRC_STATE* <A HREF="#Init">src_new</A> (int converter_type, int channels, int *error) ;
  62       SRC_STATE* <A HREF="#CleanUp">src_delete</A> (SRC_STATE *state) ;
  63
  64       int <A HREF="#Process">src_process</A> (SRC_STATE *state, SRC_DATA *data) ;
  65       int <A HREF="#Reset">src_reset</A> (SRC_STATE *state) ;
  66       int <A HREF="#SetRatio">src_set_ratio</A> (SRC_STATE *state, double new_ratio) ;
  67 </PRE>
  68
  69 <A NAME="Init"></A>
  70 <H3><BR>Initialisation</H3>
  71 <PRE>
  72       SRC_STATE* src_new (int converter_type, int channels, int *error) ;
  73 </PRE>
  74 <P>
  75 The <B>src_new</B> function returns an anonymous pointer to a sample rate
  76 converter object, src_state.
  77 If an error occurs the function returns a NULL pointer and fills in the
  78 error value pointed to by the <B>error</B> pointer supplied by the caller.
  79 The converter must be one of the supplied converter types documented
  80 <A HREF="api_misc.html#Converters">here</A>.
  81 </P>
  82
  83 <A NAME="CleanUp"></A>
  84 <H3><BR>Cleanup</H3>
  85 <PRE>
  86       SRC_STATE* src_delete (SRC_STATE *state) ;
  87 </PRE>
  88 <P>
  89 The <B>src_delete</B> function frees up all memory allocated for the given sample
  90 rate converter object and returns a NULL pointer.
  91 The caller is responsible for freeing any memory passed to the sample rate converter
  92 via the pointer to the <B>SRC_DATA</B> struct.
  93 </P>
  94
  95 <A NAME="Process"></A>
  96 <H3><BR>Process</H3>
  97 <PRE>
  98       int src_process (SRC_STATE *state, SRC_DATA *data) ;
  99 </PRE>
 100 <P>
 101 The <B>src_process</B> function processes the data provided by the caller
 102 in an <B>SRC_DATA</B> struct using the sample rate converter object specified
 103 by the <B>SRC_STATE</B> pointer.
 104 When operating on streaming data, this function can be called over and over again,
 105 with each new call providing new input data and returning new output data.
 106 </P>
 107
 108 <P>
 109 The <B>SRC_DATA</B> struct passed as the second parameter to the <B>src_process</B>
 110 function has the following fields:
 111 </P>
 112 <PRE>
 113       typedef struct
 114       {   float  *data_in, *data_out ;
 115
 116           long   input_frames, output_frames ;
 117           long   input_frames_used, output_frames_gen ;
 118
 119           int    end_of_input ;
 120
 121           double src_ratio ;
 122       } SRC_DATA ;
 123 </PRE>
 124 <P>
 125 The fields of this struct which must be filled in by the caller are:
 126 </P>
 127 <PRE>
 128       data_in       : A pointer to the input data samples.
 129       input_frames  : The number of frames of data pointed to by data_in.
 130       data_out      : A pointer to the output data samples.
 131       output_frames : Maximum number of frames pointer to by data_out.
 132       src_ratio     : Equal to output_sample_rate / input_sample_rate.
 133       end_of_input  : Equal to 0 if more input data is available and 1
 134                       otherwise.
 135 </PRE>
 136 <P>
 137 Note that the data_in and data_out arrays may not overlap. If they do, the
 138 library will return an error code.
 139 </P>
 140 <P>
 141 When the <B>src_process</B> function returns <B>output_frames_gen</B> will be
 142 set to the number of output frames generated and <B>input_frames_used</B> will
 143 be set to the number of input frames consumed to generate the provided number of
 144 output frames.
 145 </P>
 146
 147 <P>
 148 The <B>src_process</B> function returns non-zero if an error occurs.
 149 The non-zero error return value can be decoded into a text string using the function
 150 documented <A HREF="api_misc.html#ErrorReporting">here</A>.
 151 </P>
 152
 153 <A NAME="Reset"></A>
 154 <H3><BR>Reset</H3>
 155 <PRE>
 156       int src_reset (SRC_STATE *state) ;
 157 </PRE>
 158 <P>
 159 The <B>src_reset</B> function resets the internal state of the sample rate
 160 converter object to the same state it had immediately after its creation using
 161 <B>src_new</B>.
 162 This should be called whenever a sample rate converter is to be used on two
 163 separate, unrelated pieces of audio.
 164 </P>
 165
 166 <A NAME="SetRatio"></A>
 167 <H3><BR>Set Ratio</H3>
 168 <PRE>
 169       int src_set_ratio (SRC_STATE *state, double new_ratio) ;
 170 </PRE>
 171
 172 <p>
 173 When using the <B>src_process</B> or <B>src_callback_process</B> APIs and
 174 updating the <B>src_ratio</B> field of the <B>SRC_STATE</B> struct, the library
 175 will try to smoothly transition between the conversion ratio of the last call
 176 and the conversion ratio of the current call.
 177 <p/>
 178
 179 <P>
 180 If the user want to bypass this smooth transition and achieve a step response in
 181 the conversion ratio, the <B>src_set_ratio</B> function can be used to set the
 182 starting conversion ratio of the next call to <B>src_process</B> or
 183 <B>src_callback_process</B>.
 184 <p/>
 185
 186 <P>
 187 This function returns non-zero on error and the error return value can be
 188 decoded into a text string using the function documented
 189 <A HREF="api_misc.html#ErrorReporting">here</A>.</P>
 190
 191 <!-- <A HREF="mailto:aldel@mega-nerd.com">For the spam bots</A> -->
 192
 193 </DIV>
 194 </TD></TR>
 195 </TABLE>
 196
 197 </BODY>
 198 </HTML>
 199