Update site documentation

* Use GitHub's Jekyll static site generator. * Move all documentation to docs/ directory. * Convert HTML to Markdown.

evpobr committed 6 years ago

Commit 260c3f61 parent 01284e738 files · +1057 −2227Browse files

Showing the changes to docs/api_misc.md (1 of 38 files). Show all

Unified · Split

@@ -0,0 +1,143 @@
	1	---
	2	layout: default
	3	---
	4
	5	# Miscellaneous API Documentation
	6
	7	## Error Reporting
	8
	9	Most of the API functions either return an integer error (ie src_simple and
	10	src_process) or return an integer error value via an int pointer parameter
	11	(src_new). These integer error values can be converted into a human readable
	12	text strings by calling the function:
	13
	14	```c
	15	const char* src_strerror (int error) ;
	16	```
	17
	18	which will return an error string for valid error numbers, the string
	19	\"No Error\" for an error value of zero or a NULL pointer if no error message
	20	has been defined for that error value.
	21
	22	## Converters
	23
	24	Secret Rabbit Code has a number of different converters which can be selected
	25	using the converter_type parameter when calling src_simple or
	26	src_new. Currently, the five converters available are:
	27
	28	```c
	29	enum
	30	{
	31	SRC_SINC_BEST_QUALITY = 0,
	32	SRC_SINC_MEDIUM_QUALITY = 1,
	33	SRC_SINC_FASTEST = 2,
	34	SRC_ZERO_ORDER_HOLD = 3,
	35	SRC_LINEAR = 4
	36	} ;
	37	```
	38
	39	As new converters are added, they will given a number corresponding to the next
	40	integer.
	41
	42	The details of these converters are as follows:
	43
	44	- SRC_SINC_BEST_QUALITY - This is a bandlimited interpolator derived from
	45	the mathematical sinc function and this is the highest quality sinc based
	46	converter, providing a worst case Signal-to-Noise Ratio (SNR) of 97 decibels
	47	(dB) at a bandwidth of 97%. All three SRC_SINC_* converters are based on the
	48	techniques of [Julius O. Smith](http://ccrma.stanford.edu/~jos/resample/)
	49	although this code was developed independantly.
	50	- SRC_SINC_MEDIUM_QUALITY - This is another bandlimited interpolator much
	51	like the previous one. It has an SNR of 97dB and a bandwidth of 90%. The speed
	52	of the conversion is much faster than the previous one.
	53	- SRC_SINC_FASTEST - This is the fastest bandlimited interpolator and has an
	54	SNR of 97dB and a bandwidth of 80%.
	55	- SRC_ZERO_ORDER_HOLD - A Zero Order Hold converter (interpolated value is
	56	equal to the last value). The quality is poor but the conversion speed is
	57	blindlingly fast.
	58	- SRC_LINEAR - A linear converter. Again the quality is poor, but the
	59	conversion speed is blindingly fast.
	60
	61	There are two functions that give either a (text string) name or description for
	62	each converter:
	63
	64	```c
	65	const char *src_get_name (int converter_type) ;
	66	const char *src_get_description (int converter_type) ;
	67	```
	68
	69	The name will typically be a short string for use in a dialog box, while the
	70	description string is longer.
	71
	72	Both of these functions return a NULL pointer if there is no converter for the
	73	given converter_type value. Since the converters have consecutive
	74	converter_type values, the caller is easily able to figure out the number of
	75	converters at run time. This enables a binary dynamically linked against an old
	76	version of the library to know about converters from later versions of the
	77	library as they become available.
	78
	79	## SRC_DATA
	80
	81	Both the simple and the full featured versions of the API use the SRC_DATA
	82	struct to pass audio and control data into the sample rate converter. This
	83	struct is defined as:
	84
	85	```c
	86	typedef struct
	87	{ const float *data_in;
	88	float *data_out ;
	89
	90	long input_frames, output_frames ;
	91	long input_frames_used, output_frames_gen ;
	92
	93	int end_of_input ;
	94
	95	double src_ratio ;
	96	} SRC_DATA ;
	97	```
	98
	99	The data_in pointer is used to pass audio data into the converter while the
	100	data_out pointer supplies the converter with an array to hold the
	101	converter's output. For a converter which has been configured for mulitchannel
	102	operation, these pointers need to point to a single array of interleaved data.
	103
	104	The input_frames and output_frames fields supply the converter with the
	105	lengths of the arrays (in frames) pointed to by the data_in and data_out
	106	pointers respectively. For monophinc data, these values would indicate the
	107	length of the arrays while for multi channel data these values would be equal to
	108	the the length of the array divided by the number of channels.
	109
	110	The end_of_input field is only used when the sample rate converter is used
	111	by calling the src_process function. In this case it should be set to zero
	112	if more buffers are to be passed to the converter and 1 if the current buffer is
	113	the last.
	114
	115	Finally, the src_ratio field specifies the conversion ratio defined as the
	116	output sample rate divided by the input sample rate. For a connected set of
	117	buffers, this value can be varies on each call to src_process resulting in a
	118	time varying sample rate conversion process. For time varying sample rate
	119	conversions, the ratio will be linearly interpolated between the src_ratio
	120	value of the previous call to src_process and the value for the current
	121	call.
	122
	123	The input_frames_used and output_frames_gen fields are set by the
	124	converter to inform the caller of the number of frames consumed from the
	125	data_in array and the number of frames generated in the data_out array
	126	respectively. These values are for the current call to src_process only.
	127
	128	## Auxillary Functions
	129
	130	There are four auxillary functions for converting arrays of float data to and
	131	from short or int data. These functions are defined as:
	132
	133	```c
	134	void src_short_to_float_array (const short in, float out, int len) ;
	135	void src_float_to_short_array (const float in, short out, int len) ;
	136	void src_int_to_float_array (const int in, float out, int len) ;
	137	void src_float_to_int_array (const float in, int out, int len) ;
	138	```
	139
	140	The float data is assumed to be in the range [-1.0, 1.0] and it is automatically
	141	scaled on the conversion to and from float. On the float to short/int conversion
	142	path, any data values which would overflow the range of short/int data are
	143	clipped.

Update site documentation

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code