saf_utilities.h

Go to the documentation of this file.

/*
 * Copyright 2016-2018 Leo McCormack
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
 * OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
 */

 
#ifndef __SAF_UTILITIES_H_INCLUDED__
#define __SAF_UTILITIES_H_INCLUDED__
 
/* The usual suspects: */
#include <stdlib.h>
#include <stdio.h>
#include <math.h>
#include <string.h>
#include <float.h>
#include <assert.h>
#include <limits.h>
 
/* ========================================================================== */
/*                        Macros and Global Constants                         */
/* ========================================================================== */

#define NUM_EARS 2

#define SAF_MIN(a,b) (( (a) < (b) ) ? (a) : (b))

#define SAF_MAX(a,b) (( (a) > (b) ) ? (a) : (b))

#define SAF_CLAMP(a,min,max) (SAF_MAX(min, SAF_MIN(max, a)))

#define SAF_TRUE ( 1 )

#define SAF_FALSE ( 0 )

# define SAF_PI ( 3.14159265358979323846264338327950288f )

# define SAF_PId ( 3.14159265358979323846264338327950288 )

#define SAF_ISPOW2(x) (((x & ~(x-1))==x) ? x : 0)
 
#ifndef ISEVEN
# define ISEVEN(n)   ((n%2 == 0) ? 1 : 0)
#endif
 
#ifndef ISODD
# define ISODD(n)    ((n%2 != 0) ? 1 : 0)
#endif

#define SQRT4PI ( 3.544907701811032f )

#define FOURPI ( 12.566370614359172f )

#define ELEV2INCL(E) ( (SAF_PI/2.0f - E) )
 
#ifndef DEG2RAD
# define DEG2RAD(x) (x * SAF_PI / 180.0f)
#endif
 
#ifndef RAD2DEG
# define RAD2DEG(x) (x * 180.0f / SAF_PI)
#endif
 
#ifndef MKSTRING_
# define MKSTRING_(s) #s
#endif
 
#ifndef MKSTRING
# define MKSTRING(s) MKSTRING_(s)
#endif

#define SAF_UNUSED(x) (void)(x)
 
#ifndef NDEBUG /* If debug mode: */
# define saf_print_warning(message) {fprintf(stdout, \
                                    "SAF WARNING: %s [%s LINE %u] \n", message,\
                                    __FILE__, __LINE__);}

# define saf_print_error(message) {fprintf(stderr, \
                                  "SAF ERROR: %s [%s LINE %u] \n", message, \
                                  __FILE__, __LINE__); \
                                  exit(EXIT_FAILURE);}

# define saf_assert(x, message) if (!(x)) \
                    {printf("SAF ASSERTION FAILED: (%s), %s [%s LINE %u].\n", \
                     MKSTRING(x), message, __FILE__, __LINE__); \
                     exit(EXIT_FAILURE); }
 
#else /* ...otherwise macros do nothing, or just the standard behaviour: */
# define saf_print_warning(message)
# define saf_print_error(message) exit(EXIT_FAILURE)
# define saf_assert(x, message) assert(x)
#endif
 
/* ========================================================================== */
/*                 External Resources and SAF Utility Headers                 */
/* ========================================================================== */
 
/* For allocating contiguous multi-dimensional arrays.
 * The original source code can be found here (MIT license):
 *   https://github.com/leomccormack/md_malloc
 */
#include "../../resources/md_malloc/md_malloc.h"
 
/* The default FFT implementation, for when no optimised implementation is
 * available.
 * The original source code can be found here (BSD-3-Clause license):
 *   https://github.com/mborgerding/kissfft
 */
#include "../../resources/kissFFT/kiss_fftr.h"
#include "../../resources/kissFFT/kiss_fft.h"
 
/* For computing N-dimensional convex hulls and Delaunay meshes.
 * The original source code can be found here (MIT license):
 *   https://github.com/leomccormack/convhull_3d
 */
#include "../../resources/convhull_3d/convhull_3d.h"
 
/* For resampling audio and FIR filters.
 * The original source code can be found here (BSD-3-Clause license):
 *   https://github.com/xiph/speexdsp/
 */
#include "../../resources/speex_resampler/speex_resampler.h"
 
/* For data compression/decompression (Lempel–Ziv 1977 and Huffman coding based)
 * The original source code can be found here (BSD-3-Clause license):
 *   https://github.com/madler/zlib
 */
#include "../../resources/zlib/zlib.h"
 
/* For cross-platform complex number support */
#include "saf_utility_complex.h"
 
/* For misc. functions */
#include "saf_utility_misc.h"
 
/* For sorting vectors */
#include "saf_utility_sort.h"
 
/* Filter coefficients and filterbanks (IIR/FIR) */
#include "saf_utility_filters.h"
 
/* Many handy linear algebra functions based on CBLAS/LAPACK. Additionally, some
 * optimised proprietary Intel MKL and Apple Accelerate routines are employed
 * (for e.g. vector-vector products, addition etc.) if available; otherwise
 * reverting to default implementations. */
#include "saf_utility_veclib.h"
 
/* For computing spherical/cylindrical Bessel and Hankel functions and their
 * derivatives */
#include "saf_utility_bessel.h"
 
/* Wrappers for different FFT implementations */
#include "saf_utility_fft.h"
 
/* Matrix and multi-channel convolvers */
#include "saf_utility_matrixConv.h"
 
/* Pitch shifting algorithms */
#include "saf_utility_pitch.h"
 
/* A collection of signal decorrelators */
#include "saf_utility_decor.h"
 
/* For computational geometry functions */
#include "saf_utility_geometry.h"
 
/* For an implementation of the hybrid complex quadrature mirror filterbank */
#include "saf_utility_qmf.h"
 
/* Various presets for loudspeaker arrays and uniform distributions of points on
 * spheres. */
#include "saf_utility_loudspeaker_presets.h"
 
/* Various presets for microphone and hydrophone arrays. */
#include "saf_utility_sensorarray_presets.h"
 
/* A modified version of the alias-free STFT implementation by Juha Vilkamo.
 * The original source code can be found here (MIT license):
 *   https://github.com/jvilkamo/afSTFT
 * The design is also detailed in chapter 1 of [1]
 *
 * @see [1] Pulkki, V., Delikaris-Manias, S. and Politis, A. 2018. Parametric
 *          time--frequency domain spatial audio. John Wiley & Sons,
 *          Incorporated.
 */
#include "../../resources/afSTFT/afSTFTlib.h"
 
/* Distance variation function filter coefficient functions. */
#include "saf_utility_dvf.h"
 
 
#endif /* __SAF_UTILITIES_H_INCLUDED__ */
 /* doxygen addtogroup Utilities */