Changeset 6ba2f1c

Timestamp:

Jul 23, 2006, 12:14:39 PM (18 years ago)

Author:

Paul Brossier <piem@altern.org>

Branches:

feature/autosink, feature/cnn, feature/cnn_org, feature/constantq, feature/crepe, feature/crepe_org, feature/pitchshift, feature/pydocstrings, feature/timestretch, fix/ffmpeg5, master, pitchshift, sampler, timestretch, yinfft+

Children:

a89438a

Parents:

989bf7f

Message:

add documentation for fvec_t and cvec_t
add documentation for fvec_t and cvec_t

File:

• src/sample.h (modified) (1 diff)

src/sample.h

@@ -25 +25 @@
 #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] */
 };
-
-
-/* buffer function */
+/** fvec_t buffer creation function
+
+  \param length the length of the buffer to create
+  \param channels the number of channels in the buffer
+
+*/
 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);
+/** 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);
-void fvec_put_channel(fvec_t *s, smpl_t * data, uint_t channel);
-
+
+/** 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);