diff --git a/INSTALL b/INSTALL index 2721e38..3f30772 100644 --- a/INSTALL +++ b/INSTALL @@ -6,7 +6,7 @@ INSTALLATION GUIDE CONTENTS * Build customisation * Cross-compilation * Integration with other build systems -* SIMD +* Run-time configuration @@ -21,7 +21,7 @@ STANDARD BUILD * A 'make' utility (most compiler installations already have one of these). - * CMake: http://www.cmake.org/cmake/resources/software.html + * CMake: https://cmake.org/download/ 2. Build: @@ -31,7 +31,7 @@ STANDARD BUILD go (on MS-Windows with nmake) or - ./go (on unix-like systems) + ./go (on Unix-like systems) This should build the library and run a few sanity tests. @@ -39,14 +39,14 @@ STANDARD BUILD 3. Installation: Note that this step may need to be performed by a system - adminstrator. Enter: + administrator. Enter: nmake install (on MS-Windows) or - cd Release; make install (on unix-like) + cd Release; make install (on Unix-like) -4. Configuration: +4. Preparation for use: To use the library you may need to set up appropriate paths to the library and its header file in your development environment. @@ -82,6 +82,31 @@ Options, if given, should be preceded with '-D', e.g. +Resampling engines + +As available on a given system, the library may include up to four resampling +‘engines’, as follows: + + cr32: for constant-rate resampling with precision up to 20 bits, + cr32s: SIMD variant of cr32, + cr64: for constant-rate resampling with precision greater than 20 bits, + vr32: for variable-rate resampling. + +Engine inclusion is controlled (as above) by the following cmake option +variables: + + cr32: WITH_SINGLE_PRECISION + cr32s: WITH_SINGLE_PRECISION, WITH_SIMD + cr32: WITH_DOUBLE_PRECISION + +By default, these variables are all set to ON. + +When both cr32 and cr32s engines are included, run-time selection is automatic +(based on CPU capability) for x86 CPUs, and can be automatic for ARM CPUs if +the 3rd-party library `libavutil' is available at libsoxr build-time. + + + CROSS-COMPILATION E.g. targeting a Linux ARM system: @@ -130,23 +155,31 @@ INTEGRATION WITH OTHER BUILD SYSTEMS Autotools-based systems might find it useful to create a file called `configure' in the directory containing this file, consisting of the line: - cmake -DBUILD_SHARED_LIBS=OFF . + cmake -DBUILD_SHARED_LIBS=OFF . (or with other build options as required). -For MS visual studio, see msvc/README +For MS visual studio, see msvc/README. -SIMD +RUN-TIME CONFIGURATION -A single build of the library can support both SIMD and non-SIMD variants of a -particular CPU via run-time selection of which instruction-set to use. The -SOXR_USE_SIMD boolean environment provides manual selection; otherwise, -selection is automatic for x86 CPUs, and can be automatic for ARM CPUs if the -3rd-party library `libavutil' is available when libsoxr is built. +The libsoxr API structure ‘soxr_runtime_spec_t’ allows application developers +to optimise some aspects of libsoxr’s operation for a particular application. +However, since optimal performance might depend on an individual end-user’s +run-time system and the end-user’s preferences, environment variables are +available to set (override) the run-time parameters: -Example #3 can be used to determine the result of the selection on a particular -system. E.g. (on unix-like): + Env. variable Equivalent soxr_runtime_spec_t item + ------------------ ----------------------------------- + SOXR_COEFS_SIZE coef_size_kbytes + SOXR_COEF_INTERP SOXR_COEF_INTERP_xxx + SOXR_LARGE_DFT_SIZE log2_large_dft_size + SOXR_MIN_DFT_SIZE log2_min_dft_size + SOXR_NUM_THREADS num_threads - $ ./3-options-input-fn < /dev/null - ./3-options-input-fn no error; 0 clips; I/O: no error (single-precision-SIMD) +Additionally, the SOXR_USE_SIMD environment variable may be used to override +automatic selection (or to provide manual selection where automatic selection +is not available) between the cr32 and cr32s resampling engines. (Which engine +is selected for a specific configuration of libsoxr can be checked using +example #3, which reports it.) diff --git a/lsr-tests/CMakeLists.txt b/lsr-tests/CMakeLists.txt index 6c77bfd..1ac041e 100644 --- a/lsr-tests/CMakeLists.txt +++ b/lsr-tests/CMakeLists.txt @@ -34,7 +34,10 @@ enable_testing () set (tests callback_hang_test callback_test downsample_test float_short_test misc_test multi_channel_test - reset_test simple_test snr_bw_test termination_test varispeed_test) + reset_test simple_test termination_test varispeed_test) +if (WITH_DOUBLE_PRECISION) + set (tests ${tests} snr_bw_test) +endif () foreach (test ${tests}) add_executable (${test} ${test}) diff --git a/src/rate32.c b/src/rate32.c index d6dd3b9..fe85bae 100644 --- a/src/rate32.c +++ b/src/rate32.c @@ -5,5 +5,5 @@ #define RATE_SIMD 0 #define RDFT_CB _soxr_rdft32_cb #define RATE_CB _soxr_rate32_cb -#define RATE_ID "single-precision" +#define RATE_ID "cr32" #include "rate.h" diff --git a/src/rate32s.c b/src/rate32s.c index 26a371a..3acfcb4 100644 --- a/src/rate32s.c +++ b/src/rate32s.c @@ -5,5 +5,5 @@ #define RATE_SIMD 1 #define RDFT_CB _soxr_rdft32s_cb #define RATE_CB _soxr_rate32s_cb -#define RATE_ID "single-precision-SIMD" +#define RATE_ID "cr32s" #include "rate.h" diff --git a/src/rate64.c b/src/rate64.c index 6289911..6f25143 100644 --- a/src/rate64.c +++ b/src/rate64.c @@ -5,5 +5,5 @@ #define RATE_SIMD 0 #define RDFT_CB _soxr_rdft64_cb #define RATE_CB _soxr_rate64_cb -#define RATE_ID "double-precision" +#define RATE_ID "cr64" #include "rate.h" diff --git a/src/vr32.c b/src/vr32.c index 188bd32..000d340 100644 --- a/src/vr32.c +++ b/src/vr32.c @@ -639,7 +639,7 @@ static char const * vr_create(void * channel, void * shared,double max_io_ratio, static char const * vr_id(void) { - return "single-precision variable-rate"; + return "vr32"; } typedef void (* fn_t)(void);