Control and command line functions

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

Functions
void	Bela_defaultSettings (BelaInitSettings *settings)
	Initialise the data structure containing settings for Bela. More...
int	Bela_getopt_long (int argc, char *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_setVerboseLevel (int level)
	Set level of verbose (debugging) printing. 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_startAuxiliaryTask (AuxiliaryTask it)
	Stop processing audio and sensor data. More...
void	Bela_stopAudio ()
void	Bela_cleanupAudio ()
	Clean up resources from audio and sensor processing. 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

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.

int Bela_getopt_long	(	int	argc,
		char *	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.

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_startAuxiliaryTask

(

AuxiliaryTask

it

)

Stop processing audio and sensor data.

Start an auxiliary task so that it can be run.

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

This function will start an auxiliary task but will NOT schedule it. It will also set a flag in the associate InternalAuxiliaryTask to flag the task as "started", so that successive calls to the same function for a given AuxiliaryTask have no effect. The user should never be required to call this function directly, as it is called by Bela_scheduleAuxiliaryTask if needed (e.g.: if a task is scheduled in setup() ) or immediately after starting the audio thread.

Parameters

task	Task to start.

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.