Audio functions

This category contains functions for start/stop playing audio and retrieving/changing some audio-related settings. More...

Enumerations

Type

Name

enum

fplAudioResultType { fplAudioResultType_None , fplAudioResultType_Success , fplAudioResultType_InvalidArguments , fplAudioResultType_SystemNotInitialized , fplAudioResultType_DeviceNotInitialized , fplAudioResultType_DeviceAlreadyStopped , fplAudioResultType_DeviceAlreadyStarted , fplAudioResultType_DeviceBusy , fplAudioResultType_DeviceFailure , fplAudioResultType_NoDeviceFound , fplAudioResultType_DeviceByIdNotFound , fplAudioResultType_ApiFailed , fplAudioResultType_PlatformNotInitialized , fplAudioResultType_BackendAlreadyInitialized , fplAudioResultType_NoBackendsFound , fplAudioResultType_UnsetAudioFormat , fplAudioResultType_UnsetAudioChannels , fplAudioResultType_UnsetAudioSampleRate , fplAudioResultType_UnsetAudioBufferSize , fplAudioResultType_UnsuportedDeviceFormat , fplAudioResultType_OutOfMemory , fplAudioResultType_NotImplemented , fplAudioResultType_Failed , fplAudioResultType_First , fplAudioResultType_Last } An enumeration of audio results. More...

Functions

Type	Name
fpl_common_api fplAudioResultType	fplAudioInit (fplAudioSettings *audioSettings) Re/Initializes the audio system with the specified audio settings.
fpl_common_api bool	fplAudioRelease (void) Unloads/Releases the audio system.
fpl_common_api fplAudioMode	fplCreateAudioMode (const fplAudioLatencyType latencyType, const fplAudioShareMode shareMode) Creates an audio mode from the specified audio latency type and share mode.
fpl_common_api bool	fplDecodeAudioFormatU64 (const fplAudioFormatU64 format64, uint32_t *outSampleRate, uint16_t *outChannels, fplAudioFormatType *outType) Decodes the specified encoded audio format to the specified sample rate, channels, and type.
fpl_common_api fplAudioFormatU64	fplEncodeAudioFormatU64 (const uint32_t sampleRate, const uint16_t channels, const fplAudioFormatType type) Creates an encoded audio format from the specified sample rate, channels, and type.
fpl_common_api const char *	fplGetAudioBackendName (const fplAudioBackendType backendType) Gets the string that represents the given audio backend type.
fpl_common_api fplAudioBackendType	fplGetAudioBackendType (void) Gets the current audio backend type.
fpl_common_api uint32_t	fplGetAudioBufferSizeInBytes (const fplAudioFormatType format, const uint16_t channelCount, const uint32_t frameCount) Computes the total number of bytes for the buffer and the given parameters.
fpl_common_api uint32_t	fplGetAudioBufferSizeInFrames (const uint32_t sampleRate, const uint32_t bufferSizeInMilliSeconds) Computes the total number of frames for a given sample rate and buffer size.
fpl_common_api uint32_t	fplGetAudioBufferSizeInMilliseconds (const uint32_t sampleRate, const uint32_t frameCount) Computes the duration in milliseconds for the given sample rate and frame count.
fpl_common_api bool	fplGetAudioChannelMap (fplAudioChannelMap *outMapping) Gets the audio channels mapping table.
fpl_common_api uint16_t	fplGetAudioChannelsFromLayout (const fplAudioChannelLayout channelLayout) Returns the number of channels from the specified audio channel layout.
fpl_common_api bool	fplGetAudioDeviceInfo (const fplAudioDeviceID *deviceId, fplAudioDeviceInfo *outDeviceInfo) Gets the audio device info for the specified audio device ID.
fpl_common_api uint32_t	fplGetAudioDevices (const uint32_t maxDeviceCount, const uint32_t deviceInfoSize, fplAudioDeviceInfo *outDevices) Retrieves all playback audio devices.
fpl_common_api const char *	fplGetAudioFormatName (const fplAudioFormatType format) Gets the string that represents the given audio format type.
fpl_common_api uint32_t	fplGetAudioFrameSizeInBytes (const fplAudioFormatType format, const uint16_t channelCount) Computes the number of bytes required for one interleaved audio frame - containing all the channels.
fpl_common_api bool	fplGetAudioHardwareDevice (fplAudioDeviceInfo *outDevice) Retrieves the audio device info for the current audio device.
fpl_common_api const char *	fplGetAudioHardwareDeviceName (void) Retrieves the audio device name for the current audio device.
fpl_common_api bool	fplGetAudioHardwareFormat (fplAudioFormat *outFormat) Retrieves the native audio format for the current audio device.
fpl_common_api fplAudioLatencyType	fplGetAudioLatencyType (const fplAudioMode mode) Gets the audio latency type from the specified audio mode.
fpl_common_api uint32_t	fplGetAudioSampleSizeInBytes (const fplAudioFormatType format) Computes the number of bytes required to write one sample with one channel.
fpl_common_api fplAudioShareMode	fplGetAudioShareMode (const fplAudioMode mode) Gets the audio share mode from the specified audio mode.
fpl_common_api fplAudioChannelLayout	fplGetDefaultAudioChannelLayoutFromChannels (const uint16_t channelCount) Returns the default audio channel layout from the specified channel count.
fpl_common_api uint32_t	fplGetTargetAudioFrameCount (const uint32_t inputFrameCount, const uint32_t inputSampleRate, const uint32_t outputSampleRate) Computes the target number of audio frames from the specified input frame count and sample rate and the output sample rate.
fpl_common_api fplAudioResultType	fplPlayAudio (void) Start playing asynchronous audio.
fpl_common_api bool	fplSetAudioClientReadCallback (fpl_audio_client_read_callback *newCallback, void *userData) Overwrites the audio client read callback.
fpl_common_api fplAudioResultType	fplStopAudio (void) Stop playing asynchronous audio.

