 Mozzi  version v1.1.0 sound synthesis library for Arduino Line.h
1 /*
2  * Line.h
3  *
4  * Copyright 2012 Tim Barrass.
5  *
6  * This file is part of Mozzi.
7  *
9  *
10  */
11
12 #ifndef LINE_H_
13 #define LINE_H_
14
15 #if ARDUINO >= 100
16  #include "Arduino.h"
17 #else
18  #include "WProgram.h"
19 #endif
20
21 /** For linear changes with a minimum of calculation at each step. For instance,
22 you can use Line to make an oscillator glide from one frequency to another,
23 pre-calculating the required phase increments for each end and then letting your
24 Line change the phase increment with only a simple addition at each step.
25 @tparam T the type of numbers to use. For example, Line <int> myline; makes a
26 Line which uses ints.
27 @note Watch out for underflows in the internal calcualtion of Line() if you're not
28 using floats (but on the other hand try to avoid lots of floats, they're too slow!).
29 If it seems like the Line() is not working, there's a good chance you need to
30 scale up the numbers you're using, so internal calculations don't get truncated
31 away. Use Mozzi's fixed-point number types in mozzi_fixmath.h, which enable you to
32 represent fractional numbers. Google "fixed point arithmetic" if this is new to
33 you.
34 */
35
36 template <class T>
37 class Line
38 {
39 private:
40  volatile T current_value; // volatile because it could be set in control interrupt and updated in audio
41  volatile T step_size;
42
43 public:
44  /** Constructor. Use the template parameter to set the type of numbers you
45  want to use. For example, Line <int> myline; makes a Line which uses ints.
46  */
47  Line ()
48  {
49  ;
50  }
51
52
53
54  /** Increments one step along the line.
55  @return the next value.
56  */
57  inline
58  T next()
59  {
60  current_value += step_size;
61  //Serial.println(current_value);
62  return current_value;
63  }
64
65
66
67  /** Set the current value of the line.
68  The Line will continue incrementing from this
69  value using any previously calculated step size.
70  @param value the number to set the Line's current_value to.
71  */
72  inline
73  void set(T value)
74  {
75  current_value=value;
76  }
77
78
79
80  /** Given a target value and the number of steps to take on the way, this calculates the step size needed to get there from the current value.
81  @param targetvalue the value to move towards.
82  @param num_steps how many steps to take to reach the target.
83  */
84  inline
85  void set(T targetvalue, T num_steps)
86  {
87  if(num_steps) {
88  T numerator = targetvalue-current_value;
89  step_size= numerator/num_steps;
90  } else {
91  step_size = 0;
92  current_value = targetvalue;
93  }
94  }
95
96  /** Given a new starting value, target value and the number of steps to take on the way, this sets the step size needed to get there.
97  @param startvalue the number to set the Line's current_value to.
98  @param targetvalue the value to move towards.
99  @param num_steps how many steps to take to reach the target.
100  */
101  inline
102  void set(T startvalue, T targetvalue, T num_steps)
103  {
104  set(startvalue);
105  set(targetvalue, num_steps);
106  }
107 };
108
109
110 /* unsigned char specialisation (probably not very useful because step size will likely = 0) */
111 template <>
112 class Line <unsigned char>
113 {
114 private:
115  volatile unsigned char current_value; // volatile because it could be set in control interrupt and updated in audio
116  char step_size;
117
118 public:
119  /** Constructor. Use the template parameter to set the type of numbers you
120  want to use. For example, Line <int> myline; makes a Line which uses ints.
121  */
122  Line ()
123  {
124  ;
125  }
126
127
128
129  /** Increments one step along the line.
130  @return the next value.
131  */
132  inline
133  unsigned char next()
134  {
135  current_value += step_size;
136  return current_value;
137  }
138
139
140
141  /** Set the current value of the line.
142  The Line will continue incrementing from this
143  value using any previously calculated step size.
144  @param value the number to set the Line's current_value to.
145  */
146  inline
147  void set(unsigned char value)
148  {
149  current_value=value;
150  }
151
152
153
154  /** Given a target value and the number of steps to take on the way, this calculates the step size needed to get there from the current value.
155  @param targetvalue the value to move towards.
156  @param num_steps how many steps to take to reach the target.
157  */
158  inline
159  void set(unsigned char targetvalue, unsigned char num_steps)
160  {
161  step_size=(char)((((float)targetvalue-current_value)/num_steps));
162  }
163
164  /** Given a new starting value, target value and the number of steps to take on the way, this sets the step size needed to get there.
165  @param startvalue the number to set the Line's current_value to.
166  @param targetvalue the value to move towards.
167  @param num_steps how many steps to take to reach the target.
168  */
169  inline
170  void set(unsigned char startvalue, unsigned char targetvalue, unsigned char num_steps)
171  {
172  set(startvalue);
173  set(targetvalue, num_steps);
174  }
175
176 };
177
178
179 /* unsigned int specialisation */
180 template <>
181 class Line <unsigned int>
182 {
183 private:
184  volatile unsigned int current_value; // volatile because it could be set in control interrupt and updated in audio
185  int step_size;
186
187 public:
188  /** Constructor. Use the template parameter to set the type of numbers you
189  want to use. For example, Line <int> myline; makes a Line which uses ints.
190  */
191  Line ()
192  {
193  ;
194  }
195
196
197
198  /** Increments one step along the line.
199  @return the next value.
200  */
201  inline
202  unsigned int next()
203  {
204  current_value += step_size;
205  return current_value;
206  }
207
208
209
210  /** Set the current value of the line.
211  The Line will continue incrementing from this
212  value using any previously calculated step size.
213  @param value the number to set the Line's current_value to.
214  */
215  inline
216  void set(unsigned int value)
217  {
218  current_value=value;
219  }
220
221
222
223  /** Given a target value and the number of steps to take on the way, this calculates the step size needed to get there from the current value.
224  @param targetvalue the value to move towards.
225  @param num_steps how many steps to take to reach the target.
226  */
227  inline
228  void set(unsigned int targetvalue, unsigned int num_steps)
229  {
230  step_size=(int)((((float)targetvalue-current_value)/num_steps));
231  }
232
233
234  /** Given a new starting value, target value and the number of steps to take on the way, this sets the step size needed to get there.
235  @param startvalue the number to set the Line's current_value to.
236  @param targetvalue the value to move towards.
237  @param num_steps how many steps to take to reach the target.
238  */
239  inline
240  void set(unsigned int startvalue, unsigned int targetvalue, unsigned int num_steps)
241  {
242  set(startvalue);
243  set(targetvalue, num_steps);
244  }
245 };
246
247
248
249
250
251 /* unsigned long specialisation */
252 template <>
253 class Line <unsigned long>
254 {
255 private:
256  volatile unsigned long current_value; // volatile because it could be set in control interrupt and updated in audio
257  long step_size;
258
259 public:
260  /** Constructor. Use the template parameter to set the type of numbers you
261  want to use. For example, Line <int> myline; makes a Line which uses ints.
262  */
263  Line ()
264  {
265  ;
266  }
267
268
269
270  /** Increments one step along the line.
271  @return the next value.
272  */
273  inline
274  unsigned long next()
275  {
276  current_value += step_size;
277  return current_value;
278  }
279
280
281
282  /** Set the current value of the line.
283  The Line will continue incrementing from this
284  value using any previously calculated step size.
285  @param value the number to set the Line's current_value to.
286  */
287  inline
288  void set(unsigned long value)
289  {
290  current_value=value;
291  }
292
293
294
295  /** Given a target value and the number of steps to take on the way, this calculates the step size needed to get there from the current value.
296  @param targetvalue the value to move towards.
297  @param num_steps how many steps to take to reach the target.
298  */
299  inline
300  void set(unsigned long targetvalue, unsigned long num_steps)
301  {
302  step_size=(long)((((float)targetvalue-current_value)/num_steps));
303  }
304
305  /** Given a new starting value, target value and the number of steps to take on the way, this sets the step size needed to get there.
306  @param startvalue the number to set the Line's current_value to.
307  @param targetvalue the value to move towards.
308  @param num_steps how many steps to take to reach the target.
309  */
310  inline
311  void set(unsigned long startvalue, unsigned long targetvalue, unsigned long num_steps)
312  {
313  set(startvalue);
314  set(targetvalue, num_steps);
315  }
316 };
317
318 /**
319 @example 02.Control/Control_Tremelo/Control_Tremelo.ino
320 This example demonstrates the Line class.
321 */
322
323 #endif /* LINE_H_ */
void set(T value)
Set the current value of the line.
Definition: Line.h:73
Line()
Constructor.
Definition: Line.h:191
void set(unsigned int targetvalue, unsigned int num_steps)
Given a target value and the number of steps to take on the way, this calculates the step size needed...
Definition: Line.h:228
void set(unsigned long value)
Set the current value of the line.
Definition: Line.h:288
void set(unsigned long targetvalue, unsigned long num_steps)
Given a target value and the number of steps to take on the way, this calculates the step size needed...
Definition: Line.h:300
unsigned char next()
Increments one step along the line.
Definition: Line.h:133
void set(unsigned int value)
Set the current value of the line.
Definition: Line.h:216
void set(unsigned char value)
Set the current value of the line.
Definition: Line.h:147
void set(T startvalue, T targetvalue, T num_steps)
Given a new starting value, target value and the number of steps to take on the way, this sets the step size needed to get there.
Definition: Line.h:102
Line()
Constructor.
Definition: Line.h:47
For linear changes with a minimum of calculation at each step.
Definition: Line.h:37
Line()
Constructor.
Definition: Line.h:122
void set(unsigned char startvalue, unsigned char targetvalue, unsigned char num_steps)
Given a new starting value, target value and the number of steps to take on the way, this sets the step size needed to get there.
Definition: Line.h:170
void set(T targetvalue, T num_steps)
Given a target value and the number of steps to take on the way, this calculates the step size needed...
Definition: Line.h:85
Line()
Constructor.
Definition: Line.h:263
void set(unsigned long startvalue, unsigned long targetvalue, unsigned long num_steps)
Given a new starting value, target value and the number of steps to take on the way, this sets the step size needed to get there.
Definition: Line.h:311
void set(unsigned int startvalue, unsigned int targetvalue, unsigned int num_steps)
Given a new starting value, target value and the number of steps to take on the way, this sets the step size needed to get there.
Definition: Line.h:240
unsigned long next()
Increments one step along the line.
Definition: Line.h:274
unsigned int next()
Increments one step along the line.
Definition: Line.h:202
void set(unsigned char targetvalue, unsigned char num_steps)
Given a target value and the number of steps to take on the way, this calculates the step size needed...
Definition: Line.h:159
T next()
Increments one step along the line.
Definition: Line.h:58