[audio-libsamplerate.git] / libsamplerate / doc / api_callback.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>

<HEAD>
	<TITLE>
	Secret Rabbit Code (aka libsamplerate)
	</TITLE>
	<META NAME="Author"      CONTENT="Erik de Castro Lopo (erikd AT mega-nerd DOT com)">
    <META NAME="Version"     CONTENT="libsamplerate-0.1.8">
	<META NAME="Description" CONTENT="The Secret Rabbit Code Home Page">
	<META NAME="Keywords"    CONTENT="libsamplerate sound resample audio dsp Linux">
	<LINK REL=StyleSheet HREF="SRC.css" TYPE="text/css" MEDIA="all">
</HEAD>

<BODY TEXT="#FFFFFF" BGCOLOR="#000000" LINK="#FB1465" VLINK="#FB1465" ALINK="#FB1465">
<!-- pepper -->
<CENTER>
	<IMG SRC="SRC.png" HEIGHT=100 WIDTH=760 ALT="SRC.png">
</CENTER>
<!-- pepper -->
<BR>
<!-- pepper -->
<TABLE ALIGN="center" WIDTH="98%">
<TR>
<TD VALIGN="top">
<BR>
<DIV CLASS="nav">
	<BR>
	<A HREF="index.html">Home</A><BR>
	<BR>
	<A HREF="api_simple.html">Simple API</A><BR>
	<A HREF="api_full.html">Full API</A><BR>
	<A HREF="api_callback.html">Callback API</A><BR>
	<A HREF="api_misc.html">Miscellaneous</A><BR>
	<A HREF="api_misc.html#ErrorReporting">Error Handling</A><BR>
<BR>
<DIV CLASS="block">
Author :<BR>Erik de Castro Lopo
<!-- pepper -->
<BR><BR>
<!-- pepper -->

</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"
	HEIGHT=30 WIDTH=100 ALT="counter.gif">
</DIV>

</TD>
<!-- pepper -->
<!-- ######################################################################## -->
<!-- pepper -->
<TD VALIGN="top">
<DIV CLASS="block">

<H1><B>Callback API</B></H1>
<P>
The callback API consists of the following functions :
</P>
<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,
	                      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 frames, float *data) ;

      int <A HREF="api_full.html#Reset">src_reset</A> (SRC_STATE *state) ;
      int <A HREF="api_full.html#SetRatio">src_set_ratio</A> (SRC_STATE *state, double new_ratio) ;
</PRE>
<BR>

<P>
Like the
	<A HREF="api_simple.html">simple API</a>
and the
	<A HREF="api_full.html">full API</a>,
the callback based API is able to operate on interleaved multi channel data.
</P>

<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
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,
	                      int *error, void* cb_data) ;
</PRE>
<P>
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.
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>
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 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>
If the converter was initialised to work with more than one channel, the
callback function must work with mutiple channels of interleaved data.
The callback function should return the number of frames it supplying to
the converter.
For multi channel files, this return value should be the number of floats
divided by the number of channels.
</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 frames, float *data) ;
</PRE>
<P>
The <B>src_callback_read</B> function is passed the
	<A HREF="api_misc.html#SRC_DATA"><B>SRC_STATE</B></A>
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 pointer to a buffer in which to place the output data.
For multi channel files, the data int the output buffer is stored in
interleaved format.
</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
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>

<P>
See also :
	<A HREF="api_full.html#SetRatio"><B>src_set_ratio</B></A>
</P>

<!-- pepper -->

</DIV>
</TD></TR>
</TABLE>

</BODY>
</HTML>
Commit	Line	Data
8529da43 MG	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