src/cvec.h

   1 /*
   2   Copyright (C) 2003-2009 Paul Brossier <piem@aubio.org>
   3
   4   This file is part of aubio.
   5
   6   aubio is free software: you can redistribute it and/or modify
   7   it under the terms of the GNU General Public License as published by
   8   the Free Software Foundation, either version 3 of the License, or
   9   (at your option) any later version.
  10
  11   aubio is distributed in the hope that it will be useful,
  12   but WITHOUT ANY WARRANTY; without even the implied warranty of
  13   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14   GNU General Public License for more details.
  15
  16   You should have received a copy of the GNU General Public License
  17   along with aubio.  If not, see <http://www.gnu.org/licenses/>.
  18
  19 */
  20
  21 #ifndef _CVEC_H
  22 #define _CVEC_H
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /** \file
  29
  30   Vector of complex-valued data
  31
  32   This file specifies the ::cvec_t buffer type, which is used throughout aubio
  33   to store complex data. Complex values are stored in terms of ::cvec_t.phas
  34   and norm, within size/2+1 long vectors of ::smpl_t.
  35
  36   \example test-cvec.c
  37
  38 */
  39
  40 /** Buffer for complex data
  41
  42   \code
  43
  44   uint_t buffer_size = 1024;
  45
  46   // create a complex vector of 512 values
  47   cvec_t * input = new_cvec (buffer_size);
  48
  49   // set some values of the vector
  50   input->norm[23] = 2.;
  51   input->phas[23] = M_PI;
  52   // ..
  53
  54   // compute the mean of the vector
  55   mean = cvec_mean(input);
  56
  57   // destroy the vector
  58   del_cvec (input);
  59
  60   \endcode
  61
  62  */
  63 typedef struct {
  64   uint_t length;  /**< length of buffer = (requested length)/2 + 1 */
  65   smpl_t *norm;   /**< norm array of size ::cvec_t.length */
  66   smpl_t *phas;   /**< phase array of size ::cvec_t.length */
  67 } cvec_t;
  68
  69 /** cvec_t buffer creation function
  70
  71   This function creates a cvec_t structure holding two arrays of size
  72   [length/2+1], corresponding to the norm and phase values of the
  73   spectral frame. The length stored in the structure is the actual size of both
  74   arrays, not the length of the complex and symmetrical vector, specified as
  75   creation argument.
  76
  77   \param length the length of the buffer to create
  78
  79 */
  80 cvec_t * new_cvec(uint_t length);
  81 /** cvec_t buffer deletion function
  82
  83   \param s buffer to delete as returned by new_cvec()
  84
  85 */
  86 void del_cvec(cvec_t *s);
  87 /** write norm value in a complex buffer
  88
  89   Note that this function is not used in the aubio library, since the same
  90   result can be obtained by assigning vec->norm[position]. Its purpose
  91   is to access these values from wrappers, as created by swig.
  92
  93   \param s vector to write to
  94   \param data norm value to write in s->norm[position]
  95   \param position sample position to write to
  96
  97 */
  98 void cvec_write_norm(cvec_t *s, smpl_t data, uint_t position);
  99 /** write phase value in a complex buffer
 100
 101   Note that this function is not used in the aubio library, since the same
 102   result can be obtained by assigning vec->phas[position]. Its purpose
 103   is to access these values from wrappers, as created by swig.
 104
 105   \param s vector to write to
 106   \param data phase value to write in s->phas[position]
 107   \param position sample position to write to
 108
 109 */
 110 void cvec_write_phas(cvec_t *s, smpl_t data, uint_t position);
 111 /** read norm value from a complex buffer
 112
 113   Note that this function is not used in the aubio library, since the same
 114   result can be obtained with vec->norm[position]. Its purpose is to
 115   access these values from wrappers, as created by swig.
 116
 117   \param s vector to read from
 118   \param position sample position to read from
 119
 120 */
 121 smpl_t cvec_read_norm(cvec_t *s, uint_t position);
 122 /** read phase value from a complex buffer
 123
 124   Note that this function is not used in the aubio library, since the same
 125   result can be obtained with vec->phas[position]. Its purpose is to
 126   access these values from wrappers, as created by swig.
 127
 128   \param s vector to read from
 129   \param position sample position to read from
 130
 131 */
 132 smpl_t cvec_read_phas(cvec_t *s, uint_t position);
 133 /** read norm data from a complex buffer
 134
 135   Note that this function is not used in the aubio library, since the same
 136   result can be obtained with vec->norm. Its purpose is to access these values
 137   from wrappers, as created by swig.
 138
 139   \param s vector to read from
 140
 141 */
 142 smpl_t * cvec_get_norm(cvec_t *s);
 143 /** read phase data from a complex buffer
 144
 145   Note that this function is not used in the aubio library, since the same
 146   result can be obtained with vec->phas. Its purpose is to access these values
 147   from wrappers, as created by swig.
 148
 149   \param s vector to read from
 150
 151 */
 152 smpl_t * cvec_get_phas(cvec_t *s);
 153
 154 /** print out cvec data
 155
 156   \param s vector to print out
 157
 158 */
 159 void cvec_print(cvec_t *s);
 160
 161 /** set all elements to a given value
 162
 163   \param s vector to modify
 164   \param val value to set elements to
 165
 166 */
 167 void cvec_set(cvec_t *s, smpl_t val);
 168
 169 /** set all elements to zero
 170
 171   \param s vector to modify
 172
 173 */
 174 void cvec_zeros(cvec_t *s);
 175
 176 /** set all elements to ones
 177
 178   \param s vector to modify
 179
 180 */
 181 void cvec_ones(cvec_t *s);
 182
 183 #ifdef __cplusplus
 184 }
 185 #endif
 186
 187 #endif /* _CVEC_H */
 188