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

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) ;
struct SNDFILE_tag;

AMBIX_API
struct SNDFILE_tag *ambix_get_sndfile (ambix_t *ambix) ;
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 */
#endif /* AMBIX_AMBIX_H */