Provide basic PCM audio playback. More...

Collaboration diagram for Audio:

Detailed Description

The audio component offers 1-channel Pulse-Code Modulation (PCM) playback with a callback-based interface, suitable for retro-style games and basic procedural sound generation.

Data Structures
struct	bj_audio_properties_t
	Describe properties of an audio device. More...

struct	bj_audio_play_note_data_t
	Define parameters for generating simple waveforms. More...

struct	bj_audio_layer_t
	Represent an audio backend (ALSA, MME, etc). More...

struct	bj_audio_layer_create_info
	Declare a backend and its constructor function. More...

Macros
#define	BJ_AUDIO_FORMAT_WIDTH(x)

#define	BJ_AUDIO_FORMAT_FLOAT(x)

#define	BJ_AUDIO_FORMAT_INT(x)

#define	BJ_AUDIO_FORMAT_BIG_ENDIAN(x)

#define	BJ_AUDIO_FORMAT_SIGNED(x)

Typedefs
typedef struct bj_audio_device_t	bj_audio_device
	Opaque handle to an audio device instance.

typedef enum bj_audio_format_t	bj_audio_format
	Describes how and audio device encodes sound samples.

typedef struct bj_audio_properties_t	bj_audio_properties
	Describe properties of an audio device.

typedef void(*	bj_audio_callback_t) (void buffer, unsigned frames, const bj_audio_properties audio, void *user_data, uint64_t base_sample_index)
	Define a callback for generating audio samples.

typedef struct bj_audio_play_note_data_t	bj_audio_play_note_data
	Define parameters for generating simple waveforms.

typedef struct bj_audio_layer_t	bj_audio_layer
	Represent an audio backend (ALSA, MME, etc).

Enumerations
enum	bj_audio_format_t { BJ_AUDIO_FORMAT_UNKNOWN = 0x0000 , BJ_AUDIO_FORMAT_INT16 = 0x8010 , BJ_AUDIO_FORMAT_F32 = 0x8120 }
	Describes how and audio device encodes sound samples. More...

Functions
bj_audio_device *	bj_open_audio_device (const bj_audio_properties p_properties, bj_audio_callback_t p_callback, void p_callback_user_data, bj_error **p_error)
	Open the default audio device for playback.

void	bj_close_audio_device (bj_audio_device *p_device)
	Close an audio device and release all associated resources.

void	bj_audio_device_play (bj_audio_device *p_device)
	Resume audio playback.

void	bj_audio_device_pause (bj_audio_device *p_device)
	Pause audio playback.

void	bj_audio_device_reset (bj_audio_device *p_device)
	Reset the playback stream sample index to 0.

void	bj_audio_device_stop (bj_audio_device *p_device)
	Stop playback and reset the sample stream.

bj_bool	bj_audio_device_is_playing (const bj_audio_device *p_device)
	Query whether the device is currently playing audio.

void	bj_audio_play_note (void buffer, unsigned frames, const bj_audio_properties audio, void *user_data, uint64_t base_sample_index)
	Generate a basic waveform tone using a built-in callback.

Data Structure Documentation

◆ bj_audio_properties_t

struct bj_audio_properties_t

This structure is passed to audio callbacks to inform them about the format and limits of the current playback device.

See also: bj_audio_callback_t

Data Fields
int16_t	amplitude	Maximum amplitude of the output samples.
unsigned int	channels	Number of channels (currently always 1).
bj_audio_format	format	Sampling format.
unsigned int	sample_rate	Number of samples per second (Hz).

◆ bj_audio_layer_t

struct bj_audio_layer_t

This internal structure handles platform-specific device control and is used to abstract away the OS details.

Data Fields

void(*)(struct bj_audio_layer_t *self, bj_audio_device *device)

close_device

Close an audio device managed by this backend.

Used to stop and destroy a specific audio device instance.

Parameters

self	Pointer to the audio layer instance.
device	Pointer to the audio device to close.

struct bj_audio_layer_data_t *

data

Backend-specific data pointer.

Used internally by the backend to store platform-specific state.

void(*)(struct bj_audio_layer_t *self, bj_error **p_error)

end

Shutdown and clean up the backend.

Called during deinitialization to release all backend-related resources.

Parameters

self	Pointer to the audio layer instance.
p_error	Optional pointer to receive error information.

bj_audio_device *(*)(struct bj_audio_layer_t *self, const bj_audio_properties *p_properties, bj_audio_callback_t callback, void *user_data, bj_error **p_error)

open_device

Open an audio device through this backend.

Initializes a new audio device using the given callback and context.

Parameters

self	Pointer to the audio layer instance.
p_error	Optional pointer to receive error information.
callback	User-provided callback for audio sample generation.
user_data	Pointer to be passed to the audio callback.

Returns: A new audio device instance, or NULL on failure.

◆ bj_audio_layer_create_info

struct bj_audio_layer_create_info

Used at initialization time to register available backends such as ALSA, MME, or WebAudio.

See also: bj_audio_layer

Collaboration diagram for bj_audio_layer_create_info:

[legend]

Data Fields
bj_audio_layer ()(bj_error **)	create	Factory function to instantiate the backend.
const char *	name	Name of the backend (e.g., "alsa", "mme").

Macro Definition Documentation

◆ BJ_AUDIO_FORMAT_BIG_ENDIAN

#define BJ_AUDIO_FORMAT_BIG_ENDIAN ( x )

Value:

((x) & (1u<<12))

◆ BJ_AUDIO_FORMAT_FLOAT

#define BJ_AUDIO_FORMAT_FLOAT ( x )

Value:

((x) & (1u<<8))

◆ BJ_AUDIO_FORMAT_INT

#define BJ_AUDIO_FORMAT_INT ( x )

Value:

(!((x) & (1u<<8)))

◆ BJ_AUDIO_FORMAT_SIGNED

#define BJ_AUDIO_FORMAT_SIGNED ( x )

Value:

((x) & (1u<<15))

◆ BJ_AUDIO_FORMAT_WIDTH

#define BJ_AUDIO_FORMAT_WIDTH ( x )

Value:

((x) & (0xFFu))

Typedef Documentation

◆ bj_audio_callback_t

typedef void(* bj_audio_callback_t) (void *buffer, unsigned frames, const bj_audio_properties *audio, void *user_data, uint64_t base_sample_index)

This callback is called periodically from a dedicated audio thread to generate PCM audio data.

Parameters

buffer	Output buffer to write `int16_t` samples into.
frames	Number of audio frames to generate.
audio	Pointer to audio device properties (readonly).
user_data	User-defined pointer passed at device creation.
base_sample_index	Index of the first sample in the current buffer.

See also: bj_open_audio_device; bj_audio_properties

◆ bj_audio_device

typedef struct bj_audio_device_t bj_audio_device

See also: bj_open_audio_device; bj_close_audio_device

◆ bj_audio_format

typedef enum bj_audio_format_t bj_audio_format

See also: bj_audio_properties

◆ bj_audio_layer

typedef struct bj_audio_layer_t bj_audio_layer

This internal structure handles platform-specific device control and is used to abstract away the OS details.

◆ bj_audio_play_note_data

typedef struct bj_audio_play_note_data_t bj_audio_play_note_data

Used in conjunction with bj_audio_play_note to synthesize basic musical tones such as sine or square waves.

See also: bj_audio_play_note

◆ bj_audio_properties

typedef struct bj_audio_properties_t bj_audio_properties

This structure is passed to audio callbacks to inform them about the format and limits of the current playback device.

See also: bj_audio_callback_t

Enumeration Type Documentation

◆ bj_audio_format_t

enum bj_audio_format_t

See also: bj_audio_properties

Enumerator
BJ_AUDIO_FORMAT_INT16	!< Unknown
BJ_AUDIO_FORMAT_F32	!< 16-bit signed integer

Function Documentation

◆ bj_audio_device_is_playing()

bj_bool bj_audio_device_is_playing ( const bj_audio_device * p_device )

Parameters

p_device Pointer to the audio device.

Returns: BJ_TRUE if playing, BJ_FALSE if paused or stopped.

