ref: ace89ad7cca307fd24225c672f613c6d40587588
parent: 834dcfcc45fe4f21fefdced79561c8081ce05bc6
author: Erik de Castro Lopo <erikd@miles>
date: Tue Sep 6 07:01:54 EDT 2005
api_callback.html : Complete documentation.
--- a/doc/api_callback.html
+++ b/doc/api_callback.html
@@ -42,7 +42,7 @@
</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"
+ "/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>
@@ -60,13 +60,13 @@
<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,
+ 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 <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) ;
@@ -74,59 +74,73 @@
</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
+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>
+<!-- pepper -->
<A NAME="Init"></A>
<H3><BR>Initialisation</H3>
<PRE>
- SRC_STATE* src_callback_new (src_callback_t func,
- int converter_type, int channels,
+ 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
+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.
+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
+The caller then passes the SRC_STATE object to the <B>src_callback_read</B>
+function to pull data out of the converter.
+When the caller is finished with the converter they should pass it to the
+clean up function <A HREF="api_full.html#CleanUp">src_delete</A>.
</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 <B>func</B> parameter is a user supplied function which must match the
+<B>src_callback_t</B> type signature while <B>cb_data</B> is a pointer to
+data which be passed as the first parameter to the user supplied callback
+function.
+This function is called by the converter whenever it needs input data as a
+result of being calls to <B>src_callback_read</B>.
+</P>
+<P>
The converter must be one of the supplied converter types documented
<A HREF="api_misc.html#Converters">here</A>.
</P>
+<P>
+The caller then passes the SRC_STATE pointer to the <B>src_callback_read</B>
+function to pull data out of the converter.
+</P>
+<!-- pepper -->
<A NAME="Read"></A>
<H3><BR>Callback Read</H3>
<PRE>
- long src_callback_read (SRC_STATE *state, double src_ratio,
+ 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
+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
+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> -->
+<!-- pepper -->
</DIV>
</TD></TR>
@@ -137,9 +151,9 @@
<!--
Do not edit or modify anything in this comment block.
- The arch-tag line is a file identity tag for the GNU Arch
+ The arch-tag line is a file identity tag for the GNU Arch
revision control system.
-
+
arch-tag: c80cf67e-b7a1-4701-a608-a1718c5aa57d
-->