Mercurial > hg > sv-dependency-builds

annotate src/libsamplerate-0.1.9/doc/api_full.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 481f5f8c5634
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