[audio-libsamplerate.git] / libsamplerate / doc / api_full.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>Full API</B></H1>
<P>
The full API consists of the following functions :
</P>
<PRE>
      SRC_STATE* <A HREF="#Init">src_new</A> (int converter_type, int channels, int *error) ;
      SRC_STATE* <A HREF="#CleanUp">src_delete</A> (SRC_STATE *state) ;

      int <A HREF="#Process">src_process</A> (SRC_STATE *state, SRC_DATA *data) ;
      int <A HREF="#Reset">src_reset</A> (SRC_STATE *state) ;
      int <A HREF="#SetRatio">src_set_ratio</A> (SRC_STATE *state, double new_ratio) ;
</PRE>

<A NAME="Init"></A>
<H3><BR>Initialisation</H3>
<PRE>
      SRC_STATE* src_new (int converter_type, int channels, int *error) ;
</PRE>
<P>
The <B>src_new</B> function returns an anonymous pointer to a sample rate 
converter object, src_state. 
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.
The converter must be one of the supplied converter types documented
<A HREF="api_misc.html#Converters">here</A>.
</P>

<A NAME="CleanUp"></A>
<H3><BR>Cleanup</H3>
<PRE>
      SRC_STATE* src_delete (SRC_STATE *state) ;
</PRE>
<P>
The <B>src_delete</B> function frees up all memory allocated for the given sample
rate converter object and returns a NULL pointer.
The caller is responsible for freeing any memory passed to the sample rate converter
via the pointer to the <B>SRC_DATA</B> struct.
</P>

<A NAME="Process"></A>
<H3><BR>Process</H3>
<PRE>
      int src_process (SRC_STATE *state, SRC_DATA *data) ;
</PRE>
<P>
The <B>src_process</B> function processes the data provided by the caller
in an <B>SRC_DATA</B> struct using the sample rate converter object specified
by the <B>SRC_STATE</B> pointer.
When operating on streaming data, this function can be called over and over again,
with each new call providing new input data and returning new output data.
</P>

<P>
The <B>SRC_DATA</B> struct passed as the second parameter to the <B>src_process</B> 
function has the following fields:
</P>
<PRE>
      typedef struct
      {   float  *data_in, *data_out ;

          long   input_frames, output_frames ;
          long   input_frames_used, output_frames_gen ;

          int    end_of_input ;

          double src_ratio ;
      } SRC_DATA ;
</PRE>
<P>
The fields of this struct which must be filled in by the caller are:
</P>
<PRE>
      data_in       : A pointer to the input data samples.
      input_frames  : The number of frames of data pointed to by data_in.
      data_out      : A pointer to the output data samples.
      output_frames : Maximum number of frames pointer to by data_out.
      src_ratio     : Equal to output_sample_rate / input_sample_rate.
      end_of_input  : Equal to 0 if more input data is available and 1 
                      otherwise.
</PRE>
<P>
Note that the data_in and data_out arrays may not overlap. If they do, the 
library will return an error code.
</P>
<P>
When the <B>src_process</B> function returns <B>output_frames_gen</B> will be 
set to the number of output frames generated and <B>input_frames_used</B> will 
be set to the number of input frames consumed to generate the provided number of 
output frames.
</P>

<P>
The <B>src_process</B> function returns non-zero if an error occurs.
The non-zero error return value can be decoded into a text string using the function
documented <A HREF="api_misc.html#ErrorReporting">here</A>.
</P>

<A NAME="Reset"></A>
<H3><BR>Reset</H3>
<PRE>
      int src_reset (SRC_STATE *state) ;
</PRE>
<P>
The <B>src_reset</B> function resets the internal state of the sample rate 
converter object to the same state it had immediately after its creation using
<B>src_new</B>.
This should be called whenever a sample rate converter is to be used on two 
separate, unrelated pieces of audio.
</P>

<A NAME="SetRatio"></A>
<H3><BR>Set Ratio</H3>
<PRE>
      int src_set_ratio (SRC_STATE *state, double new_ratio) ;
</PRE>

<p>
When using the <B>src_process</B> or <B>src_callback_process</B> APIs and 
updating the <B>src_ratio</B> field of the <B>SRC_STATE</B> struct, the library
will try to smoothly transition between the conversion ratio of the last call
and the conversion ratio of the current call.
<p/>

<P>
If the user want to bypass this smooth transition and achieve a step response in
the conversion ratio, the <B>src_set_ratio</B> function can be used to set the
starting conversion ratio of the next call to <B>src_process</B> or
<B>src_callback_process</B>.
<p/>

<P>
This function returns non-zero on error and the error return value can be
decoded into a text string using the function documented 
<A HREF="api_misc.html#ErrorReporting">here</A>.</P>

<!-- <A HREF="mailto:aldel@mega-nerd.com">For the spam bots</A> -->

</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>Full API</B></H1>
	57	<P>
	58	The full API consists of the following functions :
	59	</P>
	60	<PRE>
	61	SRC_STATE* <A HREF="#Init">src_new</A> (int converter_type, int channels, int *error) ;
	62	SRC_STATE* <A HREF="#CleanUp">src_delete</A> (SRC_STATE *state) ;
	63
	64	int <A HREF="#Process">src_process</A> (SRC_STATE state, SRC_DATA data) ;
