ambix.h
Go to the documentation of this file.
/* ambix/ambix.h - AMBIsonics eXchange Library Interface -*- c -*-
Copyright © 2012 IOhannes m zmölnig <zmoelnig@iem.at>.
Institute of Electronic Music and Acoustics (IEM),
University of Music and Dramatic Arts, Graz
This file is part of libambix
libambix 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.
libambix 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 program; if not, see <http://www.gnu.org/licenses/>.
*/
#ifndef AMBIX_AMBIX_H
#define AMBIX_AMBIX_H
#include "exportdefs.h"
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
typedef float float32_t;
typedef double float64_t;
#ifdef _MSC_VER
typedef signed short int16_t;
typedef unsigned short uint16_t;
typedef signed int int32_t;
typedef unsigned int uint32_t;
typedef signed long int64_t;
typedef unsigned long uint64_t;
#else
# include <stdint.h>
#endif
/* ugly hack to provide to allow the use type 'SNDFILE*'
* regardless of whether <sndfile.h> is included or not
*/
#ifndef HAVE_PUSH_MACRO
# define HAVE_PUSH_MACRO 1
#endif
#if HAVE_PUSH_MACRO
# pragma push_macro("SNDFILE")
# ifdef SNDFILE
# undef SNDFILE
# endif
# define SNDFILE void
#elif !defined(SNDFILE_1)
# define SNDFILE void
#endif
typedef union {
float32_t f;
int32_t i;
uint32_t u;
} number32_t;
typedef struct ambix_t_struct ambix_t;
typedef enum
{
AMBIX_ERR_UNKNOWN=-1,
AMBIX_ERR_SUCCESS= 0,
AMBIX_ERR_INVALID_HANDLE,
AMBIX_ERR_INVALID_FILE,
AMBIX_ERR_INVALID_DIMENSION,
AMBIX_ERR_INVALID_FORMAT,
AMBIX_ERR_INVALID_MATRIX,
} ambix_err_t;
typedef enum {
AMBIX_READ = (1 << 4),
AMBIX_WRITE = (1 << 5),
AMBIX_RDRW = (AMBIX_READ|AMBIX_WRITE)
} ambix_filemode_t;
typedef enum {
AMBIX_NONE = 0,
AMBIX_BASIC = 1,
AMBIX_EXTENDED = 2
} ambix_fileformat_t;
typedef enum {
AMBIX_SAMPLEFORMAT_NONE=0,
AMBIX_SAMPLEFORMAT_PCM16,
AMBIX_SAMPLEFORMAT_PCM24,
AMBIX_SAMPLEFORMAT_PCM32,
AMBIX_SAMPLEFORMAT_FLOAT32,
AMBIX_SAMPLEFORMAT_FLOAT64,
} ambix_sampleformat_t;
typedef enum {
AMBIX_MATRIX_INVALID = -1,
AMBIX_MATRIX_ZERO = 0,
AMBIX_MATRIX_ONE = 1,
AMBIX_MATRIX_IDENTITY,
AMBIX_MATRIX_AMBIX = 0x8000,
AMBIX_MATRIX_N3D = 1 | AMBIX_MATRIX_AMBIX,
AMBIX_MATRIX_SID = 2 | AMBIX_MATRIX_AMBIX,
AMBIX_MATRIX_FUMA = 3 | AMBIX_MATRIX_AMBIX,
AMBIX_MATRIX_TO_AMBIX = 0x4000 | AMBIX_MATRIX_AMBIX,
AMBIX_MATRIX_TO_N3D = AMBIX_MATRIX_TO_AMBIX | AMBIX_MATRIX_N3D,
AMBIX_MATRIX_TO_SID = AMBIX_MATRIX_TO_AMBIX | AMBIX_MATRIX_SID,
AMBIX_MATRIX_TO_FUMA = AMBIX_MATRIX_TO_AMBIX | AMBIX_MATRIX_FUMA,
} ambix_matrixtype_t;
typedef struct ambix_matrix_t {
uint32_t rows;
uint32_t cols;
float32_t **data;
} ambix_matrix_t;
typedef struct ambix_info_t {
uint64_t frames;
double samplerate;
ambix_sampleformat_t sampleformat;
ambix_fileformat_t fileformat;
uint32_t extrachannels;
uint32_t ambichannels;
} ambix_info_t;
typedef struct ambix_marker_t {
float64_t position;
char name[256];
} ambix_marker_t;
typedef struct ambix_region_t {
float64_t start_position;
float64_t end_position;
char name[256];
} ambix_region_t;
/*
* @section api_main Main Interface
*/
AMBIX_API
ambix_t *ambix_open (const char *path, const ambix_filemode_t mode, ambix_info_t *ambixinfo) ;
AMBIX_API
ambix_err_t ambix_close (ambix_t *ambix) ;
AMBIX_API
int64_t ambix_seek (ambix_t *ambix, int64_t frames, int whence) ;
AMBIX_API
int64_t ambix_readf_int16 (ambix_t *ambix, int16_t *ambidata, int16_t *otherdata, int64_t frames) ;
AMBIX_API
int64_t ambix_readf_int32 (ambix_t *ambix, int32_t *ambidata, int32_t *otherdata, int64_t frames) ;
AMBIX_API
int64_t ambix_readf_float32 (ambix_t *ambix, float32_t *ambidata, float32_t *otherdata, int64_t frames) ;
AMBIX_API
int64_t ambix_readf_float64 (ambix_t *ambix, float64_t *ambidata, float64_t *otherdata, int64_t frames) ;
AMBIX_API
int64_t ambix_writef_int16 (ambix_t *ambix, const int16_t *ambidata, const int16_t *otherdata, int64_t frames) ;
AMBIX_API
int64_t ambix_writef_int32 (ambix_t *ambix, const int32_t *ambidata, const int32_t *otherdata, int64_t frames) ;
AMBIX_API
int64_t ambix_writef_float32 (ambix_t *ambix, const float32_t *ambidata, const float32_t *otherdata, int64_t frames) ;
AMBIX_API
int64_t ambix_writef_float64 (ambix_t *ambix, const float64_t *ambidata, const float64_t *otherdata, int64_t frames) ;
AMBIX_API
SNDFILE *ambix_get_sndfile (ambix_t *ambix) ;
#pragma pop_macro("SNDFILE")
AMBIX_API
uint32_t ambix_get_num_markers(ambix_t *ambix) ;
AMBIX_API
uint32_t ambix_get_num_regions(ambix_t *ambix) ;
AMBIX_API
ambix_marker_t *ambix_get_marker(ambix_t *ambix, uint32_t id) ;
AMBIX_API
ambix_region_t *ambix_get_region(ambix_t *ambix, uint32_t id) ;
AMBIX_API
ambix_err_t ambix_add_marker(ambix_t *ambix, ambix_marker_t *marker) ; // returns id
AMBIX_API
ambix_err_t ambix_add_region(ambix_t *ambix, ambix_region_t *region) ; // returns id
AMBIX_API
ambix_err_t ambix_delete_markers(ambix_t *ambix) ;
AMBIX_API
ambix_err_t ambix_delete_regions(ambix_t *ambix) ;
AMBIX_API
const ambix_matrix_t *ambix_get_adaptormatrix (ambix_t *ambix) ;
AMBIX_API
ambix_err_t ambix_set_adaptormatrix (ambix_t *ambix, const ambix_matrix_t *matrix) ;
/*
* @section api_matrix matrix utility functions
*/
AMBIX_API
ambix_matrix_t *ambix_matrix_create (void) ;
AMBIX_API
void ambix_matrix_destroy (ambix_matrix_t *mtx) ;
AMBIX_API
ambix_matrix_t *ambix_matrix_init (uint32_t rows, uint32_t cols, ambix_matrix_t *mtx) ;
AMBIX_API
void ambix_matrix_deinit (ambix_matrix_t *mtx) ;
AMBIX_API
ambix_matrix_t *ambix_matrix_fill (ambix_matrix_t *matrix, ambix_matrixtype_t type) ;
AMBIX_API
ambix_err_t ambix_matrix_fill_data (ambix_matrix_t *mtx, const float32_t *data) ;
AMBIX_API
ambix_matrix_t *ambix_matrix_copy (const ambix_matrix_t *src, ambix_matrix_t *dest) ;
AMBIX_API AMBIX_DEPRECATED
ambix_matrix_t *ambix_matrix_multiply (const ambix_matrix_t *A, const ambix_matrix_t *B, ambix_matrix_t *result) ;
AMBIX_API AMBIX_DEPRECATED
ambix_matrix_t* ambix_matrix_pinv(const ambix_matrix_t*matrix, ambix_matrix_t*pinv) ;
AMBIX_API
ambix_err_t ambix_matrix_multiply_float32(float32_t *dest, const ambix_matrix_t *mtx, const float32_t *source, int64_t frames) ;
AMBIX_API
ambix_err_t ambix_matrix_multiply_float64(float64_t *dest, const ambix_matrix_t *mtx, const float64_t *source, int64_t frames) ;
AMBIX_API
ambix_err_t ambix_matrix_multiply_int32(int32_t *dest, const ambix_matrix_t *mtx, const int32_t *source, int64_t frames) ;
AMBIX_API
ambix_err_t ambix_matrix_multiply_int16(int16_t *dest, const ambix_matrix_t *mtx, const int16_t *source, int64_t frames) ;
AMBIX_API
uint32_t ambix_order2channels(uint32_t order) ;
AMBIX_API
int32_t ambix_channels2order(uint32_t channels) ;
AMBIX_API
int ambix_is_fullset(uint32_t channels) ;
#ifdef __cplusplus
} /* extern "C" */
#endif /* __cplusplus */
#if HAVE_PUSH_MACRO
# pragma pop_macro("SNDFILE")
#elif !defined(SNDFILE_1)
# undef SNDFILE void
#endif
#endif /* AMBIX_AMBIX_H */
ambix_sampleformat_t
ambix_sampleformat_t
Definition ambix.h:142
AMBIX_SAMPLEFORMAT_PCM32
@ AMBIX_SAMPLEFORMAT_PCM32
Definition ambix.h:150
AMBIX_SAMPLEFORMAT_FLOAT32
@ AMBIX_SAMPLEFORMAT_FLOAT32
Definition ambix.h:152
AMBIX_SAMPLEFORMAT_FLOAT64
@ AMBIX_SAMPLEFORMAT_FLOAT64
Definition ambix.h:154
AMBIX_SAMPLEFORMAT_PCM24
@ AMBIX_SAMPLEFORMAT_PCM24
Definition ambix.h:148
AMBIX_SAMPLEFORMAT_NONE
@ AMBIX_SAMPLEFORMAT_NONE
Definition ambix.h:144
AMBIX_SAMPLEFORMAT_PCM16
@ AMBIX_SAMPLEFORMAT_PCM16
Definition ambix.h:146
float32_t
float float32_t
Definition ambix.h:41
ambix_matrixtype_t
ambix_matrixtype_t
Definition ambix.h:158
AMBIX_MATRIX_SID
@ AMBIX_MATRIX_SID
Definition ambix.h:178
AMBIX_MATRIX_TO_N3D
@ AMBIX_MATRIX_TO_N3D
Definition ambix.h:186
AMBIX_MATRIX_N3D
@ AMBIX_MATRIX_N3D
Definition ambix.h:176
AMBIX_MATRIX_ZERO
@ AMBIX_MATRIX_ZERO
Definition ambix.h:162
AMBIX_MATRIX_IDENTITY
@ AMBIX_MATRIX_IDENTITY
Definition ambix.h:166
AMBIX_MATRIX_TO_FUMA
@ AMBIX_MATRIX_TO_FUMA
Definition ambix.h:190
AMBIX_MATRIX_AMBIX
@ AMBIX_MATRIX_AMBIX
Definition ambix.h:174
AMBIX_MATRIX_FUMA
@ AMBIX_MATRIX_FUMA
Definition ambix.h:180
AMBIX_MATRIX_INVALID
@ AMBIX_MATRIX_INVALID
Definition ambix.h:160
AMBIX_MATRIX_TO_AMBIX
@ AMBIX_MATRIX_TO_AMBIX
Definition ambix.h:183
AMBIX_MATRIX_ONE
@ AMBIX_MATRIX_ONE
Definition ambix.h:164
AMBIX_MATRIX_TO_SID
@ AMBIX_MATRIX_TO_SID
Definition ambix.h:188
ambix_fileformat_t
ambix_fileformat_t
Definition ambix.h:132
AMBIX_NONE
@ AMBIX_NONE
Definition ambix.h:134
AMBIX_BASIC
@ AMBIX_BASIC
Definition ambix.h:136
AMBIX_EXTENDED
@ AMBIX_EXTENDED
Definition ambix.h:138
ambix_filemode_t
ambix_filemode_t
Definition ambix.h:121
AMBIX_RDRW
@ AMBIX_RDRW
Definition ambix.h:127
AMBIX_READ
@ AMBIX_READ
Definition ambix.h:123
AMBIX_WRITE
@ AMBIX_WRITE
Definition ambix.h:125
float64_t
double float64_t
Definition ambix.h:44
ambix_err_t
ambix_err_t
Definition ambix.h:97
AMBIX_ERR_INVALID_HANDLE
@ AMBIX_ERR_INVALID_HANDLE
Definition ambix.h:105
AMBIX_ERR_UNKNOWN
@ AMBIX_ERR_UNKNOWN
Definition ambix.h:99
AMBIX_ERR_INVALID_FORMAT
@ AMBIX_ERR_INVALID_FORMAT
Definition ambix.h:113
AMBIX_ERR_INVALID_DIMENSION
@ AMBIX_ERR_INVALID_DIMENSION
Definition ambix.h:109
AMBIX_ERR_INVALID_FILE
@ AMBIX_ERR_INVALID_FILE
Definition ambix.h:107
AMBIX_ERR_SUCCESS
@ AMBIX_ERR_SUCCESS
Definition ambix.h:102
AMBIX_ERR_INVALID_MATRIX
@ AMBIX_ERR_INVALID_MATRIX
Definition ambix.h:116
ambix_t
struct ambix_t_struct ambix_t
Definition ambix.h:93
exportdefs.h
export definitions for various compilers
AMBIX_DEPRECATED
#define AMBIX_DEPRECATED
Definition exportdefs.h:66
AMBIX_API
#define AMBIX_API
Definition exportdefs.h:74
ambix_matrix_multiply_int32
AMBIX_API ambix_err_t ambix_matrix_multiply_int32(int32_t *dest, const ambix_matrix_t *mtx, const int32_t *source, int64_t frames)
Multiply a matrix with (32bit signed integer) data.
ambix_matrix_multiply_int16
AMBIX_API ambix_err_t ambix_matrix_multiply_int16(int16_t *dest, const ambix_matrix_t *mtx, const int16_t *source, int64_t frames)
Multiply a matrix with (16 bit signed integer) data.
ambix_matrix_multiply_float32
AMBIX_API ambix_err_t ambix_matrix_multiply_float32(float32_t *dest, const ambix_matrix_t *mtx, const float32_t *source, int64_t frames)
Multiply a matrix with (32bit floating point) data.
ambix_matrix_multiply_float64
AMBIX_API ambix_err_t ambix_matrix_multiply_float64(float64_t *dest, const ambix_matrix_t *mtx, const float64_t *source, int64_t frames)
Multiply a matrix with (64bit float) data.
ambix_matrix_fill_data
AMBIX_API ambix_err_t ambix_matrix_fill_data(ambix_matrix_t *mtx, const float32_t *data)
Fill a matrix with values.
ambix_matrix_destroy
AMBIX_API void ambix_matrix_destroy(ambix_matrix_t *mtx)
Destroy a matrix.
ambix_matrix_init
AMBIX_API ambix_matrix_t * ambix_matrix_init(uint32_t rows, uint32_t cols, ambix_matrix_t *mtx)
Initialize a matrix.
ambix_matrix_fill
AMBIX_API ambix_matrix_t * ambix_matrix_fill(ambix_matrix_t *matrix, ambix_matrixtype_t type)
Fill a matrix according to specs.
ambix_matrix_create
AMBIX_API ambix_matrix_t * ambix_matrix_create(void)
Create a matrix.
ambix_matrix_deinit
AMBIX_API void ambix_matrix_deinit(ambix_matrix_t *mtx)
De-initialize a matrix.
ambix_matrix_copy
AMBIX_API ambix_matrix_t * ambix_matrix_copy(const ambix_matrix_t *src, ambix_matrix_t *dest)
Copy a matrix to another matrix.
ambix_readf_float64
AMBIX_API int64_t ambix_readf_float64(ambix_t *ambix, float64_t *ambidata, float64_t *otherdata, int64_t frames)
Read samples (as double precision floating point values) from the ambix file.
ambix_readf_float32
AMBIX_API int64_t ambix_readf_float32(ambix_t *ambix, float32_t *ambidata, float32_t *otherdata, int64_t frames)
Read samples (as single precision floating point values) from the ambix file.
ambix_readf_int32
AMBIX_API int64_t ambix_readf_int32(ambix_t *ambix, int32_t *ambidata, int32_t *otherdata, int64_t frames)
Read samples (as 32bit signed integer values) from the ambix file.
ambix_readf_int16
AMBIX_API int64_t ambix_readf_int16(ambix_t *ambix, int16_t *ambidata, int16_t *otherdata, int64_t frames)
Read samples (as 16bit signed integer values) from the ambix file.
ambix_order2channels
AMBIX_API uint32_t ambix_order2channels(uint32_t order)
Calculate the number of channels for a full 3d ambisonics set of a given order.
ambix_is_fullset
AMBIX_API int ambix_is_fullset(uint32_t channels)
Checks whether the channel can form a full 3d ambisonics set.
ambix_channels2order
AMBIX_API int32_t ambix_channels2order(uint32_t channels)
Calculate the order of a full 3d ambisonics set for a given number of channels.
ambix_writef_float64
AMBIX_API int64_t ambix_writef_float64(ambix_t *ambix, const float64_t *ambidata, const float64_t *otherdata, int64_t frames)
Write (64bit floating point) samples to the ambix file.
ambix_writef_int32
AMBIX_API int64_t ambix_writef_int32(ambix_t *ambix, const int32_t *ambidata, const int32_t *otherdata, int64_t frames)
Write (32bit signed integer) samples to the ambix file.
ambix_writef_int16
AMBIX_API int64_t ambix_writef_int16(ambix_t *ambix, const int16_t *ambidata, const int16_t *otherdata, int64_t frames)
Write (16bit signed integer) samples to the ambix file.
ambix_writef_float32
AMBIX_API int64_t ambix_writef_float32(ambix_t *ambix, const float32_t *ambidata, const float32_t *otherdata, int64_t frames)
Write (32bit floating point) samples to the ambix file.
ambix_delete_markers
AMBIX_API ambix_err_t ambix_delete_markers(ambix_t *ambix)
Deletes all markers in the ambix file.
ambix_seek
AMBIX_API int64_t ambix_seek(ambix_t *ambix, int64_t frames, int whence)
Reposition the file pointer.
ambix_close
AMBIX_API ambix_err_t ambix_close(ambix_t *ambix)
Close an ambix handle.
ambix_get_sndfile
AMBIX_API SNDFILE * ambix_get_sndfile(ambix_t *ambix)
Get the libsndfile handle associated with the ambix handle.
ambix_open
AMBIX_API ambix_t * ambix_open(const char *path, const ambix_filemode_t mode, ambix_info_t *ambixinfo)
Open an ambix file.
ambix_delete_regions
AMBIX_API ambix_err_t ambix_delete_regions(ambix_t *ambix)
Deletes all regions in the ambix file.
ambix_set_adaptormatrix
AMBIX_API ambix_err_t ambix_set_adaptormatrix(ambix_t *ambix, const ambix_matrix_t *matrix)
Set a matrix to be pre-multiplied.
ambix_add_marker
AMBIX_API ambix_err_t ambix_add_marker(ambix_t *ambix, ambix_marker_t *marker)
Add a new marker to the ambix file.
ambix_get_num_regions
AMBIX_API uint32_t ambix_get_num_regions(ambix_t *ambix)
Get the number of stored regions within the ambix file.
ambix_get_region
AMBIX_API ambix_region_t * ambix_get_region(ambix_t *ambix, uint32_t id)
Get one region.
ambix_get_adaptormatrix
AMBIX_API const ambix_matrix_t * ambix_get_adaptormatrix(ambix_t *ambix)
Get the adaptor matrix.
ambix_get_num_markers
AMBIX_API uint32_t ambix_get_num_markers(ambix_t *ambix)
Get the number of stored markers within the ambix file.
ambix_add_region
AMBIX_API ambix_err_t ambix_add_region(ambix_t *ambix, ambix_region_t *region)
Add a new region to the ambix file.
ambix_get_marker
AMBIX_API ambix_marker_t * ambix_get_marker(ambix_t *ambix, uint32_t id)
Get one marker.
ambix_info_t
Definition ambix.h:207
ambix_info_t::fileformat
ambix_fileformat_t fileformat
Definition ambix.h:228
ambix_info_t::samplerate
double samplerate
Definition ambix.h:211
ambix_info_t::frames
uint64_t frames
Definition ambix.h:209
ambix_info_t::ambichannels
uint32_t ambichannels
Definition ambix.h:246
ambix_info_t::extrachannels
uint32_t extrachannels
Definition ambix.h:233
ambix_info_t::sampleformat
ambix_sampleformat_t sampleformat
Definition ambix.h:213
ambix_marker_t
Definition ambix.h:250
ambix_marker_t::name
char name[256]
Definition ambix.h:254
ambix_marker_t::position
float64_t position
Definition ambix.h:252
ambix_matrix_t
Definition ambix.h:195
ambix_matrix_t::data
float32_t ** data
Definition ambix.h:201
ambix_matrix_t::cols
uint32_t cols
Definition ambix.h:199
ambix_matrix_t::rows
uint32_t rows
Definition ambix.h:197
ambix_region_t
Definition ambix.h:258
ambix_region_t::name
char name[256]
Definition ambix.h:264
ambix_region_t::start_position
float64_t start_position
Definition ambix.h:260
ambix_region_t::end_position
float64_t end_position
Definition ambix.h:262
number32_t
Definition ambix.h:83
number32_t::u
uint32_t u
Definition ambix.h:89
number32_t::i
int32_t i
Definition ambix.h:87
number32_t::f
float32_t f
Definition ambix.h:85