Mercurial > hg > sv-dependency-builds

annotate src/libsamplerate-0.1.8/doc/api_misc.html @ 83:ae30d91d2ffe

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