65	int <A HREF="#Reset">src_reset</A> (SRC_STATE *state) ;
66	int <A HREF="#SetRatio">src_set_ratio</A> (SRC_STATE *state, double new_ratio) ;
67	</PRE>
68
69	<A NAME="Init"></A>
70	<H3><BR>Initialisation</H3>
71	<PRE>
72	SRC_STATE* src_new (int converter_type, int channels, int *error) ;
73	</PRE>
74	<P>
75	The <B>src_new</B> function returns an anonymous pointer to a sample rate
76	converter object, src_state.
77	If an error occurs the function returns a NULL pointer and fills in the
78	error value pointed to by the <B>error</B> pointer supplied by the caller.
79	The converter must be one of the supplied converter types documented
80	<A HREF="api_misc.html#Converters">here</A>.
81	</P>
82
83	<A NAME="CleanUp"></A>
84	<H3><BR>Cleanup</H3>
85	<PRE>
86	SRC_STATE* src_delete (SRC_STATE *state) ;
87	</PRE>
88	<P>
89	The <B>src_delete</B> function frees up all memory allocated for the given sample
90	rate converter object and returns a NULL pointer.
91	The caller is responsible for freeing any memory passed to the sample rate converter
92	via the pointer to the <B>SRC_DATA</B> struct.
93	</P>
94
95	<A NAME="Process"></A>
96	<H3><BR>Process</H3>
97	<PRE>
98	int src_process (SRC_STATE state, SRC_DATA data) ;
99	</PRE>
100	<P>
101	The <B>src_process</B> function processes the data provided by the caller
102	in an <B>SRC_DATA</B> struct using the sample rate converter object specified
103	by the <B>SRC_STATE</B> pointer.
104	When operating on streaming data, this function can be called over and over again,
105	with each new call providing new input data and returning new output data.
106	</P>
107
108	<P>
109	The <B>SRC_DATA</B> struct passed as the second parameter to the <B>src_process</B>
110	function has the following fields:
111	</P>
112	<PRE>
113	typedef struct
114	{ float data_in, data_out ;
115
116	long input_frames, output_frames ;
117	long input_frames_used, output_frames_gen ;
118
119	int end_of_input ;
120
121	double src_ratio ;
122	} SRC_DATA ;
123	</PRE>
124	<P>
125	The fields of this struct which must be filled in by the caller are:
126	</P>
127	<PRE>
128	data_in : A pointer to the input data samples.
129	input_frames : The number of frames of data pointed to by data_in.
130	data_out : A pointer to the output data samples.
131	output_frames : Maximum number of frames pointer to by data_out.
132	src_ratio : Equal to output_sample_rate / input_sample_rate.
133	end_of_input : Equal to 0 if more input data is available and 1
134	otherwise.
135	</PRE>
136	<P>
137	Note that the data_in and data_out arrays may not overlap. If they do, the
138	library will return an error code.
139	</P>
140	<P>
141	When the <B>src_process</B> function returns <B>output_frames_gen</B> will be
142	set to the number of output frames generated and <B>input_frames_used</B> will
143	be set to the number of input frames consumed to generate the provided number of
144	output frames.
145	</P>
146
147	<P>
148	The <B>src_process</B> function returns non-zero if an error occurs.
149	The non-zero error return value can be decoded into a text string using the function
150	documented <A HREF="api_misc.html#ErrorReporting">here</A>.
151	</P>
152
153	<A NAME="Reset"></A>
154	<H3><BR>Reset</H3>
155	<PRE>
156	int src_reset (SRC_STATE *state) ;
157	</PRE>
158	<P>
159	The <B>src_reset</B> function resets the internal state of the sample rate
160	converter object to the same state it had immediately after its creation using
161	<B>src_new</B>.
162	This should be called whenever a sample rate converter is to be used on two
163	separate, unrelated pieces of audio.
164	</P>
165
166	<A NAME="SetRatio"></A>
167	<H3><BR>Set Ratio</H3>
168	<PRE>
169	int src_set_ratio (SRC_STATE *state, double new_ratio) ;
170	</PRE>
171
172	<p>
173	When using the <B>src_process</B> or <B>src_callback_process</B> APIs and
174	updating the <B>src_ratio</B> field of the <B>SRC_STATE</B> struct, the library
175	will try to smoothly transition between the conversion ratio of the last call
176	and the conversion ratio of the current call.
177	<p/>
178
179	<P>
180	If the user want to bypass this smooth transition and achieve a step response in
181	the conversion ratio, the <B>src_set_ratio</B> function can be used to set the
182	starting conversion ratio of the next call to <B>src_process</B> or
183	<B>src_callback_process</B>.
184	<p/>
185
186	<P>
187	This function returns non-zero on error and the error return value can be
188	decoded into a text string using the function documented
189	<A HREF="api_misc.html#ErrorReporting">here</A>.</P>
190
191	<!-- <A HREF="mailto:aldel@mega-nerd.com">For the spam bots</A> -->
192
193	</DIV>
194	</TD></TR>
195	</TABLE>
196
197	</BODY>
198	</HTML>
199