src/synth/{wavetable,sampler}.h: improve documentation
[aubio.git] / src / synth / wavetable.h
1 /*
2   Copyright (C) 2003-2013 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_SYNTH_WAVETABLE_H
22 #define _AUBIO_SYNTH_WAVETABLE_H
23
24 /** \file
25
26   Wavetable synthesis.
27
28   This file creates a wavetable and plays it at different frequency.
29
30   The `_do` function adds the new samples to the input, and write the result as
31   the output.
32
33   \example synth/test-wavetable.c
34
35 */
36
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40
41 /** wavetable object */
42 typedef struct _aubio_wavetable_t aubio_wavetable_t;
43
44 /** create new wavetable object
45
46   \param samplerate the sampling rate of the new wavetable
47   \param hop_size the block size of the new wavetable
48
49   \return the newly created aubio_wavetable_t
50
51 */
52 aubio_wavetable_t * new_aubio_wavetable(uint_t samplerate, uint_t hop_size);
53
54 /** load source in wavetable
55
56   \param o wavetable, created by new_aubio_wavetable()
57   \param uri the uri of the source to load
58
59   \return 0 if successful, non-zero otherwise
60
61 */
62 uint_t aubio_wavetable_load( aubio_wavetable_t * o, char_t * uri );
63
64 /** process wavetable function
65
66   \param o wavetable, created by new_aubio_wavetable()
67   \param input input of the wavetable, to be added to the output
68   \param output output of the wavetable
69
70 This function adds the new samples from the playing wavetable to the output.
71
72 If `input` is not NULL and different from `output`, then the samples from `input`
73 are added to the output.
74
75 */
76 void aubio_wavetable_do ( aubio_wavetable_t * o, fvec_t * input, fvec_t * output);
77
78 /** process wavetable function, multiple channels
79
80   \param o wavetable, created by new_aubio_wavetable()
81   \param input input of the wavetable, to be added to the output
82   \param output output of the wavetable
83
84 This function adds the new samples from the playing wavetable to the output.
85
86 If `input` is not NULL and different from `output`, then the samples from `input`
87 are added to the output.
88
89 */
90 void aubio_wavetable_do_multi ( aubio_wavetable_t * o, fmat_t * input, fmat_t * output);
91
92 /** get current playing state
93
94   \param o wavetable, created by new_aubio_wavetable()
95
96   \return 0 if not playing, 1 if playing
97
98 */
99 uint_t aubio_wavetable_get_playing ( aubio_wavetable_t * o );
100
101 /** set current playing state
102
103   \param o wavetable, created by new_aubio_wavetable()
104   \param playing 0 for not playing, 1 for playing
105
106   \return 0 if successful, 1 otherwise
107
108 */
109 uint_t aubio_wavetable_set_playing ( aubio_wavetable_t * o, uint_t playing );
110
111 /** play sample from start
112
113   \param o wavetable, created by new_aubio_wavetable()
114
115   \return 0 if successful, 1 otherwise
116
117 */
118 uint_t aubio_wavetable_play ( aubio_wavetable_t * o );
119
120 /** stop wavetable
121
122   \param o wavetable, created by new_aubio_wavetable()
123
124   \return 0 if successful, 1 otherwise
125
126 */
127 uint_t aubio_wavetable_stop ( aubio_wavetable_t * o );
128
129 /** set wavetable frequency
130
131   \param o wavetable, created by new_aubio_wavetable()
132   \param freq new frequency value for the wavetable
133
134   \return 0 if successful, 1 otherwise
135
136 */
137 uint_t aubio_wavetable_set_freq ( aubio_wavetable_t * o, smpl_t freq );
138
139 /** get wavetable frequency
140
141   \param o wavetable, created by new_aubio_wavetable()
142
143   \return current frequency, in Hz
144
145 */
146 smpl_t aubio_wavetable_get_freq ( aubio_wavetable_t * o);
147
148 /** set wavetable amplitude
149
150   \param o wavetable, created by new_aubio_wavetable()
151   \param amp new amplitude value for the wavetable
152
153   \return 0 if successful, 1 otherwise
154
155 */
156 uint_t aubio_wavetable_set_amp ( aubio_wavetable_t * o, smpl_t amp );
157
158 /** get wavetable amplitude
159
160   \param o wavetable, created by new_aubio_wavetable()
161
162   \return current amplitude
163
164 */
165 smpl_t aubio_wavetable_get_amp ( aubio_wavetable_t * o);
166
167 /** destroy aubio_wavetable_t object
168
169   \param o wavetable, created by new_aubio_wavetable()
170
171 */
172 void del_aubio_wavetable( aubio_wavetable_t * o );
173
174 #ifdef __cplusplus
175 }
176 #endif
177
178 #endif /* _AUBIO_SYNTH_WAVETABLE_H */