Crate bela_sys

Expand description

Raw FFI bindings to the Bela core API (libbela) for Bela Gem.

This crate exposes the C surface of the Bela core API (Bela.h): BelaContext, BelaInitSettings, the Bela_* lifecycle and auxiliary-task functions, and rt_printf. Bindings are generated from vendored headers (see vendor/bela/COMMIT for the pinned upstream commit) with cargo xtask bindgen; see the crate README for how to regenerate them.

One thing here is not the core API and not generated: the bela_midi_* functions, a C surface this crate compiles (shim/midi.cpp) over Bela’s Midi class in libbelaextra. MIDI is what a Bela program reaches for first after audio, and the class is C++ with only half a C surface of its own. The other higher-level C++ libraries (Scope, Trill, Fft, Gui) remain out of scope.

The setup / render / cleanup callbacks are not bound: they are either provided to Bela_initAudio via BelaInitSettings or defined as #[unsafe(no_mangle)] symbols by the linking crate.

Target platform is Bela Gem on PocketBeagle 2 (aarch64-unknown-linux-gnu). For a safe API, use the bela crate instead.

Structs§

BelaChannelGain
BelaChannelGainArray
BelaContext: \ingroup render \brief Structure holding audio and sensor settings and pointers to I/O data buffers.
BelaCpuData
BelaInitSettings: \ingroup control \brief Structure containing initialisation parameters for the real-time audio control system.
BelaMidi: An opened Midi object, as an opaque pointee.
_BelaHwConfig
option
timespec

Constants§

BELA_AUDIO_PRIORITY
BELA_BUGFIX_VERSION
BELA_FLAG_ANALOG_OUTPUTS_PERSIST
BELA_FLAG_DETECT_UNDERRUNS
BELA_FLAG_INTERLEAVED
BELA_FLAG_OFFLINE
BELA_MAJOR_VERSION
BELA_MIDI_ALREADY_OPEN: That direction of this object is already open.
BELA_MIDI_MESSAGE_MAX: Bytes of the longest message bela_midi_get_message writes: a status byte and two data bytes.
BELA_MIDI_NO_SUCH_PORT: No port has the name that was given.
BELA_MINOR_VERSION
BelaHwDetectMode_Cache: < read cached value from /run/bela/belaconfig first. If it does not exist, fall back to #BelaHwDetectMode_Scan
BelaHwDetectMode_CacheOnly: <read cached value from /run/bela/belaconfig. If it does not exist, return #BelaHw_NoHw
BelaHwDetectMode_Scan: < perform an automatic detection by scanning the peripherals and busses available, and cache value in /run/bela/belaconfig
BelaHwDetectMode_User: <read user-specified value from ~/.bela/belaconfig. If it does not exist, fall back to #BelaHwDetectMode_Cache
BelaHwDetectMode_UserOnly: <read user-specified value from ~/.bela/belaconfig. If it does not exist, return #BelaHw_NoHw
BelaHw_Batch: < Dummy offline
BelaHw_Bela: < Bela
BelaHw_BelaEs9080: < A Bela cape with Es9080 EVB on top, all as audio
BelaHw_BelaMini: < Bela Mini
BelaHw_BelaMiniMultiAudio: < Bela Mini with extra codecs
BelaHw_BelaMiniMultiI2s: < Bela Mini with extra rx and tx I2S data lines.
BelaHw_BelaMiniMultiTdm: < Bela Mini with extra codecs and/or tdm devices
BelaHw_BelaMultiTdm: < Bela with extra codecs and/or tdm devices
BelaHw_BelaRevC: < A Bela cape rev C: Es9080 is used for analog outs
BelaHw_CtagBeast: < Ctag Beast
BelaHw_CtagBeastBela: < Ctag Beast and Bela cape
BelaHw_CtagFace: < Ctag Face
BelaHw_CtagFaceBela: < Ctag Face and Bela cape
BelaHw_GemMulti: < Gem Multi
BelaHw_GemStereo: < Gem Stereo
BelaHw_NoHw: < No hardware
BelaHw_Salt: < Salt
DEFAULT_HP_LEVEL
DEFAULT_LINE_OUT_LEVEL
DEFAULT_PGA_GAIN
INPUT
OUTPUT

Functions§

