Bela
Real-time, ultra-low-latency audio and sensor processing system for BeagleBone Black
 All Classes Files Functions Variables Typedefs Macros Groups
Utilities.h
Go to the documentation of this file.
1 
13 #ifndef UTILITIES_H_
14 #define UTILITIES_H_
15 
16 #include "Bela.h"
17 
34 #ifndef INPUT
35  #define INPUT 0x0
36 #endif /* INPUT */
37 
38 #ifndef OUTPUT
39  #define OUTPUT 0x1
40 #endif /* OUTPUT */
41 
50 #define setBit(word,bit) ((word) | (1 << (bit)))
52 
54 #define clearBit(word,bit) ((word) &~ (1 << (bit)))
55 
57 #define getBit(word,bit) (((word) >> (bit)) & 1)
58 
60 #define changeBit(word,bit,value) ((clearBit((word),(bit))) | ((value) << (bit)))
61 
72 // Note: pinMode(), analogWrite() and digitalWrite() should be able to be called from setup()
73 // Likewise, thread launch should be able to be called from setup()
74 // Also, make volume change functions callable from render() thread -- as an aux task?
75 
89 static inline float audioRead(BelaContext *context, int frame, int channel);
90 
94 static inline float audioReadNI(BelaContext *context, int frame, int channel);
95 
109 static inline void audioWrite(BelaContext *context, int frame, int channel, float value);
110 
114 static inline void audioWriteNI(BelaContext *context, int frame, int channel, float value);
115 
129 static inline float analogRead(BelaContext *context, int frame, int channel);
130 
134 static inline float analogReadNI(BelaContext *context, int frame, int channel);
135 
152 static inline void analogWrite(BelaContext *context, int frame, int channel, float value);
153 
157 static inline void analogWriteNI(BelaContext *context, int frame, int channel, float value);
158 
178 static inline void analogWriteOnce(BelaContext *context, int frame, int channel, float value);
179 
183 static inline void analogWriteOnceNI(BelaContext *context, int frame, int channel, float value);
184 
199 static inline int digitalRead(BelaContext *context, int frame, int channel);
200 
217 static inline void digitalWrite(BelaContext *context, int frame, int channel, int value);
218 
237 static inline void digitalWriteOnce(BelaContext *context, int frame, int channel, int value);
238 
255 static inline void pinMode(BelaContext *context, int frame, int channel, int mode);
256 
273 static inline void pinModeOnce(BelaContext *context, int frame, int channel, int mode);
274 
275 /*
276  * \brief Returns the value of the given multiplexer channel for the given analog input.
277  *
278  * This function reads an input from the Multiplexer Capelet hardware, which needs to be
279  * attached and enabled by selecting 16, 32 or 64 analog input channels in the command line
280  * arguments. With the Multiplexer Capelet, each analog input can be connected to one of 8
281  * multiplexer channels. This function will return a particular multiplexer channel for a
282  * particular input, with the returned valued being the most recent sample taken from that pin.
283  *
284  * Depending on the block size, it may take longer than a single block to scan all multiplexer
285  * channels. For this reason, successive calls to multiplexerAnalogRead() may return the same
286  * sample. If you want precise timing control on when a multiplexer input was sampled, use
287  * multiplexerChannelForFrame() instead to determine which multiplexer channels were sampled
288  * in a particular block.
289  *
290  * \param context The I/O data structure which is passed by Bela to render().
291  * \param input The analog input to read, i.e. what would be passed as \c channel to analogRead().
292  * Valid values are 0 to (context->analogInChannels - 1).
293  * \param muxChannel Which multiplexer channel to read. Valid values are 0 to
294  * (context->multiplexerChannels - 1).
295  * \return Value of the analog input from the Multiplexer Capelet.
296  */
297 
298 static inline float multiplexerAnalogRead(BelaContext *context, int input, int muxChannel);
299 
300 /*
301  * \brief Returns which multiplexer channel the given analog frame was taken from.
302  *
303  * This function indicates what the multiplexer setting was for a given analog input frame.
304  * This can be used to work out which pin on the Multiplexer Capelet a given analog input sample
305  * was taken from. For this function to have any meaning, the Multiplexer Capelet hardware must
306  * be attached and it should be enabled by selecting 16, 32 or 64 analog input channels in the
307  * command line arguments.
308  *
309  * Depending on the block size, it may take longer than a single block to scan all multiplexer
310  * channels. For this reason, each call to render() may contain only a subset of the available
311  * multiplexer channels. This function allows you timing precision by knowing at what frame each
312  * multiplexer reading was taken, but it does not guarantee that all channels can be read in
313  * any given callback. If you need access to all the multiplexer inputs in every call to render(),
314  * use multiplexerAnalogRead() instead.
315  *
316  * \param context The I/O data structure which is passed by Bela to render().
317  * \param frame The analog frame (i.e. the time) whose multiplexer setting should be queried.
318  * \return Multiplexer channel setting at the given frame.
319  */
320 
321 static inline unsigned int multiplexerChannelForFrame(BelaContext *context, int frame);
322 
352 static inline float map(float x, float in_min, float in_max, float out_min, float out_max);
353 
370 static inline float constrain(float x, float min_val, float max_val);
371 
377 static inline float min(float x, float y);
378 
384 static inline float max(float x, float y);
385 
387 // audioRead()
388 //
389 // Returns the value of the given audio input at the given frame number.
390 static inline float audioRead(BelaContext *context, int frame, int channel) {
391  return context->audioIn[frame * context->audioInChannels + channel];
392 }
393 
394 static inline float audioReadNI(BelaContext *context, int frame, int channel) {
395  return context->audioIn[channel * context->audioFrames + frame];
396 }
397 
398 // audioWrite()
399 //
400 // Sets a given audio output channel to a value for the current frame
401 static inline void audioWrite(BelaContext *context, int frame, int channel, float value) {
402  context->audioOut[frame * context->audioOutChannels + channel] = value;
403 }
404 
405 static inline void audioWriteNI(BelaContext *context, int frame, int channel, float value) {
406  context->audioOut[channel * context->audioFrames + frame] = value;
407 }
408 
409 // analogRead()
410 //
411 // Returns the value of the given analog input at the given frame number.
412 static inline float analogRead(BelaContext *context, int frame, int channel) {
413  return context->analogIn[frame * context->analogInChannels + channel];
414 }
415 
416 static inline float analogReadNI(BelaContext *context, int frame, int channel) {
417  return context->analogIn[channel * context->analogFrames + frame];
418 }
419 
420 // analogWriteOnce()
421 //
422 // Sets a given channel to a value for only the current frame
423 static inline void analogWriteOnce(BelaContext *context, int frame, int channel, float value) {
424  context->analogOut[frame * context->analogOutChannels + channel] = value;
425 }
426 
427 static inline void analogWriteOnceNI(BelaContext *context, int frame, int channel, float value) {
428  context->analogOut[channel * context->analogFrames + frame] = value;
429 }
430 
431 // analogWrite()
432 //
433 // Sets a given analog output channel to a value for the current frame and, if persistent outputs are
434 // enabled, for all subsequent frames
435 static inline void analogWrite(BelaContext *context, int frame, int channel, float value) {
436  unsigned int f;
437  for(f = frame; f < context->analogFrames; f++)
438  analogWriteOnce(context, f, channel, value);
439 }
440 
441 static inline void analogWriteNI(BelaContext *context, int frame, int channel, float value) {
442  unsigned int f;
443  for(f = frame; f < context->analogFrames; f++)
444  analogWriteOnceNI(context, f, channel, value);
445 }
446 
447 // digitalRead()
448 //
449 // Returns the value of a given digital input at the given frame number
450 static inline int digitalRead(BelaContext *context, int frame, int channel) {
451  return getBit(context->digital[frame], channel + 16);
452 }
453 
454 // digitalWrite()
455 //
456 // Sets a given digital output channel to a value for the current frame and all subsequent frames
457 static inline void digitalWrite(BelaContext *context, int frame, int channel, int value) {
458  unsigned int f;
459  for(f = frame; f < context->digitalFrames; f++) {
460  if(value)
461  context->digital[f] |= 1 << (channel + 16);
462  else
463  context->digital[f] &= ~(1 << (channel + 16));
464  }
465 }
466 
467 // digitalWriteOnce()
468 //
469 // Sets a given digital output channel to a value for the current frame only
470 static inline void digitalWriteOnce(BelaContext *context, int frame, int channel, int value) {
471  if(value)
472  context->digital[frame] |= 1 << (channel + 16);
473  else
474  context->digital[frame] &= ~(1 << (channel + 16));
475 }
476 
477 // pinMode()
478 //
479 // Sets the direction of a digital pin for the current frame and all subsequent frames
480 static inline void pinMode(BelaContext *context, int frame, int channel, int mode) {
481  unsigned int f;
482  for(f = frame; f < context->digitalFrames; f++) {
483  if(mode == INPUT)
484  context->digital[f] |= (1 << channel);
485  else
486  context->digital[f] &= ~(1 << channel);
487  }
488 }
489 
490 // pinModeOnce()
491 //
492 // Sets the direction of a digital pin for the current frame only
493 static inline void pinModeOnce(BelaContext *context, int frame, int channel, int mode) {
494  if(mode == INPUT)
495  context->digital[frame] |= (1 << channel);
496  else
497  context->digital[frame] &= ~(1 << channel);
498 }
499 
500 // multiplexerAnalogRead()
501 //
502 // Returns the value of the given multiplexer channel for the given analog input.
503 static inline float multiplexerAnalogRead(BelaContext *context, int input, int muxChannel) {
504  return context->multiplexerAnalogIn[muxChannel * context->analogInChannels + input];
505 }
506 
507 // multiplexerChannelForFrame()
508 //
509 // Returns which multiplexer channel the given analog frame was taken from.
510 static inline unsigned int multiplexerChannelForFrame(BelaContext *context, int frame) {
511  if(context->multiplexerChannels <= 1)
512  return 1;
513  return (context->multiplexerStartingChannel + frame) % context->multiplexerChannels;
514 }
515 
516 // map()
517 //
518 // Scale an input value from one range to another. Works like its Wiring language equivalent.
519 // x is the value to scale; in_min and in_max are the input range; out_min and out_max
520 // are the output range.
521 
522 static inline float map(float x, float in_min, float in_max, float out_min, float out_max)
523 {
524  return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min;
525 }
526 
527 // constrain()
528 //
529 // Clips an input value to be between two end points
530 // x is the value to constrain; min_val and max_val are the range
531 
532 static inline float constrain(float x, float min_val, float max_val)
533 {
534  if(x < min_val) return min_val;
535  if(x > max_val) return max_val;
536  return x;
537 }
538 
539 static inline float max(float x, float y){
540  return x > y ? x : y;
541 }
542 
543 static inline float min(float x, float y){
544  return x < y ? x : y;
545 }
546 
547 #endif /* UTILITIES_H_ */
const uint32_t multiplexerChannels
Number of multiplexer channels for each analog input.
Definition: Bela.h:302
const float *const analogIn
Buffer holding analog input samples.
Definition: Bela.h:200
static void audioWriteNI(BelaContext *context, int frame, int channel, float value)
Definition: Utilities.h:405
const uint32_t audioInChannels
The number of audio input channels.
Definition: Bela.h:241
const uint32_t analogInChannels
The number of analog input channels.
Definition: Bela.h:263
static float analogRead(BelaContext *context, int frame, int channel)
Read an analog input, specifying the frame number (when to read) and the channel. ...
Definition: Utilities.h:412
static float audioReadNI(BelaContext *context, int frame, int channel)
Definition: Utilities.h:394
static void audioWrite(BelaContext *context, int frame, int channel, float value)
Write an audio output, specifying the frame number (when to write) and the channel.
Definition: Utilities.h:401
static float constrain(float x, float min_val, float max_val)
Constrain a number to stay within a given range.
Definition: Utilities.h:532
const uint32_t analogOutChannels
The number of analog output channels.
Definition: Bela.h:268
const uint32_t multiplexerStartingChannel
Multiplexer channel corresponding to the first analog frame.
Definition: Bela.h:308
static void analogWriteOnceNI(BelaContext *context, int frame, int channel, float value)
Definition: Utilities.h:427
const uint32_t digitalFrames
Number of digital frames per period.
Definition: Bela.h:282
static float map(float x, float in_min, float in_max, float out_min, float out_max)
Linearly rescale a number from one range of values to another.
Definition: Utilities.h:522
static void analogWriteNI(BelaContext *context, int frame, int channel, float value)
Definition: Utilities.h:441
static int digitalRead(BelaContext *context, int frame, int channel)
Read a digital input, specifying the frame number (when to read) and the pin.
Definition: Utilities.h:450
static unsigned int multiplexerChannelForFrame(BelaContext *context, int frame)
Read an audio input, specifying the frame number (when to read) and the channel.
Definition: Utilities.h:510
float *const audioOut
Buffer holding audio output samples.
Definition: Bela.h:181
const uint32_t audioFrames
The number of audio frames per block.
Definition: Bela.h:239
static void digitalWriteOnce(BelaContext *context, int frame, int channel, int value)
Write a digital output, specifying the frame number (when to write) and the pin.
Definition: Utilities.h:470
Structure holding audio and sensor settings and pointers to I/O data buffers.
Definition: Bela.h:148
static float min(float x, float y)
Returns the maximum of two numbers.
Definition: Utilities.h:543
float *const analogOut
Buffer holding analog output samples.
Definition: Bela.h:215
const uint32_t audioOutChannels
The number of audio output channels.
Definition: Bela.h:243
static void analogWriteOnce(BelaContext *context, int frame, int channel, float value)
Write an analog output, specifying the frame number (when to write) and the channel.
Definition: Utilities.h:423
uint32_t *const digital
Buffer holding digital input/output samples.
Definition: Bela.h:225
static void analogWrite(BelaContext *context, int frame, int channel, float value)
Write an analog output, specifying the frame number (when to write) and the channel.
Definition: Utilities.h:435
static float max(float x, float y)
Returns the minimum of two numbers.
Definition: Utilities.h:539
Main Bela public API.
static float audioRead(BelaContext *context, int frame, int channel)
Read an audio input, specifying the frame number (when to read) and the channel.
Definition: Utilities.h:390
const uint32_t analogFrames
The number of analog frames per block.
Definition: Bela.h:258
static float analogReadNI(BelaContext *context, int frame, int channel)
Definition: Utilities.h:416
const float *const multiplexerAnalogIn
Buffer which holds multiplexed analog inputs, when multiplexer capelet is enabled.
Definition: Bela.h:315
static void pinMode(BelaContext *context, int frame, int channel, int mode)
Set the direction of a digital pin to input or output.
Definition: Utilities.h:480
static void pinModeOnce(BelaContext *context, int frame, int channel, int mode)
Set the direction of a digital pin to input or output.
Definition: Utilities.h:493
static void digitalWrite(BelaContext *context, int frame, int channel, int value)
Write a digital output, specifying the frame number (when to write) and the pin.
Definition: Utilities.h:457
const float *const audioIn
Buffer holding audio input samples.
Definition: Bela.h:166
static float multiplexerAnalogRead(BelaContext *context, int input, int muxChannel)
Read an audio input, specifying the frame number (when to read) and the channel.
Definition: Utilities.h:503