Spatial Sound
Module: Audio / Audio Definitions / Audio Output / Acoustics
Functions
Name | |
---|---|
MLResult | MLAudioSetSpatialSoundEnable(MLHandle handle, bool is_enabled) Sets whether a sound output is enabled as a spatial sound. |
MLResult | MLAudioGetSpatialSoundEnable(MLHandle handle, bool * out_is_enabled) Queries whether a sound output is enabled as a spatial sound. |
MLResult | MLAudioSetSpatialSoundPosition(MLHandle handle, uint32_t channel, const MLVec3f * position) Sets the 3D position for one channel of a spatial sound. |
MLResult | MLAudioGetSpatialSoundPosition(MLHandle handle, uint32_t channel, MLVec3f * out_position) Queries the 3D position of one channel of a spatial sound. |
MLResult | MLAudioSetSpatialSoundDirection(MLHandle handle, uint32_t channel, const MLQuaternionf * direction) Sets the 3D direction for one channel of a spatial sound. |
MLResult | MLAudioGetSpatialSoundDirection(MLHandle handle, uint32_t channel, MLQuaternionf * out_direction) Queries the 3D direction of one channel of a spatial sound. |
MLResult | MLAudioSetSpatialSoundBillboarding(MLHandle handle, bool is_billboarding) Enables or disables billboarding for all channels of a spatial sound. |
MLResult | MLAudioGetSpatialSoundBillboarding(MLHandle handle, bool * out_is_billboarding) Queries whether billboarding is enabled for a spatial sound. |
MLResult | MLAudioSetSpatialSoundObstruction(MLHandle handle, uint32_t channel, const MLAudioObstruction left_ear, const MLAudioObstruction right_ear) Sets the direct path obstruction status for one channel of a spatial sound. |
MLResult | MLAudioGetSpatialSoundObstruction(MLHandle handle, uint32_t channel, MLAudioObstruction out_left_ear, MLAudioObstruction out_right_ear) Queries the direct path obstruction status for one channel of a spatial sound. |
MLResult | MLAudioSetSpatialSoundObstructionOverride(MLHandle handle, const MLAudioMultibandLevel * override) Sets the extent to which a spatial sound is exempt from obstruction effects. |
MLResult | MLAudioGetSpatialSoundObstructionOverride(MLHandle handle, MLAudioMultibandLevel * out_override) Queries the extent to which a spatial sound is exempt from obstruction effects. |
MLResult | MLAudioSetSpatialSoundDistanceAttenuation(MLHandle handle, uint32_t channel, const MLAudioSpatialSoundDistanceProperties * properties) Sets the behavior by which a spatial sound is attenuated due to distance. |
MLResult | MLAudioGetSpatialSoundDistanceAttenuation(MLHandle handle, uint32_t channel, MLAudioSpatialSoundDistanceProperties * out_properties) Queries the behavior by which a spatial sound is attenuated due to distance. |
MLResult | MLAudioSetSpatialSoundRadiation(MLHandle handle, uint32_t channel, const MLAudioSpatialSoundRadiationProperties * properties) Sets a radiation pattern that describes the directionality for one channel of a spatial sound. |
MLResult | MLAudioGetSpatialSoundRadiation(MLHandle handle, uint32_t channel, MLAudioSpatialSoundRadiationProperties * out_properties) Queries the radiation pattern that describes the directionality for one channel of a spatial sound. |
MLResult | MLAudioSetSpatialSoundDirectLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level) Sets the gain and 3-band EQ on the Direct Path for one channel of a spatial sound. |
MLResult | MLAudioGetSpatialSoundDirectLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level) Queries the gain and 3-band EQ on the Direct Path for one channel of a spatial sound. |
MLResult | MLAudioSetSpatialSoundIndirectLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level) Sets a gain and 3-band EQ applied to all indirect paths for one channel of a spatial sound. |
MLResult | MLAudioGetSpatialSoundIndirectLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level) Queries the gain and 3-band EQ applied to all indirect paths for one channel of a spatial sound. |
MLResult | MLAudioSetSpatialSoundDispersionSendLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level) Sets the gain and 3-band EQ on the Dispersion stage for one channel of a spatial sound. |
MLResult | MLAudioGetSpatialSoundDispersionSendLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level) Queries the gain and 3-band EQ on the Dispersion stage for one channel of a spatial sound. |
MLResult | MLAudioSetSpatialSoundReverbSendLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level) Sets the gain and 3-band EQ on the Reverb stage for one channel of a spatial sound. |
MLResult | MLAudioGetSpatialSoundReverbSendLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level) Queries the gain and 3-band EQ on the Reverb stage for one channel of a spatial sound. |
MLResult | MLAudioSetSpatialSoundHeadRelative(MLHandle handle, bool is_head_relative) Sets whether the position and direction for a spatial sound are interpreted in head-relative coordinates. |
MLResult | MLAudioGetSpatialSoundHeadRelative(MLHandle handle, bool * out_is_head_relative) Queries whether the position and direction for a spatial sound are interpreted in head-relative coordinates. |
MLResult | MLAudioGetSpatialRaycastRequests(MLAudioRaycastRequest * out_raycast_requests, uint32_t out_request_count) Queries a list of ID-tracked requests for raycast operations. |
MLResult | MLAudioSetSpatialRaycastResults(MLAudioRaycastResult * raycast_results, uint32_t result_count) Sets the ID-tracked results for previously requested raycast operations. |
Detailed Description
SPATIAL SOUND.
Functions Documentation
MLAudioSetSpatialSoundEnable
MLResult MLAudioSetSpatialSoundEnable(
MLHandle handle,
bool is_enabled
)
Sets whether a sound output is enabled as a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
bool | is_enabled | If true, spatial audio will be enabled for a sound output. |
Returns
MLResult | MLResult_Ok | Successfully set the value. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Enabling a sound output as a spatial sound will cause each of its channels to be rendered at a per-channel-specified position in 3D space. Spatial sounds also have other customizable per-channel properties such as direction, radiation, distance attenuation, etc. All these properties can be set whether or not a sound output is currently enabled as a spatial sound. Simulated acoustics for spatial sounds are defined by the client's Acoustic Scene. By default, sound outputs are not enabled as spatial sounds.
MLAudioGetSpatialSoundEnable
MLResult MLAudioGetSpatialSoundEnable(
MLHandle handle,
bool * out_is_enabled
)
Queries whether a sound output is enabled as a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
bool * | out_is_enabled | If true, spatial audio is be enabled for a sound output. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully retrieved the value. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
For a sound output enabled as a spatial sound, each of its channels will be rendered at a per-channel-specified position in 3D space. Spatial sounds also have other customizable per-channel properties such as direction, radiation, distance attenuation, etc. All these properties can be queried whether or not a sound output is currently enabled as a spatial sound. Simulated acoustics for spatial sounds are defined by the client's Acoustic Scene. By default, sound outputs are not enabled as spatial sounds.
MLAudioSetSpatialSoundPosition
MLResult MLAudioSetSpatialSoundPosition(
MLHandle handle,
uint32_t channel,
const MLVec3f * position
)
Sets the 3D position for one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
const MLVec3f * | position | Struct to set the position. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully set the properties. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Each channel of a spatial sound is rendered at a position specified by an x,y,z point in cartesian coordinates. Positive x is to the right, positive y is up, and positive z is to the rear.
Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
MLAudioGetSpatialSoundPosition
MLResult MLAudioGetSpatialSoundPosition(
MLHandle handle,
uint32_t channel,
MLVec3f * out_position
)
Queries the 3D position of one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
MLVec3f * | out_position | Struct to be filled with the position. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully retrieved the properties. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Each channel of a spatial sound is rendered at a position specified by an x,y,z point in cartesian coordinates. Positive x is to the right, positive y is up, and positive z is to the rear.
Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
MLAudioSetSpatialSoundDirection
MLResult MLAudioSetSpatialSoundDirection(
MLHandle handle,
uint32_t channel,
const MLQuaternionf * direction
)
Sets the 3D direction for one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
const MLQuaternionf * | direction | Struct to set the radiation direction. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully set the properties. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed to set radiation direction due to an internal configuration error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Each channel of a spatial sound radiates into 3D space with a pattern whose center is specified by the sound channel's direction. The radiation pattern can be set by calling MLAudioSetSpatialSoundRadiation. By default, sounds have billboarding enabled, which overrides the direction for every channel such that they always face the listener. Billboarding can be disabled by calling MLAudioSetSpatialSoundBillboarding.
Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
MLAudioGetSpatialSoundDirection
MLResult MLAudioGetSpatialSoundDirection(
MLHandle handle,
uint32_t channel,
MLQuaternionf * out_direction
)
Queries the 3D direction of one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
MLQuaternionf * | out_direction | Struct to be filled with the radiation direction. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully retrieved the properties. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Each channel of a spatial sound radiates into 3D space with a pattern whose center is specified by the sound channel's direction. The radiation pattern can be set by calling MLAudioSetSpatialSoundRadiation. By default, sounds have billboarding enabled, which overrides the direction for every channel such that they always face the listener. Billboarding can be disabled by calling MLAudioSetSpatialSoundBillboarding.
Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
MLAudioSetSpatialSoundBillboarding
MLResult MLAudioSetSpatialSoundBillboarding(
MLHandle handle,
bool is_billboarding
)
Enables or disables billboarding for all channels of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
bool | is_billboarding | If true, billboarding will be enabled. |
Returns
MLResult | MLResult_OK | Successfully set the value. |
MLResult | MLAudioResult_HandleNotFound | Unable to find resource handle. |
MLResult | MLAudioResult_OperationUnavailable | Operation is unavailable for this sound output. |
Required Permissions:
- None
Billboarding causes each channel of a spatial sound to always face the listener. When billboarding is enabled, channel directions set using MLAudioSetSpatialSoundDirection are ignored. Billboarding gives the impression of an omnidirectional sound, while allowing radiation properties set using MLAudioSetSpatialSoundRadiation to affect this sound's contribution to dispersion and reverb. By default, billboarding is enabled on newly created sound outputs.
API Level:
- 20
MLAudioGetSpatialSoundBillboarding
MLResult MLAudioGetSpatialSoundBillboarding(
MLHandle handle,
bool * out_is_billboarding
)
Queries whether billboarding is enabled for a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
bool * | out_is_billboarding | If true, billboarding is enabled. |
Returns
MLResult | MLResult_OK | Successfully retrieved the value. |
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_OperationUnavailable | Operation is unavailable for this sound output. |
Required Permissions:
- None
Billboarding causes each channel of a spatial sound to always face the listener. When billboarding is enabled, channel directions set using MLAudioSetSpatialSoundDirection are ignored. Billboarding gives the impression of an omnidirectional sound, while allowing radiation properties set using MLAudioSetSpatialSoundRadiation to affect this sound's contribution to dispersion and reverb. By default, billboarding is enabled on newly created sound outputs.
API Level:
- 20
MLAudioSetSpatialSoundObstruction
MLResult MLAudioSetSpatialSoundObstruction(
MLHandle handle,
uint32_t channel,
const MLAudioObstruction * left_ear,
const MLAudioObstruction * right_ear
)
Sets the direct path obstruction status for one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
const MLAudioObstruction * | left_ear | MLAudioObstruction struct to set the direct path obstruction properties for the left ear. |
const MLAudioObstruction * | right_ear | MLAudioObstruction struct to set the direct path obstruction properties for the right ear. |
Returns
MLResult | MLResult_Ok | Successfully set the properties. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLAudioResult_HandleNotFound | Handle not found. |
MLResult | MLAudioResult_OperationUnavailable | Operation is unavailable for this sound output. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_InternalConfigError | Internal configuration error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
THIS IS AN INTERNAL FUNCTION INTENDED FOR ENGINE DEVELOPMENT ONLY.
Spatial sounds are subject to obstruction effects by real and virtual objects. Each channel of the spatial sound output contains a left and right ear MLAudioObstruction for the direct path, which can be set by repeated calls to this function. The obstruction effect for each channel of a spatial sound is determined by this set of MLAudioObstruction structs and a set of transmission properties. The MLAudioObstruction hit_point determines which transmission properties to apply and the MLAudioObstruction factor determines the extent to which these properties are applied. Transmission properties can be set globally for the scene using MLAudioSetAcousticSceneTransmissionDefault.
Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
API Level:
- 20
MLAudioGetSpatialSoundObstruction
MLResult MLAudioGetSpatialSoundObstruction(
MLHandle handle,
uint32_t channel,
MLAudioObstruction * out_left_ear,
MLAudioObstruction * out_right_ear
)
Queries the direct path obstruction status for one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
MLAudioObstruction * | out_left_ear | MLAudioObstruction struct to be filled with the obstruction properties for the left ear. |
MLAudioObstruction * | out_right_ear | MLAudioObstruction struct to be filled with the obstruction properties for the right ear. |
Returns
MLResult | MLResult_Ok | Successfully retrieved the properties. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLAudioResult_HandleNotFound | Handle not found. |
MLResult | MLAudioResult_OperationUnavailable | Operation is unavailable for this sound output. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_InternalConfigError | Internal config error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
THIS IS AN INTERNAL FUNCTION INTENDED FOR ENGINE DEVELOPMENT ONLY.
Spatial sounds are subject to obstruction effects by real and virtual objects. Each channel of the spatial sound output contains a left and right ear MLAudioObstruction for the direct path, which can be queried by this function. The obstruction effect for each channel of a spatial sound is determined by this set of MLAudioObstruction structs and a set of transmission properties. The MLAudioObstruction hit_point determines which transmission properties to apply and the MLAudioObstruction factor determines the extent to which these properties are applied. Transmission properties can be set globally for the scene using MLAudioSetAcousticSceneTransmissionDefault.
Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
API Level:
- 20
MLAudioSetSpatialSoundObstructionOverride
MLResult MLAudioSetSpatialSoundObstructionOverride(
MLHandle handle,
const MLAudioMultibandLevel * override
)
Sets the extent to which a spatial sound is exempt from obstruction effects.
Parameters
MLHandle | handle | MLHandle of the sound output. |
const MLAudioMultibandLevel * | override | MLAudioMultibandLevel struct to set the override properties. |
Returns
MLResult | MLResult_OK | Successfully set the properties. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLAudioResult_HandleNotFound | Unable to find resource handle. |
MLResult | MLAudioResult_OperationUnavailable | Operation is unavailable for this sound output. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_InternalConfigError | Internal config error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
This function provides a way to prevent obstruction effects on specified spatial sounds. The extent to which a spatial sound is exempt from obstruction effects is specified per band using an MLAudioMultibandLevel struct. The value for each band determines that band's interpolation between its computed obstruction effect, represented by 0, and no obstruction effect, represented by 1. For example, to completely exempt a spatial sound from obstruction effects, set the override argument to [1,1,1,1], and to fully allow obstruction effects set to [0,0,0,0]. On newly created spatial sounds, obstruction override defaults to [0,0,0,0]. For multi-channel spatial sounds, all channels are affected equally by this function.
API Level:
- 20
MLAudioGetSpatialSoundObstructionOverride
MLResult MLAudioGetSpatialSoundObstructionOverride(
MLHandle handle,
MLAudioMultibandLevel * out_override
)
Queries the extent to which a spatial sound is exempt from obstruction effects.
Parameters
MLHandle | handle | MLHandle of the sound output. |
MLAudioMultibandLevel * | out_override | MLAudioMultibandLevel struct to be filled with the override properties. |
Returns
MLResult | MLResult_OK | Successfully retrieved the properties. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLAudioResult_HandleNotFound | Unable to find resource handle. |
MLResult | MLAudioResult_OperationUnavailable | Operation is unavailable for this sound output. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_InternalConfigError | Internal config error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
Obstruction override provides a way to prevent obstruction effects on specified spatial sounds. The extent to which a spatial sound is exempt from obstruction effects is specified per band using an MLAudioMultibandLevel struct. The value for each band determines that band's interpolation between its computed obstruction effect, represented by 0, and no obstruction effect, represented by 1. For example, a spatial sound completely exempt from obstruction effects has an override value of [1,1,1,1], and a spatial sound fully subject to obstruction effects has an override value of [0,0,0,0]. For multi-channel spatial sounds, all channels are affected equally by the override value.
API Level:
- 20
MLAudioSetSpatialSoundDistanceAttenuation
MLResult MLAudioSetSpatialSoundDistanceAttenuation(
MLHandle handle,
uint32_t channel,
const MLAudioSpatialSoundDistanceProperties * properties
)
Sets the behavior by which a spatial sound is attenuated due to distance.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
const MLAudioSpatialSoundDistanceProperties * | properties | MLAudioSpatialSoundDistanceProperties struct to set the properties. |
Returns
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_Ok | Successfully set the properties. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_HandleNotFound | Handle not found. |
MLResult | MLAudioResult_InternalConfigError | Internal config error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
The behavior for distance attenuation is specified by an MLAudioSpatialSoundDistanceProperties struct provided as the properties argument of this function. Within this struct the min_distance specifies the distance from the listener beyond which a spatial sound starts attenuating with distance. The max_distance specifies the distance from the listener beyond which no further attenuation occurs. Between min_distance and max_distance a spatial sound will be attenuated with distance according to the rolloff_factor. A rolloff_factor of 1 will produce distance attenuation that approximates real world distance attenuation. A rolloff_factor greater than 1 will produce distance attenuation that rolls off faster as distance increases, while less than 1 will produce distance attenuation that rolls off more gradually. If rolloff_factor is 0, no distance attenuation will be applied.
Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
API Level:
- 20
MLAudioGetSpatialSoundDistanceAttenuation
MLResult MLAudioGetSpatialSoundDistanceAttenuation(
MLHandle handle,
uint32_t channel,
MLAudioSpatialSoundDistanceProperties * out_properties
)
Queries the behavior by which a spatial sound is attenuated due to distance.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
MLAudioSpatialSoundDistanceProperties * | out_properties | MLAudioSpatialSoundDistanceProperties struct to be filled with the properties. |
Returns
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_Ok | Successfully retrieved the properties. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_HandleNotFound | Handle not found. |
MLResult | MLAudioResult_InternalConfigError | Internal config error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
The behavior for distance attenuation is specified by an MLAudioSpatialSoundDistanceProperties struct reported by the out_properties argument of this function. Within this struct the min_distance specifies the distance from the listener beyond which a spatial sound starts attenuating with distance. The max_distance specifies the distance from the listener beyond which no further attenuation occurs. Between min_distance and max_distance a spatial sound will be attenuated with distance according to the rolloff_factor. A rolloff_factor of 1 will produce distance attenuation that approximates real world distance attenuation. A rolloff_factor greater than 1 will produce distance attenuation that rolls off faster as distance increases, while less than 1 will produce distance attenuation that rolls off more gradually. If rolloff_factor is 0, no distance attenuation will be applied.
Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
API Level:
- 20
MLAudioSetSpatialSoundRadiation
MLResult MLAudioSetSpatialSoundRadiation(
MLHandle handle,
uint32_t channel,
const MLAudioSpatialSoundRadiationProperties * properties
)
Sets a radiation pattern that describes the directionality for one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
const MLAudioSpatialSoundRadiationProperties * | properties | MLAudioSpatialSoundRadiationProperties struct to set the properties. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully set the properties. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Each channel of a spatial sound has a dual cone radiation pattern specified by an MLAudioSpatialSoundRadiationProperties struct. The radiation pattern is oriented toward the listener for all channels if billboarding is enabled, or in the direction set by MLAudioSetSpatialSoundDirection for each channel if billboarding is disabled. The default values for the MLAudioSpatialSoundRadiationProperties struct were chosen to model a human speaking.
Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
API Level:
- 20
MLAudioGetSpatialSoundRadiation
MLResult MLAudioGetSpatialSoundRadiation(
MLHandle handle,
uint32_t channel,
MLAudioSpatialSoundRadiationProperties * out_properties
)
Queries the radiation pattern that describes the directionality for one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
MLAudioSpatialSoundRadiationProperties * | out_properties | MLAudioSpatialSoundRadiationProperties struct to be filled with the properties. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully retrieved the properties. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Each channel of a spatial sound has a dual cone radiation pattern specified by an MLAudioSpatialSoundRadiationProperties struct. The radiation pattern is oriented toward the listener for all channels if billboarding is enabled, or in the direction set by MLAudioSetSpatialSoundDirection for each channel if billboarding is disabled.
Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
API Level:
- 20
MLAudioSetSpatialSoundDirectLevel
MLResult MLAudioSetSpatialSoundDirectLevel(
MLHandle handle,
uint32_t channel,
const MLAudioMultibandLevel * level
)
Sets the gain and 3-band EQ on the Direct Path for one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
const MLAudioMultibandLevel * | level | MLAudioMultibandLevel struct to set the gain and eq properties. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully set the properties. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.
The Direct Level is applied to the sound traveling directly from the source to the listener. The gain and 3-band EQ for this stage is specified by an MLAudioMultibandLevel struct.
Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
API Level:
- 20
MLAudioGetSpatialSoundDirectLevel
MLResult MLAudioGetSpatialSoundDirectLevel(
MLHandle handle,
uint32_t channel,
MLAudioMultibandLevel * out_level
)
Queries the gain and 3-band EQ on the Direct Path for one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
MLAudioMultibandLevel * | out_level | MLAudioMultibandLevel struct to be filled with the gain and eq properties. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully retrieved the properties. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.
The Direct Level is applied to the sound traveling directly from the source to the listener. The gain and 3-band EQ for this stage is specified by an MLAudioMultibandLevel struct.
Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
API Level:
- 20
MLAudioSetSpatialSoundIndirectLevel
MLResult MLAudioSetSpatialSoundIndirectLevel(
MLHandle handle,
uint32_t channel,
const MLAudioMultibandLevel * level
)
Sets a gain and 3-band EQ applied to all indirect paths for one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
const MLAudioMultibandLevel * | level | MLAudioMultibandLevel struct to set the gain and eq properties. |
Returns
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_Ok | Successfully set the properties. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_HandleNotFound | Handle not found. |
MLResult | MLAudioResult_InternalConfigError | Internal config error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.
The Indirect Level is applied to the Reflections, Dispersion, and Reverb stages as a group, combining with the level specified for each individual stage. The Reflections stage consists of discrete reflections off of distinct surfaces. The Dispersion stage consists of clustered groups of late reflections smeared in time. The Reverb stage consists of the well-mixed reverberation tail of the sound. The gain and 3-band EQ applied to these stages as a group is specified by an MLAudioMultibandLevel struct.
Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
API Level:
- 20
MLAudioGetSpatialSoundIndirectLevel
MLResult MLAudioGetSpatialSoundIndirectLevel(
MLHandle handle,
uint32_t channel,
MLAudioMultibandLevel * out_level
)
Queries the gain and 3-band EQ applied to all indirect paths for one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
MLAudioMultibandLevel * | out_level | MLAudioMultibandLevel struct to be filled with the gain and eq properties. |
Returns
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_Ok | Successfully retrieved the properties. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_HandleNotFound | Handle not found. |
MLResult | MLAudioResult_InternalConfigError | Internal config error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.
The Indirect Level is applied to the Reflections, Dispersion, and Reverb stages as a group, combining with the level specified for each individual stage. The Reflections stage consists of discrete reflections off of distinct surfaces. The Dispersion stage consists of clustered groups of late reflections smeared in time. The Reverb stage consists of the well-mixed reverberation tail of the sound. The gain and 3-band EQ applied to these stages as a group is specified by an MLAudioMultibandLevel struct.
Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
API Level:
- 20
MLAudioSetSpatialSoundDispersionSendLevel
MLResult MLAudioSetSpatialSoundDispersionSendLevel(
MLHandle handle,
uint32_t channel,
const MLAudioMultibandLevel * level
)
Sets the gain and 3-band EQ on the Dispersion stage for one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
const MLAudioMultibandLevel * | level | MLAudioMultibandLevel struct to set the gain and eq properties. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully set the properties. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.
The Dispersion stage consists of clustered groups of late reflections smeared in time. The gain and 3-band EQ for this stage is specified by an MLAudioMultibandLevel struct.
This 'SpatialSoundSendLevel' API sets the amount of signal that a particular sound feeds into a shared acoustic processing effect. To set the properties of the processing effect itself, see the corresponding 'AcousticScene' API which is MLAudioSetAcousticSceneDispersionDefault.
Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
API Level:
- 20
MLAudioGetSpatialSoundDispersionSendLevel
MLResult MLAudioGetSpatialSoundDispersionSendLevel(
MLHandle handle,
uint32_t channel,
MLAudioMultibandLevel * out_level
)
Queries the gain and 3-band EQ on the Dispersion stage for one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
MLAudioMultibandLevel * | out_level | MLAudioMultibandLevel struct to be filled with the gain and eq properties. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully retrieved the properties. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.
The Dispersion stage consists of clustered groups of late reflections smeared in time. The gain and 3-band EQ for this stage is specified by an MLAudioMultibandLevel struct.
This 'SpatialSoundSendLevel' API queries the amount of signal that a particular sound feeds into a shared acoustic processing effect. To query the properties of the processing effect itself, see the corresponding 'AcousticScene' API which is MLAudioGetAcousticSceneDispersionDefault.
Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
API Level:
- 20
MLAudioSetSpatialSoundReverbSendLevel
MLResult MLAudioSetSpatialSoundReverbSendLevel(
MLHandle handle,
uint32_t channel,
const MLAudioMultibandLevel * level
)
Sets the gain and 3-band EQ on the Reverb stage for one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
const MLAudioMultibandLevel * | level | MLAudioMultibandLevel struct to set the gain and eq properties. |
Returns
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_Ok | Successfully set the properties. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_HandleNotFound | Handle not found. |
MLResult | MLAudioResult_InternalConfigError | Internal config error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.
The Reverb stage consists of the well-mixed reverberation tail of the sound. The gain and 3-band EQ for this stage is specified by an MLAudioMultibandLevel struct.
This 'SpatialSoundSendLevel' API sets the amount of signal that a particular sound feeds into a shared acoustic processing effect. To set the properties of the processing effect itself, see the corresponding 'AcousticScene' API which is MLAudioSetAcousticSceneReverbDefault.
Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
API Level:
- 20
MLAudioGetSpatialSoundReverbSendLevel
MLResult MLAudioGetSpatialSoundReverbSendLevel(
MLHandle handle,
uint32_t channel,
MLAudioMultibandLevel * out_level
)
Queries the gain and 3-band EQ on the Reverb stage for one channel of a spatial sound.
Parameters
MLHandle | handle | MLHandle of the sound output. |
uint32_t | channel | Channel of the sound output. |
MLAudioMultibandLevel * | out_level | MLAudioMultibandLevel struct to be filled with the gain and eq properties. |
Returns
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_Ok | Successfully retrieved the properties. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_HandleNotFound | Handle not found. |
MLResult | MLAudioResult_InternalConfigError | Internal config error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.
The Reverb stage consists of the well-mixed reverberation tail of the sound. The gain and 3-band EQ for this stage is specified by an MLAudioMultibandLevel struct.
This 'SpatialSoundSendLevel' API queries the amount of signal that a particular sound feeds into a shared acoustic processing effect. To query the properties of the processing effect itself, see the corresponding 'AcousticScene' API which is MLAudioGetAcousticSceneReverbDefault.
Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.
API Level:
- 20
MLAudioSetSpatialSoundHeadRelative
MLResult MLAudioSetSpatialSoundHeadRelative(
MLHandle handle,
bool is_head_relative
)
Sets whether the position and direction for a spatial sound are interpreted in head-relative coordinates.
Parameters
MLHandle | handle | MLHandle of the sound output. |
bool | is_head_relative | If true, coordinates will be head-relative. |
Returns
MLResult | MLResult_Ok | Successfully set the value. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown failure. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
A head-relative coordinate system has an origin and orientation locked to the user's head center and forward direction. For spatial sounds with head-relative enabled, the position and direction as specified by MLAudioSetSpatialSoundPosition and MLAudioSetSpatialSoundDirection (and reported by MLAudioGetSpatialSoundPosition and MLAudioGetSpatialSoundDirection) are interpreted within such a coordinate system. For spatial sounds with head-relative disabled, the position and direction are interpreted within the world coordinate system defined by the platform. By default, head-relative is disabled for spatial sounds.
API Level:
- 7
MLAudioGetSpatialSoundHeadRelative
MLResult MLAudioGetSpatialSoundHeadRelative(
MLHandle handle,
bool * out_is_head_relative
)
Queries whether the position and direction for a spatial sound are interpreted in head-relative coordinates.
Parameters
MLHandle | handle | MLHandle of the sound output. |
bool * | out_is_head_relative | If true, coordinates are head-relative. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully retrieved the value. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown failure. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
A head-relative coordinate system has an origin and orientation locked to the user's head center and forward direction. For spatial sounds with head-relative enabled, the position and direction as specified by MLAudioSetSpatialSoundPosition and MLAudioSetSpatialSoundDirection (and reported by MLAudioGetSpatialSoundPosition and MLAudioGetSpatialSoundDirection) are interpreted within such a coordinate system. For spatial sounds with head-relative disabled, the position and direction are interpreted within the world coordinate system defined by the platform. By default, head-relative is disabled for spatial sounds.
API Level:
- 20
MLAudioGetSpatialRaycastRequests
MLResult MLAudioGetSpatialRaycastRequests(
MLAudioRaycastRequest ** out_raycast_requests,
uint32_t * out_request_count
)
Queries a list of ID-tracked requests for raycast operations.
Parameters
MLAudioRaycastRequest ** | out_raycast_requests | MLAudioRaycastRequest struct to be filled with requests for raycast operation. |
uint32_t * | out_request_count | Value to be filled with number of raycast operations requested. |
Returns
MLResult | MLResult_Ok | Successfully set the properties. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_InternalConfigError | Internal config error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
For a custom spatial audio to physics engine integration, typically handled by audio plugins, this function provides a list of raycasts to be performed by the physics engine.
- This function is not intended to be called directly by developers.
- The caller is responsible for deallocating the memory containing the raycast requests.
API Level:
- 20
MLAudioSetSpatialRaycastResults
MLResult MLAudioSetSpatialRaycastResults(
MLAudioRaycastResult * raycast_results,
uint32_t result_count
)
Sets the ID-tracked results for previously requested raycast operations.
Parameters
MLAudioRaycastResult * | raycast_results | MLAudioRaycastResult struct to set the list of raycast operation results. |
uint32_t | result_count | Sets the number of raycast results. |
Returns
MLResult | MLResult_Ok | Successfully retrieved the properties. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_InternalConfigError | Internal config error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
For a custom spatial audio to physics engine integration, typically handled by audio plugins, this function reports the results of raycasts performed by the physics engine.
This function is not intended to be called directly by developers.
API Level:
- 20