See also: bj_audio_device_play; bj_audio_device_pause

◆ bj_audio_device_pause()

void bj_audio_device_pause ( bj_audio_device * p_device )

While paused, the audio thread continues running and outputs silence.

Parameters

p_device Pointer to the audio device.

See also: bj_audio_device_play; bj_audio_device_stop; bj_audio_device_is_playing

◆ bj_audio_device_play()

void bj_audio_device_play ( bj_audio_device * p_device )

Playback resumes from where it was previously paused.

Parameters

p_device Pointer to the audio device.

See also: bj_audio_device_pause; bj_audio_device_stop; bj_audio_device_is_playing

Examples: audio_pcm.c.

◆ bj_audio_device_reset()

void bj_audio_device_reset ( bj_audio_device * p_device )

This does not stop or pause playback, but restarts timing from zero.

Parameters

p_device Pointer to the audio device.

See also: bj_audio_device_stop; bj_audio_callback_t

◆ bj_audio_device_stop()

void bj_audio_device_stop ( bj_audio_device * p_device )

This is equivalent to calling pause followed by reset.

Parameters

p_device Pointer to the audio device.

See also: bj_audio_device_pause; bj_audio_device_reset

◆ bj_audio_play_note()

void bj_audio_play_note	(	void *	buffer,
		unsigned	frames,
		const bj_audio_properties *	audio,
		void *	user_data,
		uint64_t	base_sample_index )

This function can be passed as a bj_audio_callback_t and uses the data provided in bj_audio_play_note_data_t to generate tones.

Parameters

buffer	Output buffer to write samples into.
frames	Number of frames to generate.
audio	Audio device properties.
user_data	Pointer to a bj_audio_play_note_data_t instance.
base_sample_index	Starting sample index (used to compute phase).

See also: bj_audio_play_note_data_t; bj_audio_callback_t

◆ bj_close_audio_device()

void bj_close_audio_device ( bj_audio_device * p_device )

This stops playback and joins the audio thread before cleanup.

Parameters

p_device Pointer to the audio device to close.

See also: bj_open_audio_device

Examples: audio_pcm.c.

◆ bj_open_audio_device()

bj_audio_device * bj_open_audio_device	(	const bj_audio_properties *	p_properties,
		bj_audio_callback_t	p_callback,
		void *	p_callback_user_data,
		bj_error **	p_error )

This initializes the audio backend and starts playback immediately using the provided callback.

Parameters

p_properties	An optional pointer to required properties, can be 0.
p_callback	Function pointer to the user-provided audio callback.
p_callback_user_data	User-defined pointer passed to the callback.
p_error	Pointer to receive error information.

Returns: A handle to the opened audio device, or NULL on failure.

Behavior

If p_properties is set, the driver will attempt to open a device with the provided properties. The opened device may not have the requested requirements.

See also: bj_audio_callback_t; bj_close_audio_device; bj_audio_device_play; bj_audio_device_pause

Examples: audio_pcm.c.

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Data Structure Documentation

◆ bj_audio_properties_t

◆ bj_audio_layer_t

◆ bj_audio_layer_create_info

Macro Definition Documentation

◆ BJ_AUDIO_FORMAT_BIG_ENDIAN

◆ BJ_AUDIO_FORMAT_FLOAT

◆ BJ_AUDIO_FORMAT_INT

◆ BJ_AUDIO_FORMAT_SIGNED

◆ BJ_AUDIO_FORMAT_WIDTH

Typedef Documentation

◆ bj_audio_callback_t

◆ bj_audio_device

◆ bj_audio_format

◆ bj_audio_layer

◆ bj_audio_play_note_data

◆ bj_audio_properties

Enumeration Type Documentation

◆ bj_audio_format_t

Function Documentation

◆ bj_audio_device_is_playing()

◆ bj_audio_device_pause()

◆ bj_audio_device_play()

◆ bj_audio_device_reset()

◆ bj_audio_device_stop()

◆ bj_audio_play_note()

◆ bj_close_audio_device()

◆ bj_open_audio_device()