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::SpatialAudio::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 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 calculation which is probably much less than 100% (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::SpatialAudio::SetEmitterObstructionAndOcclusion(), and then test for obstructing objects between the portal and the listener, passing the results with
||Game object ID of the sound emitter.
||Obstruction value. Valid range 0.f-1.f
||Occlusion value. Valid range 0.f-1.f