Audio callbacks

Audio callbacks runs concurrently with calling thread until noted otherwise. See explanation of callback annotations here. Example use of play and finish callbacks along with audio system initialization:

main [exit: 0] {
	; Initialize audio system
	;
	audio_init(\
		cb_track_play:		"cb_play", \
		cb_track_mode:		NULL, \
		cb_track_finish:	"cb_finish", \
		cb_track_restart:	NULL, \
		cb_track_cancel:	NULL, \
		cb_track_pan:		NULL, \
		cb_track_vol:		NULL, \
		cb_master_vol:		NULL, \
		cb_buffer_start:	NULL, \
		cb_buffer_done:		NULL)

	; Generate 2 seconds of white noise and play it
	;
	_hnd = audio_create_noise_white(\
		seconds:		2.0, \
		pink:			0.0)

	if_invalid error

	_hnd.play(\
		volume:			1.0, \
		pan:			0.0)

	; Wait until track completes and free it
	;
	_hnd.wait()
	_hnd.eject()

	exit
error:
	print "Failed to initialize audio subsystem.\n"
}

_AUDIOCB_PLAY_ callback cb_play (_hnd, _vol, _pan, _data_size, \
	_ch1_data, _ch1_vol, _ch2_data, _ch2_vol) {

	print "Track playing.\n"
}

_AUDIOCB_FINISH_ callback cb_finish (_hnd, _data_size, \
	_ch1_data, _ch2_data) {

	print "Track finished.\n"
}

Play track callback

Play track callback runs when track starts playing.

_AUDIOCB_PLAY_ callback cb_play (track_handle, track_vol, track_pan, data_size, \
	ch1_data, ch1_vol, ch2_data, ch2_vol, \
	[ch3_data, ch3_vol, ...]) {
	;
	; This callback runs when track starts playing.
	; Track is identified by track_handle variable.
	;
	; track_vol is from 0.0 to 1.0, from silence to maximum volume,
	; respectively.
	;
	; track_pan is from -1.0 to 1.0, from far left to far right,
	; respectively. Zero is the center.
	;
	; data_size is in samples, not bytes.
	;
	; Amount of ch*_data and ch*_vol pairs must match to value of
	; AUDIO_MIXER_CHANNELS which is two by default. ch*_data buffer
	; type is float, each sample ranging from -1.0 to 1.0.
	;
	; ch*_vol is from 0.0 to 1.0, from silence to maximum volume,
	; respectively.
	;
	; Parameter types:
	;
	; track_handle ... handle
	; track_vol ...... float
	; track_pan ...... float
	; data_size ...... usize
	; ch*_data ....... pointer
	; ch*_vol ........ float
	;
}

Track mode callback

Track mode callback runs when track mode changes, for example, when mute is set, or playing mode is changed to loop.

_AUDIOCB_MODE_ callback cb_mode (track_handle, sample_state, sample_mode) {
	;
	; This callback runs when track state or mode changes.
	; Track is identified by track_handle variable.
	;
	; sample_state is one of:
	;  SAMPLE_STATE_NONE - track is allocated but stopped
	;  SAMPLE_STATE_BUSY - track is about to be played
	;  SAMPLE_STATE_PLAY - track is playing normally
	;  SAMPLE_STATE_HOLD - track is paused
	;  SAMPLE_STATE_MUTE - track is playing but silently
	;
	; sample_mode is one of:
	;  SAMPLE_MODE_NONE - track plays only once
	;  SAMPLE_MODE_LOOP - track plays again when it completes
	;
	; Parameter types:
	;
	; track_handle ... handle
	; sample_state ... uint
	; sample_mode .... uint
	;
}

Track finished callback

Track finished callback runs when track is finished.

_AUDIOCB_FINISH_ callback cb_finish (track_handle, data_size, \
	ch1_data, ch2_data, \
	[ch3_data, ...]) {
	;
	; This callback runs when track completes playing.
	; Track is identified by track_handle variable.
	;
	; data_size is in samples, not bytes.
	;
	; Amount of ch*_data variables must match to value of
	; AUDIO_MIXER_CHANNELS which is two by default. ch*_data buffer
	; type is float, each sample ranging from -1.0 to 1.0.
	;
	; Parameter types:
	;
	; track_handle ... handle
	; data_size ...... usize
	; ch*_data ....... pointer
	;
}

Track restart callback

Track restart callback runs when track is restarted.

_AUDIOCB_RESTART_ callback cb_restart (track_handle, data_size, \
	ch1_data, ch2_data, \
	[ch3_data, ...]) {
	;
	; This callback runs when track restarts playing in loop mode.
	; Track is identified by track_handle variable.
	;
	; data_size is in samples, not bytes.
	;
	; Amount of ch*_data variables must match to value of
	; AUDIO_MIXER_CHANNELS which is two by default. ch*_data buffer
	; type is float, each sample ranging from -1.0 to 1.0.
	;
	; Parameter types:
	;
	; track_handle ... handle
	; data_size ...... usize
	; ch*_data ....... pointer
	;
}