Detailed Description

This category contains functions for start/stop playing audio and retrieving/changing some audio-related settings.

Enumeration Type Documentation

fplAudioResultType

enum fplAudioResultType

An enumeration of audio results.

Name	Description
fplAudioResultType_None	No result.
fplAudioResultType_Success	Success.
fplAudioResultType_InvalidArguments	Invalid arguments are passed to an audio function.
fplAudioResultType_SystemNotInitialized	The audio system is not initialized.
fplAudioResultType_DeviceNotInitialized	The audio device is not initialized.
fplAudioResultType_DeviceAlreadyStopped	The audio device is already stopped.
fplAudioResultType_DeviceAlreadyStarted	The audio device is already started.
fplAudioResultType_DeviceBusy	The audio device is busy/waiting.
fplAudioResultType_DeviceFailure	Error occurred while initializing an audio device.
fplAudioResultType_NoDeviceFound	No audio device is found.
fplAudioResultType_DeviceByIdNotFound	Audio device by id was not found.
fplAudioResultType_ApiFailed	Failed to load the audio API.
fplAudioResultType_PlatformNotInitialized	The platform is not initialized.
fplAudioResultType_BackendAlreadyInitialized	The audio backend is already initialized.
fplAudioResultType_NoBackendsFound	No audio backends found.
fplAudioResultType_UnsetAudioFormat	The audio format type is not set.
fplAudioResultType_UnsetAudioChannels	The number of audio channels is not set.
fplAudioResultType_UnsetAudioSampleRate	The sample rate is not set.
fplAudioResultType_UnsetAudioBufferSize	The audio buffer size is not set.
fplAudioResultType_UnsuportedDeviceFormat	The audio device format is unsupported.
fplAudioResultType_OutOfMemory	No memory available.
fplAudioResultType_NotImplemented	Feature or device is not implemented.
fplAudioResultType_Failed	Unknown error.
fplAudioResultType_First	First audio result type.
fplAudioResultType_Last	Last audio result type.

Definition at line 10437 of file final_platform_layer.h.

Function Documentation

fplAudioInit()

fpl_common_api fplAudioResultType fplAudioInit ( fplAudioSettings * audioSettings)

Re/Initializes the audio system with the specified audio settings.

Parameters

Direction	Parameter	Description
[in]	audioSettings	Reference to the audio settings structure fplAudioSettings.

Returns: Returns the audio result type

fplAudioResultType .

fplAudioRelease()

fpl_common_api bool fplAudioRelease ( void )

Unloads/Releases the audio system.

Returns: Returns a boolean indicating whether the audio system was unloaded or not.

fplCreateAudioMode()

fpl_common_api fplAudioMode fplCreateAudioMode ( const fplAudioLatencyType latencyType, const fplAudioShareMode shareMode )

Creates an audio mode from the specified audio latency type and share mode.

Parameters

Direction	Parameter	Description
[in]	latencyType	The audio latency type fplAudioLatencyType.
[in]	shareMode	The audio share mode fplAudioShareMode.

Returns: Returns the resulting audio mode

fplAudioMode .

fplDecodeAudioFormatU64()

fpl_common_api bool fplDecodeAudioFormatU64 ( const fplAudioFormatU64 format64, uint32_t * outSampleRate, uint16_t * outChannels, fplAudioFormatType * outType )

