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
37 extern "C" {
38 #endif /* __cplusplus */
39 
41 typedef float float32_t;
42 
44 typedef double float64_t;
45 
46 #ifdef _MSC_VER
48 typedef signed short int16_t;
50 typedef unsigned short uint16_t;
52 typedef signed int int32_t;
54 typedef unsigned int uint32_t;
56 typedef signed long int64_t;
58 typedef 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
83 typedef union {
87  int32_t i;
89  uint32_t u;
90 } number32_t;
91 
93 typedef struct ambix_t_struct ambix_t;
94 
96 typedef enum
97 {
100 
103 
114 
117 
118 } ambix_err_t;
119 
121 typedef enum {
123  AMBIX_READ = (1 << 4),
125  AMBIX_WRITE = (1 << 5),
128 
130 
132 typedef enum {
138  AMBIX_EXTENDED = 2
140 
142 typedef enum {
156 
158 typedef enum {
167 
181 
184 
191 
193 
195 typedef struct ambix_matrix_t {
197  uint32_t rows;
199  uint32_t cols;
203 
207 typedef struct ambix_info_t {
209  uint64_t frames;
211  double samplerate;
214 
229 
233  uint32_t extrachannels;
234 
246  uint32_t ambichannels;
248 
250 typedef struct ambix_marker_t {
254  char name[256];
256 
258 typedef struct ambix_region_t {
264  char name[256];
266 
267 /*
268  * @section api_main Main Interface
269  */
303 AMBIX_API
304 ambix_t *ambix_open (const char *path, const ambix_filemode_t mode, ambix_info_t *ambixinfo) ;
305 
317 AMBIX_API
319 
337 AMBIX_API
338 int64_t ambix_seek (ambix_t *ambix, int64_t frames, int whence) ;
339 
369 AMBIX_API
370 int64_t ambix_readf_int16 (ambix_t *ambix, int16_t *ambidata, int16_t *otherdata, int64_t frames) ;
374 AMBIX_API
375 int64_t ambix_readf_int32 (ambix_t *ambix, int32_t *ambidata, int32_t *otherdata, int64_t frames) ;
380 AMBIX_API
381 int64_t ambix_readf_float32 (ambix_t *ambix, float32_t *ambidata, float32_t *otherdata, int64_t frames) ;
382 
387 AMBIX_API
388 int64_t ambix_readf_float64 (ambix_t *ambix, float64_t *ambidata, float64_t *otherdata, int64_t frames) ;
389 
420 AMBIX_API
421 int64_t ambix_writef_int16 (ambix_t *ambix, const int16_t *ambidata, const int16_t *otherdata, int64_t frames) ;
425 AMBIX_API
426 int64_t ambix_writef_int32 (ambix_t *ambix, const int32_t *ambidata, const int32_t *otherdata, int64_t frames) ;
430 AMBIX_API
431 int64_t ambix_writef_float32 (ambix_t *ambix, const float32_t *ambidata, const float32_t *otherdata, int64_t frames) ;
435 AMBIX_API
436 int64_t ambix_writef_float64 (ambix_t *ambix, const float64_t *ambidata, const float64_t *otherdata, int64_t frames) ;
437 
452 AMBIX_API
453 SNDFILE *ambix_get_sndfile (ambix_t *ambix) ;
454 
455 #pragma pop_macro("SNDFILE")
456 
463 AMBIX_API
464 uint32_t ambix_get_num_markers(ambix_t *ambix) ;
473 AMBIX_API
474 uint32_t ambix_get_num_regions(ambix_t *ambix) ;
485 AMBIX_API
486 ambix_marker_t *ambix_get_marker(ambix_t *ambix, uint32_t id) ;
497 AMBIX_API
498 ambix_region_t *ambix_get_region(ambix_t *ambix, uint32_t id) ;
511 AMBIX_API
512 ambix_err_t ambix_add_marker(ambix_t *ambix, ambix_marker_t *marker) ; // returns id
525 AMBIX_API
526 ambix_err_t ambix_add_region(ambix_t *ambix, ambix_region_t *region) ; // returns id
535 AMBIX_API
545 AMBIX_API
573 AMBIX_API
575 
602 AMBIX_API
604 
605 /*
606  * @section api_matrix matrix utility functions
607  */
608 
618 AMBIX_API
620 
630 AMBIX_API
632 
649 AMBIX_API
650 ambix_matrix_t *ambix_matrix_init (uint32_t rows, uint32_t cols, ambix_matrix_t *mtx) ;
651 
660 AMBIX_API
662 
682 AMBIX_API
684 
699 AMBIX_API
701 
714 AMBIX_API
737 ambix_matrix_t *ambix_matrix_multiply (const ambix_matrix_t *A, const ambix_matrix_t *B, ambix_matrix_t *result) ;
753 ambix_matrix_t* ambix_matrix_pinv(const ambix_matrix_t*matrix, ambix_matrix_t*pinv) ;
782 AMBIX_API
783 ambix_err_t ambix_matrix_multiply_float32(float32_t *dest, const ambix_matrix_t *mtx, const float32_t *source, int64_t frames) ;
788 AMBIX_API
789 ambix_err_t ambix_matrix_multiply_float64(float64_t *dest, const ambix_matrix_t *mtx, const float64_t *source, int64_t frames) ;
794 AMBIX_API
795 ambix_err_t ambix_matrix_multiply_int32(int32_t *dest, const ambix_matrix_t *mtx, const int32_t *source, int64_t frames) ;
800 AMBIX_API
801 ambix_err_t ambix_matrix_multiply_int16(int16_t *dest, const ambix_matrix_t *mtx, const int16_t *source, int64_t frames) ;
802 
818 AMBIX_API
819 uint32_t ambix_order2channels(uint32_t order) ;
820 
830 AMBIX_API
831 int32_t ambix_channels2order(uint32_t channels) ;
832 
841 AMBIX_API
842 int 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 ambix_matrix_t * ambix_matrix_fill(ambix_matrix_t *matrix, ambix_matrixtype_t type)
Fill a matrix according to specs.
AMBIX_API void ambix_matrix_destroy(ambix_matrix_t *mtx)
Destroy 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 void ambix_matrix_deinit(ambix_matrix_t *mtx)
De-initialize a matrix.
AMBIX_API ambix_matrix_t * ambix_matrix_create(void)
Create 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 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 ambix_marker_t * ambix_get_marker(ambix_t *ambix, uint32_t id)
Get one marker.
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 const ambix_matrix_t * ambix_get_adaptormatrix(ambix_t *ambix)
Get the adaptor matrix.
AMBIX_API ambix_region_t * ambix_get_region(ambix_t *ambix, uint32_t id)
Get one region.
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_t * ambix_open(const char *path, const ambix_filemode_t mode, ambix_info_t *ambixinfo)
Open an ambix file.
AMBIX_API uint32_t ambix_get_num_markers(ambix_t *ambix)
Get the number of stored markers within the ambix file.
AMBIX_API SNDFILE * ambix_get_sndfile(ambix_t *ambix)
Get the libsndfile handle associated with the ambix handle.
AMBIX_API ambix_err_t ambix_add_region(ambix_t *ambix, ambix_region_t *region)
Add a new region to the ambix file.
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