cog/ThirdParty/soxr/include/soxr.h

345 lines
14 KiB
C

/* SoX Resampler Library Copyright (c) 2007-18 robs@users.sourceforge.net
*
* This library is free software; you can redistribute it and/or modify it
* under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation; either version 2.1 of the License, or (at
* your option) any later version.
*
* This library is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
* General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with this library; if not, write to the Free Software Foundation,
* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
/* -------------------------------- Gubbins --------------------------------- */
#if !defined soxr_included
#define soxr_included
#if defined __cplusplus
#include <cstddef>
extern "C" {
#else
#include <stddef.h>
#endif
#if defined SOXR_DLL
#if defined soxr_EXPORTS
#define SOXR __declspec(dllexport)
#else
#define SOXR __declspec(dllimport)
#endif
#elif defined SOXR_VISIBILITY && defined __GNUC__ && (__GNUC__ > 4 || __GNUC__ == 4 && __GNUC_MINOR__ >= 1)
#define SOXR __attribute__ ((visibility("default")))
#else
#define SOXR
#endif
typedef struct soxr_io_spec soxr_io_spec_t;
typedef struct soxr_quality_spec soxr_quality_spec_t;
typedef struct soxr_runtime_spec soxr_runtime_spec_t;
/* ---------------------------- API conventions --------------------------------
Buffer lengths (and occupancies) are expressed as the number of contained
samples per channel.
Parameter names for buffer lengths have the suffix `len'.
A single-character `i' or 'o' is often used in names to give context as
input or output (e.g. ilen, olen). */
/* --------------------------- Version management --------------------------- */
/* E.g. #if SOXR_THIS_VERSION >= SOXR_VERSION(0,1,1) ... */
#define SOXR_VERSION(x,y,z) (((x)<<16)|((y)<<8)|(z))
#define SOXR_THIS_VERSION SOXR_VERSION(0,1,3)
#define SOXR_THIS_VERSION_STR "0.1.3"
/* --------------------------- Type declarations ---------------------------- */
typedef struct soxr * soxr_t; /* A resampler for 1 or more channels. */
typedef char const * soxr_error_t; /* 0:no-error; non-0:error. */
typedef void * soxr_buf_t; /* 1 buffer of channel-interleaved samples. */
typedef void const * soxr_cbuf_t; /* Ditto; read-only. */
typedef soxr_buf_t const * soxr_bufs_t;/* Or, a separate buffer for each ch. */
typedef soxr_cbuf_t const * soxr_cbufs_t; /* Ditto; read-only. */
typedef void const * soxr_in_t; /* Either a soxr_cbuf_t or soxr_cbufs_t,
depending on itype in soxr_io_spec_t. */
typedef void * soxr_out_t; /* Either a soxr_buf_t or soxr_bufs_t,
depending on otype in soxr_io_spec_t. */
/* --------------------------- API main functions --------------------------- */
SOXR char const * soxr_version(void); /* Query library version: "libsoxr-x.y.z" */
#define soxr_strerror(e) /* Soxr counterpart to strerror. */ \
((e)?(e):"no error")
/* Create a stream resampler: */
SOXR soxr_t soxr_create(
double input_rate, /* Input sample-rate. */
double output_rate, /* Output sample-rate. */
unsigned num_channels, /* Number of channels to be used. */
/* All following arguments are optional (may be set to NULL). */
soxr_error_t *, /* To report any error during creation. */
soxr_io_spec_t const *, /* To specify non-default I/O formats. */
soxr_quality_spec_t const *, /* To specify non-default resampling quality.*/
soxr_runtime_spec_t const *);/* To specify non-default runtime resources.
Default io_spec is per soxr_io_spec(SOXR_FLOAT32_I, SOXR_FLOAT32_I)
Default quality_spec is per soxr_quality_spec(SOXR_HQ, 0)
Default runtime_spec is per soxr_runtime_spec(1) */
/* If not using an app-supplied input function, after creating a stream
* resampler, repeatedly call: */
SOXR soxr_error_t soxr_process(
soxr_t resampler, /* As returned by soxr_create. */
/* Input (to be resampled): */
soxr_in_t in, /* Input buffer(s); may be NULL (see below). */
size_t ilen, /* Input buf. length (samples per channel). */
size_t * idone, /* To return actual # samples used (<= ilen). */
/* Output (resampled): */
soxr_out_t out, /* Output buffer(s).*/
size_t olen, /* Output buf. length (samples per channel). */
size_t * odone); /* To return actual # samples out (<= olen).
Note that no special meaning is associated with ilen or olen equal to
zero. End-of-input (i.e. no data is available nor shall be available)
may be indicated by seting `in' to NULL. */
/* If using an app-supplied input function, it must look and behave like this:*/
typedef size_t /* data_len */
(* soxr_input_fn_t)( /* Supply data to be resampled. */
void * input_fn_state, /* As given to soxr_set_input_fn (below). */
soxr_in_t * data, /* Returned data; see below. N.B. ptr to ptr(s)*/
size_t requested_len); /* Samples per channel, >= returned data_len.
data_len *data Indicates Meaning
------- ------- ------------ -------------------------
!=0 !=0 Success *data contains data to be
input to the resampler.
0 !=0 (or End-of-input No data is available nor
not set) shall be available.
0 0 Failure An error occurred whilst trying to
source data to be input to the resampler. */
/* and be registered with a previously created stream resampler using: */
SOXR soxr_error_t soxr_set_input_fn(/* Set (or reset) an input function.*/
soxr_t resampler, /* As returned by soxr_create. */
soxr_input_fn_t, /* Function to supply data to be resampled.*/
void * input_fn_state, /* If needed by the input function. */
size_t max_ilen); /* Maximum value for input fn. requested_len.*/
/* then repeatedly call: */
SOXR size_t /*odone*/ soxr_output(/* Resample and output a block of data.*/
soxr_t resampler, /* As returned by soxr_create. */
soxr_out_t data, /* App-supplied buffer(s) for resampled data.*/
size_t olen); /* Amount of data to output; >= odone. */
/* Common stream resampler operations: */
SOXR soxr_error_t soxr_error(soxr_t); /* Query error status. */
SOXR size_t * soxr_num_clips(soxr_t); /* Query int. clip counter (for R/W). */
SOXR double soxr_delay(soxr_t); /* Query current delay in output samples.*/
SOXR char const * soxr_engine(soxr_t); /* Query resampling engine name. */
SOXR soxr_error_t soxr_clear(soxr_t); /* Ready for fresh signal, same config. */
SOXR void soxr_delete(soxr_t); /* Free resources. */
/* `Short-cut', single call to resample a (probably short) signal held entirely
* in memory. See soxr_create and soxr_process above for parameter details.
* Note that unlike soxr_create however, the default quality spec. for
* soxr_oneshot is per soxr_quality_spec(SOXR_LQ, 0). */
SOXR soxr_error_t soxr_oneshot(
double input_rate,
double output_rate,
unsigned num_channels,
soxr_in_t in , size_t ilen, size_t * idone,
soxr_out_t out, size_t olen, size_t * odone,
soxr_io_spec_t const *,
soxr_quality_spec_t const *,
soxr_runtime_spec_t const *);
/* For variable-rate resampling. See example # 5 for how to create a
* variable-rate resampler and how to use this function. */
SOXR soxr_error_t soxr_set_io_ratio(soxr_t, double io_ratio, size_t slew_len);
/* -------------------------- API type definitions -------------------------- */
typedef enum { /* Datatypes supported for I/O to/from the resampler: */
/* Internal; do not use: */
SOXR_FLOAT32, SOXR_FLOAT64, SOXR_INT32, SOXR_INT16, SOXR_SPLIT = 4,
/* Use for interleaved channels: */
SOXR_FLOAT32_I = SOXR_FLOAT32, SOXR_FLOAT64_I, SOXR_INT32_I, SOXR_INT16_I,
/* Use for split channels: */
SOXR_FLOAT32_S = SOXR_SPLIT , SOXR_FLOAT64_S, SOXR_INT32_S, SOXR_INT16_S
} soxr_datatype_t;
#define soxr_datatype_size(x) /* Returns `sizeof' a soxr_datatype_t sample. */\
((unsigned char *)"\4\10\4\2")[(x)&3]
struct soxr_io_spec { /* Typically */
soxr_datatype_t itype; /* Input datatype. SOXR_FLOAT32_I */
soxr_datatype_t otype; /* Output datatype. SOXR_FLOAT32_I */
double scale; /* Linear gain to apply during resampling. 1 */
void * e; /* Reserved for internal use 0 */
unsigned long flags; /* Per the following #defines. 0 */
};
#define SOXR_TPDF 0 /* Applicable only if otype is INT16. */
#define SOXR_NO_DITHER 8u /* Disable the above. */
struct soxr_quality_spec { /* Typically */
double precision; /* Conversion precision (in bits). 20 */
double phase_response; /* 0=minimum, ... 50=linear, ... 100=maximum 50 */
double passband_end; /* 0dB pt. bandwidth to preserve; nyquist=1 0.913*/
double stopband_begin; /* Aliasing/imaging control; > passband_end 1 */
void * e; /* Reserved for internal use. 0 */
unsigned long flags; /* Per the following #defines. 0 */
};
#define SOXR_ROLLOFF_SMALL 0u /* <= 0.01 dB */
#define SOXR_ROLLOFF_MEDIUM 1u /* <= 0.35 dB */
#define SOXR_ROLLOFF_NONE 2u /* For Chebyshev bandwidth. */
#define SOXR_HI_PREC_CLOCK 8u /* Increase `irrational' ratio accuracy. */
#define SOXR_DOUBLE_PRECISION 16u /* Use D.P. calcs even if precision <= 20. */
#define SOXR_VR 32u /* Variable-rate resampling. */
struct soxr_runtime_spec { /* Typically */
unsigned log2_min_dft_size; /* For DFT efficiency. [8,15] 10 */
unsigned log2_large_dft_size; /* For DFT efficiency. [8,20] 17 */
unsigned coef_size_kbytes; /* For SOXR_COEF_INTERP_AUTO (below). 400 */
unsigned num_threads; /* 0: per OMP_NUM_THREADS; 1: 1 thread. 1 */
void * e; /* Reserved for internal use. 0 */
unsigned long flags; /* Per the following #defines. 0 */
};
/* For `irrational' ratios only: */
#define SOXR_COEF_INTERP_AUTO 0u /* Auto select coef. interpolation. */
#define SOXR_COEF_INTERP_LOW 2u /* Man. select: less CPU, more memory. */
#define SOXR_COEF_INTERP_HIGH 3u /* Man. select: more CPU, less memory. */
/* -------------------------- API type constructors ------------------------- */
/* These functions allow setting of the most commonly-used structure
* parameters, with other parameters being given default values. The default
* values may then be overridden, directly in the structure, if needed. */
SOXR soxr_quality_spec_t soxr_quality_spec(
unsigned long recipe, /* Per the #defines immediately below. */
unsigned long flags); /* As soxr_quality_spec_t.flags. */
/* The 5 standard qualities found in SoX: */
#define SOXR_QQ 0 /* 'Quick' cubic interpolation. */
#define SOXR_LQ 1 /* 'Low' 16-bit with larger rolloff. */
#define SOXR_MQ 2 /* 'Medium' 16-bit with medium rolloff. */
#define SOXR_HQ SOXR_20_BITQ /* 'High quality'. */
#define SOXR_VHQ SOXR_28_BITQ /* 'Very high quality'. */
#define SOXR_16_BITQ 3
#define SOXR_20_BITQ 4
#define SOXR_24_BITQ 5
#define SOXR_28_BITQ 6
#define SOXR_32_BITQ 7
/* Reserved for internal use (to be removed): */
#define SOXR_LSR0Q 8 /* 'Best sinc'. */
#define SOXR_LSR1Q 9 /* 'Medium sinc'. */
#define SOXR_LSR2Q 10 /* 'Fast sinc'. */
#define SOXR_LINEAR_PHASE 0x00
#define SOXR_INTERMEDIATE_PHASE 0x10
#define SOXR_MINIMUM_PHASE 0x30
#define SOXR_STEEP_FILTER 0x40
SOXR soxr_runtime_spec_t soxr_runtime_spec(
unsigned num_threads);
SOXR soxr_io_spec_t soxr_io_spec(
soxr_datatype_t itype,
soxr_datatype_t otype);
/* --------------------------- Advanced use only ---------------------------- */
/* For new designs, the following functions/usage will probably not be needed.
* They might be useful when adding soxr into an existing design where values
* for the resampling-rate and/or number-of-channels parameters to soxr_create
* are not available when that function will be called. In such cases, the
* relevant soxr_create parameter(s) can be given as 0, then one or both of the
* following (as appropriate) later invoked (but prior to calling soxr_process
* or soxr_output):
*
* soxr_set_error(soxr, soxr_set_io_ratio(soxr, io_ratio, 0));
* soxr_set_error(soxr, soxr_set_num_channels(soxr, num_channels));
*/
SOXR soxr_error_t soxr_set_error(soxr_t, soxr_error_t);
SOXR soxr_error_t soxr_set_num_channels(soxr_t, unsigned);
#undef SOXR
#if defined __cplusplus
}
#endif
#endif