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 /** make a copy of a vector
 162
 163   \param s source vector
 164   \param t vector to copy to
 165
 166 */
 167 void cvec_copy(cvec_t *s, cvec_t *t);
 168
 169 /** set all norm elements to a given value
 170
 171   \param s vector to modify
 172   \param val value to set elements to
 173
 174 */
 175 void cvec_set_all_norm(cvec_t *s, smpl_t val);
 176
 177 /** set all norm elements to zero
 178
 179   \param s vector to modify
 180
 181 */
 182 void cvec_zeros_norm(cvec_t *s);
 183
 184 /** set all norm elements to one
 185
 186   \param s vector to modify
 187
 188 */
 189 void cvec_ones_norm(cvec_t *s);
 190
 191 /** set all phase elements to a given value
 192
 193   \param s vector to modify
 194   \param val value to set elements to
 195
 196 */
 197 void cvec_set_all_phas(cvec_t *s, smpl_t val);
 198
 199 /** set all phase elements to zero
 200
 201   \param s vector to modify
 202
 203 */
 204 void cvec_zeros_phas(cvec_t *s);
 205
 206 /** set all phase elements to one
 207
 208   \param s vector to modify
 209
 210 */
 211 void cvec_ones_phas(cvec_t *s);
 212
 213 /** set all norm and phas elements to zero
 214
 215   \param s vector to modify
 216
 217 */
 218 void cvec_zeros(cvec_t *s);
 219
 220 #ifdef __cplusplus
 221 }
 222 #endif
 223
 224 #endif /* _CVEC_H */
 225