Mercurial > hg > sv-dependency-builds

annotate src/libsamplerate-0.1.9/doc/api_callback.html @ 169:223a55898ab9 tip default

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