Track cancel callback

Track cancel callback runs when track is stopped before it is finished.

_AUDIOCB_CANCEL_ callback cb_cancel (track_handle) {
	;
	; This callback runs when track cancels playing.
	; Track is identified by track_handle variable.
	;
	; Parameter types:
	;
	; track_handle ... handle
	;
}

Track panning callback

Track panning callback runs when track panning changes.

_AUDIOCB_PAN_ callback cb_pan (track_handle, track_pan) {
	;
	; This callback runs when track panning changes.
	; Track is identified by track_handle variable.
	;
	; track_pan is from -1.0 to 1.0, from far left to far right,
	; respectively. Zero is the center.
	;
	; Parameter types:
	;
	; track_handle ... handle
	; track_pan ...... float
	;
}

Track volume callback

Track volume callback runs when track volume changes.

_AUDIOCB_VOL_ callback cb_vol (track_handle, ch1_vol, ch2_vol, \
	[ch3_vol, ...]) {
	;
	; This callback runs when track volume changes.
	; Track is identified by track_handle variable.
	;
	; ch*_vol is from 0.0 to 1.0, from silence to maximum volume,
	; respectively.
	;
	; Amount of ch*_vol variables must match to value of
	; AUDIO_MIXER_CHANNELS which is two by default.
	;
	; Parameter types:
	;
	; track_handle ... handle
	; ch*_vol ........ float
	;
}

Master volume callback

Master volume callback runs when master volume changes. This callback blocks calling thread until it is complete.

_AUDIOCB_MASTER_ callback cb_master_vol (ch1_vol, ch2_vol, \
	[ch3_vol, ...]) {
	;
	; This callback runs when master volume changes.
	;
	; ch*_vol is from 0.0 to 1.0, from silence to maximum volume,
	; respectively.
	;
	; Amount of ch*_vol variables must match to value of
	; AUDIO_MIXER_CHANNELS which is two by default.
	;
	; This callback does not run concurrently, but blocks mixer thread
	; until callback function is complete.
	;
	; Parameter types:
	;
	; ch*_vol ........ float
	;
}

Buffer start callback

Buffer start callback runs when mixing buffer is about to start playing. This callback blocks calling thread until it is complete.

_AUDIOCB_START_ callback cb_buffer_start (buf_data, buf_channels, buf_speed, buf_size, buf_samplesize, \
	buf_be, buf_signed) {
	;
	; This callback runs just before mixing buffer playback starts.
	; Application command line parameters may affect these values.
	;
	; buf_data is pointer to yet uninitialized buffer data.
	; Buffer type is float, each sample ranging from -1.0 to 1.0.
	;
	; buf_channels is amount of channels in buffer.
	;
	; buf_speed is buffer samplerate in Hz.
	;
	; buf_size is total buffer size in bytes.
	;
	; buf_samplesize is buffer sample size in bytes, aka physical width.
	;
	; buf_be is zero if buffer is little endian, nonzero otherwise.
	;
	; buf_signed is zero if buffer not signed, nonzero otherwise.
	;
	; This callback does not run concurrently, but blocks mixer thread
	; until callback function is complete.
	;
	; Parameter types:
	;
	; buf_data ....... pointer
	; buf_channels ... int
	; buf_speed ...... int
	; buf_size ....... usize
	; buf_samplesize . usize
	; buf_be ......... uint
	; buf_signed ..... uint
	;
}

Buffer done callback

Buffer done callback runs when mixing buffer is done but not necessarily played yet. This callback blocks calling thread until it is complete.

_AUDIOCB_DONE_ callback cb_buffer_done (buf_data, buf_channels, buf_speed, buf_size, buf_samplesize, \
	buf_be, buf_signed, usecs) {
	;
	; This callback runs right after mixing buffer playback completes.
	; Application command line parameters may affect these values.
	;
	; buf_data is pointer to now initialized buffer data.
	; Buffer type is float, each sample ranging from -1.0 to 1.0.
	;
	; buf_channels is amount of channels in buffer.
	;
	; buf_speed is buffer samplerate in Hz.
	;
	; buf_size is total buffer size in bytes.
	;
	; buf_samplesize is buffer sample size in bytes, aka physical width.
	;
	; buf_be is zero if buffer is little endian, nonzero otherwise.
	;
	; buf_signed is zero if buffer not signed, nonzero otherwise.
	;
	; usecs is time in microseconds consumed by mixer for last buffer.
	; Time includes possible buffer start callback execution as well.
	;
	; This callback does not run concurrently, but blocks mixer thread
	; until callback function is complete.
	;
	; Parameter types:
	;
	; buf_data ....... pointer
	; buf_channels ... int
	; buf_speed ...... int
	; buf_size ....... usize
	; buf_samplesize . usize
	; buf_be ......... uint
	; buf_signed ..... uint
	; usecs .......... ulong
	;
}