Mercurial > hg > sv-dependency-builds

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