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
47 
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 typedef union {
68  int32_t i;
70  uint32_t u;
71 } number32_t;
72 
74 typedef struct ambix_t_struct ambix_t;
75 
77 typedef enum
78 {
81 
84 
95 
98 
99 } ambix_err_t;
100 
102 typedef enum {
104  AMBIX_READ = (1 << 4),
106  AMBIX_WRITE = (1 << 5),
109 
111 
113 typedef enum {
121 
123 typedef enum {
137 
139 typedef enum {
148 
162 
165 
172 
174 
176 typedef struct ambix_matrix_t {
178  uint32_t rows;
180  uint32_t cols;
184 
188 typedef struct ambix_info_t {
190  uint64_t frames;
192  double samplerate;
195 
210 
214  uint32_t extrachannels;
215 
227  uint32_t ambichannels;
228 } ambix_info_t;
229 
231 typedef struct ambix_marker_t {
235  char name[256];
237 
239 typedef struct ambix_region_t {
245  char name[256];
247 
248 /*
249  * @section api_main Main Interface
250  */
284 AMBIX_API
285 ambix_t *ambix_open (const char *path, const ambix_filemode_t mode, ambix_info_t *ambixinfo) ;
286 
298 AMBIX_API
300 
318 AMBIX_API
319 int64_t ambix_seek (ambix_t *ambix, int64_t frames, int whence) ;
320 
350 AMBIX_API
351 int64_t ambix_readf_int16 (ambix_t *ambix, int16_t *ambidata, int16_t *otherdata, int64_t frames) ;
355 AMBIX_API
356 int64_t ambix_readf_int32 (ambix_t *ambix, int32_t *ambidata, int32_t *otherdata, int64_t frames) ;
361 AMBIX_API
362 int64_t ambix_readf_float32 (ambix_t *ambix, float32_t *ambidata, float32_t *otherdata, int64_t frames) ;
363 
368 AMBIX_API
369 int64_t ambix_readf_float64 (ambix_t *ambix, float64_t *ambidata, float64_t *otherdata, int64_t frames) ;
370 
401 AMBIX_API
402 int64_t ambix_writef_int16 (ambix_t *ambix, const int16_t *ambidata, const int16_t *otherdata, int64_t frames) ;
406 AMBIX_API
407 int64_t ambix_writef_int32 (ambix_t *ambix, const int32_t *ambidata, const int32_t *otherdata, int64_t frames) ;
411 AMBIX_API
412 int64_t ambix_writef_float32 (ambix_t *ambix, const float32_t *ambidata, const float32_t *otherdata, int64_t frames) ;
416 AMBIX_API
417 int64_t ambix_writef_float64 (ambix_t *ambix, const float64_t *ambidata, const float64_t *otherdata, int64_t frames) ;
422 struct SNDFILE_tag;
423 
436 AMBIX_API
437 struct SNDFILE_tag *ambix_get_sndfile (ambix_t *ambix) ;
444 AMBIX_API
445 uint32_t ambix_get_num_markers(ambix_t *ambix) ;
454 AMBIX_API
455 uint32_t ambix_get_num_regions(ambix_t *ambix) ;
466 AMBIX_API
467 ambix_marker_t *ambix_get_marker(ambix_t *ambix, uint32_t id) ;
478 AMBIX_API
479 ambix_region_t *ambix_get_region(ambix_t *ambix, uint32_t id) ;
492 AMBIX_API
493 ambix_err_t ambix_add_marker(ambix_t *ambix, ambix_marker_t *marker) ; // returns id
506 AMBIX_API
507 ambix_err_t ambix_add_region(ambix_t *ambix, ambix_region_t *region) ; // returns id
516 AMBIX_API
526 AMBIX_API
554 AMBIX_API
556 
583 AMBIX_API
585 
586 /*
587  * @section api_matrix matrix utility functions
588  */
589 
599 AMBIX_API
601 
611 AMBIX_API
613 
630 AMBIX_API
631 ambix_matrix_t *ambix_matrix_init (uint32_t rows, uint32_t cols, ambix_matrix_t *mtx) ;
632 
641 AMBIX_API
643 
663 AMBIX_API
665 
680 AMBIX_API
682 
695 AMBIX_API
718 ambix_matrix_t *ambix_matrix_multiply (const ambix_matrix_t *A, const ambix_matrix_t *B, ambix_matrix_t *result) ;
734 ambix_matrix_t* ambix_matrix_pinv(const ambix_matrix_t*matrix, ambix_matrix_t*pinv) ;
763 AMBIX_API
764 ambix_err_t ambix_matrix_multiply_float32(float32_t *dest, const ambix_matrix_t *mtx, const float32_t *source, int64_t frames) ;
769 AMBIX_API
770 ambix_err_t ambix_matrix_multiply_float64(float64_t *dest, const ambix_matrix_t *mtx, const float64_t *source, int64_t frames) ;
775 AMBIX_API
776 ambix_err_t ambix_matrix_multiply_int32(int32_t *dest, const ambix_matrix_t *mtx, const int32_t *source, int64_t frames) ;
781 AMBIX_API
782 ambix_err_t ambix_matrix_multiply_int16(int16_t *dest, const ambix_matrix_t *mtx, const int16_t *source, int64_t frames) ;
783 
799 AMBIX_API
800 uint32_t ambix_order2channels(uint32_t order) ;
801 
811 AMBIX_API
812 int32_t ambix_channels2order(uint32_t channels) ;
813 
822 AMBIX_API
823 int ambix_is_fullset(uint32_t channels) ;
824 
825 #ifdef __cplusplus
826 } /* extern "C" */
827 #endif /* __cplusplus */
828 #endif /* AMBIX_AMBIX_H */
float32_t
float float32_t
Definition: ambix.h:41
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_ERR_SUCCESS
@ AMBIX_ERR_SUCCESS
Definition: ambix.h:83
AMBIX_ERR_INVALID_HANDLE
@ AMBIX_ERR_INVALID_HANDLE
Definition: ambix.h:86
AMBIX_RDRW
@ AMBIX_RDRW
Definition: ambix.h:108
AMBIX_MATRIX_TO_SID
@ AMBIX_MATRIX_TO_SID
Definition: ambix.h:169
ambix_marker_t::position
float64_t position
Definition: ambix.h:233
AMBIX_ERR_UNKNOWN
@ AMBIX_ERR_UNKNOWN
Definition: ambix.h:80
ambix_info_t
struct ambix_info_t ambix_info_t
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_t
struct ambix_t_struct ambix_t
Definition: ambix.h:74
AMBIX_MATRIX_FUMA
@ AMBIX_MATRIX_FUMA
Definition: ambix.h:161
AMBIX_MATRIX_INVALID
@ AMBIX_MATRIX_INVALID
Definition: ambix.h:141
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_region_t
Definition: ambix.h:239
float64_t
double float64_t
Definition: ambix.h:44
ambix_info_t::samplerate
double samplerate
Definition: ambix.h:192
ambix_matrix_destroy
AMBIX_API void ambix_matrix_destroy(ambix_matrix_t *mtx)
Destroy a matrix.
AMBIX_MATRIX_TO_AMBIX
@ AMBIX_MATRIX_TO_AMBIX
Definition: ambix.h:164
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_ERR_INVALID_MATRIX
@ AMBIX_ERR_INVALID_MATRIX
Definition: ambix.h:97
ambix_is_fullset
AMBIX_API int ambix_is_fullset(uint32_t channels)
Checks whether the channel can form a full 3d ambisonics set.
ambix_filemode_t
ambix_filemode_t
Definition: ambix.h:102
AMBIX_BASIC
@ AMBIX_BASIC
Definition: ambix.h:117
ambix_info_t::fileformat
ambix_fileformat_t fileformat
Definition: ambix.h:209
ambix_get_marker
AMBIX_API ambix_marker_t * ambix_get_marker(ambix_t *ambix, uint32_t id)
Get one marker.
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_info_t::ambichannels
uint32_t ambichannels
Definition: ambix.h:227
AMBIX_SAMPLEFORMAT_PCM16
@ AMBIX_SAMPLEFORMAT_PCM16
Definition: ambix.h:127
ambix_get_adaptormatrix
const AMBIX_API ambix_matrix_t * ambix_get_adaptormatrix(ambix_t *ambix)
Get the adaptor matrix.
AMBIX_MATRIX_SID
@ AMBIX_MATRIX_SID
Definition: ambix.h:159
ambix_close
AMBIX_API ambix_err_t ambix_close(ambix_t *ambix)
Close an ambix handle.
ambix_region_t::name
char name[256]
Definition: ambix.h:245
AMBIX_MATRIX_TO_N3D
@ AMBIX_MATRIX_TO_N3D
Definition: ambix.h:167
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_SAMPLEFORMAT_NONE
@ AMBIX_SAMPLEFORMAT_NONE
Definition: ambix.h:125
ambix_region_t::end_position
float64_t end_position
Definition: ambix.h:243
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_seek
AMBIX_API int64_t ambix_seek(ambix_t *ambix, int64_t frames, int whence)
Reposition the file pointer.
AMBIX_NONE
@ AMBIX_NONE
Definition: ambix.h:115
ambix_matrix_t::cols
uint32_t cols
Definition: ambix.h:180
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_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.
number32_t::u
uint32_t u
Definition: ambix.h:70
ambix_matrix_t
struct ambix_matrix_t ambix_matrix_t
AMBIX_MATRIX_TO_FUMA
@ AMBIX_MATRIX_TO_FUMA
Definition: ambix.h:171
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_ZERO
@ AMBIX_MATRIX_ZERO
Definition: ambix.h:143
ambix_matrix_t::data
float32_t ** data
Definition: ambix.h:182
ambix_delete_markers
AMBIX_API ambix_err_t ambix_delete_markers(ambix_t *ambix)
Deletes all markers in the ambix file.
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_DEPRECATED
#define AMBIX_DEPRECATED
Definition: exportdefs.h:66
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_ERR_INVALID_DIMENSION
@ AMBIX_ERR_INVALID_DIMENSION
Definition: ambix.h:90
AMBIX_ERR_INVALID_FILE
@ AMBIX_ERR_INVALID_FILE
Definition: ambix.h:88
AMBIX_API
#define AMBIX_API
Definition: exportdefs.h:74
ambix_err_t
ambix_err_t
Definition: ambix.h:77
ambix_info_t
Definition: ambix.h:188
number32_t::i
int32_t i
Definition: ambix.h:68
ambix_marker_t
struct ambix_marker_t ambix_marker_t
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_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_matrix_t
Definition: ambix.h:176
AMBIX_MATRIX_AMBIX
@ AMBIX_MATRIX_AMBIX
Definition: ambix.h:155
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_matrix_deinit
AMBIX_API void ambix_matrix_deinit(ambix_matrix_t *mtx)
De-initialize a matrix.
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_marker_t
Definition: ambix.h:231
AMBIX_ERR_INVALID_FORMAT
@ AMBIX_ERR_INVALID_FORMAT
Definition: ambix.h:94
ambix_matrixtype_t
ambix_matrixtype_t
Definition: ambix.h:139
ambix_delete_regions
AMBIX_API ambix_err_t ambix_delete_regions(ambix_t *ambix)
Deletes all regions in the ambix file.
ambix_info_t::sampleformat
ambix_sampleformat_t sampleformat
Definition: ambix.h:194
ambix_open
AMBIX_API ambix_t * ambix_open(const char *path, const ambix_filemode_t mode, ambix_info_t *ambixinfo)
Open an ambix file.
number32_t::f
float32_t f
Definition: ambix.h:66
AMBIX_EXTENDED
@ AMBIX_EXTENDED
Definition: ambix.h:119
ambix_info_t::extrachannels
uint32_t extrachannels
Definition: ambix.h:214
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_fileformat_t
ambix_fileformat_t
Definition: ambix.h:113
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_READ
@ AMBIX_READ
Definition: ambix.h:104
exportdefs.h
export definitions for various compilers
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_sampleformat_t
ambix_sampleformat_t
Definition: ambix.h:123
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_MATRIX_N3D
@ AMBIX_MATRIX_N3D
Definition: ambix.h:157
ambix_matrix_t::rows
uint32_t rows
Definition: ambix.h:178
AMBIX_SAMPLEFORMAT_FLOAT64
@ AMBIX_SAMPLEFORMAT_FLOAT64
Definition: ambix.h:135
AMBIX_MATRIX_IDENTITY
@ AMBIX_MATRIX_IDENTITY
Definition: ambix.h:147
AMBIX_SAMPLEFORMAT_PCM32
@ AMBIX_SAMPLEFORMAT_PCM32
Definition: ambix.h:131
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_info_t::frames
uint64_t frames
Definition: ambix.h:190
ambix_region_t::start_position
float64_t start_position
Definition: ambix.h:241
ambix_matrix_create
AMBIX_API ambix_matrix_t * ambix_matrix_create(void)
Create a matrix.
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_marker_t::name
char name[256]
Definition: ambix.h:235
AMBIX_MATRIX_ONE
@ AMBIX_MATRIX_ONE
Definition: ambix.h:145
AMBIX_SAMPLEFORMAT_PCM24
@ AMBIX_SAMPLEFORMAT_PCM24
Definition: ambix.h:129
number32_t
Definition: ambix.h:64
ambix_get_region
AMBIX_API ambix_region_t * ambix_get_region(ambix_t *ambix, uint32_t id)
Get one region.
ambix_region_t
struct ambix_region_t ambix_region_t
ambix_get_sndfile
AMBIX_API struct SNDFILE_tag * ambix_get_sndfile(ambix_t *ambix)
Get the libsndfile handle associated with the ambix handle.
AMBIX_SAMPLEFORMAT_FLOAT32
@ AMBIX_SAMPLEFORMAT_FLOAT32
Definition: ambix.h:133
AMBIX_WRITE
@ AMBIX_WRITE
Definition: ambix.h:106
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.