ambix.h File Reference

AMBIsonics eXchange Library Interface. More...

`#include "exportdefs.h"`
`#include <stdint.h>`

Go to the source code of this file.

## Classes

union | number32_t
struct | ambix_matrix_t
struct | ambix_info_t
struct | ambix_marker_t
struct | ambix_region_t

## Typedefs

typedef float | float32_t
typedef double | float64_t
typedef struct ambix_t_struct | ambix_t
typedef struct ambix_matrix_t | ambix_matrix_t
typedef struct ambix_info_t | ambix_info_t
typedef struct ambix_marker_t | ambix_marker_t
typedef struct ambix_region_t | ambix_region_t

## Enumerations

enum | ambix_err_t { 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 }
enum | ambix_filemode_t { AMBIX_READ = (1 << 4) , AMBIX_WRITE = (1 << 5) , AMBIX_RDRW = (AMBIX_READ|AMBIX_WRITE) }
enum | ambix_fileformat_t { AMBIX_NONE = 0 , AMBIX_BASIC = 1 , AMBIX_EXTENDED = 2 }
enum | ambix_sampleformat_t { AMBIX_SAMPLEFORMAT_NONE =0 , AMBIX_SAMPLEFORMAT_PCM16 , AMBIX_SAMPLEFORMAT_PCM24 , AMBIX_SAMPLEFORMAT_PCM32 , AMBIX_SAMPLEFORMAT_FLOAT32 , AMBIX_SAMPLEFORMAT_FLOAT64 }

enum

ambix_matrixtype_t {
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
}

## Functions

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_close (ambix_t *ambix)
| Close an ambix handle.
AMBIX_API int64_t | ambix_seek (ambix_t *ambix, int64_t frames, int whence)
| Reposition the file pointer.
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 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_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_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_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_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_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 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 SNDFILE * | ambix_get_sndfile (ambix_t *ambix)
| Get the libsndfile handle associated with the ambix handle.
AMBIX_API uint32_t | ambix_get_num_markers (ambix_t *ambix)
| Get the number of stored markers within 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_marker_t * | ambix_get_marker (ambix_t *ambix, uint32_t id)
| Get one marker.
AMBIX_API ambix_region_t * | ambix_get_region (ambix_t *ambix, uint32_t id)
| Get one region.
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 ambix_err_t | ambix_add_region (ambix_t *ambix, ambix_region_t *region)
| Add a new region 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_err_t | ambix_delete_regions (ambix_t *ambix)
| Deletes all regions in the ambix file.
AMBIX_API const ambix_matrix_t * | ambix_get_adaptormatrix (ambix_t *ambix)
| Get the adaptor matrix.
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_matrix_t * | ambix_matrix_create (void)
| Create a matrix.
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 void | ambix_matrix_deinit (ambix_matrix_t *mtx)
| De-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_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_copy (const ambix_matrix_t *src, ambix_matrix_t *dest)
| Copy a matrix to another matrix.
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_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 uint32_t | ambix_order2channels (uint32_t order)
| Calculate the number of channels for a full 3d ambisonics set of a given order.
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 int | ambix_is_fullset (uint32_t channels)
| Checks whether the channel can form a full 3d ambisonics set.

## Detailed Description

AMBIsonics eXchange Library Interface.

This file is part of libambix

Author
  IOhannes m zmölnig zmoel.nosp@m.nig@.nosp@m.iem.a.nosp@m.t

Date
  2012

Copyright
  LGPL-2.1

## Typedef Documentation

## ambix_info_t

typedef struct ambix_info_t ambix_info_t

this is for passing data about the opened ambix file between the host application and the library

## ambix_marker_t

typedef struct ambix_marker_t ambix_marker_t

struct for holding a marker

## ambix_matrix_t

typedef struct ambix_matrix_t ambix_matrix_t

a 2-dimensional floating point matrix

## ambix_region_t

typedef struct ambix_region_t ambix_region_t

struct for holding a region

## ambix_t

typedef struct ambix_t_struct ambix_t

opaque handle to an ambix file

## float32_t

typedef float float32_t

32bit floating point number

## float64_t

typedef double float64_t

64bit floating point number

## Enumeration Type Documentation

## ambix_err_t

enum ambix_err_t

error codes returned by functions

Enumerator
AMBIX_ERR_UNKNOWN | an unknown error
AMBIX_ERR_SUCCESS | no error encountered
AMBIX_ERR_INVALID_HANDLE | an invalid ambix handle was passed to the function
AMBIX_ERR_INVALID_FILE | the file in question is invalid (e.g. doesn't contain audio)
AMBIX_ERR_INVALID_DIMENSION | matrix dimension mismatch
AMBIX_ERR_INVALID_FORMAT | the ambix handle is in a format that does not allow the function (e.g. setting a premultiply matrix for a format other than AMBIX_BASIC)
AMBIX_ERR_INVALID_MATRIX | you specified an invalid matrix

## ambix_fileformat_t

enum ambix_fileformat_t

ambix file types

Enumerator
AMBIX_NONE | file is not an ambix file (or unknown)
AMBIX_BASIC | basic ambix file (w/ pre-multiplication matrix)
AMBIX_EXTENDED | extended ambix file (w pre-multiplication matrix )

## ambix_filemode_t

enum ambix_filemode_t

error codes returned by functions

Enumerator
AMBIX_READ | open file for reading
AMBIX_WRITE | open file for writing
AMBIX_RDRW | open file for reading&writing

## ambix_matrixtype_t

enum ambix_matrixtype_t

ambix matrix types

Enumerator
AMBIX_MATRIX_INVALID | invalid matrix format
AMBIX_MATRIX_ZERO | a matrix filled with zeros
AMBIX_MATRIX_ONE | a matrix filled with ones
AMBIX_MATRIX_IDENTITY | an identity matrix (diagonal is 1, rest is 0)

AMBIX_MATRIX_AMBIX

matrices with the 0x8000 bit set convert between ambix and other ambisonics formats: if the 0x4000 bit is set to 0, the matrix converts to ambix, if the 0x4000 bit is set to 1, the matrix converts from ambix.

Remarks
  some of the following matrixes might not be implemented yet
  AMBIX_MATRIX_AMBIX converts from ambix to ambix (and is quite useless by itself)

AMBIX_MATRIX_N3D | conversion matrix N3D -> SN3D
AMBIX_MATRIX_SID | conversion matrix SID -> ACN
AMBIX_MATRIX_FUMA | conversion matrix Furse-Malham -> ambix
AMBIX_MATRIX_TO_AMBIX | back conversion matrix ambix -> ambix
AMBIX_MATRIX_TO_N3D | conversion matrix SN3D -> N3D
AMBIX_MATRIX_TO_SID | conversion matrix ACN -> SID
AMBIX_MATRIX_TO_FUMA | conversion matrix ambix -> Furse-Malham

## ambix_sampleformat_t

enum ambix_sampleformat_t

ambix sample formats

Enumerator
AMBIX_SAMPLEFORMAT_NONE | unknown (or illegal) sample formats
AMBIX_SAMPLEFORMAT_PCM16 | signed 16 bit integer
AMBIX_SAMPLEFORMAT_PCM24 | signed 24 bit integer
AMBIX_SAMPLEFORMAT_PCM32 | signed 32 bit integer
AMBIX_SAMPLEFORMAT_FLOAT32 | 32 bit floating point
AMBIX_SAMPLEFORMAT_FLOAT64 | 64 bit floating point