[audio-libsamplerate.git] / libsamplerate / src / samplerate.h

/*
** Copyright (c) 2002-2016, Erik de Castro Lopo <erikd@mega-nerd.com>
** All rights reserved.
**
** This code is released under 2-clause BSD license. Please see the
** file at : https://github.com/erikd/libsamplerate/blob/master/COPYING
*/

/*
** API documentation is available here:
**     http://www.mega-nerd.com/SRC/api.html
*/

#ifndef SAMPLERATE_H
#define SAMPLERATE_H

#ifdef __cplusplus
extern "C" {
#endif	/* __cplusplus */


/* Opaque data type SRC_STATE. */
typedef struct SRC_STATE_tag SRC_STATE ;

/* SRC_DATA is used to pass data to src_simple() and src_process(). */
typedef struct
{	const float	*data_in ;
	float	 *data_out ;

	long	input_frames, output_frames ;
	long	input_frames_used, output_frames_gen ;

	int		end_of_input ;

	double	src_ratio ;
} SRC_DATA ;

/*
** User supplied callback function type for use with src_callback_new()
** and src_callback_read(). First parameter is the same pointer that was
** passed into src_callback_new(). Second parameter is pointer to a
** pointer. The user supplied callback function must modify *data to
** point to the start of the user supplied float array. The user supplied
** function must return the number of frames that **data points to.
*/

typedef long (*src_callback_t) (void *cb_data, float **data) ;

/*
**	Standard initialisation function : return an anonymous pointer to the
**	internal state of the converter. Choose a converter from the enums below.
**	Error returned in *error.
*/

SRC_STATE* src_new (int converter_type, int channels, int *error) ;

/*
**	Initilisation for callback based API : return an anonymous pointer to the
**	internal state of the converter. Choose a converter from the enums below.
**	The cb_data pointer can point to any data or be set to NULL. Whatever the
**	value, when processing, user supplied function "func" gets called with
**	cb_data as first parameter.
*/

SRC_STATE* src_callback_new (src_callback_t func, int converter_type, int channels,
				int *error, void* cb_data) ;

/*
**	Cleanup all internal allocations.
**	Always returns NULL.
*/

SRC_STATE* src_delete (SRC_STATE *state) ;

/*
**	Standard processing function.
**	Returns non zero on error.
*/

int src_process (SRC_STATE *state, SRC_DATA *data) ;

/*
**	Callback based processing function. Read up to frames worth of data from
**	the converter int *data and return frames read or -1 on error.
*/
long src_callback_read (SRC_STATE *state, double src_ratio, long frames, float *data) ;

/*
**	Simple interface for performing a single conversion from input buffer to
**	output buffer at a fixed conversion ratio.
**	Simple interface does not require initialisation as it can only operate on
**	a single buffer worth of audio.
*/

int src_simple (SRC_DATA *data, int converter_type, int channels) ;

/*
** This library contains a number of different sample rate converters,
** numbered 0 through N.
**
** Return a string giving either a name or a more full description of each
** sample rate converter or NULL if no sample rate converter exists for
** the given value. The converters are sequentially numbered from 0 to N.
*/

const char *src_get_name (int converter_type) ;
const char *src_get_description (int converter_type) ;
const char *src_get_version (void) ;

/*
**	Set a new SRC ratio. This allows step responses
**	in the conversion ratio.
**	Returns non zero on error.
*/

int src_set_ratio (SRC_STATE *state, double new_ratio) ;

/*
**	Get the current channel count.
**	Returns negative on error, positive channel count otherwise
*/

int src_get_channels (SRC_STATE *state) ;

/*
**	Reset the internal SRC state.
**	Does not modify the quality settings.
**	Does not free any memory allocations.
**	Returns non zero on error.
*/

int src_reset (SRC_STATE *state) ;

/*
** Return TRUE if ratio is a valid conversion ratio, FALSE
** otherwise.
*/

int src_is_valid_ratio (double ratio) ;

/*
**	Return an error number.
*/

int src_error (SRC_STATE *state) ;

/*
**	Convert the error number into a string.
*/
const char* src_strerror (int error) ;

/*
** The following enums can be used to set the interpolator type
** using the function src_set_converter().
*/

enum
{
	SRC_SINC_BEST_QUALITY		= 0,
	SRC_SINC_MEDIUM_QUALITY		= 1,
	SRC_SINC_FASTEST			= 2,
	SRC_ZERO_ORDER_HOLD			= 3,
	SRC_LINEAR					= 4,
} ;

/*
** Extra helper functions for converting from short to float and
** back again.
*/

void src_short_to_float_array (const short *in, float *out, int len) ;
void src_float_to_short_array (const float *in, short *out, int len) ;

void src_int_to_float_array (const int *in, float *out, int len) ;
void src_float_to_int_array (const float *in, int *out, int len) ;


#ifdef __cplusplus
}		/* extern "C" */
#endif	/* __cplusplus */

