aubio  0.4.1
cvec.h
Go to the documentation of this file.
00001 /*
00002   Copyright (C) 2003-2013 Paul Brossier <piem@aubio.org>
00003 
00004   This file is part of aubio.
00005 
00006   aubio is free software: you can redistribute it and/or modify
00007   it under the terms of the GNU General Public License as published by
00008   the Free Software Foundation, either version 3 of the License, or
00009   (at your option) any later version.
00010 
00011   aubio is distributed in the hope that it will be useful,
00012   but WITHOUT ANY WARRANTY; without even the implied warranty of
00013   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014   GNU General Public License for more details.
00015 
00016   You should have received a copy of the GNU General Public License
00017   along with aubio.  If not, see <http://www.gnu.org/licenses/>.
00018 
00019 */
00020 
00021 #ifndef _AUBIO__CVEC_H
00022 #define _AUBIO__CVEC_H
00023 
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00028 /** \file
00029 
00030   Vector of complex-valued data, stored in polar coordinates
00031 
00032   This file specifies the ::cvec_t buffer type, which is used throughout aubio
00033   to store complex data. Complex values are stored in terms of ::cvec_t.phas
00034   and norm, within 2 vectors of ::smpl_t of size (size/2+1) each.
00035 
00036   \example test-cvec.c
00037 
00038 */
00039 
00040 /** Vector of real-valued phase and spectrum data
00041 
00042   \code
00043 
00044   uint_t buffer_size = 1024;
00045 
00046   // create a complex vector of 512 values
00047   cvec_t * input = new_cvec (buffer_size);
00048 
00049   // set some values of the vector
00050   input->norm[23] = 2.;
00051   input->phas[23] = M_PI;
00052   // ..
00053 
00054   // compute the mean of the vector
00055   mean = cvec_mean(input);
00056 
00057   // destroy the vector
00058   del_cvec (input);
00059 
00060   \endcode
00061 
00062  */
00063 typedef struct {
00064   uint_t length;  /**< length of buffer = (requested length)/2 + 1 */
00065   smpl_t *norm;   /**< norm array of size ::cvec_t.length */
00066   smpl_t *phas;   /**< phase array of size ::cvec_t.length */
00067 } cvec_t;
00068 
00069 /** cvec_t buffer creation function
00070 
00071   This function creates a cvec_t structure holding two arrays of size
00072   [length/2+1], corresponding to the norm and phase values of the
00073   spectral frame. The length stored in the structure is the actual size of both
00074   arrays, not the length of the complex and symmetrical vector, specified as
00075   creation argument.
00076 
00077   \param length the length of the buffer to create
00078 
00079 */
00080 cvec_t * new_cvec(uint_t length);
00081 
00082 /** cvec_t buffer deletion function
00083 
00084   \param s buffer to delete as returned by new_cvec()
00085 
00086 */
00087 void del_cvec(cvec_t *s);
00088 
00089 /** write norm value in a complex buffer
00090 
00091   This is equivalent to:
00092   \code
00093   s->norm[position] = val;
00094   \endcode
00095 
00096   \param s vector to write to
00097   \param val norm value to write in s->norm[position]
00098   \param position sample position to write to
00099 
00100 */
00101 void cvec_norm_set_sample (cvec_t *s, smpl_t val, uint_t position);
00102 
00103 /** write phase value in a complex buffer
00104 
00105   This is equivalent to:
00106   \code
00107   s->phas[position] = val;
00108   \endcode
00109 
00110   \param s vector to write to
00111   \param val phase value to write in s->phas[position]
00112   \param position sample position to write to
00113 
00114 */
00115 void cvec_phas_set_sample (cvec_t *s, smpl_t val, uint_t position);
00116 
00117 /** read norm value from a complex buffer
00118 
00119   This is equivalent to:
00120   \code
00121   smpl_t foo = s->norm[position];
00122   \endcode
00123 
00124   \param s vector to read from
00125   \param position sample position to read from
00126 
00127 */
00128 smpl_t cvec_norm_get_sample (cvec_t *s, uint_t position);
00129 
00130 /** read phase value from a complex buffer
00131 
00132   This is equivalent to:
00133   \code
00134   smpl_t foo = s->phas[position];
00135   \endcode
00136 
00137   \param s vector to read from
00138   \param position sample position to read from
00139   \returns the value of the sample at position
00140 
00141 */
00142 smpl_t cvec_phas_get_sample (cvec_t *s, uint_t position);
00143 
00144 /** read norm data from a complex buffer
00145 
00146   \code
00147   smpl_t *data = s->norm;
00148   \endcode
00149 
00150   \param s vector to read from
00151 
00152 */
00153 smpl_t * cvec_norm_get_data (cvec_t *s);
00154 
00155 /** read phase data from a complex buffer
00156 
00157   This is equivalent to:
00158   \code
00159   smpl_t *data = s->phas;
00160   \endcode
00161 
00162   \param s vector to read from
00163 
00164 */
00165 smpl_t * cvec_phas_get_data (cvec_t *s);
00166 
00167 /** print out cvec data
00168 
00169   \param s vector to print out
00170 
00171 */
00172 void cvec_print(cvec_t *s);
00173 
00174 /** make a copy of a vector
00175 
00176   \param s source vector
00177   \param t vector to copy to
00178 
00179 */
00180 void cvec_copy(cvec_t *s, cvec_t *t);
00181 
00182 /** set all norm elements to a given value
00183 
00184   \param s vector to modify
00185   \param val value to set elements to
00186 
00187 */
00188 void cvec_norm_set_all (cvec_t *s, smpl_t val);
00189 
00190 /** set all norm elements to zero
00191 
00192   \param s vector to modify
00193 
00194 */
00195 void cvec_norm_zeros(cvec_t *s);
00196 
00197 /** set all norm elements to one
00198 
00199   \param s vector to modify
00200 
00201 */
00202 void cvec_norm_ones(cvec_t *s);
00203 
00204 /** set all phase elements to a given value
00205 
00206   \param s vector to modify
00207   \param val value to set elements to
00208 
00209 */
00210 void cvec_phas_set_all (cvec_t *s, smpl_t val);
00211 
00212 /** set all phase elements to zero
00213 
00214   \param s vector to modify
00215 
00216 */
00217 void cvec_phas_zeros(cvec_t *s);
00218 
00219 /** set all phase elements to one
00220 
00221   \param s vector to modify
00222 
00223 */
00224 void cvec_phas_ones(cvec_t *s);
00225 
00226 /** set all norm and phas elements to zero
00227 
00228   \param s vector to modify
00229 
00230 */
00231 void cvec_zeros(cvec_t *s);
00232 
00233 #ifdef __cplusplus
00234 }
00235 #endif
00236 
00237 #endif /* _AUBIO__CVEC_H */
 All Data Structures Files Functions Variables Typedefs Defines