* 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) | ||