* Use GitHub's Jekyll static site generator. * Move all documentation to docs/ directory. * Convert HTML to Markdown.
Showing the changes to docs/api_callback.md (1 of 38 files). Show all
Unified · Split
| @@ -0,0 +1,88 @@ | ||
| 1 | +--- | |
| 2 | +layout: default | |
| 3 | +--- | |
| 4 | + | |
| 5 | +# Callback API | |
| 6 | + | |
| 7 | +The callback API consists of the following functions : | |
| 8 | + | |
| 9 | +```c | |
| 10 | +typedef long (*src_callback_t) (void *cb_data, float **data) ; | |
| 11 | + | |
| 12 | +SRC_STATE* src_callback_new (src_callback_t func, | |
| 13 | + int converter_type, int channels, | |
| 14 | + int *error, void* cb_data) ; | |
| 15 | + | |
| 16 | +SRC_STATE* src_delete (SRC_STATE *state) ; | |
| 17 | + | |
| 18 | +long src_callback_read (SRC_STATE *state, double src_ratio, | |
| 19 | + long frames, float *data) ; | |
| 20 | + | |
| 21 | +int src_reset (SRC_STATE *state) ; | |
| 22 | +int src_set_ratio (SRC_STATE *state, double new_ratio) ; | |
| 23 | +``` | |
| 24 | + | |
| 25 | +Like the [simple API](api_simple.md) and the [full API](api_full.md), the | |
| 26 | +callback based API is able to operate on interleaved multi channel data. | |
| 27 | + | |
| 28 | +An example of the use of the callback based API can be found in the | |
| 29 | +**varispeed-play** program in the **examples/** directory of the source code | |
| 30 | +tarball. | |
| 31 | + | |
| 32 | +## Initialisation | |
| 33 | + | |
| 34 | +```c | |
| 35 | +SRC_STATE* src_callback_new (src_callback_t func, | |
| 36 | + int converter_type, int channels, | |
| 37 | + int *error, void* cb_data) ; | |
| 38 | +``` | |
| 39 | + | |
| 40 | +The **src_callback_new** function returns an anonymous pointer to a sample rate | |
| 41 | +converter callback object, src_state. This is the same type of object as that | |
| 42 | +returned by [src\_new](api_full.md#initialisation), but with different internal | |
| 43 | +state. Although these are the same object type, they cannot be used | |
| 44 | +interchangeably. If an error occurs the function returns a NULL pointer and | |
| 45 | +fills in the error value pointed to by the **error** pointer supplied by the | |
| 46 | +caller. | |
| 47 | + | |
| 48 | +The caller then passes the SRC_STATE object to the **src_callback_read** | |
| 49 | +function to pull data out of the converter. When the caller is finished with the | |
| 50 | +converter they should pass it to the clean up function [src_delete](api_full.md#cleanup). | |
| 51 | + | |
| 52 | +The **func** parameter is a user supplied function which must match the | |
| 53 | +**src_callback_t** type signature while **cb_data** is a pointer to data which | |
| 54 | +be passed as the first parameter to the user supplied callback function. This | |
| 55 | +function is called by the converter whenever it needs input data as a result of | |
| 56 | +being calls to **src_callback_read**. | |
| 57 | + | |
| 58 | +If the converter was initialised to work with more than one channel, the | |
| 59 | +callback function must work with mutiple channels of interleaved data. The | |
| 60 | +callback function should return the number of frames it supplying to the | |
| 61 | +converter. For multi channel files, this return value should be the number of | |
| 62 | +floats divided by the number of channels. | |
| 63 | + | |
| 64 | +The converter must be one of the supplied converter types documented [here](api_misc.md#converters). | |
| 65 | + | |
| 66 | +The caller then passes the SRC_STATE pointer to the **src_callback_read** | |
| 67 | +function to pull data out of the converter. | |
| 68 | + | |
| 69 | +## Callback Read | |
| 70 | + | |
| 71 | +```c | |
| 72 | +long src_callback_read (SRC_STATE *state, double src_ratio, | |
| 73 | + long frames, float *data) ; | |
| 74 | +``` | |
| 75 | + | |
| 76 | +The **src_callback_read** function is passed the [**SRC_STATE**](api_misc.md#src_data) | |
| 77 | +pointer returned by **src_callback_new**, the coversion ratio | |
| 78 | +(output_sample_rate / input_sample_rate), the maximum number of output frames to | |
| 79 | +generate and a pointer to a buffer in which to place the output data. For multi | |
| 80 | +channel files, the data int the output buffer is stored in interleaved format. | |
| 81 | + | |
| 82 | +The **src_callback_read** function returns the number of frames generated or | |
| 83 | +zero if an error occurs or it runs out of input (ie the user supplied callback | |
| 84 | +function returns zero and there is no more data buffered internally). If an | |
| 85 | +error has occurred, the function [src_error](api_misc.md#error-reporting) | |
| 86 | +will return non-zero. | |
| 87 | + | |
| 88 | +See also : [**src_set_ratio**](api_full.md#set-ratio) | |