Version
menu_open
Wwise SDK 2023.1.8
Rooms and Portals API Configuration

Creating Rooms and Portals

You need to create Rooms and Portals based on the geometry of your map or level, with AK::SpatialAudio::SetRoom and AK::SpatialAudio::SetPortal. Rooms and Portals have settings that you may change at run-time by calling these functions again with the same ID. Then the game calls AK::SpatialAudio::SetGameObjectInRoom for each emitter and the listener to tell Spatial Audio in what room they are. From the point of view of Spatial Audio, Rooms don't have a defined position, shape, or size. They can thus be of any shape, but it is the responsibility of the game engine to perform containment tests to determine in which Room the objects are.

Warning: Beware of Room IDs. They share the same scope as game objects, so make sure that you never use an ID that is already used as a game object.
Warning: Under the hood, Spatial Audio registers a game object to Wwise for each Room. The user can post events on this game object for ambience/room tone sounds, but should not attempt to alter the position or game-defined sends of the object in calls to AK::SoundEngine.

The most important Room setting is AkRoomParams::ReverbAuxBus, which tells Spatial Audio to which auxiliary bus emitters should send when they are in that Room. Other settings will be discussed in sections below (see Setting Up a Room Auxiliary Bus in Wwise and Transmission).

Portals represent openings between two Rooms. Contrary to Rooms, Portals have position and size, so Spatial Audio can perform containment tests itself. Portal size is given by the Portal setting AkPortalParams::Extent. Width and height (X and Y) are used by Spatial Audio to compute diffraction and spread, while depth (Z) defines a region in which Spatial Audio performs a smooth transition between the two connected Rooms by carefully manipulating the auxiliary send levels, Room object placement, and Spread (used by 3D Spatialization). Refer to sections Setting Up a Room Auxiliary Bus in Wwise and Summary of Sound Propagation Features below for more details. Additionally, Portals may be enabled (open) or disabled (closed) using the AkPortalParams::bEnabled Portal setting.

Posting Events on Room Game Objects

It is possible to post an event on a Room Game object to take advantage of their spatialization behavior. Simply call AK::SoundEngine::PostEvent, passing the room ID as the AkGameObjectID. The room ID can be safely cast to a AkGameObjectID by calling AkRoomID::AsGameObjectID. If a room is to be used for posting events, then Spatial Audio must be told not to unregister the Room Game Object when it is not in use. To do so, make sure to set AkRoomParams::RoomGameObj_KeepRegistered to true.

Additionally, when using room tones, it may be useful to have the Game Object send to its own Room Auxiliary Bus. To do so, pass a value greater than zero to AkRoomParams::RoomGameObj_AuxSendLevelToSelf.

Setting up Room Geometry

Associating a Geometry Instance with a Room serves the following purposes:

  • It enables calculation of the Room's bounding box, which in turn is used to calculate the position and spread of the Room's transmission path.
  • It allows Spatial Audio to determine which Game Objects are in which Room. Alternatively, clients can use AK::SpatialAudio::SetGameObjectInRoom for this purpose, if desired.
  • It enables accurate specification of transmission loss values, according to the transmission loss coefficient of each individual surface.
  • It enables the display of the room inside the Game Object 3D Viewer.
  • Optionally, it enables reflection and diffraction simulation using the walls of a room, if AkGeometryInstanceParams::UseForReflectionAndDiffraction is set to true.

Setting up Room geometry is optional but recommended. Without Room geometry, the Room will not be visible in the Game Object 3D viewer, and Spatial Audio will estimate the extent of the Room (for Room transmission) by calculating a bounding box that encompasses all attached portals. For more information about Room transmission refer to Transmission of Room Tones and a Room's Diffuse Field.

Spatial Audio performs containment tests using Room geometry to determine which Room each Game Object is in. If a specific type of containment test is desired, this task can instead by performed by the client, using AK::SpatialAudio::SetGameObjectInRoom. However, geometry is mandatory for Rooms that are designated as Reverb Zones, so that Spatial Audio can determine whether a Game Object is inside the transition region of a the Reverb Zone. Refer to spatial_audio_roomsportals_reverbzones_transition_regions.

To associate geometry with a Room, first, pass the geometry to Wwise using AK::SpatialAudio::SetGeometry. It is then necessary to create a Geometry Instance to assign a position, scale and rotation to the geometry. Refer to AK::SpatialAudio::SetGeometryInstance. Lastly, populate the AkRoomParams::GeometryInstanceID field when calling AK::SpatialAudio::SetRoom, with the ID of the Geometry Instance representing the room. Spatial Audio assumes that there was, or will be, a corresponding call to AK::SpatialAudio::SetGeometryInstance, however, it does not matter in which order AK::SpatialAudio::SetRoom and AK::SpatialAudio::SetGeometryInstance are called.

Note: If a geometry instance is to be used only by a Room, for purposes listed above, and not for reflection and diffraction calculation, then set AkGeometryInstanceParams::UseForReflectionAndDiffraction to false.

For information about how to define geometry in Spatial Audio, refer to Geometry.

Note: If a geometry set is only to be used for describing a Room and not for reflection and diffraction calculation, then make sure to set AkGeometryParams::EnableTriangles to false.
Warning: AkRoomParams::GeometryInstanceID should not be confused with AkGeometryInstanceParams::RoomID. AkRoomParams::GeometryInstanceID is used as described above to define a room bounding box for transmission spread calculation and for visualization in the Game Object 3D Viewer. AkGeometryInstanceParams::RoomID is used solely as an optimization to limit the scope in which the geometry is visible/accessible, when performing ray traces inside of Spatial Audio.

Sound Emitters with Multiple Positions

When using AK::SoundEngine::SetMultiplePositions, Spatial Audio performs various calculations including reflections, diffraction and transmission for each sound position passed to the API.

There are a few important points to note when using AK::SoundEngine::SetMultiplePositions on game objects that use room sends, because a given game object can only be assigned to a single room at a given time (using AK::SpatialAudio::SetGameObjectInRoom). This limitation arises from the constraint that all sound positions must have the same Auxiliary send configuration inside the Sound Engine.

All sound paths that are calculated from an emitter's position are done so with respect to the (single) requested room. For this reason, in the case that a sound position is outside the (game-defined) boundary of the room set via AK::SpatialAudio::SetGameObjectInRoom, the resulting sound path will most likely be erroneous.

In addition, if the game object is transitioning through a portal, Spatial Audio takes the average of all sound positions passed to AK::SoundEngine::SetMultiplePositions and uses it to calculate a cross-fade between the two rooms.

For this reason, it is recommended that the game also use the average sound position to derive room containment and pass the resulting room ID to AK::SpatialAudio::SetGameObjectInRoom.

Example Rooms and Portals Integration

The Integration Demo sample (in SDK/samples/IntegrationDemo) has a demo page which shows how to use the API. Look for Demo Positioning > Spatial Audio: Portals.

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise