Classes
struct	BelaInitSettings
	Structure containing initialisation parameters for the real-time audio control system. More...

Functions
BelaInitSettings *	Bela_InitSettings_alloc ()
	Allocate the data structure containing settings for Bela. More...

void	Bela_InitSettings_free (BelaInitSettings *settings)
	De-allocate the data structure containing settings for Bela. More...

void	Bela_defaultSettings (BelaInitSettings *settings)
	Initialise the data structure containing settings for Bela. More...

void	Bela_userSettings (BelaInitSettings *settings)
	Initialise the data structure containing settings for Bela. More...

int	Bela_getopt_long (int argc, char const argv[], const char customShortOptions, const struct option customLongOptions, BelaInitSettings settings)
	Get long options from command line argument list, including Bela standard options. More...

void	Bela_usage ()
	Print usage information for Bela standard options. More...

void	Bela_getVersion (int major, int minor, int *bugfix)
	Get the version of Bela you are running.

void	Bela_setVerboseLevel (int level)
	Set level of verbose (debugging) printing. More...

BelaHw	Bela_detectHw (BelaHwDetectMode mode)
	Detect what hardware we are running on. More...

int	Bela_initAudio (BelaInitSettings settings, void userData)
	Initialise audio and sensor rendering environment. More...

int	Bela_startAudio ()
	Begin processing audio and sensor data. More...

int	Bela_runInSameThread ()
	Begin processing audio and sensor data in the same thread as the caller. More...

void	Bela_stopAudio ()
	Stop processing audio and sensor data. More...

void	Bela_cleanupAudio ()
	Clean up resources from audio and sensor processing. More...

void	Bela_setUserData (void *newUserData)
	Set the `userData` variable, which is passed to setup(), render() and cleanup(). More...

void	Bela_requestStop ()
	Tell the Bela program to stop. More...

int	Bela_stopRequested ()
	Check whether the program should stop. More...

Detailed Description

These functions are used to initialise the Bela settings, process arguments from the command line, and start/stop the audio and sensor system.

Function Documentation

BelaInitSettings* Bela_InitSettings_alloc ( )

Allocate the data structure containing settings for Bela.

This function should be used to allocate the structure that holds initialisation data for Bela in order to preserve binary compatibility across versions of the library.

void Bela_InitSettings_free ( BelaInitSettings * settings )

De-allocate the data structure containing settings for Bela.

This function should be used to de-allocate the structure that holds initialisation data for Bela.

Parameters

settings Pointer to structure to be de-allocated.

void Bela_defaultSettings ( BelaInitSettings * settings )

Initialise the data structure containing settings for Bela.

This function should be called in main() before parsing any command-line arguments. It sets default values in the data structure which specifies the Bela settings, including frame sizes, numbers of channels, volume levels and other parameters.

Parameters

settings Structure holding initialisation data for Bela.

void Bela_userSettings ( BelaInitSettings * settings )

Initialise the data structure containing settings for Bela.

This function fwill be called by Bela_defaultSettings() after the settings have been initialied. It has weak linking so the user is free - but not forced to - define it. It can be used to override some of the default settings if the user code does not have access to the call to Bela_defaultSettings() (e.g.: because it is handled by the backend code).

Parameters

settings Structure holding initialisation data for Bela.

Examples:: Extras/pru-pwm/render.cpp, and Extras/second-pru/render.cpp.

int Bela_getopt_long	(	int	argc,
		char *const	argv[],
		const char *	customShortOptions,
		const struct option *	customLongOptions,
		BelaInitSettings *	settings
	)

Get long options from command line argument list, including Bela standard options.

This function should be used in main() to process command line options, in place of the standard library getopt_long(). Internally, it parses standard Bela command-line options, storing the results in the settings data structure. Any options which are not part of the Bela standard options will be returned, as they would normally be in getopt_long().

Parameters

