Mercurial > hg > sv-dependency-builds

annotate src/libsamplerate-0.1.8/doc/api_callback.html @ 23:619f715526df sv_v2.1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update Vamp plugin SDK to 2.5
author Chris Cannam
date Thu, 09 May 2013 10:52:46 +0100
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_callback.html">Callback API</A><BR>
Chris@0 34 <A HREF="api_misc.html">Miscellaneous</A><BR>
Chris@0 35 <A HREF="api_misc.html#ErrorReporting">Error Handling</A><BR>
Chris@0 36 <BR>
Chris@0 37 <DIV CLASS="block">
Chris@0 38 Author :<BR>Erik de Castro Lopo
Chris@0 39 <!-- pepper -->
Chris@0 40 <BR><BR>
Chris@0 41 <!-- pepper -->
Chris@0 42
Chris@0 43 </DIV>
Chris@0 44 <IMG SRC=
Chris@0 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@0 46 HEIGHT=30 WIDTH=100 ALT="counter.gif">
Chris@0 47 </DIV>
Chris@0 48
Chris@0 49 </TD>
Chris@0 50 <!-- pepper -->
Chris@0 51 <!-- ######################################################################## -->
Chris@0 52 <!-- pepper -->
Chris@0 53 <TD VALIGN="top">
Chris@0 54 <DIV CLASS="block">
Chris@0 55
Chris@0 56 <H1><B>Callback API</B></H1>
Chris@0 57 <P>
Chris@0 58 The callback API consists of the following functions :
Chris@0 59 </P>
Chris@0 60 <PRE>
Chris@0 61 typedef long (*src_callback_t) (void *cb_data, float **data) ;
Chris@0 62
Chris@0 63 SRC_STATE* <A HREF="#Init">src_callback_new</A> (src_callback_t func,
Chris@0 64 int converter_type, int channels,
Chris@0 65 int *error, void* cb_data) ;
Chris@0 66
Chris@0 67 SRC_STATE* <A HREF="api_full.html#CleanUp">src_delete</A> (SRC_STATE *state) ;
Chris@0 68
Chris@0 69 long <A HREF="#Read">src_callback_read</A> (SRC_STATE *state, double src_ratio,
Chris@0 70 long frames, float *data) ;
Chris@0 71
Chris@0 72 int <A HREF="api_full.html#Reset">src_reset</A> (SRC_STATE *state) ;
Chris@0 73 int <A HREF="api_full.html#SetRatio">src_set_ratio</A> (SRC_STATE *state, double new_ratio) ;
Chris@0 74 </PRE>
Chris@0 75 <BR>
Chris@0 76
Chris@0 77 <P>
Chris@0 78 Like the
Chris@0 79 <A HREF="api_simple.html">simple API</a>
Chris@0 80 and the
Chris@0 81 <A HREF="api_full.html">full API</a>,
Chris@0 82 the callback based API is able to operate on interleaved multi channel data.
Chris@0 83 </P>
Chris@0 84
Chris@0 85 <P>
Chris@0 86 An example of the use of the callback based API can be found in the
Chris@0 87 <B>varispeed-play</B> program in the <B>examples/</B> directory of the
Chris@0 88 source code tarball.
Chris@0 89 </P>
Chris@0 90
Chris@0 91 <!-- pepper -->
Chris@0 92 <A NAME="Init"></A>
Chris@0 93 <H3><BR>Initialisation</H3>
Chris@0 94 <PRE>
Chris@0 95 SRC_STATE* src_callback_new (src_callback_t func,
Chris@0 96 int converter_type, int channels,
Chris@0 97 int *error, void* cb_data) ;
Chris@0 98 </PRE>
Chris@0 99 <P>
Chris@0 100 The <B>src_callback_new</B> function returns an anonymous pointer to a
Chris@0 101 sample rate converter callback object, src_state.
Chris@0 102 This is the same type of object as that returned by <A HREF="api_full.html#init">
Chris@0 103 src_new</A>, but with different internal state.
Chris@0 104 Although these are the same object type, they cannot be used interchangeably.
Chris@0 105 If an error occurs the function returns a NULL pointer and fills in the
Chris@0 106 error value pointed to by the <B>error</B> pointer supplied by the caller.
Chris@0 107 </P>
Chris@0 108 <P>
Chris@0 109 The caller then passes the SRC_STATE object to the <B>src_callback_read</B>
Chris@0 110 function to pull data out of the converter.
Chris@0 111 When the caller is finished with the converter they should pass it to the
Chris@0 112 clean up function <A HREF="api_full.html#CleanUp">src_delete</A>.
Chris@0 113 </P>
Chris@0 114 <P>
Chris@0 115 The <B>func</B> parameter is a user supplied function which must match the
Chris@0 116 <B>src_callback_t</B> type signature while <B>cb_data</B> is a pointer to
Chris@0 117 data which be passed as the first parameter to the user supplied callback
Chris@0 118 function.
Chris@0 119 This function is called by the converter whenever it needs input data as a
Chris@0 120 result of being calls to <B>src_callback_read</B>.
Chris@0 121 </P>
Chris@0 122 <P>
Chris@0 123 If the converter was initialised to work with more than one channel, the
Chris@0 124 callback function must work with mutiple channels of interleaved data.
Chris@0 125 The callback function should return the number of frames it supplying to
Chris@0 126 the converter.
Chris@0 127 For multi channel files, this return value should be the number of floats
Chris@0 128 divided by the number of channels.
Chris@0 129 </P>
Chris@0 130 <P>
Chris@0 131 The converter must be one of the supplied converter types documented
Chris@0 132 <A HREF="api_misc.html#Converters">here</A>.
Chris@0 133 </P>
Chris@0 134 <P>
Chris@0 135 The caller then passes the SRC_STATE pointer to the <B>src_callback_read</B>
Chris@0 136 function to pull data out of the converter.
Chris@0 137 </P>
Chris@0 138
Chris@0 139 <!-- pepper -->
Chris@0 140 <A NAME="Read"></A>
Chris@0 141 <H3><BR>Callback Read</H3>
Chris@0 142 <PRE>
Chris@0 143 long src_callback_read (SRC_STATE *state, double src_ratio,
Chris@0 144 long frames, float *data) ;
Chris@0 145 </PRE>
Chris@0 146 <P>
Chris@0 147 The <B>src_callback_read</B> function is passed the
Chris@0 148 <A HREF="api_misc.html#SRC_DATA"><B>SRC_STATE</B></A>
Chris@0 149 pointer returned by <B>src_callback_new</B>, the coversion ratio
Chris@0 150 (output_sample_rate / input_sample_rate), the maximum number of output frames
Chris@0 151 to generate and a pointer to a buffer in which to place the output data.
Chris@0 152 For multi channel files, the data int the output buffer is stored in
Chris@0 153 interleaved format.
Chris@0 154 </P>
Chris@0 155 <P>
Chris@0 156 The <B>src_callback_read</B> function returns the number of frames generated
Chris@0 157 or zero if an error occurs or it runs out of input (ie the user supplied
Chris@0 158 callback function returns zero and there is no more data buffered internally).
Chris@0 159 If an error has occurred, the function <A HREF="api_misc.html#ErrorReporting">
Chris@0 160 src_error</A> will return non-zero.
Chris@0 161 </P>
Chris@0 162
Chris@0 163 <P>
Chris@0 164 See also :
Chris@0 165 <A HREF="api_full.html#SetRatio"><B>src_set_ratio</B></A>
Chris@0 166 </P>
Chris@0 167
Chris@0 168 <!-- pepper -->
Chris@0 169
Chris@0 170 </DIV>
Chris@0 171 </TD></TR>
Chris@0 172 </TABLE>
Chris@0 173
Chris@0 174 </BODY>
Chris@0 175 </HTML>
Chris@0 176