shithub: libsamplerate

ref: 6a0181f59f816326f52db1775cb0c2ab4ef1758d
dir: /doc/api_callback.html/

View raw version
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>

<HEAD>
	<TITLE>
	Secret Rabbit Code (aka libsamplerate)
	</TITLE>
	<META NAME="Author"      CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
    <META NAME="Version"     CONTENT="libsamplerate-0.1.0">
	<META NAME="Description" CONTENT="The Secret Rabbit Code Home Page">
	<META NAME="Keywords"    CONTENT="libsamplerate sound audio dsp Linux">
	<LINK REL=StyleSheet HREF="SRC.css" TYPE="text/css" MEDIA="all">
</HEAD>

<BODY TEXT="#FFFFFF" BGCOLOR="#000000" LINK="#FB1465" VLINK="#FB1465" ALINK="#FB1465">
<!-- pepper -->
<CENTER>
	<IMG SRC="SRC.png" HEIGHT=100 WIDTH=760 ALT="SRC.png">
</CENTER>
<!-- pepper -->
<BR>
<!-- pepper -->
<TABLE ALIGN="center" WIDTH="98%">
<TR>
<TD VALIGN="top">
<BR>
<DIV CLASS="nav">
	<BR>
	<A HREF="index.html">Home</A><BR>
	<BR>
	<A HREF="api_simple.html">Simple API</A><BR>
	<A HREF="api_full.html">Full API</A><BR>
	<A HREF="api_callback.html">Callback API</A><BR>
	<A HREF="api_misc.html">Miscellaneous</A><BR>
	<A HREF="api_misc.html#ErrorReporting">Error Handling</A><BR>
<BR>
<DIV CLASS="block">
Author :<BR>Erik de Castro Lopo
<!-- pepper -->
<BR><BR>
<!-- pepper -->

</DIV>
	<IMG SRC=
	"/cgi-bin/Count.cgi?ft=6|frgb=55;55;55|tr=0|md=6|dd=B|st=1|sh=1|df=src_api.dat" 
	HEIGHT=30 WIDTH=100 ALT="counter.gif">
</DIV>

</TD>
<!-- pepper -->
<!-- ######################################################################## -->
<!-- pepper -->
<TD VALIGN="top">
<DIV CLASS="block">

<H1><B>Callback API</B></H1>
<P>
The callback API consists of the following functions :
</P>
<PRE>
      typedef long (*src_callback_t) (void *cb_data, float **data) ;

      SRC_STATE* <A HREF="#Init">src_callback_new</A> (src_callback_t func, 
	                      int converter_type, int channels, 
	                      int *error, void* cb_data) ;

      SRC_STATE* <A HREF="api_full.html#CleanUp">src_delete</A> (SRC_STATE *state) ;

      long <A HREF="#Read">src_callback_read</A> (SRC_STATE *state, double src_ratio, 
	                       long frames, float *data) ;

      int <A HREF="api_full.html#Reset">src_reset</A> (SRC_STATE *state) ;
      int <A HREF="api_full.html#SetRatio">src_set_ratio</A> (SRC_STATE *state, double new_ratio) ;
</PRE>
<BR>
<P>
An example of the use of the callback based API can be found in the 
<B>varispeed-play</B> program in the <B>examples/</B> directory of the 
source code tarball.
</P>

<A NAME="Init"></A>
<H3><BR>Initialisation</H3>
<PRE>
      SRC_STATE* src_callback_new (src_callback_t func, 
	                      int converter_type, int channels, 
	                      int *error, void* cb_data) ;
</PRE>
<P>
The <B>src_callback_new</B> function returns an anonymous pointer to a 
sample rate converter callback object, src_state.
This is the same type of object as that returned by <A HREF="api_full.html#init">
src_new</A>, but with different internal state. 
Although these are the same object type, they cannot be used interchangeably.
If an error occurs the function returns a NULL pointer and fills in the
error value pointed to by the <B>error</B> pointer supplied by the caller.
</P>
<P>
When the caller 
</P>
<P>
The <B>func</B> parameter is a user supplied function which must match the 
<B>src_callback_t</B> type while <B>cb_data</B> is a pointer to data which
be passed as the first parameter to the user supplied callback function.
The converter must be one of the supplied converter types documented
<A HREF="api_misc.html#Converters">here</A>.
</P>

<A NAME="Read"></A>
<H3><BR>Callback Read</H3>
<PRE>
      long src_callback_read (SRC_STATE *state, double src_ratio, 
	                       long frames, float *data) ;
</PRE>
<P>
The <B>src_callback_read</B> function is passed the <B>SRC_STATE</B> pointer
returned by <B>src_callback_new</B>, the coversion ratio (output_sample_rate 
/ input_sample_rate), the maximum number of output frames to generate and a 
pointer to a buffer in which to place the output data.
</P>
<P>
The <B>src_callback_read</B> function returns the number of frames generated
or zero if an error occurs or it runs out of input (ie the user supplied 
callback function returns zero and there is no more data buffered internally).
If an error has occurred, the function <A HREF="api_misc.html#ErrorReporting">
src_error</A> will return non-zero.
</P>

<!-- <A HREF="mailto:[email protected]">For the spam bots</A> -->

</DIV>
</TD></TR>
</TABLE>

</BODY>
</HTML>

<!--
  Do not edit or modify anything in this comment block.
  The arch-tag line is a file identity tag for the GNU Arch 
  revision control system.
 
  arch-tag: c80cf67e-b7a1-4701-a608-a1718c5aa57d
-->