Version: 20 Mar 2024

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.

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

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:

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

API Level:

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.

API Level:

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.

API Level:

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:

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:

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.

API Level:

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.

API Level:

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.

API Level:

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

API Level:

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.

API Level:

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

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.

API Level:

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

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.

API Level:

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

API Level:

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

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.

API Level:

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

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.

API Level:

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

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.

API Level:

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

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.

API Level:

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:

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

API Level:

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.

note

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:

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.

note

This function is not intended to be called directly by developers.

API Level:

Spatial Sound

Functions​

Detailed Description​

Functions Documentation​

MLAudioSetSpatialSoundEnable​

MLAudioGetSpatialSoundEnable​

MLAudioSetSpatialSoundPosition​

MLAudioGetSpatialSoundPosition​

MLAudioSetSpatialSoundDirection​

MLAudioGetSpatialSoundDirection​

MLAudioSetSpatialSoundBillboarding​

MLAudioGetSpatialSoundBillboarding​

MLAudioSetSpatialSoundObstruction​

MLAudioGetSpatialSoundObstruction​

MLAudioSetSpatialSoundObstructionOverride​

MLAudioGetSpatialSoundObstructionOverride​

MLAudioSetSpatialSoundDistanceAttenuation​

MLAudioGetSpatialSoundDistanceAttenuation​

MLAudioSetSpatialSoundRadiation​

MLAudioGetSpatialSoundRadiation​

MLAudioSetSpatialSoundDirectLevel​

MLAudioGetSpatialSoundDirectLevel​

MLAudioSetSpatialSoundIndirectLevel​

MLAudioGetSpatialSoundIndirectLevel​

MLAudioSetSpatialSoundDispersionSendLevel​

MLAudioGetSpatialSoundDispersionSendLevel​

MLAudioSetSpatialSoundReverbSendLevel​

MLAudioGetSpatialSoundReverbSendLevel​

MLAudioSetSpatialSoundHeadRelative​

MLAudioGetSpatialSoundHeadRelative​

MLAudioGetSpatialRaycastRequests​

MLAudioSetSpatialRaycastResults​

Functions

Detailed Description

Functions Documentation

MLAudioSetSpatialSoundEnable

MLAudioGetSpatialSoundEnable

MLAudioSetSpatialSoundPosition

MLAudioGetSpatialSoundPosition

MLAudioSetSpatialSoundDirection

MLAudioGetSpatialSoundDirection

MLAudioSetSpatialSoundBillboarding

MLAudioGetSpatialSoundBillboarding

MLAudioSetSpatialSoundObstruction

MLAudioGetSpatialSoundObstruction

MLAudioSetSpatialSoundObstructionOverride

MLAudioGetSpatialSoundObstructionOverride

MLAudioSetSpatialSoundDistanceAttenuation

MLAudioGetSpatialSoundDistanceAttenuation

MLAudioSetSpatialSoundRadiation

MLAudioGetSpatialSoundRadiation

MLAudioSetSpatialSoundDirectLevel

MLAudioGetSpatialSoundDirectLevel

MLAudioSetSpatialSoundIndirectLevel

MLAudioGetSpatialSoundIndirectLevel

MLAudioSetSpatialSoundDispersionSendLevel

MLAudioGetSpatialSoundDispersionSendLevel

MLAudioSetSpatialSoundReverbSendLevel

MLAudioGetSpatialSoundReverbSendLevel

MLAudioSetSpatialSoundHeadRelative

MLAudioGetSpatialSoundHeadRelative

MLAudioGetSpatialRaycastRequests

MLAudioSetSpatialRaycastResults