Mercurial > hg > sv-dependency-builds

annotate src/libsamplerate-0.1.9/doc/api_full.html @ 41:481f5f8c5634

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