Acoustics
Module: Audio / Audio Definitions / Audio Output
Modules
| Name |
|---|
| Spatial Sound |
| Buffering |
| Master Volume |
Functions
| Name | |
|---|---|
| MLResult | MLAudioResetAcousticScene() Resets the Acoustic Scene. |
| MLResult | MLAudioBeginAcousticSceneUpdate() Pauses the processing of changes to the Acoustic Scene. |
| MLResult | MLAudioEndAcousticSceneUpdate() Resumes the processing of changes to the Acoustic Scene. |
| MLResult | MLAudioSetAcousticSceneMapEnable(bool is_enabled) Sets whether spatial rendering emulates the acoustics of the user's environment. |
| MLResult | MLAudioGetAcousticSceneMapEnable(bool * out_is_enabled) Queries whether spatial rendering emulates the acoustics of the user's environment. |
| MLResult | MLAudioSetAcousticSceneTransmissionDefault(const MLAudioMultibandLevel * transmission) Sets the default attenuation applied to obstructed spatial sounds. |
| MLResult | MLAudioGetAcousticSceneTransmissionDefault(MLAudioMultibandLevel * out_transmission) Queries the default attenuation applied to obstructed spatial sounds. |
| MLResult | MLAudioSetAcousticSceneDispersionDefault(const MLAudioDispersionProperties * properties) Sets the default dispersion properties, which control the rendering of clustered reflections. |
| MLResult | MLAudioGetAcousticSceneDispersionDefault(MLAudioDispersionProperties * out_properties) Queries the default dispersion properties, which control the rendering of clustered reflections. |
| MLResult | MLAudioSetAcousticSceneReverbDefault(const MLAudioReverbProperties * properties) Sets the default reverb properties, which control the rendering of late reverberation. |
| MLResult | MLAudioGetAcousticSceneReverbDefault(MLAudioReverbProperties * out_properties) Queries the default reverb properties, which control the rendering of late reverberation. |
| MLResult | MLAudioGetChangedAcousticMap(uint32_t prev_map_tag, uint8_t * out_map_data, uint32_t out_map_size_in_bytes, uint32_t * out_map_tag) INTERNAL USE ONLY: Retrieves the Acoustic Map if it has been updated since the previous call. |
Detailed Description
ACOUSTICS.
Functions Documentation
MLAudioResetAcousticScene
MLResult MLAudioResetAcousticScene()
Resets the Acoustic Scene.
Returns
| MLResult | MLResult_Ok | Successfully reset the Acoustic Scene. |
| MLResult | MLResult_UnspecifiedFailure | Internal error. |
| MLResult | MLAudioResult_HandleNotFound | No custom scene exists for client. |
Required Permissions:
- None
Each client of this audio API is automatically assigned an Acoustic Scene that specifies the acoustic behaviors of that client's spatial audio content. An Acoustic Scene can be modified and customized by calling functions in the ACOUSTICS section of this audio API. This function resets the caller's Acoustic Scene to its initial default state.
API Level:
- 20
MLAudioBeginAcousticSceneUpdate
MLResult MLAudioBeginAcousticSceneUpdate()
Pauses the processing of changes to the Acoustic Scene.
Returns
| MLResult | MLResult_Ok | Successfully began the Acoustic Scene update. |
| MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
This function signals the beginning of a collection of changes to the Acoustic Scene, intended to be heard at the same time. After calling MLAudioBeginAcousticSceneUpdate, any subsequent calls to functions in the ACOUSTICS section of this audio API will be deferred, and will be applied simultaneously when MLAudioEndAcousticSceneUpdate is called.
API Level:
- 20
MLAudioEndAcousticSceneUpdate
MLResult MLAudioEndAcousticSceneUpdate()
Resumes the processing of changes to the Acoustic Scene.
Returns
| MLResult | MLResult_Ok | Successfully ended the Acoustic Scene update. |
| MLResult | MLResult_UnspecifiedFailure | Internal error. |
| MLResult | MLAudioResult_HandleNotFound | No custom scene exists for client. |
Required Permissions:
- None
This function signals the ending of a collection of changes to the Acoustic Scene, causing them to be heard at the same time. After calling MLAudioBeginAcousticSceneUpdate, any subsequent calls to functions in the ACOUSTICS section of this audio API will be deferred, and will be applied simultaneously when MLAudioEndAcousticSceneUpdate is called.
API Level:
- 20
MLAudioSetAcousticSceneMapEnable
MLResult MLAudioSetAcousticSceneMapEnable(
bool is_enabled
)
Sets whether spatial rendering emulates the acoustics of the user's environment.
Parameters
| bool | is_enabled | If true, the Acoustic Map will be enabled. |
Returns
| MLResult | MLResult_Ok | Successfully set the value. |
| MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
The Acoustic Map is a device-curated representation of the acoustics of the local physical environment. Enabling the Acoustic Map makes virtual objects sound as though they exist in the local physical environment.
API Level:
- 20
MLAudioGetAcousticSceneMapEnable
MLResult MLAudioGetAcousticSceneMapEnable(
bool * out_is_enabled
)
Queries whether spatial rendering emulates the acoustics of the user's environment.
Parameters
| bool * | out_is_enabled | If true, the Acoustic Map is enabled. |
Returns
| MLResult | MLResult_Ok | Successfully retrieved the value. |
| MLResult | MLResult_InvalidParam | If input parameter is invalid. |
| MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
The Acoustic Map is a device-curated representation of the acoustics of the local physical environment. When the Acoustic Map is enabled, virtual objects sound as though they exist in the local physical environment.
API Level:
- 20
MLAudioSetAcousticSceneTransmissionDefault
MLResult MLAudioSetAcousticSceneTransmissionDefault(
const MLAudioMultibandLevel * transmission
)
Sets the default attenuation applied to obstructed spatial sounds.
Parameters
| const MLAudioMultibandLevel * | transmission | MLAudioMultibandLevel struct to set the default properties. |
Returns
| MLResult | MLResult_Ok | Successfully set the default properties. |
| MLResult | MLResult_InvalidParam | If input parameter is invalid. |
| MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
The propagation of virtual sound in space can be obstructed by virtual objects created by the client, or by the virtual representation of the local physical environment. In cases where these obstructions have no transmission properties defined, the Acoustic Scene default transmission properties set by this function are used. Transmission properties are specified by an MLAudioMultibandLevel struct in which values of [1, (1, 1, 1)] represent fully unobstructed, while [0, (1, 1, 1)] or [1, (0, 0, 0)] both represent fully obstructed.
API Level:
- 20
MLAudioGetAcousticSceneTransmissionDefault
MLResult MLAudioGetAcousticSceneTransmissionDefault(
MLAudioMultibandLevel * out_transmission
)
Queries the default attenuation applied to obstructed spatial sounds.
Parameters
| MLAudioMultibandLevel * | out_transmission | MLAudioMultibandLevel struct to be filled with the default properties. |
Returns
| MLResult | MLResult_Ok | Successfully retrieved the default properties. |
| MLResult | MLResult_InvalidParam | If input parameter is invalid. |
| MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
The propagation of virtual sound in space can be obstructed by virtual objects created by the client, or by the virtual representation of the local physical environment. In cases where these obstructions have no transmission properties defined, the Acoustic Scene default transmission properties queried by this function are used. Transmission properties are specified by an MLAudioMultibandLevel struct in which values of [1, (1, 1, 1)] represent fully unobstructed, while [0, (1, 1, 1)] or [1, (0, 0, 0)] both represent fully obstructed.
API Level:
- 20
MLAudioSetAcousticSceneDispersionDefault
MLResult MLAudioSetAcousticSceneDispersionDefault(
const MLAudioDispersionProperties * properties
)
Sets the default dispersion properties, which control the rendering of clustered reflections.
Parameters
| const MLAudioDispersionProperties * | properties | MLAudioDispersionProperties struct to set the default properties. |
Returns
| MLResult | MLResult_Ok | Successfully set the default properties. |
| MLResult | MLResult_InvalidParam | If input parameter is invalid. |
| MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
The propagation model for a spatial sound has 4 parts: direct path, reflections, dispersion, and reverb. Dispersion comprises the clustered non-discrete reflections that precede the reverb. In areas where no dispersion properties are explicitly defined, the Acoustic Scene default dispersion properties set by this function are used. Dispersion properties are specified by an MLAudioDispersionProperties struct which specifies a gain using an MLAudioMultibandLevel, and a pre-delay. If the pre-delay setting is greater than the pre-delay of the default reverb properties, it will be clamped to an equal value.
This 'AcousticScene' API sets a shared acoustic processing effect that is applied to multiple spatial sounds. To set the per-sound mix levels for this effect, see the corresponding 'SpatialSoundSendLevel' API which is MLAudioSetSpatialSoundDispersionSendLevel.
API Level:
- 20
MLAudioGetAcousticSceneDispersionDefault
MLResult MLAudioGetAcousticSceneDispersionDefault(
MLAudioDispersionProperties * out_properties
)
Queries the default dispersion properties, which control the rendering of clustered reflections.
Parameters
| MLAudioDispersionProperties * | out_properties | MLAudioDispersionProperties struct to be filled with the default properties. |
Returns
| MLResult | MLResult_Ok | Successfully retrieved the default properties. |
| MLResult | MLResult_InvalidParam | If input parameter is invalid. |
| MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
The propagation model for a spatial sound has 4 parts: direct path, reflections, dispersion, and reverb. Dispersion comprises the clustered non-discrete reflections that precede the reverb. In areas where no dispersion properties are explicitly defined, the Acoustic Scene default dispersion properties queried by this function are used. Dispersion properties are specified by an MLAudioDispersionProperties struct which specifies a gain using an MLAudioMultibandLevel, and a pre-delay.
This 'AcousticScene' API queries a shared acoustic processing effect that is applied to multiple spatial sounds. To query the per-sound mix levels for this effect, see the corresponding 'SpatialSoundSendLevel' API which is MLAudioGetSpatialSoundDispersionSendLevel.
API Level:
- 20
MLAudioSetAcousticSceneReverbDefault
MLResult MLAudioSetAcousticSceneReverbDefault(
const MLAudioReverbProperties * properties
)
Sets the default reverb properties, which control the rendering of late reverberation.
Parameters
| const MLAudioReverbProperties * | properties | MLAudioReverbProperties struct to set the properties. |
Returns
| MLResult | MLResult_Ok | Successfully set the default properties. |
| MLResult | MLResult_InvalidParam | If input parameter is invalid. |
| MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
The propagation model for a spatial sound has 4 parts: direct path, reflections, dispersion, and reverb. The reverb comprises late stage sound decay caused by the acoustic space. In areas where no reverb properties are explicitly defined, the Acoustic Scene default reverb properties set by this function are used. Reverb properties are specified by an MLAudioReverbProperties struct which specifies a gain using an MLAudioMultibandLevel, a pre-delay, and the time and frequency contour of the reverb envelope. If the pre-delay setting is less than the pre-delay of the default dispersion properties, it will be clamped to an equal value.
This 'AcousticScene' API sets a shared acoustic processing effect that is applied to multiple spatial sounds. To set the per-sound mix levels for this effect, see the corresponding 'SpatialSoundSendLevel' API which is MLAudioSetSpatialSoundReverbSendLevel.
API Level:
- 20
MLAudioGetAcousticSceneReverbDefault
MLResult MLAudioGetAcousticSceneReverbDefault(
MLAudioReverbProperties * out_properties
)
Queries the default reverb properties, which control the rendering of late reverberation.
Parameters
| MLAudioReverbProperties * | out_properties | MLAudioReverbProperties struct to be filled with the default properties. |
Returns
| MLResult | MLResult_Ok | Successfully retrieved the default properties. |
| MLResult | MLResult_InvalidParam | If input parameter is invalid. |
| MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
The propagation model for a spatial sound has 4 parts: direct path, reflections, dispersion, and reverb. The reverb comprises late stage sound decay caused by the acoustic space. In areas where no reverb properties are explicitly defined, the Acoustic Scene default reverb properties queried by this function are used. Reverb properties are specified by an MLAudioReverbProperties struct which specifies a gain using an MLAudioMultibandLevel, a pre-delay, and the time and frequency contour of the reverb envelope.
This 'AcousticScene' API queries a shared acoustic processing effect that is applied to multiple spatial sounds. To query the per-sound mix levels for this effect, see the corresponding 'SpatialSoundSendLevel' API which is MLAudioGetSpatialSoundReverbSendLevel.
API Level:
- 20
MLAudioGetChangedAcousticMap
MLResult MLAudioGetChangedAcousticMap(
uint32_t prev_map_tag,
uint8_t ** out_map_data,
uint32_t * out_map_size_in_bytes,
uint32_t * out_map_tag
)
INTERNAL USE ONLY: Retrieves the Acoustic Map if it has been updated since the previous call.
Parameters
| uint32_t | prev_map_tag | The map tag received in previous call. |
| uint8_t ** | out_map_data | Retrieved pointer to serialized copy of Acoustic Map data if prev_map_tag != out_map_tag. |
| uint32_t * | out_map_size_in_bytes | Retrieved length of serialized Acoustic Map data in bytes. |
| uint32_t * | out_map_tag | Retrieved current map tag to be passed in subsequent call. |
Returns
| MLResult | MLResult_Ok | Successfully retrieved properties. |
| MLResult | MLResult_InvalidParam | If input parameter is invalid. |
| MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
Acoustic Map data is a device-curated representation of the acoustics of the local physical environment. The out_map_data argument will point to a serialized copy of the map and must deleted after use. This function is intended for internal use and should not be called by clients of the MLAudio API.
API Level:
- 20