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
settingsStructure 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
argcNumber of command line options, as passed to main().
argvArray of command line options, as passed to main().
customShortOptionsList 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.
customLongOptionsList 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.
settingsData 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
levelVerbosity 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
settingsData structure holding system settings, including numbers of channels, frame sizes, volume levels and other information.
userDataAn 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
taskTask 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.