cannam@126:
cannam@126:
Callback API
cannam@126:
cannam@126: The callback API consists of the following functions :
cannam@126:
cannam@126:
cannam@126: typedef long (*src_callback_t) (void *cb_data, float **data) ;
cannam@126:
cannam@126: SRC_STATE* src_callback_new (src_callback_t func,
cannam@126: int converter_type, int channels,
cannam@126: int *error, void* cb_data) ;
cannam@126:
cannam@126: SRC_STATE* src_delete (SRC_STATE *state) ;
cannam@126:
cannam@126: long src_callback_read (SRC_STATE *state, double src_ratio,
cannam@126: long frames, float *data) ;
cannam@126:
cannam@126: int src_reset (SRC_STATE *state) ;
cannam@126: int src_set_ratio (SRC_STATE *state, double new_ratio) ;
cannam@126:
cannam@126:
cannam@126:
cannam@126:
cannam@126: Like the
cannam@126: simple API
cannam@126: and the
cannam@126: full API,
cannam@126: the callback based API is able to operate on interleaved multi channel data.
cannam@126:
cannam@126:
cannam@126:
cannam@126: An example of the use of the callback based API can be found in the
cannam@126: varispeed-play program in the examples/ directory of the
cannam@126: source code tarball.
cannam@126:
cannam@126:
cannam@126:
cannam@126:
cannam@126:
Initialisation
cannam@126:
cannam@126: SRC_STATE* src_callback_new (src_callback_t func,
cannam@126: int converter_type, int channels,
cannam@126: int *error, void* cb_data) ;
cannam@126:
cannam@126:
cannam@126: The src_callback_new function returns an anonymous pointer to a
cannam@126: sample rate converter callback object, src_state.
cannam@126: This is the same type of object as that returned by
cannam@126: src_new, but with different internal state.
cannam@126: Although these are the same object type, they cannot be used interchangeably.
cannam@126: If an error occurs the function returns a NULL pointer and fills in the
cannam@126: error value pointed to by the error pointer supplied by the caller.
cannam@126:
cannam@126:
cannam@126: The caller then passes the SRC_STATE object to the src_callback_read
cannam@126: function to pull data out of the converter.
cannam@126: When the caller is finished with the converter they should pass it to the
cannam@126: clean up function src_delete.
cannam@126:
cannam@126:
cannam@126: The func parameter is a user supplied function which must match the
cannam@126: src_callback_t type signature while cb_data is a pointer to
cannam@126: data which be passed as the first parameter to the user supplied callback
cannam@126: function.
cannam@126: This function is called by the converter whenever it needs input data as a
cannam@126: result of being calls to src_callback_read.
cannam@126:
cannam@126:
cannam@126: If the converter was initialised to work with more than one channel, the
cannam@126: callback function must work with mutiple channels of interleaved data.
cannam@126: The callback function should return the number of frames it supplying to
cannam@126: the converter.
cannam@126: For multi channel files, this return value should be the number of floats
cannam@126: divided by the number of channels.
cannam@126:
cannam@126:
cannam@126: The converter must be one of the supplied converter types documented
cannam@126: here.
cannam@126:
cannam@126:
cannam@126: The caller then passes the SRC_STATE pointer to the src_callback_read
cannam@126: function to pull data out of the converter.
cannam@126:
cannam@126:
cannam@126:
cannam@126:
cannam@126:
Callback Read
cannam@126:
cannam@126: long src_callback_read (SRC_STATE *state, double src_ratio,
cannam@126: long frames, float *data) ;
cannam@126:
cannam@126:
cannam@126: The src_callback_read function is passed the
cannam@126: SRC_STATE
cannam@126: pointer returned by src_callback_new, the coversion ratio
cannam@126: (output_sample_rate / input_sample_rate), the maximum number of output frames
cannam@126: to generate and a pointer to a buffer in which to place the output data.
cannam@126: For multi channel files, the data int the output buffer is stored in
cannam@126: interleaved format.
cannam@126:
cannam@126:
cannam@126: The src_callback_read function returns the number of frames generated
cannam@126: or zero if an error occurs or it runs out of input (ie the user supplied
cannam@126: callback function returns zero and there is no more data buffered internally).
cannam@126: If an error has occurred, the function
cannam@126: src_error will return non-zero.
cannam@126:
cannam@126:
cannam@126:
cannam@126: See also :
cannam@126: src_set_ratio
cannam@126:
cannam@126:
cannam@126:
cannam@126:
cannam@126:
cannam@126: