Mercurial > hg > sv-dependency-builds

comparison 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
comparison
equal deleted inserted replaced
40:1df64224f5ac 41:481f5f8c5634
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