Final Platform Layer  0.9.6-beta
Initialization & Usage

Default initialization

To initialize audio playback with default settings (Interleaved, 48 kHz, 2 Channels, signed 16-bit integer format), you have to set the fplInitFlags_Audio flag in the fplPlatformInit() call and ensure that audio is not disabled by a preprocessor directive FPL_NO_AUDIO.

// ... your code here
}

Setting the client callback

Next is to specify the client user callback which gets invoked regularly when the audio device requires new samples to play.
This client callback can be set up in the fplAudioSettings::clientReadCallback field from the fplSettings::audio or changed by calling fplSetAudioClientReadCallback() :

static uint32_t MyAudioPlaybackCallback(const fplAudioDeviceFormat *nativeFormat, const uint32_t frameCount, void *outputSamples, void *userData) {
// ... Fill audio frames here
}
fplSettings settings;
fplAudioSettings &audioSettings = settings->audio;
audioSettings.clientReadCallback = MyAudioPlaybackCallback;
audioSettings.userData = // ... pointer to some user data
// ... your code here
}
Note
This step must be done before you can start playing the audio!
You can specify a user data pointer that gets passed to the client callback as well.

Custom initialization

You can change several audio settings (Sample rate, Number of Channels, Format, etc.) before initializing the audio playback like this:

fplSettings settings;
fplAudioSettings &audioSettings = settings.audio;
audioSettings.clientReadCallback = MyAudioPlaybackCallback;
audioSettings.userData = // ... pointer to some user data
fplAudioDeviceFormat &audioDeviceFormat = audioSettings.deviceFormat;
audioDeviceFormat.sampleRate = 48000;
audioDeviceFormat.channels = 2;
audioDeviceFormat.type = fplAudioFormatType_F32;
// ... your code here
}
Note
Please see the Notes for possible limitations!

Choosing the audio backend

By default, FPL uses the first available audio backend which is supported on your platform.
If you want to force FPL to use a certain audio backend, you can do this by changing the fplAudioSettings::backend field in the fplAudioSettings structure:

fplSettings settings;
fplAudioSettings &audioSettings = settings.audio;
// Forcing to use the DirectSound audio backend
// ... your code here
}

It is recommended to use the default fplAudioBackendType_Auto which uses the first supported audio backend.

Warning
If your platform/system does not support the desired backend, the audio and platform initialization will fail!

Automatic play/stop of audio samples playback

By default, FPL starts the playback of audio samples automatically, but only when fplAudioSettings::clientReadCallback was set!
Also audio playback will be stopped when fplPlatformRelease() is called as well.

You can disable this behavior by changing the fields fplAudioSettings::startAuto and fplAudioSettings.stopAuto in the fplAudioSettings configuration respectively.

Manual play/stop of audio samples playback

For manual control of start/stop playback of audio samples use the following functions:

Warning
Please ensure that fplStopAudio() is called before fplPlatformRelease() always!

Notes

There is no guarantee that you get the desired audio format you specified back!
You should always check the nativeAudioFormat in your client callback and convert/write the correct samples the audio device expects!

For more details see the page: Writing audio samples

If needed you can use fplSetDefaultAudioSettings() to fill in just the default video settings inside the fplAudioSettings structure.

fplInitFlags_Audio
Use asynchronous audio playback.
Definition: final_platform_layer.h:3386
fplAudioSettings::userData
void * userData
User data pointer for client read callback.
Definition: final_platform_layer.h:3750
fplAudioFormatType_F32
32-bit IEEE_FLOAT
Definition: final_platform_layer.h:3612
fplAudioBackendType_DirectSound
DirectSound.
Definition: final_platform_layer.h:3587
fplSettings
A structure containing settings, such as window, video, etc.
Definition: final_platform_layer.h:3930
fplAudioSettings
A structure containing audio settings, such as format, device info, callbacks, backend,...
Definition: final_platform_layer.h:3740
fplAudioSettings::clientReadCallback
fpl_audio_client_read_callback * clientReadCallback
The callback for retrieving audio data from the client.
Definition: final_platform_layer.h:3748
fplPlatformInit
fpl_common_api bool fplPlatformInit(const fplInitFlags initFlags, const fplSettings *initSettings)
Initializes the platform layer.
fplAudioDeviceFormat::channels
uint32_t channels
Number of channels.
Definition: final_platform_layer.h:3655
fplAudioDeviceFormat
A structure containing audio device format runtime properties, such as type, samplerate,...
Definition: final_platform_layer.h:3649
fplAudioDeviceFormat::sampleRate
uint32_t sampleRate
Samples per seconds.
Definition: final_platform_layer.h:3653
fplSettings::audio
fplAudioSettings audio
Audio settings.
Definition: final_platform_layer.h:3936
fplAudioSettings::backend
fplAudioBackendType backend
The targeted backend.
Definition: final_platform_layer.h:3752
fpl_null
#define fpl_null
Null.
Definition: final_platform_layer.h:2166
fplAudioDeviceFormat::type
fplAudioFormatType type
Format.
Definition: final_platform_layer.h:3659
fplSetDefaultSettings
fpl_common_api void fplSetDefaultSettings(fplSettings *settings)
Resets the given settings container to default values for window, video, audio, etc.