libsamplerate/doc/api_callback.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2 <HTML>
   3
   4 <HEAD>
   5         <TITLE>
   6         Secret Rabbit Code (aka libsamplerate)
   7         </TITLE>
   8         <META NAME="Author"      CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
   9     <META NAME="Version"     CONTENT="libsamplerate-0.1.8">
  10         <META NAME="Description" CONTENT="The Secret Rabbit Code Home Page">
  11         <META NAME="Keywords"    CONTENT="libsamplerate sound resample audio dsp Linux">
  12         <LINK REL=StyleSheet HREF="SRC.css" TYPE="text/css" MEDIA="all">
  13 </HEAD>
  14
  15 <BODY TEXT="#FFFFFF" BGCOLOR="#000000" LINK="#FB1465" VLINK="#FB1465" ALINK="#FB1465">
  16 <!-- pepper -->
  17 <CENTER>
  18         <IMG SRC="SRC.png" HEIGHT=100 WIDTH=760 ALT="SRC.png">
  19 </CENTER>
  20 <!-- pepper -->
  21 <BR>
  22 <!-- pepper -->
  23 <TABLE ALIGN="center" WIDTH="98%">
  24 <TR>
  25 <TD VALIGN="top">
  26 <BR>
  27 <DIV CLASS="nav">
  28         <BR>
  29         <A HREF="index.html">Home</A><BR>
  30         <BR>
  31         <A HREF="api_simple.html">Simple API</A><BR>
  32         <A HREF="api_full.html">Full API</A><BR>
  33         <A HREF="api_callback.html">Callback API</A><BR>
  34         <A HREF="api_misc.html">Miscellaneous</A><BR>
  35         <A HREF="api_misc.html#ErrorReporting">Error Handling</A><BR>
  36 <BR>
  37 <DIV CLASS="block">
  38 Author :<BR>Erik de Castro Lopo
  39 <!-- pepper -->
  40 <BR><BR>
  41 <!-- pepper -->
  42
  43 </DIV>
  44         <IMG SRC=
  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"
  46         HEIGHT=30 WIDTH=100 ALT="counter.gif">
  47 </DIV>
  48
  49 </TD>
  50 <!-- pepper -->
  51 <!-- ######################################################################## -->
  52 <!-- pepper -->
  53 <TD VALIGN="top">
  54 <DIV CLASS="block">
  55
  56 <H1><B>Callback API</B></H1>
  57 <P>
  58 The callback API consists of the following functions :
  59 </P>
  60 <PRE>
  61       typedef long (*src_callback_t) (void *cb_data, float **data) ;
  62
  63       SRC_STATE* <A HREF="#Init">src_callback_new</A> (src_callback_t func,
  64                               int converter_type, int channels,
  65                               int *error, void* cb_data) ;
  66
  67       SRC_STATE* <A HREF="api_full.html#CleanUp">src_delete</A> (SRC_STATE *state) ;
  68
  69       long <A HREF="#Read">src_callback_read</A> (SRC_STATE *state, double src_ratio,
  70                                long frames, float *data) ;
  71
  72       int <A HREF="api_full.html#Reset">src_reset</A> (SRC_STATE *state) ;
  73       int <A HREF="api_full.html#SetRatio">src_set_ratio</A> (SRC_STATE *state, double new_ratio) ;
  74 </PRE>
  75 <BR>
  76
  77 <P>
  78 Like the
  79         <A HREF="api_simple.html">simple API</a>
  80 and the
  81         <A HREF="api_full.html">full API</a>,
  82 the callback based API is able to operate on interleaved multi channel data.
  83 </P>
  84
  85 <P>
  86 An example of the use of the callback based API can be found in the
  87 <B>varispeed-play</B> program in the <B>examples/</B> directory of the
  88 source code tarball.
  89 </P>
  90
  91 <!-- pepper -->
  92 <A NAME="Init"></A>
  93 <H3><BR>Initialisation</H3>
  94 <PRE>
  95       SRC_STATE* src_callback_new (src_callback_t func,
  96                               int converter_type, int channels,
  97                               int *error, void* cb_data) ;
  98 </PRE>
  99 <P>
 100 The <B>src_callback_new</B> function returns an anonymous pointer to a
 101 sample rate converter callback object, src_state.
 102 This is the same type of object as that returned by <A HREF="api_full.html#init">
 103 src_new</A>, but with different internal state.
 104 Although these are the same object type, they cannot be used interchangeably.
 105 If an error occurs the function returns a NULL pointer and fills in the
 106 error value pointed to by the <B>error</B> pointer supplied by the caller.
 107 </P>
 108 <P>
 109 The caller then passes the SRC_STATE object to the <B>src_callback_read</B>
 110 function to pull data out of the converter.
 111 When the caller is finished with the converter they should pass it to the
 112 clean up function <A HREF="api_full.html#CleanUp">src_delete</A>.
 113 </P>
 114 <P>
 115 The <B>func</B> parameter is a user supplied function which must match the
 116 <B>src_callback_t</B> type signature while <B>cb_data</B> is a pointer to
 117 data which be passed as the first parameter to the user supplied callback
 118 function.
 119 This function is called by the converter whenever it needs input data as a
 120 result of being calls to <B>src_callback_read</B>.
 121 </P>
 122 <P>
 123 If the converter was initialised to work with more than one channel, the
 124 callback function must work with mutiple channels of interleaved data.
 125 The callback function should return the number of frames it supplying to
 126 the converter.
 127 For multi channel files, this return value should be the number of floats
 128 divided by the number of channels.
 129 </P>
 130 <P>
 131 The converter must be one of the supplied converter types documented
 132 <A HREF="api_misc.html#Converters">here</A>.
 133 </P>
 134 <P>
 135 The caller then passes the SRC_STATE pointer to the <B>src_callback_read</B>
 136 function to pull data out of the converter.
 137 </P>
 138
 139 <!-- pepper -->
 140 <A NAME="Read"></A>
 141 <H3><BR>Callback Read</H3>
 142 <PRE>
 143       long src_callback_read (SRC_STATE *state, double src_ratio,
 144                                long frames, float *data) ;
 145 </PRE>
 146 <P>
 147 The <B>src_callback_read</B> function is passed the
 148         <A HREF="api_misc.html#SRC_DATA"><B>SRC_STATE</B></A>
 149 pointer returned by <B>src_callback_new</B>, the coversion ratio
 150 (output_sample_rate / input_sample_rate), the maximum number of output frames
 151 to generate and a pointer to a buffer in which to place the output data.
 152 For multi channel files, the data int the output buffer is stored in
 153 interleaved format.
 154 </P>
 155 <P>
 156 The <B>src_callback_read</B> function returns the number of frames generated
 157 or zero if an error occurs or it runs out of input (ie the user supplied
 158 callback function returns zero and there is no more data buffered internally).
 159 If an error has occurred, the function <A HREF="api_misc.html#ErrorReporting">
 160 src_error</A> will return non-zero.
 161 </P>
 162
 163 <P>
 164 See also :
 165         <A HREF="api_full.html#SetRatio"><B>src_set_ratio</B></A>
 166 </P>
 167
 168 <!-- pepper -->
 169
 170 </DIV>
 171 </TD></TR>
 172 </TABLE>
 173
 174 </BODY>
 175 </HTML>
 176