Spatial Mapping best practices

Because of the volume of data that can be generated by Spatial Mapping, and the effect on speed and performance of generating that data, there are many issues to consider when using the low-level API.

If you don’t carefully plan your application’s use of Spatial Mapping, your application’s speed and performance can be poor. Below are some potential issues that Spatial Mapping can create, and best practice advice on how to work around them.

Issue: Generating collision data is very slow

Generating collision data uses most of the CPU computation when generating Spatial Mapping data. Requesting collision data that isn’t going to be used unnecessarily ties up CPU resources and reduces battery life.

Best practice solution:

• Request collision data only where necessary. Avoiding collision data requests when they are not needed decreases the latency for other Spatial Mapping requests, and prolongs battery life.
• Request only those Surfaces that are most important. Use a Surface’s update time and bounding boxes to prioritize data requests.

Issue: High triangle densities generate a lot of geometry

You can specify high values of trianglesPerCubicMeter in the SurfaceData struct when requesting Surface data through RequestMeshAsync. This generates a very large amount of geometry, especially in spaces with a lot of objects such as a cluttered office. Large amounts of geometry increase data generation latency and memory usage. In addition, higher Mesh densities can make run-time systems such as rendering and physics run more slowly.

Best practice solution:

• Ask for the minimum resolution of Spatial Mapping data required. Asking for lower resolutions of generated Meshes results in less CPU time spent serving requests. This reduces power consumption, increases battery life, and reduces the latency of Mesh data delivery. Lower resolution Meshes also have fewer negative effects on run-time performance and are less resource-intensive on memory requirements. This is especially true for the physics runtime, which expects low complexity geometry.

Issue: Queuing too many mesh requests result in doing unnecessary work

SurfaceObservers report all added, updated, and removed Surfaces within their volume when Update is called.

Adding the total list of changed Surfaces to the work queue can result in Surfaces remaining in the work queue after they have been removed by the system. Surfaces still in the work queue after they have been removed still take up CPU time moving through the system, but do not generate any mMsh data. This increases the latency of any waiting requests.

Best practice solution:

• Limit the number of Surfaces in the work queue when possible. Given the long latencies associated with the Mesh work queue, keep only a single RequestMeshAsync in use at a time. Applications can use a Surface’s reported update time and bounds to prioritize RequestMeshAsync calls.
• Prioritize Surface data requests so that your application gets the most important data first. Examples of this include:
  • Prioritize new Surfaces over updates to existing ones.
  • Prioritize near Surfaces over more distant ones.

Issue: Overlapping or adjacent SurfaceObservers report the same Mesh, resulting in duplicate RequestMeshAsync calls

Each SurfaceObserver reports changes for all Surfaces that overlap its volume. A Surface can overlap multiple SurfaceObserver volumes if those volumes are close, so your application code might request the same Surfaces multiple times.

Best practice solution:

• Use a single work submit queue across all SurfaceObservers. Often, a single SurfaceObserver is enough, as using just one avoids application complexity. However, there are several advanced use cases for Spatial Mapping that require multiple SurfaceObservers. In these cases, use a single queue across all SurfaceObservers to uniquely prioritize Mesh requests.
• Use a single SurfaceObserver if your application does not require more complexity.

Issue: Updating a SurfaceObserver generates no onSurfaceChanged callbacks

This common issue is typically due to one or more set-up issues.

Best practice solution:

• Ensure that you set a valid volume on your SurfaceObserver through a function like SetVolumeAsAxisAlignedBox.
• Ensure that you’ve checked Spatial Perception from the Publishing Settings section of Player Settings.