Mercurial > hg > sv-dependency-builds

annotate src/libsamplerate-0.1.9/doc/api_callback.html @ 41:481f5f8c5634

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