Final Platform Layer 0.9.8-beta
Loading...
Searching...
No Matches
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
}
#define fpl_null
Null.
fpl_common_api bool fplPlatformInit(const fplInitFlags initFlags, const fplSettings *initSettings)
Initializes the platform layer.
@ fplInitFlags_Audio
Use asynchronous audio playback.

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
}
fpl_common_api void fplSetDefaultSettings(fplSettings *settings)
Resets the given settings container to default values for window, video, audio, etc.
A structure containing audio device format runtime properties, such as type, samplerate,...
A structure containing audio settings, such as format, device info, callbacks, backend,...
void * userData
User data pointer for client read callback.
fpl_audio_client_read_callback * clientReadCallback
The callback for retrieving audio data from the client.
A structure containing settings, such as window, video, etc.
fplAudioSettings audio
Audio settings.
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
}
@ fplAudioFormatType_F32
32-bit IEEE_FLOAT
fplAudioFormatType type
Format.
uint32_t sampleRate
Samples per seconds.
uint32_t channels
Number of channels.
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
}
@ fplAudioBackendType_DirectSound
DirectSound.
fplAudioBackendType backend
The targeted backend.

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.