MozziGuts_impl_template.hpp

Go to the documentation of this file.

/*
 * MozziGuts_impl_template.hpp
 *
 * This file is part of Mozzi.
 *
 * Copyright 2023-2024 Thomas Friedrichsmeier and the Mozzi Team
 *
 * Mozzi is licensed under the GNU Lesser General Public Licence (LGPL) Version 2.1 or later.
 *
*/
 
// The main point of this check is to document, what platform & variants this implementation file is for.
#if !(IS_MYPLATFORM())
#  error "Wrong implementation included for this platform"
#endif
// Add platform specific includes and declarations, here
 
//#include <my_hardware_header.h>
 
// In order to allow simple yet efficient user configuration, the entire contents of this file are compiled in the same translation unit
// as (the main file of) the user sketch. To avoid name clashes, we encapsulate everyghing in a namespace.
// For the most part, this namescape can just extend from the start of the file to the end (as shown, here), and you will not have to
// worry about it. However, there may be a few situations, where you have to "leave" the MozziPrivate namespace. This includes:
// - When you include a further (hardware-dependent library). Consider gathering all includes at the top of this file, instead.
// - When you provide definitions for special names, importantly for ISR-functions. If these would be placed in the namespace, the linker would not
//   recognize them as the definition of the intended ISR-vector. See MozziGuts_impl_AVR.hpp for examples.
 
namespace MozziPrivate {
 
 
#if MOZZI_IS(MOZZI_ANALOG_READ, MOZZI_ANALOG_READ_STANDARD)
#error not yet implemented
 
// Insert here code to read the result of the latest asynchronous conversion, when it is finished.
// You can also provide this as a function returning unsigned int, should it be more complex on your platform
#define getADCReading() GET_MY_PLATFORM_ADC_REGISTER
 
// NOTE: Theoretically, adcPinToChannelNum is public API for historical reasons, thus cannot be replaced by a define
#define channelNumToIndex(channel) channel
uint8_t adcPinToChannelNum(uint8_t pin) {
  return pin;
}
 
void adcStartConversion(uint8_t channel) {
}
 
void startSecondADCReadOnCurrentChannel() {
}
 
void setupMozziADC(int8_t speed) {
  setupFastAnalogRead(speed);
  // insert further custom code
}
 
/* NOTE: Most platforms call a specific function/ISR when conversion is complete. Provide this function, here.
 * From inside its body, simply call advanceADCStep(). E.g.:
void stm32_adc_eoc_handler() {
  advanceADCStep();
}
*/
 
void setupFastAnalogRead(int8_t speed) {
}
 
#endif
 
 
/* NOTE: Some platforms rely on control returning from loop() every so often. However, updateAudio() may take too long (it tries to completely fill the output buffer,
 * which of course is being drained at the same time, theoretically it may not return at all). If you set this define, it will be called once per audio frame to keep things
 * running smoothly. */
//#define LOOP_YIELD yield();
 
/* NOTE: On some platforms, what can be called in the ISR used to output the sound is limited.
 * This define can be used, for instance, to output the sound in audioHook() instead to overcome
 * this limitation (see MozziGuts_impl_MBED.hpp). It can also be used if something needs to be called in audioHook() regarding
 * analog reads for instance. */
//#define AUDIO_HOOK_HOOK
 
/* NOTE: Code sections that are needed for a certain audio mode, only, should be guarded as follows (in this example, code will compile for the
 * two modes MOZZI_OUTPUT_PWM, and MOZZI_OUTPUT_INTERNAL_DAC (should your port happen to support these two).
 *
 * Keep in mind that you probably want to support MOZZI_OUTPUT_EXTERNAL_TIMED, and MOZZI_OUTPUT_EXTERNAL_CUSTOM, too, which is usually very
 * easy: For both, do *not* provide an audioOutput() function, as this will be provided by the user. For MOZZI_OUTPUT_EXTERNAL_TIMED make sure some
 * timer is set up to call defaultAudioOutput() at MOZZI_AUDIO_RATE. For MOZZI_OUTPUT_EXTERNAL_CUSTOM, nothing else will be needed. */
 
#if MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_PWM, MOZZI_OUTPUT_INTERNAL_DAC)  // just an example!
inline void audioOutput(const AudioOutput f) {
  // e.g. analogWrite(MOZZI_AUDIO_CHANNEL_1_PIN, f.l()+MOZZI_AUDIO_BIAS);
#  if (MOZZI_AUDIO_CHANNELS > 1)
  // e.g. analogWrite(MOZZI_AUDIO_CHANNEL_2_PIN, f.r()+MOZZI_AUDIO_BIAS);
#  endif
}
#endif
 
static void startAudio() {
  // Add here code to get audio output going. This usually involves:
  // 1) setting up some DAC mechanism (e.g. setting up a PWM pin with appropriate resolution
  // 2a) setting up a timer to call defaultAudioOutput() at MOZZI_AUDIO_RATE
  // OR 2b) setting up a buffered output queue such as I2S (see ESP32 / ESP8266 for examples for this setup)
#if MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_PWM)
  // [...]
#elif MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_INTERNAL_DAC)
  // [...]
#elif MOZZI_IS(MOZZI_AUDIO_MODE, MOZZI_OUTPUT_EXTERNAL_TIMED)
  // remember that the user may configure MOZZI_OUTPUT_EXTERNAL_TIMED, in which case, you'll want to provide step 2a), and only that.
#endif
}
 
void stopMozzi() {
  // Add here code to pause whatever mechanism moves audio samples to the output
}
 
void MozziRandPrivate::autoSeed() {
  // Add here code to initialize the values of MozziRandPrivate::x, MozziRandPrivate::y, and MozziRandPrivate::z to some random values
  // This doesn't need to be crypographically safe. If nothing better is available, e.g. try reading an internal temperature sensor
  // in order to get some noise. It also doesn't have to be fast.
  // It *should* however ensure that rand() sequences will differ across reboots, after randSeed() has been called.
  // x, y, and z are already initialized to non-zero, when this function is called.
  // It's ok to leave this unimplemented, initially.
#warning Automatic random seeding is not implemented on this platform
}
 
} // namespace MozziPrivate