From 6ba2f1cee97928ae75b94e8f32407249766a4403 Mon Sep 17 00:00:00 2001 From: Paul Brossier Date: Sun, 23 Jul 2006 10:14:39 +0000 Subject: [PATCH] add documentation for fvec_t and cvec_t add documentation for fvec_t and cvec_t --- src/sample.h | 240 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 207 insertions(+), 33 deletions(-) diff --git a/src/sample.h b/src/sample.h index e0970afb..6776d93a 100644 --- a/src/sample.h +++ b/src/sample.h @@ -24,65 +24,239 @@ extern "C" { #endif -/** @file - * Sample buffers - * - * Create fvec_t and cvec_t buffers - */ - -/** - * Sample buffer type - * - * contains length and channels number - */ +/** \file + + Real and complex buffers + + This file specifies fvec_t and cvec_t buffers types, which are used + throughout aubio to store real and complex data. Complex values are stored in + terms of phase and norm. + +*/ + +/** Sample buffer type */ typedef struct _fvec_t fvec_t; -/** - * Spectrum buffer type - * - * contains length and channels number - */ +/** Spectrum buffer type */ typedef struct _cvec_t cvec_t; - -/** - * Buffer for audio samples - */ +/** Buffer for real values */ struct _fvec_t { - uint_t length; - uint_t channels; - smpl_t **data; + uint_t length; /**< length of buffer */ + uint_t channels; /**< number of channels */ + smpl_t **data; /**< data array of size [length] * [channels] */ }; - -/** - * Buffer for spectral data - */ +/** Buffer for complex data */ struct _cvec_t { - uint_t length; - uint_t channels; - smpl_t **norm; - smpl_t **phas; + uint_t length; /**< length of buffer = (requested length)/2 + 1 */ + uint_t channels; /**< number of channels */ + smpl_t **norm; /**< norm array of size [length] * [channels] */ + smpl_t **phas; /**< phase array of size [length] * [channels] */ }; +/** fvec_t buffer creation function + \param length the length of the buffer to create + \param channels the number of channels in the buffer -/* buffer function */ +*/ extern fvec_t * new_fvec(uint_t length, uint_t channels); +/** fvec_t buffer deletion function + + \param s buffer to delete as returned by new_fvec() + +*/ extern void del_fvec(fvec_t *s); +/** read sample value in a buffer + + Note that this function is not used in the aubio library, since the same + result can be obtained using vec->data[channel][position]. Its purpose is to + access these values from wrappers, as created by swig. + + \param s vector to read from + \param channel channel to read from + \param position sample position to read from + +*/ smpl_t fvec_read_sample(fvec_t *s, uint_t channel, uint_t position); +/** write sample value in a buffer + + Note that this function is not used in the aubio library, since the same + result can be obtained by assigning vec->data[channel][position]. Its purpose + is to access these values from wrappers, as created by swig. + + \param s vector to write to + \param data value to write in s->data[channel][position] + \param channel channel to write to + \param position sample position to write to + +*/ void fvec_write_sample(fvec_t *s, smpl_t data, uint_t channel, uint_t position); +/** read channel vector from a buffer + + Note that this function is not used in the aubio library, since the same + result can be obtained with vec->data[channel]. Its purpose is to access + these values from wrappers, as created by swig. + + \param s vector to read from + \param channel channel to read from + +*/ smpl_t * fvec_get_channel(fvec_t *s, uint_t channel); -smpl_t ** fvec_get_data(fvec_t *s); +/** write channel vector into a buffer + + Note that this function is not used in the aubio library, since the same + result can be obtained by assigning vec->data[channel]. Its purpose is to + access these values from wrappers, as created by swig. + + \param s vector to write to + \param data vector of [length] values to write + \param channel channel to write to + +*/ void fvec_put_channel(fvec_t *s, smpl_t * data, uint_t channel); +/** read data from a buffer + + Note that this function is not used in the aubio library, since the same + result can be obtained with vec->data. Its purpose is to access these values + from wrappers, as created by swig. + + \param s vector to read from +*/ +smpl_t ** fvec_get_data(fvec_t *s); + +/** cvec_t buffer creation function + + This function creates a cvec_t structure holding two arrays of size + [length/2+1] * channels, corresponding to the norm and phase values of the + spectral frame. The length stored in the structure is the actual size of both + arrays, not the length of the complex and symetrical vector, specified as + creation argument. + + \param length the length of the buffer to create + \param channels the number of channels in the buffer + +*/ extern cvec_t * new_cvec(uint_t length, uint_t channels); +/** cvec_t buffer deletion function + + \param s buffer to delete as returned by new_cvec() + +*/ extern void del_cvec(cvec_t *s); +/** write norm value in a complex buffer + + Note that this function is not used in the aubio library, since the same + result can be obtained by assigning vec->norm[channel][position]. Its purpose + is to access these values from wrappers, as created by swig. + + \param s vector to write to + \param data norm value to write in s->norm[channel][position] + \param channel channel to write to + \param position sample position to write to + +*/ void cvec_write_norm(cvec_t *s, smpl_t data, uint_t channel, uint_t position); +/** write phase value in a complex buffer + + Note that this function is not used in the aubio library, since the same + result can be obtained by assigning vec->phas[channel][position]. Its purpose + is to access these values from wrappers, as created by swig. + + \param s vector to write to + \param data phase value to write in s->phas[channel][position] + \param channel channel to write to + \param position sample position to write to + +*/ void cvec_write_phas(cvec_t *s, smpl_t data, uint_t channel, uint_t position); +/** read norm value from a complex buffer + + Note that this function is not used in the aubio library, since the same + result can be obtained with vec->norm[channel][position]. Its purpose is to + access these values from wrappers, as created by swig. + + \param s vector to read from + \param channel channel to read from + \param position sample position to read from + +*/ smpl_t cvec_read_norm(cvec_t *s, uint_t channel, uint_t position); +/** read phase value from a complex buffer + + Note that this function is not used in the aubio library, since the same + result can be obtained with vec->phas[channel][position]. Its purpose is to + access these values from wrappers, as created by swig. + + \param s vector to read from + \param channel channel to read from + \param position sample position to read from + +*/ smpl_t cvec_read_phas(cvec_t *s, uint_t channel, uint_t position); +/** write norm channel in a complex buffer + + Note that this function is not used in the aubio library, since the same + result can be obtained by assigning vec->norm[channel]. Its purpose is to + access these values from wrappers, as created by swig. + + \param s vector to write to + \param data norm vector of [length] samples to write in s->norm[channel] + \param channel channel to write to + +*/ void cvec_put_norm_channel(cvec_t *s, smpl_t * data, uint_t channel); +/** write phase channel in a complex buffer + + Note that this function is not used in the aubio library, since the same + result can be obtained by assigning vec->phas[channel]. Its purpose is to + access these values from wrappers, as created by swig. + + \param s vector to write to + \param data phase vector of [length] samples to write in s->phas[channel] + \param channel channel to write to + +*/ void cvec_put_phas_channel(cvec_t *s, smpl_t * data, uint_t channel); +/** read norm channel from a complex buffer + + Note that this function is not used in the aubio library, since the same + result can be obtained with vec->norm[channel]. Its purpose is to access + these values from wrappers, as created by swig. + + \param s vector to read from + \param channel channel to read from + +*/ smpl_t * cvec_get_norm_channel(cvec_t *s, uint_t channel); +/** write phase channel in a complex buffer + + Note that this function is not used in the aubio library, since the same + result can be obtained with vec->phas[channel]. Its purpose is to access + these values from wrappers, as created by swig. + + \param s vector to read from + \param channel channel to read from + +*/ smpl_t * cvec_get_phas_channel(cvec_t *s, uint_t channel); +/** read norm data from a complex buffer + + Note that this function is not used in the aubio library, since the same + result can be obtained with vec->norm. Its purpose is to access these values + from wrappers, as created by swig. + + \param s vector to read from + +*/ smpl_t ** cvec_get_norm(cvec_t *s); +/** read phase data from a complex buffer + + Note that this function is not used in the aubio library, since the same + result can be obtained with vec->phas. Its purpose is to access these values + from wrappers, as created by swig. + + \param s vector to read from + +*/ smpl_t ** cvec_get_phas(cvec_t *s); #ifdef __cplusplus -- 2.26.2