argc	Number of command line options, as passed to main().
argv	Array of command line options, as passed to main().
customShortOptions	List of short options to be parsed, analogous to getopt_long(). This list should not include any characters already parsed as part of the Bela standard options.
customLongOptions	List of long options to parsed, analogous to getopt_long(). This list should not include any long options already parsed as part of the Bela standard options.
settings	Data structure holding initialisation settings for Bela. Any standard options parsed will automatically update this data structure.

Returns: Value of the next option parsed which is not a Bela standard option, or -1 when the argument list has been exhausted. Similar to the return value of getopt_long() except that Bela standard options are handled internally and not returned.

void Bela_usage ( )

Print usage information for Bela standard options.

This function should be called from your code wherever you wish to print usage information for the user. It will print usage information on Bela standard options, after which you can print usage information for your own custom options.

void Bela_setVerboseLevel ( int level )

Set level of verbose (debugging) printing.

Parameters

level Verbosity level of the internal Bela system. 0 by default; higher values will print more information. Presently all positive numbers produce the same level of printing.

BelaHw Bela_detectHw ( BelaHwDetectMode mode )

Detect what hardware we are running on.

Parameters

mode	How to perform the detection. The behaviour is described in BelaHwDetectMode.

int Bela_initAudio	(	BelaInitSettings *	settings,
		void *	userData
	)

Initialise audio and sensor rendering environment.

This function prepares audio rendering in Bela. It should be called from main() sometime after command line option parsing has finished. It will initialise the rendering system, which in the process will result in a call to the user-defined setup() function.

Parameters

settings	Data structure holding system settings, including numbers of channels, frame sizes, volume levels and other information.
userData	An opaque pointer to a user-defined data structure which will be passed to setup(), render() and cleanup(). You can use this to pass custom information to the rendering functions, as an alternative to using global variables.

Returns: 0 on success, or nonzero if an error occurred.

int Bela_startAudio ( )

Begin processing audio and sensor data.

This function will start the Bela audio/sensor system. After this function is called, the system will make periodic calls to render() until Bela_stopAudio() is called.

Returns: 0 on success, or nonzero if an error occurred.

int Bela_runInSameThread ( )

Begin processing audio and sensor data in the same thread as the caller.

This function will start the Bela audio/sensor system. After this function is called, the system will make periodic calls to render() until Bela_stopAudio() is called.

Returns: 0 on success, or nonzero if an error occurred.

void Bela_stopAudio ( )

Stop processing audio and sensor data.

This function will stop the Bela audio/sensor system. After this function returns, no further calls to render() will be issued.

void Bela_cleanupAudio ( )

Clean up resources from audio and sensor processing.

This function should only be called after Bela_stopAudio(). It will release any internal resources for audio and sensor processing. In the process, it will call the user-defined cleanup() function.

void Bela_setUserData ( void * newUserData )

Set the userData variable, which is passed to setup(), render() and cleanup().

This function can be used to override userData after it has been set by Bela_initAudio().

Note: This function is experimental and may be removed in a future version.

void Bela_requestStop ( )

Tell the Bela program to stop.

This can be safely called anywhere in the code to tell the audio thread, and all threads monitoring Bela_stopRequested() that they should stop at the earliest occasion. The program will not stop immediately. If the render() function is currently running, it will keep running until it concludes its current execution, but will not be called again. The program's execution will stop when all threads have completed their execution. For this reason, all threads should check for Bela_stopRequested() to be notified when Bela_requestStop() has been called.

Examples:: Audio/record-audio/render.cpp, terminal-only/filter-FIR/render.cpp, terminal-only/filter-IIR/render.cpp, terminal-only/samples/render.cpp, and Trill/detect-all-devices/render.cpp.

int Bela_stopRequested ( )

Check whether the program should stop.

If you have several threads of execution, each of them should be regularly calling this function and complete execution as soon as possible if a non-zero value is returned.

Returns: a non-zero value if stop has been requested, 0 otherwise.

Examples:: Communication/Serial/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/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.

Classes

Functions

Detailed Description

Function Documentation