User-defined render functions

Classes
struct	BelaContext
	Structure holding audio and sensor settings and pointers to I/O data buffers. More...

Functions
bool	setup (BelaContext *context, void *userData)
	User-defined initialisation function which runs before audio rendering begins. More...
void	render (BelaContext *context, void *userData)
	User-defined callback function to process audio and sensor data. More...
void	cleanup (BelaContext *context, void *userData)
	User-defined cleanup function which runs when the program finishes. More...

Variables
int volatile	gShouldStop

Detailed Description

These three functions must be implemented by the developer in every Bela program. Typically they appear in their own .cpp source file.

Function Documentation

bool setup	(	BelaContext *	context,
		void *	userData
	)

User-defined initialisation function which runs before audio rendering begins.

This function runs once at the beginning of the program, after most of the system initialisation has begun but before audio rendering starts. Use it to prepare any memory or resources that will be needed in render().

Parameters

context	Data structure holding information on sample rates, numbers of channels, frame sizes and other state. Note: the buffers for audio, analog and digital data will not yet be available to use. Do not attempt to read or write audio or sensor data in setup().
userData	An opaque pointer to an optional user-defined data structure. Whatever is passed as the second argument to Bela_initAudio() will appear here.

Returns

true on success, or false if an error occurred. If no initialisation is required, setup() should return true.

Examples:

Analog/analog-input/render.cpp, Analog/analog-output/render.cpp, Analog/scope-analog/render.cpp, Audio/delay/render.cpp, Audio/envelope-generator/render.cpp, Audio/FFT-phase-vocoder/render.cpp, Audio/filterbanks/render.cpp, Audio/record-audio/render.cpp, Audio/sample-loader/render.cpp, Audio/sample-piezo-trigger/render.cpp, Audio/sample-streamer-multi/render.cpp, Audio/sample-streamer/render.cpp, Audio/tremolo/render.cpp, Capelets/audio-expander/render.cpp, Capelets/multiplexer-display/render.cpp, Capelets/multiplexer-spectrum/render.cpp, Communication/logging-sensors/render.cpp, Communication/MIDI/render.cpp, Communication/OSC/render.cpp, Communication/Serial/render.cpp, Communication/Spi/render.cpp, Digital/bicolor-LEDs/render.cpp, Digital/digital-input/render.cpp, Digital/digital-output/render.cpp, Digital/level-meter/render.cpp, Extras/cape-test/render.cpp, Extras/oscillator-bank/render.cpp, Extras/pru-pwm/render.cpp, Extras/second-pru/render.cpp, Extras/userdata/render.cpp, Fundamentals/minimal/render.cpp, Fundamentals/passthrough/render.cpp, Fundamentals/print/render.cpp, Fundamentals/scope/render.cpp, Fundamentals/sinetone-optimized-bank/render.cpp, Fundamentals/sinetone-optimized/render.cpp, Fundamentals/sinetone/render.cpp, Gui/ambient-ellipse/render.cpp, Gui/bela-to-gui/render.cpp, Gui/clock/render.cpp, Gui/empty-project/render.cpp, Gui/frequency-response/render.cpp, Gui/graph/render.cpp, Gui/gui-to-bela/render.cpp, Gui/mouse-track/render.cpp, Gui/sequencer/render.cpp, Gui/sliders/render.cpp, Sensors/LDR/render.cpp, Sensors/MPR121/render.cpp, Sensors/rotary-encoder/render.cpp, Sensors/shift-register-out/render.cpp, Sensors/stepped-pot/render.cpp, Sensors/ultrasonic-distance-sensor/render.cpp, synchronous-gpio/render.cpp, terminal-only/filter-FIR/render.cpp, terminal-only/filter-IIR/render.cpp, terminal-only/samples/render.cpp, Trill/bar-led/render.cpp, Trill/bar-sound/render.cpp, Trill/bar-visual/render.cpp, Trill/craft-sound/render.cpp, Trill/craft-visual/render.cpp, Trill/custom-slider/render.cpp, Trill/detect-all-devices/render.cpp, Trill/flex-default/render.cpp, Trill/flex-visual/render.cpp, Trill/general-custom-address/render.cpp, Trill/general-print/render.cpp, Trill/general-settings/render.cpp, Trill/general-visual/render.cpp, Trill/hex-sound/render.cpp, Trill/hex-visual/render.cpp, Trill/multiple-devices/render.cpp, Trill/ring-sound/render.cpp, Trill/ring-visual/render.cpp, Trill/square-multitouch/render.cpp, Trill/square-sound/render.cpp, and Trill/square-visual/render.cpp.

void render	(	BelaContext *	context,
		void *	userData
	)

User-defined callback function to process audio and sensor data.

This function is called regularly by the system every time there is a new block of audio and/or sensor data to process. Your code should process the requested samples of data, store the results within context, and return.

Parameters

context	Data structure holding buffers for audio, analog and digital data. The structure also holds information on numbers of channels, frame sizes and sample rates, which are guaranteed to remain the same throughout the program and to match what was passed to setup().
userData	An opaque pointer to an optional user-defined data structure. Will be the same as the userData parameter passed to setup().

Checking offset between analog and digital how it should be : The PRU loop does the following (the loop runs at 88.2kHz):

• Read/write audio sample (once for the left channel, once for the right channel)
• Write DAC 0 or 0/2 or 0/2/4/6
• Read ADC 0 or 0/2 or 0/2/4/6, 2 samples (@176.4) older than NOW
• /During/ the line above, every two loops we also Read/Write GPIO, therefore reading on ADC 0/2/4/6 a value that is being output from GPIO will lead to undefined results
• Write DAC 1 or 1/3 or 1/3/5/7
• Read ADC 1 or 1/3 or 1/3/5/7, 2 samples (@176.4) older than NOW

Examples:

Analog/analog-input/render.cpp, Analog/analog-output/render.cpp, Analog/scope-analog/render.cpp, Audio/delay/render.cpp, Audio/envelope-generator/render.cpp, Audio/FFT-phase-vocoder/render.cpp, Audio/filterbanks/render.cpp, Audio/record-audio/render.cpp, Audio/sample-loader/render.cpp, Audio/sample-piezo-trigger/render.cpp, Audio/sample-streamer-multi/render.cpp, Audio/sample-streamer/render.cpp, Audio/tremolo/render.cpp, Capelets/audio-expander/render.cpp, Capelets/multiplexer-display/render.cpp, Capelets/multiplexer-spectrum/render.cpp, Communication/logging-sensors/render.cpp, Communication/MIDI/render.cpp, Communication/OSC/render.cpp, Communication/Serial/render.cpp, Communication/Spi/render.cpp, Digital/bicolor-LEDs/render.cpp, Digital/digital-input/render.cpp, Digital/digital-output/render.cpp, Digital/level-meter/render.cpp, Extras/cape-test/render.cpp, Extras/oscillator-bank/render.cpp, Extras/pru-pwm/render.cpp, Extras/second-pru/render.cpp, Extras/userdata/render.cpp, Fundamentals/minimal/render.cpp, Fundamentals/passthrough/render.cpp, Fundamentals/print/render.cpp, Fundamentals/scope/render.cpp, Fundamentals/sinetone-optimized-bank/render.cpp, Fundamentals/sinetone-optimized/render.cpp, Fundamentals/sinetone/render.cpp, Gui/ambient-ellipse/render.cpp, Gui/bela-to-gui/render.cpp, Gui/clock/render.cpp, Gui/empty-project/render.cpp, Gui/frequency-response/render.cpp, Gui/graph/render.cpp, Gui/gui-to-bela/render.cpp, Gui/mouse-track/render.cpp, Gui/sequencer/render.cpp, Gui/sliders/render.cpp, Sensors/LDR/render.cpp, Sensors/MPR121/render.cpp, Sensors/rotary-encoder/render.cpp, Sensors/shift-register-out/render.cpp, Sensors/stepped-pot/render.cpp, Sensors/ultrasonic-distance-sensor/render.cpp, synchronous-gpio/render.cpp, terminal-only/filter-FIR/render.cpp, terminal-only/filter-IIR/render.cpp, terminal-only/samples/render.cpp, Trill/bar-led/render.cpp, Trill/bar-sound/render.cpp, Trill/bar-visual/render.cpp, Trill/craft-sound/render.cpp, Trill/craft-visual/render.cpp, Trill/custom-slider/render.cpp, Trill/detect-all-devices/render.cpp, Trill/flex-default/render.cpp, Trill/flex-visual/render.cpp, Trill/general-custom-address/render.cpp, Trill/general-print/render.cpp, Trill/general-settings/render.cpp, Trill/general-visual/render.cpp, Trill/hex-sound/render.cpp, Trill/hex-visual/render.cpp, Trill/multiple-devices/render.cpp, Trill/ring-sound/render.cpp, Trill/ring-visual/render.cpp, Trill/square-multitouch/render.cpp, Trill/square-sound/render.cpp, and Trill/square-visual/render.cpp.

