Wwise Unreal Integration Documentation
Fit to Geometry

To facilitate quick and accurate placement of AkAcousticPortals and AkSpatialAudioVolumes, the Wwise Unreal integration is able to detect surrounding static mesh geometry in a scene and determine the appropriate size and location of the portals and volumes within the scene. Fit to Geometry works for a variety of typical room, window, and door shapes. This section gives an overview of how to use Fit To Geometry for AkAcousticPortals and AkSpatialAudioVolumes.

Note:
The Preparation for the Spatial Audio Tutorials must be completed prior to starting this tutorial.

Note:
For Fit To Geometry to function correctly, Realtime must be enabled in the viewport options.

Enable Realtime in the Viewport Options

Fit To Geometry Prerequisites

  • Select the desired default collision channel inside the Wwise Integration settings. The Fit To Geometry feature uses the Unreal Engine to perform ray traces, and the rays must be able to intersect the surrounding static mesh geometry. Therefore, the collision channel must correspond with the collision parameters of the static mesh that the AkAcousticPortals and AkSpatialAudioVolumes are placed within.
  • If desired, individual AkAcousticPortals and AkSpatialAudioVolume can override the default collision channel and choose a different one. This setting is found in the Details panel for both AkAcousticPortals and AkSpatialAudioVolumes.
  • If using acoustic materials for early reflections on AkSurfaceReflectorSets, make sure that you have set up the desired mapping inside the Wwise integration settings. For more information, refer to Automatically Assigning Acoustic Textures to AkSpatialAudioVolumes.
Note:
The Fit To Geometry feature is only available for use with the AkAcousticPortal and AkSpatialAudioVolume actors inside the level editor viewport. It cannot be used inside the Blueprint editor viewport, nor can it be used on the individual components that make up the aforementioned actors: AkPortalComponent, AkSurfaceReflectorSet, AkRoomComponent, and AkLateReverb.

Placing AkSpatialAudioVolumes Using Fit To Geometry

  • The Fit To Geometry operation is initially performed after enabling the option in the Details panel for an AkSpatialAudioVolume. After the option has been enabled, the Fit To Geometry operation is performed any time the volume is translated to a new location using the transform gizmo.
  • While dragging the translation gizmo, a yellow preview outline is drawn to give you an indication of how the AkSpatialAudioVolume will fit to a specific location in the world. Drag the volume until a desirable fit is found, and then release the mouse to update the brush volume of the AkSpatialAudioVolume. Note that after performing a Fit To Geometry operation, the transform of the AkSpatialAudioVolume actor remains unchanged - only the child brush component is modified.
  • The Fit To Geometry operation works by tracing a number of rays from the origin of the actor, emanating spherically outwards to probe for walls. The hit points for these rays are colored green (or red, when the hits are ignored). It can be useful to take note of where the rays hit to make sense of the resulting shape, to make sure that the correct collision channel is being used, and lastly, to make sure the correct acoustic textures are assigned to the resulting surfaces.
  • Three types of shapes are supported; the shape type is selected in the Details panel of the AkSpatialAudioVolumes.
    1. Oriented Box - A box-shaped room with an arbitrary orientation. The orientation of the box is determined automatically during the Fit To Geometry operation. The shape is calculated by finding the smallest box (by volume) that all the green hit points will fit inside.
    2. Aligned Box - A box-shaped room with a fixed orientation. The orientation of the box is specified by the user. Rotate the AkSpatialAudioVolume actor using the transform gizmo to change its orientation. The aligned box shape can be useful when fitting a volume to a box-shaped area that may have various obstacles that would otherwise cause misalignment when using the oriented box shape, and when fitting a box to an outdoor area between walls or in a narrow passage.
      • In some cases, a given set of ray traces will result in an AkSpatialAudioVolume with zero volume - for example if all hit points lie on the same plane. If this happens, the outline of the box will flash red and the shape will not be updated. An error message will appear on the lower-left side of the screen. To fix this issue, move the AkSpatialAudioVolume to a new location and try again.
    3. Convex Polyhedron - A fully enclosed, convex polyhedron shaped room. This is the most complex shape, and although it may be subject to more placement errors, it can also save time when fitting volumes to rooms that do not have parallel walls or are otherwise not box-shaped. Note that the room shape must be convex and fully enclosed - in other words, it cannot have open walls, ceilings, etc.
      • In some cases, a closed convex shape cannot be found with the set of ray traces from a specific location. If this occurs, the outline of the shape will flash red, the shape will not update, and an error message will appear on the lower-left side of the screen. To fix this issue, move the AkSpatialAudioVolume to a new location and try again.
  • The ray cast hit points can be filtered using a slider in the Details panel of the AkSpatialAudioVolume.
    • The rays are sorted internally by length, and the slider then determines the percentage of the shortest ray hits that are taken into account.
      • For example, if the slider is set to 0.75, then the shortest 75% of the rays are used to apply the fitting operation, and the longest 25% of rays are ignored.
    • Ray hits that are filtered in are colored green, and ray hits that are filtered out are red.
    • Filtering hit points is useful when some rays escape through windows or doors, and the hit points of those rays are causing erroneous results.
    • Filtering hit points is probably most useful using the aligned box shape, because lowering the number of ray hits cannot cause errors in determining the orientation (since an aligned box has a fixed orientation), however, ray filtering can be used with any shape.

