cannam@126: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> cannam@126: <HTML> cannam@126: cannam@126: <HEAD> cannam@126: <TITLE> cannam@126: Secret Rabbit Code (aka libsamplerate) cannam@126: </TITLE> cannam@126: <META NAME="Author" CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)"> cannam@126: <META NAME="Version" CONTENT="libsamplerate-0.1.8"> cannam@126: <META NAME="Description" CONTENT="The Secret Rabbit Code Home Page"> cannam@126: <META NAME="Keywords" CONTENT="libsamplerate sound resample audio dsp Linux"> cannam@126: <LINK REL=StyleSheet HREF="SRC.css" TYPE="text/css" MEDIA="all"> cannam@126: </HEAD> cannam@126: cannam@126: <BODY TEXT="#FFFFFF" BGCOLOR="#000000" LINK="#FB1465" VLINK="#FB1465" ALINK="#FB1465"> cannam@126: <!-- pepper --> cannam@126: <CENTER> cannam@126: <IMG SRC="SRC.png" HEIGHT=100 WIDTH=760 ALT="SRC.png"> cannam@126: </CENTER> cannam@126: <!-- pepper --> cannam@126: <BR> cannam@126: <!-- pepper --> cannam@126: <TABLE ALIGN="center" WIDTH="98%"> cannam@126: <TR> cannam@126: <TD VALIGN="top"> cannam@126: <BR> cannam@126: <DIV CLASS="nav"> cannam@126: <BR> cannam@126: <A HREF="index.html">Home</A><BR> cannam@126: <BR> cannam@126: <A HREF="api_simple.html">Simple API</A><BR> cannam@126: <A HREF="api_full.html">Full API</A><BR> cannam@126: <A HREF="api_callback.html">Callback API</A><BR> cannam@126: <A HREF="api_misc.html">Miscellaneous</A><BR> cannam@126: <A HREF="api_misc.html#ErrorReporting">Error Handling</A><BR> cannam@126: <BR> cannam@126: <DIV CLASS="block"> cannam@126: Author :<BR>Erik de Castro Lopo cannam@126: <!-- pepper --> cannam@126: <BR><BR> cannam@126: <!-- pepper --> cannam@126: cannam@126: </DIV> cannam@126: <IMG SRC= cannam@126: "/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: HEIGHT=30 WIDTH=100 ALT="counter.gif"> cannam@126: </DIV> cannam@126: cannam@126: </TD> cannam@126: <!-- pepper --> cannam@126: <!-- ######################################################################## --> cannam@126: <!-- pepper --> cannam@126: <TD VALIGN="top"> cannam@126: <DIV CLASS="block"> cannam@126: cannam@126: <H1><B>Callback API</B></H1> cannam@126: <P> cannam@126: The callback API consists of the following functions : cannam@126: </P> cannam@126: <PRE> cannam@126: typedef long (*src_callback_t) (void *cb_data, float **data) ; cannam@126: cannam@126: SRC_STATE* <A HREF="#Init">src_callback_new</A> (src_callback_t func, cannam@126: int converter_type, int channels, cannam@126: int *error, void* cb_data) ; cannam@126: cannam@126: SRC_STATE* <A HREF="api_full.html#CleanUp">src_delete</A> (SRC_STATE *state) ; cannam@126: cannam@126: long <A HREF="#Read">src_callback_read</A> (SRC_STATE *state, double src_ratio, cannam@126: long frames, float *data) ; cannam@126: cannam@126: int <A HREF="api_full.html#Reset">src_reset</A> (SRC_STATE *state) ; cannam@126: int <A HREF="api_full.html#SetRatio">src_set_ratio</A> (SRC_STATE *state, double new_ratio) ; cannam@126: </PRE> cannam@126: <BR> cannam@126: cannam@126: <P> cannam@126: Like the cannam@126: <A HREF="api_simple.html">simple API</a> cannam@126: and the cannam@126: <A HREF="api_full.html">full API</a>, cannam@126: the callback based API is able to operate on interleaved multi channel data. cannam@126: </P> cannam@126: cannam@126: <P> cannam@126: An example of the use of the callback based API can be found in the cannam@126: <B>varispeed-play</B> program in the <B>examples/</B> directory of the cannam@126: source code tarball. cannam@126: </P> cannam@126: cannam@126: <!-- pepper --> cannam@126: <A NAME="Init"></A> cannam@126: <H3><BR>Initialisation</H3> cannam@126: <PRE> cannam@126: SRC_STATE* src_callback_new (src_callback_t func, cannam@126: int converter_type, int channels, cannam@126: int *error, void* cb_data) ; cannam@126: </PRE> cannam@126: <P> cannam@126: The <B>src_callback_new</B> function returns an anonymous pointer to a cannam@126: sample rate converter callback object, src_state. cannam@126: This is the same type of object as that returned by <A HREF="api_full.html#init"> cannam@126: src_new</A>, but with different internal state. cannam@126: Although these are the same object type, they cannot be used interchangeably. cannam@126: If an error occurs the function returns a NULL pointer and fills in the cannam@126: error value pointed to by the <B>error</B> pointer supplied by the caller. cannam@126: </P> cannam@126: <P> cannam@126: The caller then passes the SRC_STATE object to the <B>src_callback_read</B> cannam@126: function to pull data out of the converter. cannam@126: When the caller is finished with the converter they should pass it to the cannam@126: clean up function <A HREF="api_full.html#CleanUp">src_delete</A>. cannam@126: </P> cannam@126: <P> cannam@126: The <B>func</B> parameter is a user supplied function which must match the cannam@126: <B>src_callback_t</B> type signature while <B>cb_data</B> is a pointer to cannam@126: data which be passed as the first parameter to the user supplied callback cannam@126: function. cannam@126: This function is called by the converter whenever it needs input data as a cannam@126: result of being calls to <B>src_callback_read</B>. cannam@126: </P> cannam@126: <P> cannam@126: If the converter was initialised to work with more than one channel, the cannam@126: callback function must work with mutiple channels of interleaved data. cannam@126: The callback function should return the number of frames it supplying to cannam@126: the converter. cannam@126: For multi channel files, this return value should be the number of floats cannam@126: divided by the number of channels. cannam@126: </P> cannam@126: <P> cannam@126: The converter must be one of the supplied converter types documented cannam@126: <A HREF="api_misc.html#Converters">here</A>. cannam@126: </P> cannam@126: <P> cannam@126: The caller then passes the SRC_STATE pointer to the <B>src_callback_read</B> cannam@126: function to pull data out of the converter. cannam@126: </P> cannam@126: cannam@126: <!-- pepper --> cannam@126: <A NAME="Read"></A> cannam@126: <H3><BR>Callback Read</H3> cannam@126: <PRE> cannam@126: long src_callback_read (SRC_STATE *state, double src_ratio, cannam@126: long frames, float *data) ; cannam@126: </PRE> cannam@126: <P> cannam@126: The <B>src_callback_read</B> function is passed the cannam@126: <A HREF="api_misc.html#SRC_DATA"><B>SRC_STATE</B></A> cannam@126: pointer returned by <B>src_callback_new</B>, the coversion ratio cannam@126: (output_sample_rate / input_sample_rate), the maximum number of output frames cannam@126: to generate and a pointer to a buffer in which to place the output data. cannam@126: For multi channel files, the data int the output buffer is stored in cannam@126: interleaved format. cannam@126: </P> cannam@126: <P> cannam@126: The <B>src_callback_read</B> function returns the number of frames generated cannam@126: or zero if an error occurs or it runs out of input (ie the user supplied cannam@126: callback function returns zero and there is no more data buffered internally). cannam@126: If an error has occurred, the function <A HREF="api_misc.html#ErrorReporting"> cannam@126: src_error</A> will return non-zero. cannam@126: </P> cannam@126: cannam@126: <P> cannam@126: See also : cannam@126: <A HREF="api_full.html#SetRatio"><B>src_set_ratio</B></A> cannam@126: </P> cannam@126: cannam@126: <!-- pepper --> cannam@126: cannam@126: </DIV> cannam@126: </TD></TR> cannam@126: </TABLE> cannam@126: cannam@126: </BODY> cannam@126: </HTML> cannam@126: