Mercurial > hg > sv-dependency-builds

annotate src/libsamplerate-0.1.9/doc/api_misc.html @ 126:4a7071416412

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Current libsamplerate source
author Chris Cannam <cannam@all-day-breakfast.com>
date Tue, 18 Oct 2016 13:24:45 +0100
parents
children
rev   line source
cannam@126 1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
cannam@126 2 <HTML>
cannam@126 3
cannam@126 4 <HEAD>
cannam@126 5 <TITLE>
cannam@126 6 Secret Rabbit Code (aka libsamplerate)
cannam@126 7 </TITLE>
cannam@126 8 <META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
cannam@126 9 <META NAME="Version" CONTENT="libsamplerate-0.1.8">
cannam@126 10 <META NAME="Description" CONTENT="The Secret Rabbit Code Home Page">
cannam@126 11 <META NAME="Keywords" CONTENT="libsamplerate sound resample audio dsp Linux">
cannam@126 12 <LINK REL=StyleSheet HREF="SRC.css" TYPE="text/css" MEDIA="all">
cannam@126 13 </HEAD>
cannam@126 14
cannam@126 15 <BODY TEXT="#FFFFFF" BGCOLOR="#000000" LINK="#FB1465" VLINK="#FB1465" ALINK="#FB1465">
cannam@126 16 <!-- pepper -->
cannam@126 17 <CENTER>
cannam@126 18 <IMG SRC="SRC.png" HEIGHT=100 WIDTH=760 ALT="SRC.png">
cannam@126 19 </CENTER>
cannam@126 20 <!-- pepper -->
cannam@126 21 <BR>
cannam@126 22 <!-- pepper -->
cannam@126 23 <TABLE ALIGN="center" WIDTH="98%">
cannam@126 24 <TR>
cannam@126 25 <TD VALIGN="top">
cannam@126 26 <BR>
cannam@126 27 <DIV CLASS="nav">
cannam@126 28 <BR>
cannam@126 29 <A HREF="index.html">Home</A><BR>
cannam@126 30 <BR>
cannam@126 31 <A HREF="api_simple.html">Simple API</A><BR>
cannam@126 32 <A HREF="api_full.html">Full API</A><BR>
cannam@126 33 <A HREF="api_misc.html#ErrorReporting">Error Handling</A><BR>
cannam@126 34 <A HREF="api_misc.html">Miscellaneous</A><BR>
cannam@126 35 <BR>
cannam@126 36 <DIV CLASS="block">
cannam@126 37 Author :<BR>Erik de Castro Lopo
cannam@126 38 <!-- pepper -->
cannam@126 39 <BR><BR>
cannam@126 40 <!-- pepper -->
cannam@126 41
cannam@126 42 </DIV>
cannam@126 43 <IMG SRC=
cannam@126 44 "/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_api.dat"
cannam@126 45 HEIGHT=30 WIDTH=100 ALT="counter.gif">
cannam@126 46 </DIV>
cannam@126 47
cannam@126 48 </TD>
cannam@126 49 <!-- pepper -->
cannam@126 50 <!-- ######################################################################## -->
cannam@126 51 <!-- pepper -->
cannam@126 52 <TD VALIGN="top">
cannam@126 53 <DIV CLASS="block">
cannam@126 54
cannam@126 55 <H1><B>Miscellaneous API Documentation</B></H1>
cannam@126 56 <A NAME="ErrorReporting"></A>
cannam@126 57 <H3><BR>Error Reporting</H3>
cannam@126 58 <P>
cannam@126 59 Most of the API functions either return an integer error (ie <B>src_simple</B>
cannam@126 60 and <B>src_process</B>) or return an integer error value via an int pointer
cannam@126 61 parameter (<B>src_new</B>).
cannam@126 62 These integer error values can be converted into a human readable text strings by
cannam@126 63 calling the function:
cannam@126 64 </P>
cannam@126 65 <PRE>
cannam@126 66 const char* src_strerror (int error) ;
cannam@126 67 </PRE>
cannam@126 68 <P>
cannam@126 69 which will return an error string for valid error numbers, the string "No Error"
cannam@126 70 for an error value of zero or a NULL pointer if no error message has been defined
cannam@126 71 for that error value.
cannam@126 72 </P>
cannam@126 73
cannam@126 74 <A NAME="Converters"></A>
cannam@126 75 <H3><BR>Converters</H3>
cannam@126 76 <P>
cannam@126 77 Secret Rabbit Code has a number of different converters which can be selected
cannam@126 78 using the <B>converter_type</B> parameter when calling <B>src_simple</B> or
cannam@126 79 <b>src_new</B>.
cannam@126 80 Currently, the five converters available are:
cannam@126 81 </P>
cannam@126 82 <PRE>
cannam@126 83 enum
cannam@126 84 {
cannam@126 85 SRC_SINC_BEST_QUALITY = 0,
cannam@126 86 SRC_SINC_MEDIUM_QUALITY = 1,
cannam@126 87 SRC_SINC_FASTEST = 2,
cannam@126 88 SRC_ZERO_ORDER_HOLD = 3,
cannam@126 89 SRC_LINEAR = 4
cannam@126 90 } ;
cannam@126 91 </PRE>
cannam@126 92 <P>
cannam@126 93 As new converters are added, they will given a number corresponding to the
cannam@126 94 next inetger.
cannam@126 95 </P>
cannam@126 96
cannam@126 97 <P>
cannam@126 98 The details of these converters are as follows:
cannam@126 99 </P>
cannam@126 100 <UL>
cannam@126 101 <LI> <B>SRC_SINC_BEST_QUALITY</B> - This is a bandlimited interpolator derived
cannam@126 102 from the mathematical <B>sinc</B> function and this is the highest
cannam@126 103 quality sinc based converter, providing a worst case Signal-to-Noise
cannam@126 104 Ratio (SNR) of 97 decibels (dB) at a bandwidth of 97&#37;.
cannam@126 105 All three SRC_SINC_* converters are based on the techniques of
cannam@126 106 <A HREF="http://ccrma-www.stanford.edu/~jos/resample/">Julius O. Smith</A>
cannam@126 107 although this code was developed independantly.
cannam@126 108 <LI> <B>SRC_SINC_MEDIUM_QUALITY</B> - This is another bandlimited interpolator
cannam@126 109 much like the previous one. It has an SNR of 97dB and a bandwidth of 90&#37;.
cannam@126 110 The speed of the conversion is much faster than the previous one.
cannam@126 111 <LI> <B>SRC_SINC_FASTEST</B> - This is the fastest bandlimited interpolator and
cannam@126 112 has an SNR of 97dB and a bandwidth of 80&#37;.
cannam@126 113 <LI><B>SRC_ZERO_ORDER_HOLD</B> - A Zero Order Hold converter (interpolated value
cannam@126 114 is equal to the last value). The quality is poor but the conversion speed is
cannam@126 115 blindlingly fast.
cannam@126 116 <li><b>SRC_LINEAR</b> - A linear converter. Again the quality is poor, but the
cannam@126 117 conversion speed is blindingly fast.
cannam@126 118 </UL>
cannam@126 119 <P>
cannam@126 120 There are two functions that give either a (text string) name or description
cannam@126 121 for each converter:
cannam@126 122 </P>
cannam@126 123 <PRE>
cannam@126 124 const char *src_get_name (int converter_type) ;
cannam@126 125 const char *src_get_description (int converter_type) ;
cannam@126 126 </PRE>
cannam@126 127 <P>
cannam@126 128 The name will typically be a short string for use in a dialog box, while the
cannam@126 129 description string is longer.
cannam@126 130 </P>
cannam@126 131 <P>
cannam@126 132 Both of these functions return a NULL pointer if there is no converter for the
cannam@126 133 given <B>converter_type</B> value.
cannam@126 134 Since the converters have consecutive <B>converter_type</B> values, the caller
cannam@126 135 is easily able to figure out the number of converters at run time.
cannam@126 136 This enables a binary dynamically linked against an old version of the library
cannam@126 137 to know about converters from later versions of the library as they become
cannam@126 138 available.
cannam@126 139 </P>
cannam@126 140
cannam@126 141 <A NAME="SRC_DATA"></A>
cannam@126 142 <H3><BR>SRC_DATA</H3>
cannam@126 143 <P>
cannam@126 144 Both the simple and the full featured versions of the API use the <B>SRC_DATA</B>
cannam@126 145 struct to pass audio and control data into the sample rate converter.
cannam@126 146 This struct is defined as:
cannam@126 147 </P>
cannam@126 148 <PRE>
cannam@126 149 typedef struct
cannam@126 150 { float *data_in, *data_out ;
cannam@126 151
cannam@126 152 long input_frames, output_frames ;
cannam@126 153 long input_frames_used, output_frames_gen ;
cannam@126 154
cannam@126 155 int end_of_input ;
cannam@126 156
cannam@126 157 double src_ratio ;
cannam@126 158 } SRC_DATA ;
cannam@126 159 </PRE>
cannam@126 160 <P>
cannam@126 161 The <B>data_in</B> pointer is used to pass audio data into the converter while the
cannam@126 162 <B>data_out</B> pointer supplies the converter with an array to hold the converter's
cannam@126 163 output.
cannam@126 164 For a converter which has been configured for mulitchannel operation, these pointers
cannam@126 165 need to point to a single array of interleaved data.
cannam@126 166 </P>
cannam@126 167 <P>
cannam@126 168 The <B>input_frames</B> and <B>output_frames</B> fields supply the converter with
cannam@126 169 the lengths of the arrays (in frames) pointed to by the <B>data_in</B> and
cannam@126 170 <b>data_out</B> pointers respectively.
cannam@126 171 For monophinc data, these values would indicate the length of the arrays while
cannam@126 172 for multi channel data these values would be equal to the the length of the array
cannam@126 173 divided by the number of channels.
cannam@126 174 </P>
cannam@126 175
cannam@126 176 <P>
cannam@126 177 The <B>end_of_input</B> field is only used when the sample rate converter is used
cannam@126 178 by calling the <B>src_process</B> function.
cannam@126 179 In this case it should be set to zero if more buffers are to be passed to the
cannam@126 180 converter and 1 if the current buffer is the last.
cannam@126 181 </P>
cannam@126 182 <P>
cannam@126 183 Finally, the <B>src_ratio</B> field specifies the conversion ratio defined as
cannam@126 184 the input sample rate divided by the output sample rate.
cannam@126 185 For a connected set of buffers, this value can be varies on each call to
cannam@126 186 <B>src_process</B> resulting in a time varying sample rate conversion
cannam@126 187 process.
cannam@126 188 For time varying sample rate conversions, the ratio will be linearly
cannam@126 189 interpolated between the <B>src_ratio</B> value of the previous call
cannam@126 190 to <B>src_process</B> and the value for the current call.
cannam@126 191 </P>
cannam@126 192 <P>
cannam@126 193 The <B>input_frames_used</B> and <B>output_frames_gen</B> fields are set by the
cannam@126 194 converter to inform the caller of the number of frames consumed from the
cannam@126 195 <B>data_in</B> array and the number of frames generated in the <B>data_out</B>
cannam@126 196 array respectively.
cannam@126 197 These values are for the current call to <B>src_process</B> only.
cannam@126 198 </P>
cannam@126 199
cannam@126 200 <A NAME="Aux"></A>
cannam@126 201 <H3><BR>Auxillary Functions</H3>
cannam@126 202 <P>
cannam@126 203 There are four auxillary functions for converting arrays of float data
cannam@126 204 to and from short or int data.
cannam@126 205 These functions are defined as:
cannam@126 206 </P>
cannam@126 207 <PRE>
cannam@126 208 void src_short_to_float_array (const short *in, float *out, int len) ;
cannam@126 209 void src_float_to_short_array (const float *in, short *out, int len) ;
cannam@126 210 void src_int_to_float_array (const int *in, float *out, int len) ;
cannam@126 211 void src_float_to_int_array (const float *in, int *out, int len) ;
cannam@126 212 </PRE>
cannam@126 213 <P>
cannam@126 214 The float data is assumed to be in the range [-1.0, 1.0] and it is
cannam@126 215 automatically scaled on the conversion to and from float.
cannam@126 216 On the float to short/int conversion path, any data values which would overflow
cannam@126 217 the range of short/int data are clipped.
cannam@126 218 </P>
cannam@126 219
cannam@126 220 </DIV>
cannam@126 221 </TD></TR>
cannam@126 222 </TABLE>
cannam@126 223
cannam@126 224 </BODY>
cannam@126 225 </HTML>
cannam@126 226