Bela_HwConfig_delete^⚠: Use this to delete a pointer returned by Bela_HwConfig_new()
Bela_HwConfig_new^⚠: Returns the configuration for a given BelaHw or nullptr if hw is invalid.
Bela_InitSettings_alloc^⚠: \brief Allocate the data structure containing settings for Bela.
Bela_InitSettings_free^⚠: \brief De-allocate the data structure containing settings for Bela.
Bela_cleanupAudio^⚠: \brief Clean up resources from audio and sensor processing.
Bela_clock_gettime^⚠
Bela_cpuMonitoringGet^⚠: Get stats about internal CPU monitoring.
Bela_cpuMonitoringInit^⚠: Set internal CPU monitoring for the audio thread. @param count Number of samples (tic/toc pairs) in a acquisition cycle. Use 0 to disable. @return 0 on success, an error code otherwise.
Bela_cpuTic^⚠: Start measuring CPU time. When data->currentCount reaches data->count, a acquisition cycle is completed. data->percentage gives the average CPU busy time during the latest completed acquisition cycle.
Bela_cpuToc^⚠: Stop measuring CPU time.
Bela_createAuxiliaryTask^⚠: \brief Create a new auxiliary task.
Bela_defaultSettings^⚠: \brief Initialise the data structure containing settings for Bela.
Bela_deleteAllAuxiliaryTasks^⚠
Bela_detectHw^⚠: \brief Detect what hardware we are running on.
Bela_getVersion^⚠: \brief Get the version of Bela you are running.
Bela_getopt_long^⚠: \brief Get long options from command line argument list, including Bela standard options
Bela_gettime^⚠
Bela_initAudio^⚠: \brief Initialise audio and sensor rendering environment.
Bela_initRtBackend^⚠: \defgroup warppers Wrappers for real-time functionalities.
Bela_muteSpeakers^⚠: \brief Mute or unmute the onboard speaker amplifiers.
Bela_nanosleep^⚠
Bela_printFlushBuffers^⚠
Bela_printf^⚠
Bela_requestStop^⚠: \brief Tell the Bela program to stop.
Bela_runInSameThread^⚠: \brief Begin processing audio and sensor data in the same thread as the caller.
Bela_scheduleAuxiliaryTask^⚠: \brief Run an auxiliary task which has previously been created.
Bela_setADCLevel^⚠: DEPRECATED.
Bela_setAdcLevel^⚠: \brief Set the level of the audio ADC.
Bela_setAudioInputGain^⚠: \brief Set the gain of the audio input preamplifier.
Bela_setDACLevel^⚠: DEPRECATED.
Bela_setDacLevel^⚠: \brief Set the level of the audio DAC.
Bela_setHeadphoneLevel^⚠: DEPRECATED Equivalent to Bela_setHpLevel(-1, decibels);
Bela_setHpLevel^⚠: \brief Set the level of the onboard headphone amplifier.
Bela_setLineOutLevel^⚠: \brief Set the level of the audio line out.
Bela_setPgaGain^⚠: DEPRECATED.
Bela_setUserData^⚠: \brief Set the userData variable, which is passed to setup(), render() and cleanup().
Bela_setVerboseLevel^⚠: \brief Set level of verbose (debugging) printing.
Bela_startAudio^⚠: \brief Begin processing audio and sensor data.
Bela_stopAudio^⚠: \brief Stop processing audio and sensor data.
Bela_stopRequested^⚠: \brief Check whether the program should stop.
Bela_usage^⚠: \brief Print usage information for Bela standard options.
Bela_userSettings^⚠: \brief Initialise the data structure containing settings for Bela.
bela_midi_available_messages^⚠: How many parsed messages are waiting. Reads two ring indices: no allocation, no system call — and no synchronisation either, the input thread writing them as plain unsigned ints. What that can cost is a count one message stale.
bela_midi_delete^⚠: Destroys a Midi object, joining its input thread. Null is accepted. Blocks for as long as that thread takes to notice, which is up to its 50 ms poll timeout.
bela_midi_get_message^⚠: Writes the oldest waiting message into buf, which must have room for BELA_MIDI_MESSAGE_MAX bytes, and returns how many bytes it wrote — 0 when nothing was waiting, leaving buf untouched. The status byte carries the channel in its low nibble, as on the wire.
bela_midi_list_ports^⚠: Writes every MIDI port ALSA reports into buf as NUL-terminated names, one after another, and returns the bytes the whole list needs. A len shorter than that holds as many whole names as fit. buf may be null when len is 0, which is how to ask for the size before allocating.
bela_midi_new^⚠: Creates a Midi object with its input parser enabled, opening no port. Returns null if it could not be created.
bela_midi_read_from^⚠: Opens port for input and starts reading from it, once per object. Returns 0 when input is enabled afterwards, BELA_MIDI_NO_SUCH_PORT, BELA_MIDI_ALREADY_OPEN, or a negative value from Bela — -errno when ALSA refused the device.
bela_midi_write_output^⚠: Hands length bytes to Bela’s output task. Returns 1, or 0 if output was never enabled — and 1 says the bytes were handed over, not that they were queued or sent. The -1 in the C++ is unreachable while commsSend reports success unconditionally, which is what makes 1 and 0 the whole range.
bela_midi_write_to^⚠: Opens port for output, once per object, with the same return values as bela_midi_read_from and the same end after a failure.
rt_printf^⚠

Type Aliases§

AuxiliaryTask: \ingroup auxtask
BelaDigitalDirection: \defgroup iofunctions I/O functions and constants
BelaHw: A type of Bela hardware.
BelaHwConfig
BelaHwDetectMode: Arguments to be passed to Bela_detectHw()
__clockid_t
__syscall_slong_t
__time_t
clockid_t

Crate bela_sys

Crate bela_sys Copy item path

Structs§

Constants§

Functions§

Type Aliases§

Crate bela_sys