Decodes the specified encoded audio format to the specified sample rate, channels, and type.

Parameters

Direction	Parameter	Description
[in]	format64	The encoded audio format fplAudioFormatU64
[out]	outSampleRate	Reference to the output sample rate.
[out]	outChannels	Reference to the output channels.
[out]	outType	Reference to the output audio format type.

Returns: Returns a boolean indicating whether the decode was successful or not.

fplEncodeAudioFormatU64()

fpl_common_api fplAudioFormatU64 fplEncodeAudioFormatU64 ( const uint32_t sampleRate, const uint16_t channels, const fplAudioFormatType type )

Creates an encoded audio format from the specified sample rate, channels, and type.

Parameters

Direction	Parameter	Description
[in]	sampleRate	The sample rate in Hz.
[in]	channels	The number of channels.
[in]	type	The audio format type.

Returns: Returns the encoded audio format

fplAudioFormatU64

fplGetAudioBackendName()

fpl_common_api const char * fplGetAudioBackendName ( const fplAudioBackendType backendType)

Gets the string that represents the given audio backend type.

Parameters

Direction	Parameter	Description
[in]	backendType	The audio backend type fplAudioBackendType.

Returns: Returns a string for the given audio backend type.

fplGetAudioBackendType()

fpl_common_api fplAudioBackendType fplGetAudioBackendType ( void )

Gets the current audio backend type.

Returns: Returns the current audio backend type.

fplGetAudioBufferSizeInBytes()

fpl_common_api uint32_t fplGetAudioBufferSizeInBytes ( const fplAudioFormatType format, const uint16_t channelCount, const uint32_t frameCount )

Computes the total number of bytes for the buffer and the given parameters.

Parameters

Direction	Parameter	Description
[in]	format	The audio format type fplAudioFormatType.
[in]	channelCount	The number of channels.
[in]	frameCount	The number of frames.

Returns: Returns the total number of bytes for the buffer.

fplGetAudioBufferSizeInFrames()

fpl_common_api uint32_t fplGetAudioBufferSizeInFrames ( const uint32_t sampleRate, const uint32_t bufferSizeInMilliSeconds )

Computes the total number of frames for a given sample rate and buffer size.

Parameters

Direction	Parameter	Description
[in]	sampleRate	The sample rate in Hz.
[in]	bufferSizeInMilliSeconds	The buffer size in milliseconds.

Returns: Returns the total number of frames for the given sample rate and buffer size.

fplGetAudioBufferSizeInMilliseconds()

fpl_common_api uint32_t fplGetAudioBufferSizeInMilliseconds ( const uint32_t sampleRate, const uint32_t frameCount )

Computes the duration in milliseconds for the given sample rate and frame count.

Parameters

Direction	Parameter	Description
[in]	sampleRate	The sample rate in Hz.
[in]	frameCount	The number of frames.

Returns: Returns the duration in milliseconds.

fplGetAudioChannelMap()

fpl_common_api bool fplGetAudioChannelMap ( fplAudioChannelMap * outMapping)

Gets the audio channels mapping table.

Parameters

Direction	Parameter	Description
[out]	outMapping	Reference to the audio channel map structure fplAudioChannelMap.

Returns: Returns true when the channels mapping was filled out, false otherwise.

fplGetAudioChannelsFromLayout()

fpl_common_api uint16_t fplGetAudioChannelsFromLayout ( const fplAudioChannelLayout channelLayout)

Returns the number of channels from the specified audio channel layout.

Parameters

Direction	Parameter	Description
[in]	channelLayout	The audio channel layout fplAudioChannelLayout.

Returns: Returns the number of channels.

fplGetAudioDeviceInfo()

fpl_common_api bool fplGetAudioDeviceInfo ( const fplAudioDeviceID * deviceId, fplAudioDeviceInfo * outDeviceInfo )

Gets the audio device info for the specified audio device ID.

Parameters

Direction	Parameter	Description
[in]	deviceId	The audio device ID.
[out]	outDeviceInfo	The output audio device info structure fplAudioDeviceInfo.

Returns: Returns a boolean indicating whether the function succeeded or not.

fplGetAudioDevices()

fpl_common_api uint32_t fplGetAudioDevices ( const uint32_t maxDeviceCount, const uint32_t deviceInfoSize, fplAudioDeviceInfo * outDevices )

Retrieves all playback audio devices.

Parameters

Direction	Parameter	Description
[in]	maxDeviceCount	The total number of devices available in the devices array.
[in]	deviceInfoSize	The size of an audio device info.
[out]	outDevices	The output array of audio device info structures fplAudioDeviceInfo.

Returns: Returns the number of devices found.

fplGetAudioFormatName()

fpl_common_api const char * fplGetAudioFormatName ( const fplAudioFormatType format)

Gets the string that represents the given audio format type.

Parameters

Direction	Parameter	Description
[in]	format	The audio format type fplAudioFormatType.

Returns: Returns a string for the given audio format type.

fplGetAudioFrameSizeInBytes()

fpl_common_api uint32_t fplGetAudioFrameSizeInBytes ( const fplAudioFormatType format, const uint16_t channelCount )

Computes the number of bytes required for one interleaved audio frame - containing all the channels.

Parameters

Direction	Parameter	Description
[in]	format	The audio format.
[in]	channelCount	The number of channels.

Returns: Returns the number of bytes for one frame in bytes.

fplGetAudioHardwareDevice()

fpl_common_api bool fplGetAudioHardwareDevice ( fplAudioDeviceInfo * outDevice)

Retrieves the audio device info for the current audio device.

Parameters

Direction	Parameter	Description
[out]	outDevice	Reference to the audio device info structure fplAudioDeviceInfo.

Returns: Returns true when an audio hardware device was active, false otherwise.

fplGetAudioHardwareDeviceName()

fpl_common_api const char * fplGetAudioHardwareDeviceName ( void )

Retrieves the audio device name for the current audio device.

Returns: Returns the name of the audio device when an audio hardware device was active, null otherwise.

fplGetAudioHardwareFormat()

fpl_common_api bool fplGetAudioHardwareFormat ( fplAudioFormat * outFormat)

Retrieves the native audio format for the current audio device.

Parameters

Direction	Parameter	Description
[out]	outFormat	Reference to the audio format structure fplAudioFormat.

Returns: Returns true when an audio hardware format was active, false otherwise.

fplGetAudioLatencyType()

fpl_common_api fplAudioLatencyType fplGetAudioLatencyType ( const fplAudioMode mode)

Gets the audio latency type from the specified audio mode.

Parameters

Direction	Parameter	Description
[in]	mode	The audio mode fplAudioMode.

Returns: Returns the matching audio latency type

fplAudioLatencyType .

fplGetAudioSampleSizeInBytes()

fpl_common_api uint32_t fplGetAudioSampleSizeInBytes ( const fplAudioFormatType format)

Computes the number of bytes required to write one sample with one channel.

Parameters

Direction	Parameter	Description
[in]	format	The audio format type fplAudioFormatType.

Returns: Returns the number of bytes for one sample with one channel.

fplGetAudioShareMode()

fpl_common_api fplAudioShareMode fplGetAudioShareMode ( const fplAudioMode mode)

Gets the audio share mode from the specified audio mode.

Parameters

Direction	Parameter	Description
[in]	mode	The audio mode fplAudioMode.

Returns: Returns the matching audio share mode

fplAudioShareMode .

fplGetDefaultAudioChannelLayoutFromChannels()

fpl_common_api fplAudioChannelLayout fplGetDefaultAudioChannelLayoutFromChannels ( const uint16_t channelCount)

Returns the default audio channel layout from the specified channel count.

Parameters

Direction	Parameter	Description
[in]	channelCount	The number of channels.

Returns: Returns the default audio channel layout

fplAudioChannelLayout .

fplGetTargetAudioFrameCount()

fpl_common_api uint32_t fplGetTargetAudioFrameCount ( const uint32_t inputFrameCount, const uint32_t inputSampleRate, const uint32_t outputSampleRate )

Computes the target number of audio frames from the specified input frame count and sample rate and the output sample rate.

Parameters

Direction	Parameter	Description
[in]	inputFrameCount	The input frame count.
[in]	inputSampleRate	The input sample rate in Hz.
[in]	outputSampleRate	The output sample rate in Hz.

Returns: Returns the target number of audio frames.

fplPlayAudio()

fpl_common_api fplAudioResultType fplPlayAudio ( void )

Start playing asynchronous audio.

Returns: Returns the audio result.

fplSetAudioClientReadCallback()

fpl_common_api bool fplSetAudioClientReadCallback ( fpl_audio_client_read_callback * newCallback, void * userData )

Overwrites the audio client read callback.

Parameters

Direction	Parameter	Description
[in]	newCallback	Reference to the audio client read callback fpl_audio_client_read_callback.
[in]	userData	Reference to the opaque client/user data.

Returns: Returns true when an audio device is ready and the callback was set, false otherwise.

Note: This has no effect when audio is already playing, you have to call it when audio is in a stopped state!

fplStopAudio()

fpl_common_api fplAudioResultType fplStopAudio ( void )

Stop playing asynchronous audio.

Returns: Returns the audio result.