Table of Contents

AKRESULT __cdecl AK::SpatialAudio::SetEmitterObstructionAndOcclusion ( AkGameObjectID  in_gameObjectID,
AkReal32  in_fObstruction,
AkReal32  in_fOcclusion  

Set the obstruction and occlusion values of an emitter game object that has been registered with the SpatialAudio API. This function should be called instead of AK::SoundEngine::SetObjectObstructionAndOcclusion(), and can be used for setting the obstruction and occlusion values on a Spatial Audio emitter. The obstruction value passed to SetEmitterObstructionAndOcclusion() should be used to simulate obstructing objects between the emitter and the listener, if they are in the same room, or between the emitter and a portal, if the emitter and listener are in different room. The occlusion value that is passed to SetEmitterObstructionAndOcclusion() is send to the sound engine directly, unless the emitter is unreachable via sound propagation. In this case, the occlusion value is maxed with the AkRoomParams::WallOcclusion value to simulate sound transmission through walls. If the listener and the emitter are in different rooms, the maximum of the obstruction value passed into SetEmitterObstructionAndOcclusion() and the the obstruction value calculated from the diffraction angle is passed to the sound engine. If the game object is not registered as an emitter with Spatial Audio, then an error will be reported, and the call will have no effect.

Note: The game is responsible to differentiate between obstruction between the emitter and the portal (where AK::SoundEngine::SetEmitterObstructionAndOcclusion() should be used), and occlusion from room boundaries, which is better handled by the spatial audio diffraction system. For example, games that use ray-testing for obstruction may report 100 % obstruction when an object is very close to the the opening of a portal, because the ray between the emitter and the listener hits a nearby wall. If the game then sends 100 %, this will erroneously override the diffraction angle calculation which is probably much less than 180 degrees, and better matches the expected audibility of the sound. To prevent this scenario, games can ray-test for obstruction objects between the emitter and the portal, passing the results with AK::SoundEngine::SetEmitterObstructionAndOcclusion(), and then test for obstructing objects between the portal and the listener, passing the results with AK::SoundEngine::SetPortalObstructionAndOcclusion().
See also:
in_gameObjectID  Game object ID of the sound emitter.
in_fObstruction  Obstruction value. Valid range 0.f-1.f
in_fOcclusion  Occlusion value. Valid range 0.f-1.f