src/cvec.h

   1 /*
   2   Copyright (C) 2003-2015 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 AUBIO_CVEC_H
  22 #define AUBIO_CVEC_H
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /** \file
  29
  30   Vector of complex-valued data, stored in polar coordinates
  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 2 vectors of ::smpl_t of size (size/2+1) each.
  35
  36   \example test-cvec.c
  37
  38 */
  39
  40 /** Vector of real-valued phase and spectrum 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
  82 /** cvec_t buffer deletion function
  83
  84   \param s buffer to delete as returned by new_cvec()
  85
  86 */
  87 void del_cvec(cvec_t *s);
  88
  89 /** write norm value in a complex buffer
  90
  91   This is equivalent to:
  92   \code
  93   s->norm[position] = val;
  94   \endcode
  95
  96   \param s vector to write to
  97   \param val norm value to write in s->norm[position]
  98   \param position sample position to write to
  99
 100 */
 101 void cvec_norm_set_sample (cvec_t *s, smpl_t val, uint_t position);
 102
 103 /** write phase value in a complex buffer
 104
 105   This is equivalent to:
 106   \code
 107   s->phas[position] = val;
 108   \endcode
 109
 110   \param s vector to write to
 111   \param val phase value to write in s->phas[position]
 112   \param position sample position to write to
 113
 114 */
 115 void cvec_phas_set_sample (cvec_t *s, smpl_t val, uint_t position);
 116
 117 /** read norm value from a complex buffer
 118
 119   This is equivalent to:
 120   \code
 121   smpl_t foo = s->norm[position];
 122   \endcode
 123
 124   \param s vector to read from
 125   \param position sample position to read from
 126
 127 */
 128 smpl_t cvec_norm_get_sample (cvec_t *s, uint_t position);
 129
 130 /** read phase value from a complex buffer
 131
 132   This is equivalent to:
 133   \code
 134   smpl_t foo = s->phas[position];
 135   \endcode
 136
 137   \param s vector to read from
 138   \param position sample position to read from
 139   \returns the value of the sample at position
 140
 141 */
 142 smpl_t cvec_phas_get_sample (cvec_t *s, uint_t position);
 143
 144 /** read norm data from a complex buffer
 145
 146   \code
 147   smpl_t *data = s->norm;
 148   \endcode
 149
 150   \param s vector to read from
 151
 152 */
 153 smpl_t * cvec_norm_get_data (const cvec_t *s);
 154
 155 /** read phase data from a complex buffer
 156
 157   This is equivalent to:
 158   \code
 159   smpl_t *data = s->phas;
 160   \endcode
 161
 162   \param s vector to read from
 163
 164 */
 165 smpl_t * cvec_phas_get_data (const cvec_t *s);
 166
 167 /** print out cvec data
 168
 169   \param s vector to print out
 170
 171 */
 172 void cvec_print(const cvec_t *s);
 173
 174 /** make a copy of a vector
 175
 176   \param s source vector
 177   \param t vector to copy to
 178
 179 */
 180 void cvec_copy(const cvec_t *s, cvec_t *t);
 181
 182 /** set all norm elements to a given value
 183
 184   \param s vector to modify
 185   \param val value to set elements to
 186
 187 */
 188 void cvec_norm_set_all (cvec_t *s, smpl_t val);
 189
 190 /** set all norm elements to zero
 191
 192   \param s vector to modify
 193
 194 */
 195 void cvec_norm_zeros(cvec_t *s);
 196
 197 /** set all norm elements to one
 198
 199   \param s vector to modify
 200
 201 */
 202 void cvec_norm_ones(cvec_t *s);
 203
 204 /** set all phase elements to a given value
 205
 206   \param s vector to modify
 207   \param val value to set elements to
 208
 209 */
 210 void cvec_phas_set_all (cvec_t *s, smpl_t val);
 211
 212 /** set all phase elements to zero
 213
 214   \param s vector to modify
 215
 216 */
 217 void cvec_phas_zeros(cvec_t *s);
 218
 219 /** set all phase elements to one
 220
 221   \param s vector to modify
 222
 223 */
 224 void cvec_phas_ones(cvec_t *s);
 225
 226 /** set all norm and phas elements to zero
 227
 228   \param s vector to modify
 229
 230 */
 231 void cvec_zeros(cvec_t *s);
 232
 233 #ifdef __cplusplus
 234 }
 235 #endif
 236
 237 #endif /* AUBIO_CVEC_H */