Automatically Assigning Acoustic Textures to AkSpatialAudioVolumes

  • Acoustic textures are automatically assigned to the surfaces of the AkSpatialAudioVolume based on the collision results of the ray traces performed by Fit To Geometry, and the acoustic material mapping defined in the Wwise integration settings.
    • Since the result of a ray trace in the Unreal Engine yields a physical material, the mapping that is set up in the project settings is used to map each physical material to an acoustic texture.
    • It is likely that more than one ray hit will project onto a resulting surface of the AkSpatialAudioVolumes, and it is possible that the various ray hits will each return a different physical material. The physical material with the most hits is chosen to map to the acoustic texture.
    • It is possible that some rays will hit undesirable surfaces that are not representative of the acoustic properties of the resulting AkSpatialAudioVolume surface. For example, a drywall surface may have a wooden trim in some areas, but using 'drywall' for the acoustic representation makes more sense than 'wood' for the wall as a whole. In most cases, there will be enough hit points that the texture with the greater surface area will be assigned. If not, try translating the AkSpatialAudioVolume slightly so that the hit points move slightly, or if desired results are still not achieved, the acoustic texture can be manually assigned in the Details panel for the AkSurfaceReflectorSet.
  • It is necessary to create the desired mapping between physical materials and acoustic textures inside the Wwise integration settings before using Fit To Geometry on an AkSpatialAudioVolume. If you change the material mapping after fitting an AkSpatialAudioVolume, its acoustic materials are not updated.
Note:
Because Fit To Geometry must use the Unreal Engine's complex collision to find individual triangles of a static mesh, it is not possible to retrieve a physical material that has been assigned to the 'Phys Material Override' property of a static mesh actor. This property only applies to simple collision, and will not be mapped to an acoustic material.

Placing AkAcousticPortals Using Fit To Geometry

  • Like AkSpatialAudioVolumes, the Fit To Geometry operation is initially performed after enabling the option inside the Details panel for an AkAcousticPortal. After the option has been enabled, the Fit To Geometry operation is performed any time the actor is translated to a new location using the transform gizmo.
  • While dragging the translation gizmo, a yellow preview outline is drawn to give you an indication of how the AkAcousticPortal will fit to a specific location in the world. Drag the actor until a desirable fit is found, and then release the mouse to update the AkAcousticPortal.
  • The Fit To Geometry operation works by tracing a number of rays from the origin of the actor, emanating spherically outwards to probe for windows and doorways. When a potential window or doorway is found, a secondary ray is fired in the direction of the surface normal, to detect the other side of the window or door frame.
  • A portal can only be detected when the opening has a distinct 'frame' with perpendicular surfaces facing inwards.
On the left is an example of an opening that will be detected by the AkAcousticPortal; on the right is an opening that will not be detected because the mesh is too thin.
  • Use the Detection Radius property inside the Details panel to limit the size of openings that are detected. A general guideline is to set this value larger than the opening you are trying to detect, but smaller than the dimension of the entire room.
    • The default value of 500 works for most Unreal projects that use centimeters for the units, and that have average-size openings for windows and doors. Adjust this value as necessary to fit the dimensions of your static mesh.
    • If the Detection Radius is smaller than the opening, the portal will not be found.
    • If the Detection Radius is too large, erroneous portals may be detected that span the entire width of the room.
  • A portal must not have a solid door or window that collides with the Fit To Geometry ray traces, as determined by the Collision Channel property. If it does, the opening will not be detected. If the opening has a window or door, either use a different collision profile, or hide the window/door by pressing H, so that the mesh is ignored.

Tips for Using Fit To Geometry

  • Many AkAcousticPortal and/or AkSpatialAudioVolume actors can be populated quickly in a level by first enabling Fit To Geometry on a actor, and then Alt-dragging the actor's translation gizmo to create a duplicate actor that will then fit to a new location in the level.
  • If certain static mesh actors are blocking the ray traces performed by Fit To Geometry and causing erroneous results, such as pieces of furniture, props, light fixtures, etc, those actors can be hidden (press H), and they will then be ignored by the Fit To Geometry ray traces.