annotate src/libsamplerate-0.1.9/doc/api_simple.html @ 83:ae30d91d2ffe

Replace these with versions built using an older toolset (so as to avoid ABI compatibilities when linking on Ubuntu 14.04 for packaging purposes)
author Chris Cannam
date Fri, 07 Feb 2020 11:51:13 +0000
parents 481f5f8c5634
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>Simple API</B></H1>
Chris@41 57
Chris@41 58 <P>
Chris@41 59 <B>Important Note:</B>
Chris@41 60 The simple API is not designed to work on small chunks of a larger piece of
Chris@41 61 audio.
Chris@41 62 If you attempt to use it this way you are doing it wrong and will not get the
Chris@41 63 results you want.
Chris@41 64 For processing audio data in chunks you <b>must</b> use the
Chris@41 65 <a href="api_full.html">full api</a>
Chris@41 66 or the
Chris@41 67 <a href="api_callback.html">callback based api</a>.
Chris@41 68 </P>
Chris@41 69
Chris@41 70 <br/><br/>
Chris@41 71
Chris@41 72 <P>
Chris@41 73 The simple API consists of a single function :
Chris@41 74 </P>
Chris@41 75 <PRE>
Chris@41 76 int src_simple (SRC_DATA *data, int converter_type, int channels) ;
Chris@41 77 </PRE>
Chris@41 78 <P>
Chris@41 79 The use of this function rather than the more fully featured API requires the caller
Chris@41 80 to know the total length of the input data before hand and that all input and output
Chris@41 81 data can be held in the system's memory at once.
Chris@41 82 It also assumes that there is a single constant ratio between input and output sample
Chris@41 83 rates.
Chris@41 84 <!--
Chris@41 85 If these conditions cannot be met, the full featured API should be used instead.
Chris@41 86 In addition, this documentation is complemented by this
Chris@41 87 <A HREF="ex_simple.html">example code</A>. -->
Chris@41 88 </P>
Chris@41 89
Chris@41 90 <P>
Chris@41 91 Dealing with the easy stuff first, the <B>converter_type</B> parameter should be
Chris@41 92 one of the values defined in <B>samplerate.h</B> and documented
Chris@41 93 <A HREF="api_misc.html#Converters">here</A> while the <b>channels</b> parameter
Chris@41 94 specifies the number of interleaved channels that the sample rate converter
Chris@41 95 is being asked to process (number of input channels and output channels is always
Chris@41 96 equal).
Chris@41 97 There is no hard upper limit on the number of channels; it is limited purely
Chris@41 98 by the amount of memory available.
Chris@41 99 </P>
Chris@41 100
Chris@41 101
Chris@41 102 <P>
Chris@41 103 The first parameter to <B>src_simple</B> is a pointer to an <B>SRC_DATA</B> struct
Chris@41 104 (more info <A HREF="api_misc.html#SRC_DATA">here</A>) defined as follows:
Chris@41 105 </P>
Chris@41 106 <PRE>
Chris@41 107 typedef struct
Chris@41 108 { float *data_in, *data_out ;
Chris@41 109
Chris@41 110 long input_frames, output_frames ;
Chris@41 111 long input_frames_used, output_frames_gen ;
Chris@41 112
Chris@41 113 int end_of_input ;
Chris@41 114
Chris@41 115 double src_ratio ;
Chris@41 116 } SRC_DATA ;
Chris@41 117 </PRE>
Chris@41 118 <P>
Chris@41 119 The fields of this struct which must be filled in by the caller are:
Chris@41 120 </P>
Chris@41 121 <PRE>
Chris@41 122 data_in : A pointer to the input data samples.
Chris@41 123 input_frames : The number of frames of data pointed to by data_in.
Chris@41 124 data_out : A pointer to the output data samples.
Chris@41 125 output_frames : Maximum number of frames pointer to by data_out.
Chris@41 126 src_ratio : Equal to output_sample_rate / input_sample_rate.
Chris@41 127 </PRE>
Chris@41 128 <P>
Chris@41 129 When the <B>src_simple</B> function returns <B>output_frames_gen</B> will be
Chris@41 130 set to the number of output frames generated and <B>input_frames_used</B> will
Chris@41 131 be set to the number of input frames used to generate the provided number of
Chris@41 132 output frames.
Chris@41 133 </P>
Chris@41 134 <P>
Chris@41 135 The <B>src_simple</B> function returns a non-zero value when an error occurs.
Chris@41 136 See <A HREF="api_misc.html#ErrorReporting">here</A> for how to convert the error value into
Chris@41 137 a text string.
Chris@41 138 </P>
Chris@41 139
Chris@41 140 </DIV>
Chris@41 141 </TD></TR>
Chris@41 142 </TABLE>
Chris@41 143
Chris@41 144 </BODY>
Chris@41 145 </HTML>
Chris@41 146