* Use GitHub's Jekyll static site generator. * Move all documentation to docs/ directory. * Convert HTML to Markdown.
Showing the changes to docs/api_simple.md (1 of 38 files). Show all
Unified · Split
| @@ -0,0 +1,71 @@ | |||
| 1 | --- | ||
| 2 | layout: default | ||
| 3 | --- | ||
| 4 | |||
| 5 | # Simple API | ||
| 6 | |||
| 7 | **Important Note:** The simple API is not designed to work on small chunks of a | ||
| 8 | larger piece of audio. If you attempt to use it this way you are doing it wrong | ||
| 9 | and will not get the results you want. For processing audio data in chunks you | ||
| 10 | **must** use the [full api](api_full.md) or the [callback based api](api_callback.md). | ||
| 11 | |||
| 12 | The simple API consists of a single function: | ||
| 13 | |||
| 14 | ```c | ||
| 15 | int src_simple (SRC_DATA *data, int converter_type, int channels) ; | ||
| 16 | ``` | ||
| 17 | |||
| 18 | The use of this function rather than the more fully featured API requires the | ||
| 19 | caller to know the total length of the input data before hand and that all input | ||
| 20 | and output data can be held in the system's memory at once. It also assumes that | ||
| 21 | there is a single constant ratio between input and output sample rates. | ||
| 22 | |||
| 23 | Dealing with the easy stuff first, the **converter_type** parameter should be | ||
| 24 | one of the values defined in **samplerate.h** and documented [here](api_misc.md#converters) | ||
| 25 | while the **channels** parameter specifies the number of interleaved channels | ||
| 26 | that the sample rate converter is being asked to process (number of input | ||
| 27 | channels and output channels is always equal). There is no hard upper limit on | ||
| 28 | the number of channels; it is limited purely by the amount of memory available. | ||
| 29 | |||
| 30 | The first parameter to **src_simple** is a pointer to an **SRC_DATA** struct | ||
| 31 | (more info [here](api_misc.md#src_data)) defined as follows: | ||
| 32 | |||
| 33 | ```c | ||
| 34 | typedef struct | ||
| 35 | { const float *data_in; | ||
| 36 | float *data_out ; | ||
| 37 | |||
| 38 | long input_frames, output_frames ; | ||
| 39 | long input_frames_used, output_frames_gen ; | ||
| 40 | |||
| 41 | int end_of_input ; | ||
| 42 | |||
| 43 | double src_ratio ; | ||
| 44 | } SRC_DATA ; | ||
| 45 | ``` | ||
| 46 | |||
| 47 | The fields of this struct which must be filled in by the caller are: | ||
| 48 | |||
| 49 | data_in | ||
| 50 | : A pointer to the input data samples. | ||
| 51 | |||
| 52 | input_frames | ||
| 53 | : The number of frames of data pointed to by data_in. | ||
| 54 | |||
| 55 | data_out | ||
| 56 | : A pointer to the output data samples. | ||
| 57 | |||
| 58 | output_frames | ||
| 59 | : Maximum number of frames pointer to by data_out. | ||
| 60 | |||
| 61 | src_ratio | ||
| 62 | : Equal to output_sample_rate / input_sample_rate. | ||
| 63 | |||
| 64 | When the **src_simple** function returns **output_frames_gen** will be set to | ||
| 65 | the number of output frames generated and **input_frames_used** will be set to | ||
| 66 | the number of input frames used to generate the provided number of output | ||
| 67 | frames. | ||
| 68 | |||
| 69 | The **src_simple** function returns a non-zero value when an error occurs. See | ||
| 70 | [here](api_misc.md#error-reporting) for how to convert the error value into a | ||
| 71 | text string. | ||