libambix
the AMBIsonics eXchange library
ambix.h
Go to the documentation of this file.
1/* ambix/ambix.h - AMBIsonics eXchange Library Interface -*- c -*-
2
3 Copyright © 2012 IOhannes m zmölnig <zmoelnig@iem.at>.
4 Institute of Electronic Music and Acoustics (IEM),
5 University of Music and Dramatic Arts, Graz
6
7 This file is part of libambix
8
9 libambix is free software; you can redistribute it and/or modify
10 it under the terms of the GNU Lesser General Public License as
11 published by the Free Software Foundation; either version 2.1 of
12 the License, or (at your option) any later version.
13
14 libambix is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU Lesser General Public License for more details.
18
19 You should have received a copy of the GNU Lesser General Public
20 License along with this program; if not, see <http://www.gnu.org/licenses/>.
21*/
22
31#ifndef AMBIX_AMBIX_H
32#define AMBIX_AMBIX_H
33
34#include "exportdefs.h"
35
36#ifdef __cplusplus
37extern "C" {
38#endif /* __cplusplus */
39
41typedef float float32_t;
42
44typedef double float64_t;
45
46#ifdef _MSC_VER
48typedef signed short int16_t;
50typedef unsigned short uint16_t;
52typedef signed int int32_t;
54typedef unsigned int uint32_t;
56typedef signed long int64_t;
58typedef unsigned long uint64_t;
59#else
60# include <stdint.h>
61#endif
62
64 /* ugly hack to provide to allow the use type 'SNDFILE*'
65 * regardless of whether <sndfile.h> is included or not
66 */
67#ifndef HAVE_PUSH_MACRO
68# define HAVE_PUSH_MACRO 1
69#endif
70#if HAVE_PUSH_MACRO
71# pragma push_macro("SNDFILE")
72# ifdef SNDFILE
73# undef SNDFILE
74# endif
75# define SNDFILE void
76#elif !defined(SNDFILE_1)
77# define SNDFILE void
78#endif
83typedef union {
87 int32_t i;
89 uint32_t u;
91
93typedef struct ambix_t_struct ambix_t;
94
119
121typedef enum {
123 AMBIX_READ = (1 << 4),
125 AMBIX_WRITE = (1 << 5),
128
130
140
156
193
195typedef struct ambix_matrix_t {
197 uint32_t rows;
199 uint32_t cols;
203
248
256
266
267/*
268 * @section api_main Main Interface
269 */
304ambix_t *ambix_open (const char *path, const ambix_filemode_t mode, ambix_info_t *ambixinfo) ;
305
319
338int64_t ambix_seek (ambix_t *ambix, int64_t frames, int whence) ;
339
370int64_t ambix_readf_int16 (ambix_t *ambix, int16_t *ambidata, int16_t *otherdata, int64_t frames) ;
375int64_t ambix_readf_int32 (ambix_t *ambix, int32_t *ambidata, int32_t *otherdata, int64_t frames) ;
381int64_t ambix_readf_float32 (ambix_t *ambix, float32_t *ambidata, float32_t *otherdata, int64_t frames) ;
382
388int64_t ambix_readf_float64 (ambix_t *ambix, float64_t *ambidata, float64_t *otherdata, int64_t frames) ;
389
421int64_t ambix_writef_int16 (ambix_t *ambix, const int16_t *ambidata, const int16_t *otherdata, int64_t frames) ;
426int64_t ambix_writef_int32 (ambix_t *ambix, const int32_t *ambidata, const int32_t *otherdata, int64_t frames) ;
431int64_t ambix_writef_float32 (ambix_t *ambix, const float32_t *ambidata, const float32_t *otherdata, int64_t frames) ;
436int64_t ambix_writef_float64 (ambix_t *ambix, const float64_t *ambidata, const float64_t *otherdata, int64_t frames) ;
437
453SNDFILE *ambix_get_sndfile (ambix_t *ambix) ;
454
455#pragma pop_macro("SNDFILE")
456
512ambix_err_t ambix_add_marker(ambix_t *ambix, ambix_marker_t *marker) ; // returns id
526ambix_err_t ambix_add_region(ambix_t *ambix, ambix_region_t *region) ; // returns id
575
604
605/*
606 * @section api_matrix matrix utility functions
607 */
608
620
632
650ambix_matrix_t *ambix_matrix_init (uint32_t rows, uint32_t cols, ambix_matrix_t *mtx) ;
651
662
684
701
737ambix_matrix_t *ambix_matrix_multiply (const ambix_matrix_t *A, const ambix_matrix_t *B, ambix_matrix_t *result) ;
753ambix_matrix_t* ambix_matrix_pinv(const ambix_matrix_t*matrix, ambix_matrix_t*pinv) ;
783ambix_err_t ambix_matrix_multiply_float32(float32_t *dest, const ambix_matrix_t *mtx, const float32_t *source, int64_t frames) ;
789ambix_err_t ambix_matrix_multiply_float64(float64_t *dest, const ambix_matrix_t *mtx, const float64_t *source, int64_t frames) ;
795ambix_err_t ambix_matrix_multiply_int32(int32_t *dest, const ambix_matrix_t *mtx, const int32_t *source, int64_t frames) ;
801ambix_err_t ambix_matrix_multiply_int16(int16_t *dest, const ambix_matrix_t *mtx, const int16_t *source, int64_t frames) ;
802
819uint32_t ambix_order2channels(uint32_t order) ;
820
831int32_t ambix_channels2order(uint32_t channels) ;
832
842int ambix_is_fullset(uint32_t channels) ;
843
844#ifdef __cplusplus
845} /* extern "C" */
846#endif /* __cplusplus */
847
848#if HAVE_PUSH_MACRO
849# pragma pop_macro("SNDFILE")
850#elif !defined(SNDFILE_1)
851# undef SNDFILE void
852#endif
853
854#endif /* AMBIX_AMBIX_H */
struct ambix_region_t ambix_region_t
struct ambix_matrix_t ambix_matrix_t
struct ambix_info_t ambix_info_t
ambix_sampleformat_t
Definition ambix.h:142
@ AMBIX_SAMPLEFORMAT_PCM32
Definition ambix.h:150
@ AMBIX_SAMPLEFORMAT_FLOAT32
Definition ambix.h:152
@ AMBIX_SAMPLEFORMAT_FLOAT64
Definition ambix.h:154
@ AMBIX_SAMPLEFORMAT_PCM24
Definition ambix.h:148
@ AMBIX_SAMPLEFORMAT_NONE
Definition ambix.h:144
@ AMBIX_SAMPLEFORMAT_PCM16
Definition ambix.h:146
float float32_t
Definition ambix.h:41
ambix_matrixtype_t
Definition ambix.h:158
@ AMBIX_MATRIX_SID
Definition ambix.h:178
@ AMBIX_MATRIX_TO_N3D
Definition ambix.h:186
@ AMBIX_MATRIX_N3D
Definition ambix.h:176
@ AMBIX_MATRIX_ZERO
Definition ambix.h:162
@ AMBIX_MATRIX_IDENTITY
Definition ambix.h:166
@ AMBIX_MATRIX_TO_FUMA
Definition ambix.h:190
@ AMBIX_MATRIX_AMBIX
Definition ambix.h:174
@ AMBIX_MATRIX_FUMA
Definition ambix.h:180
@ AMBIX_MATRIX_INVALID
Definition ambix.h:160
@ AMBIX_MATRIX_TO_AMBIX
Definition ambix.h:183
@ AMBIX_MATRIX_ONE
Definition ambix.h:164
@ AMBIX_MATRIX_TO_SID
Definition ambix.h:188
ambix_fileformat_t
Definition ambix.h:132
@ AMBIX_NONE
Definition ambix.h:134
@ AMBIX_BASIC
Definition ambix.h:136
@ AMBIX_EXTENDED
Definition ambix.h:138
struct ambix_marker_t ambix_marker_t
ambix_filemode_t
Definition ambix.h:121
@ AMBIX_RDRW
Definition ambix.h:127
@ AMBIX_READ
Definition ambix.h:123
@ AMBIX_WRITE
Definition ambix.h:125
double float64_t
Definition ambix.h:44
ambix_err_t
Definition ambix.h:97
@ AMBIX_ERR_INVALID_HANDLE
Definition ambix.h:105
@ AMBIX_ERR_UNKNOWN
Definition ambix.h:99
@ AMBIX_ERR_INVALID_FORMAT
Definition ambix.h:113
@ AMBIX_ERR_INVALID_DIMENSION
Definition ambix.h:109
@ AMBIX_ERR_INVALID_FILE
Definition ambix.h:107
@ AMBIX_ERR_SUCCESS
Definition ambix.h:102
@ AMBIX_ERR_INVALID_MATRIX
Definition ambix.h:116
struct ambix_t_struct ambix_t
Definition ambix.h:93
export definitions for various compilers
#define AMBIX_DEPRECATED
Definition exportdefs.h:66
#define AMBIX_API
Definition exportdefs.h:74
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_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_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_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_API ambix_err_t ambix_matrix_fill_data(ambix_matrix_t *mtx, const float32_t *data)
Fill a matrix with values.
AMBIX_API void ambix_matrix_destroy(ambix_matrix_t *mtx)
Destroy a matrix.
AMBIX_API ambix_matrix_t * ambix_matrix_init(uint32_t rows, uint32_t cols, ambix_matrix_t *mtx)
Initialize a matrix.
AMBIX_API ambix_matrix_t * ambix_matrix_fill(ambix_matrix_t *matrix, ambix_matrixtype_t type)
Fill a matrix according to specs.
AMBIX_API ambix_matrix_t * ambix_matrix_create(void)
Create a matrix.
AMBIX_API void ambix_matrix_deinit(ambix_matrix_t *mtx)
De-initialize a matrix.
AMBIX_API ambix_matrix_t * ambix_matrix_copy(const ambix_matrix_t *src, ambix_matrix_t *dest)
Copy a matrix to another matrix.
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_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_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_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_API uint32_t ambix_order2channels(uint32_t order)
Calculate the number of channels for a full 3d ambisonics set of a given order.
AMBIX_API int ambix_is_fullset(uint32_t channels)
Checks whether the channel can form a full 3d ambisonics set.
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_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_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_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_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_API ambix_err_t ambix_delete_markers(ambix_t *ambix)
Deletes all markers in the ambix file.
AMBIX_API int64_t ambix_seek(ambix_t *ambix, int64_t frames, int whence)
Reposition the file pointer.
AMBIX_API ambix_err_t ambix_close(ambix_t *ambix)
Close an ambix handle.
AMBIX_API SNDFILE * ambix_get_sndfile(ambix_t *ambix)
Get the libsndfile handle associated with the ambix handle.
AMBIX_API ambix_t * ambix_open(const char *path, const ambix_filemode_t mode, ambix_info_t *ambixinfo)
Open an ambix file.
AMBIX_API ambix_err_t ambix_delete_regions(ambix_t *ambix)
Deletes all regions in the ambix file.
AMBIX_API ambix_err_t ambix_set_adaptormatrix(ambix_t *ambix, const ambix_matrix_t *matrix)
Set a matrix to be pre-multiplied.
AMBIX_API ambix_err_t ambix_add_marker(ambix_t *ambix, ambix_marker_t *marker)
Add a new marker to the ambix file.
AMBIX_API uint32_t ambix_get_num_regions(ambix_t *ambix)
Get the number of stored regions within the ambix file.
AMBIX_API ambix_region_t * ambix_get_region(ambix_t *ambix, uint32_t id)
Get one region.
AMBIX_API const ambix_matrix_t * ambix_get_adaptormatrix(ambix_t *ambix)
Get the adaptor matrix.
AMBIX_API uint32_t ambix_get_num_markers(ambix_t *ambix)
Get the number of stored markers within the ambix file.
AMBIX_API ambix_err_t ambix_add_region(ambix_t *ambix, ambix_region_t *region)
Add a new region to the ambix file.
AMBIX_API ambix_marker_t * ambix_get_marker(ambix_t *ambix, uint32_t id)
Get one marker.
Definition ambix.h:207
ambix_fileformat_t fileformat
Definition ambix.h:228
double samplerate
Definition ambix.h:211
uint64_t frames
Definition ambix.h:209
uint32_t ambichannels
Definition ambix.h:246
uint32_t extrachannels
Definition ambix.h:233
ambix_sampleformat_t sampleformat
Definition ambix.h:213
Definition ambix.h:250
char name[256]
Definition ambix.h:254
float64_t position
Definition ambix.h:252
Definition ambix.h:195
float32_t ** data
Definition ambix.h:201
uint32_t cols
Definition ambix.h:199
uint32_t rows
Definition ambix.h:197
Definition ambix.h:258
char name[256]
Definition ambix.h:264
float64_t start_position
Definition ambix.h:260
float64_t end_position
Definition ambix.h:262
Definition ambix.h:83
uint32_t u
Definition ambix.h:89
int32_t i
Definition ambix.h:87
float32_t f
Definition ambix.h:85