SAF
Loading...
Searching...
No Matches
saf_utilities.h
Go to the documentation of this file.
1/*
2 * Copyright 2016-2018 Leo McCormack
3 *
4 * Permission to use, copy, modify, and/or distribute this software for any
5 * purpose with or without fee is hereby granted, provided that the above
6 * copyright notice and this permission notice appear in all copies.
7 *
8 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
9 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
10 * AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
11 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
12 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
13 * OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
14 * PERFORMANCE OF THIS SOFTWARE.
15 */
16
35#ifndef __SAF_UTILITIES_H_INCLUDED__
36#define __SAF_UTILITIES_H_INCLUDED__
37
38/* The usual suspects: */
39#include <stdlib.h>
40#include <stdio.h>
41#include <math.h>
42#include <string.h>
43#include <float.h>
44#include <assert.h>
45#include <limits.h>
46
47/* ========================================================================== */
48/* Macros and Global Constants */
49/* ========================================================================== */
50
52#define NUM_EARS 2
53
55#define SAF_MIN(a,b) (( (a) < (b) ) ? (a) : (b))
56
58#define SAF_MAX(a,b) (( (a) > (b) ) ? (a) : (b))
59
61#define SAF_CLAMP(a,min,max) (SAF_MAX(min, SAF_MIN(max, a)))
62
64#define SAF_TRUE ( 1 )
65
67#define SAF_FALSE ( 0 )
68
70# define SAF_PI ( 3.14159265358979323846264338327950288f )
71
73# define SAF_PId ( 3.14159265358979323846264338327950288 )
74
76#define SAF_ISPOW2(x) (((x & ~(x-1))==x) ? x : 0)
77
78#ifndef ISEVEN
80# define ISEVEN(n) ((n%2 == 0) ? 1 : 0)
81#endif
82
83#ifndef ISODD
85# define ISODD(n) ((n%2 != 0) ? 1 : 0)
86#endif
87
89#define SQRT4PI ( 3.544907701811032f )
90
92#define FOURPI ( 12.566370614359172f )
93
95#define ELEV2INCL(E) ( (SAF_PI/2.0f - E) )
96
97#ifndef DEG2RAD
99# define DEG2RAD(x) (x * SAF_PI / 180.0f)
100#endif
101
102#ifndef RAD2DEG
104# define RAD2DEG(x) (x * 180.0f / SAF_PI)
105#endif
106
107#ifndef MKSTRING_
109# define MKSTRING_(s) #s
110#endif
111
112#ifndef MKSTRING
114# define MKSTRING(s) MKSTRING_(s)
115#endif
116
118#define SAF_UNUSED(x) (void)(x)
119
120#ifndef NDEBUG /* If debug mode: */
122# define saf_print_warning(message) {fprintf(stdout, \
123 "SAF WARNING: %s [%s LINE %u] \n", message,\
124 __FILE__, __LINE__);}
125
127# define saf_print_error(message) {fprintf(stderr, \
128 "SAF ERROR: %s [%s LINE %u] \n", message, \
129 __FILE__, __LINE__); \
130 exit(EXIT_FAILURE);}
131
133# define saf_assert(x, message) if (!(x)) \
134 {printf("SAF ASSERTION FAILED: (%s), %s [%s LINE %u].\n", \
135 MKSTRING(x), message, __FILE__, __LINE__); \
136 exit(EXIT_FAILURE); }
137
138#else /* ...otherwise macros do nothing, or just the standard behaviour: */
139# define saf_print_warning(message)
140# define saf_print_error(message) exit(EXIT_FAILURE)
141# define saf_assert(x, message) assert(x)
142#endif
143
144
145/* ========================================================================== */
146/* External Resources and SAF Utility Headers */
147/* ========================================================================== */
148
149/* For allocating contiguous multi-dimensional arrays.
150 * The original source code can be found here (MIT license):
151 * https://github.com/leomccormack/md_malloc
152 */
154
155/* The default FFT implementation, for when no optimised implementation is
156 * available.
157 * The original source code can be found here (BSD-3-Clause license):
158 * https://github.com/mborgerding/kissfft
159 */
162
163/* For computing N-dimensional convex hulls and Delaunay meshes.
164 * The original source code can be found here (MIT license):
165 * https://github.com/leomccormack/convhull_3d
166 */
168
169/* For resampling audio and FIR filters.
170 * The original source code can be found here (BSD-3-Clause license):
171 * https://github.com/xiph/speexdsp/
172 */
174
175/* For data compression/decompression (Lempel–Ziv 1977 and Huffman coding based)
176 * The original source code can be found here (BSD-3-Clause license):
177 * https://github.com/madler/zlib
178 */
179#include "../../resources/zlib/zlib.h"
180
181/* For cross-platform complex number support */
182#include "saf_utility_complex.h"
183
184/* For sorting vectors */
185#include "saf_utility_sort.h"
186
187/* Filter coefficients and filterbanks (IIR/FIR) */
188#include "saf_utility_filters.h"
189
190/* Many handy linear algebra functions based on CBLAS/LAPACK. Additionally, some
191 * optimised proprietary Intel MKL and Apple Accelerate routines are employed
192 * (for e.g. vector-vector products, addition etc.) if available; otherwise
193 * reverting to default implementations. */
194#include "saf_utility_veclib.h"
195
196/* For computing spherical/cylindrical Bessel and Hankel functions and their
197 * derivatives */
198#include "saf_utility_bessel.h"
199
200/* Wrappers for different FFT implementations */
201#include "saf_utility_fft.h"
202
203/* Matrix and multi-channel convolvers */
205
206/* Pitch shifting algorithms */
207#include "saf_utility_pitch.h"
208
209/* A collection of signal decorrelators */
210#include "saf_utility_decor.h"
211
212/* For misc. functions */
213#include "saf_utility_misc.h"
214
215/* For computational geometry functions */
216#include "saf_utility_geometry.h"
217
218/* For an implementation of the hybrid complex quadrature mirror filterbank */
219#include "saf_utility_qmf.h"
220
221/* Various presets for loudspeaker arrays and uniform distributions of points on
222 * spheres. */
224
225/* Various presets for microphone and hydrophone arrays. */
227
228/* A modified version of the alias-free STFT implementation by Juha Vilkamo.
229 * The original source code can be found here (MIT license):
230 * https://github.com/jvilkamo/afSTFT
231 * The design is also detailed in chapter 1 of [1]
232 *
233 * @see [1] Pulkki, V., Delikaris-Manias, S. and Politis, A. 2018. Parametric
234 * time--frequency domain spatial audio. John Wiley & Sons,
235 * Incorporated.
236 */
238
239/* Distance variation function filter coefficient functions. */
240#include "saf_utility_dvf.h"
241
242
243#endif /* __SAF_UTILITIES_H_INCLUDED__ */
244
245 /* doxygen addtogroup Utilities */
A modified version of afSTFTlib.
An implementation of the 3-D quickhull algorithm [1].
The default complex <-> complex FFT.
The default real <-> half-complex FFT.
Contiguous memory allocation functions for multi-dimensional arrays.
A collection of routines for computing spherical and cylindrical Bessel and Hankel functions,...
Contains wrappers for handling complex numbers across both C99-compliant compilers and Microsoft Visu...
A collection of signal decorrelators.
Distance variation function filter coefficient data [1].
Wrappers for optimised discrete/fast Fourier transform (FFT) routines.
A collection of IIR/FIR filter and filterbank designs.
A collection of computational geometry related functions.
A collection of loudspeaker array directions and (nearly) uniform spherical grids.
Matrix and multi-channel convolvers.
A collection of miscellaneous functions.
A collection of pitch shifting algorithms.
An implementation of the complex Quadrature Mirror Filterbank (QMF) described in [1].
A collection of microphone array sensor directions.
A collection of useful sorting functions.
Wrappers for optimised linear algebra routines, utilising CBLAS and LAPACK, and/or SIMD intrinsics.
Main header file for the Speex resampler.