#endif	/* SAMPLERATE_H */
Commit	Line	Data
8529da43 MG	1	/*
	2	** Copyright (c) 2002-2016, Erik de Castro Lopo <erikd@mega-nerd.com>
	3	** All rights reserved.
	4	**
	5	** This code is released under 2-clause BSD license. Please see the
	6	** file at : https://github.com/erikd/libsamplerate/blob/master/COPYING
	7	*/
	8
	9	/*
	10	** API documentation is available here:
	11	** http://www.mega-nerd.com/SRC/api.html
	12	*/
	13
	14	#ifndef SAMPLERATE_H
	15	#define SAMPLERATE_H
	16
	17	#ifdef __cplusplus
	18	extern "C" {
	19	#endif /* __cplusplus */
	20
	21
	22	/* Opaque data type SRC_STATE. */
	23	typedef struct SRC_STATE_tag SRC_STATE ;
	24
	25	/* SRC_DATA is used to pass data to src_simple() and src_process(). */
	26	typedef struct
	27	{ const float *data_in ;
	28	float *data_out ;
	29
	30	long input_frames, output_frames ;
	31	long input_frames_used, output_frames_gen ;
	32
	33	int end_of_input ;
	34
	35	double src_ratio ;
	36	} SRC_DATA ;
	37
	38	/*
	39	** User supplied callback function type for use with src_callback_new()
	40	** and src_callback_read(). First parameter is the same pointer that was
	41	** passed into src_callback_new(). Second parameter is pointer to a
	42	** pointer. The user supplied callback function must modify *data to
	43	** point to the start of the user supplied float array. The user supplied
	44	function must return the number of frames that data points to.
	45	*/
	46
	47	typedef long (src_callback_t) (void cb_data, float **data) ;
	48
	49	/*
	50	** Standard initialisation function : return an anonymous pointer to the
	51	** internal state of the converter. Choose a converter from the enums below.
	52	** Error returned in *error.
	53	*/
	54
	55	SRC_STATE* src_new (int converter_type, int channels, int *error) ;
	56
	57	/*
	58	** Initilisation for callback based API : return an anonymous pointer to the
	59	** internal state of the converter. Choose a converter from the enums below.
	60	** The cb_data pointer can point to any data or be set to NULL. Whatever the
	61	** value, when processing, user supplied function "func" gets called with
	62	** cb_data as first parameter.
	63	*/
	64
65	SRC_STATE* src_callback_new (src_callback_t func, int converter_type, int channels,
66	int error, void cb_data) ;
67
68	/*
69	** Cleanup all internal allocations.
70	** Always returns NULL.
71	*/
72
73	SRC_STATE* src_delete (SRC_STATE *state) ;
74
75	/*
76	** Standard processing function.
77	** Returns non zero on error.
78	*/
79
80	int src_process (SRC_STATE state, SRC_DATA data) ;
81
82	/*
83	** Callback based processing function. Read up to frames worth of data from
84	** the converter int *data and return frames read or -1 on error.
85	*/
86	long src_callback_read (SRC_STATE state, double src_ratio, long frames, float data) ;
87
88	/*
89	** Simple interface for performing a single conversion from input buffer to
90	** output buffer at a fixed conversion ratio.
91	** Simple interface does not require initialisation as it can only operate on
92	** a single buffer worth of audio.
93	*/
94
95	int src_simple (SRC_DATA *data, int converter_type, int channels) ;
96
97	/*
98	** This library contains a number of different sample rate converters,
99	** numbered 0 through N.
100	**
101	** Return a string giving either a name or a more full description of each
102	** sample rate converter or NULL if no sample rate converter exists for
103	** the given value. The converters are sequentially numbered from 0 to N.
104	*/
105
106	const char *src_get_name (int converter_type) ;
107	const char *src_get_description (int converter_type) ;
108	const char *src_get_version (void) ;
109
110	/*
111	** Set a new SRC ratio. This allows step responses
112	** in the conversion ratio.
113	** Returns non zero on error.
114	*/
115
116	int src_set_ratio (SRC_STATE *state, double new_ratio) ;
117
118	/*
119	** Get the current channel count.
120	** Returns negative on error, positive channel count otherwise
121	*/
122
123	int src_get_channels (SRC_STATE *state) ;
124
125	/*
126	** Reset the internal SRC state.
127	** Does not modify the quality settings.
128	** Does not free any memory allocations.
129	** Returns non zero on error.
130	*/
131
132	int src_reset (SRC_STATE *state) ;
133
134	/*
135	** Return TRUE if ratio is a valid conversion ratio, FALSE
136	** otherwise.
137	*/
138
139	int src_is_valid_ratio (double ratio) ;
140
141	/*
142	** Return an error number.
143	*/
144
145	int src_error (SRC_STATE *state) ;
146
147	/*
148	** Convert the error number into a string.
149	*/
150	const char* src_strerror (int error) ;
151
152	/*
153	** The following enums can be used to set the interpolator type
154	** using the function src_set_converter().
155	*/
156
157	enum
158	{
159	SRC_SINC_BEST_QUALITY = 0,
160	SRC_SINC_MEDIUM_QUALITY = 1,
161	SRC_SINC_FASTEST = 2,
162	SRC_ZERO_ORDER_HOLD = 3,
163	SRC_LINEAR = 4,
164	} ;
165
166	/*
167	** Extra helper functions for converting from short to float and
168	** back again.
169	*/
170
171	void src_short_to_float_array (const short in, float out, int len) ;
172	void src_float_to_short_array (const float in, short out, int len) ;
173
174	void src_int_to_float_array (const int in, float out, int len) ;
175	void src_float_to_int_array (const float in, int out, int len) ;
176
177
178	#ifdef __cplusplus
179	} /* extern "C" */
180	#endif /* __cplusplus */
181
182	#endif /* SAMPLERATE_H */
183