void cleanup	(	BelaContext *	context,
		void *	userData
	)

User-defined cleanup function which runs when the program finishes.

This function is called by the system once after audio rendering has finished, before the program quits. Use it to release any memory allocated in setup() and to perform any other required cleanup. If no initialisation is performed in setup(), then this function will usually be empty.

Parameters

context	Data structure holding information on sample rates, numbers of channels, frame sizes and other state. Note: the buffers for audio, analog and digital data will no longer be available to use. Do not attempt to read or write audio or sensor data in cleanup().
userData	An opaque pointer to an optional user-defined data structure. Will be the same as the userData parameter passed to setup() and render().

Examples:

Analog/analog-input/render.cpp, Analog/analog-output/render.cpp, Analog/scope-analog/render.cpp, Audio/delay/render.cpp, Audio/envelope-generator/render.cpp, Audio/FFT-phase-vocoder/render.cpp, Audio/filterbanks/render.cpp, Audio/record-audio/render.cpp, Audio/sample-loader/render.cpp, Audio/sample-piezo-trigger/render.cpp, Audio/sample-streamer-multi/render.cpp, Audio/sample-streamer/render.cpp, Audio/tremolo/render.cpp, Capelets/audio-expander/render.cpp, Capelets/multiplexer-display/render.cpp, Capelets/multiplexer-spectrum/render.cpp, Communication/logging-sensors/render.cpp, Communication/MIDI/render.cpp, Communication/OSC/render.cpp, Communication/Serial/render.cpp, Communication/Spi/render.cpp, Digital/bicolor-LEDs/render.cpp, Digital/digital-input/render.cpp, Digital/digital-output/render.cpp, Digital/level-meter/render.cpp, Extras/cape-test/render.cpp, Extras/oscillator-bank/render.cpp, Extras/pru-pwm/render.cpp, Extras/second-pru/render.cpp, Extras/userdata/render.cpp, Fundamentals/minimal/render.cpp, Fundamentals/passthrough/render.cpp, Fundamentals/print/render.cpp, Fundamentals/scope/render.cpp, Fundamentals/sinetone-optimized-bank/render.cpp, Fundamentals/sinetone-optimized/render.cpp, Fundamentals/sinetone/render.cpp, Gui/ambient-ellipse/render.cpp, Gui/bela-to-gui/render.cpp, Gui/clock/render.cpp, Gui/empty-project/render.cpp, Gui/frequency-response/render.cpp, Gui/graph/render.cpp, Gui/gui-to-bela/render.cpp, Gui/mouse-track/render.cpp, Gui/sequencer/render.cpp, Gui/sliders/render.cpp, Sensors/LDR/render.cpp, Sensors/MPR121/render.cpp, Sensors/rotary-encoder/render.cpp, Sensors/shift-register-out/render.cpp, Sensors/stepped-pot/render.cpp, Sensors/ultrasonic-distance-sensor/render.cpp, synchronous-gpio/render.cpp, terminal-only/filter-FIR/render.cpp, terminal-only/filter-IIR/render.cpp, terminal-only/samples/render.cpp, Trill/bar-led/render.cpp, Trill/bar-sound/render.cpp, Trill/bar-visual/render.cpp, Trill/craft-sound/render.cpp, Trill/craft-visual/render.cpp, Trill/custom-slider/render.cpp, Trill/detect-all-devices/render.cpp, Trill/flex-default/render.cpp, Trill/flex-visual/render.cpp, Trill/general-custom-address/render.cpp, Trill/general-print/render.cpp, Trill/general-settings/render.cpp, Trill/general-visual/render.cpp, Trill/hex-sound/render.cpp, Trill/hex-visual/render.cpp, Trill/multiple-devices/render.cpp, Trill/ring-sound/render.cpp, Trill/ring-visual/render.cpp, Trill/square-multitouch/render.cpp, Trill/square-sound/render.cpp, and Trill/square-visual/render.cpp.

Variable Documentation

int volatile gShouldStop

Flag that indicates whether the audio thread shuold stop. Threads can poll this variable to indicate when they should stop. Additionally, a program can set this to true to indicate that audio processing should terminate. Calling Bela_requestStop() simply returns the value of gShouldStop, and calling Bela_requestStop() simply sets gShouldStop. Bela_stopAudio() has the side effect of setting gShouldStop, but it also does other steps to stop running the program and should not be called from the audio thread.

Note

Normally the user wouldn't access this variable directly, but would call Bela_stopRequested() or Bela_requestStop()

Warning

The use of this variable is deprecated and may be removed in a future version.