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 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 {
119  AMBIX_EXTENDED = 2
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;
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 */
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:123
@ AMBIX_SAMPLEFORMAT_PCM32
Definition: ambix.h:131
@ AMBIX_SAMPLEFORMAT_FLOAT32
Definition: ambix.h:133
@ AMBIX_SAMPLEFORMAT_FLOAT64
Definition: ambix.h:135
@ AMBIX_SAMPLEFORMAT_PCM24
Definition: ambix.h:129
@ AMBIX_SAMPLEFORMAT_NONE
Definition: ambix.h:125
@ AMBIX_SAMPLEFORMAT_PCM16
Definition: ambix.h:127
float float32_t
Definition: ambix.h:41
ambix_matrixtype_t
Definition: ambix.h:139
@ AMBIX_MATRIX_SID
Definition: ambix.h:159
@ AMBIX_MATRIX_TO_N3D
Definition: ambix.h:167
@ AMBIX_MATRIX_N3D
Definition: ambix.h:157
@ AMBIX_MATRIX_ZERO
Definition: ambix.h:143
@ AMBIX_MATRIX_IDENTITY
Definition: ambix.h:147
@ AMBIX_MATRIX_TO_FUMA
Definition: ambix.h:171
@ AMBIX_MATRIX_AMBIX
Definition: ambix.h:155
@ AMBIX_MATRIX_FUMA
Definition: ambix.h:161
@ AMBIX_MATRIX_INVALID
Definition: ambix.h:141
@ AMBIX_MATRIX_TO_AMBIX
Definition: ambix.h:164
@ AMBIX_MATRIX_ONE
Definition: ambix.h:145
@ AMBIX_MATRIX_TO_SID
Definition: ambix.h:169
ambix_fileformat_t
Definition: ambix.h:113
@ AMBIX_NONE
Definition: ambix.h:115
@ AMBIX_BASIC
Definition: ambix.h:117
@ AMBIX_EXTENDED
Definition: ambix.h:119
struct ambix_marker_t ambix_marker_t
ambix_filemode_t
Definition: ambix.h:102
@ AMBIX_RDRW
Definition: ambix.h:108
@ AMBIX_READ
Definition: ambix.h:104
@ AMBIX_WRITE
Definition: ambix.h:106
double float64_t
Definition: ambix.h:44
ambix_err_t
Definition: ambix.h:78
@ AMBIX_ERR_INVALID_HANDLE
Definition: ambix.h:86
@ AMBIX_ERR_UNKNOWN
Definition: ambix.h:80
@ AMBIX_ERR_INVALID_FORMAT
Definition: ambix.h:94
@ AMBIX_ERR_INVALID_DIMENSION
Definition: ambix.h:90
@ AMBIX_ERR_INVALID_FILE
Definition: ambix.h:88
@ AMBIX_ERR_SUCCESS
Definition: ambix.h:83
@ AMBIX_ERR_INVALID_MATRIX
Definition: ambix.h:97
struct ambix_t_struct ambix_t
Definition: ambix.h:74
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 struct SNDFILE_tag * ambix_get_sndfile(ambix_t *ambix)
Get the libsndfile handle associated with the ambix handle.
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 ambix_err_t ambix_add_region(ambix_t *ambix, ambix_region_t *region)
Add a new region to the ambix file.
Definition: ambix.h:188
ambix_fileformat_t fileformat
Definition: ambix.h:209
double samplerate
Definition: ambix.h:192
uint64_t frames
Definition: ambix.h:190
uint32_t ambichannels
Definition: ambix.h:227
uint32_t extrachannels
Definition: ambix.h:214
ambix_sampleformat_t sampleformat
Definition: ambix.h:194
Definition: ambix.h:231
char name[256]
Definition: ambix.h:235
float64_t position
Definition: ambix.h:233
Definition: ambix.h:176
float32_t ** data
Definition: ambix.h:182
uint32_t cols
Definition: ambix.h:180
uint32_t rows
Definition: ambix.h:178
Definition: ambix.h:239
char name[256]
Definition: ambix.h:245
float64_t start_position
Definition: ambix.h:241
float64_t end_position
Definition: ambix.h:243
Definition: ambix.h:64
uint32_t u
Definition: ambix.h:70
int32_t i
Definition: ambix.h:68
float32_t f
Definition: ambix.h:66