Mixed Reality Utility Kit - Environment Raycasting
Updated: Mar 13, 2025
After completing this section, the developer should be able to:
- Use a ray to determine the position and orientation of a point in 3D space corresonding to the intersection of the ray and objects in the room,
- Use the raycast manager to place an object at that point.
Note: The API is currently in Beta, meaning that while it is available for general use in applications, the API is likely to change in future SDK versions. Environment Raycasting is implemented on top of the Depth API, imposing the same performance restrictions on your app, and only returning data for rays fired into your field of view.
This component allows users to shoot rays that collide with the physical environment using the Depth API.
The
EnvironmentRaycastManager Unity component provides programmatic access to raycasting, while also ensuring that the Depth API (EnvironmentDepthManager) is enabled and retrieving the underlying depth data from the system. Once the component is enabled in Unity, it will enable the Depth API and continuously retrieve the data. Disabling the component disables the raycasting, but leaves the Depth API enabled. Disable the Depth API manually if your app no longer needs it after that.
To get started with this feature, add the EnvironmentRaycastManager component to your scene.
Note: if you add the EnvironmentRaycastManager programatically to your scene, it will also add the EnvironmentDepthManager if it doesn’t already exist in your scene. In this scenario, the PST will not pick up that you are using Depth API in editor, and will not prompt you to fix all issues that would prevent Depth API to function. To make things easier, we recommend that you add the EnvrionmentDepthManager component to your scene in the editor.
Environment raycasting is exposed through the following functions, closely modeled after Unity’s
Physics.Raycast functionality.
EnvironmentRaycastManager _raycastManager;
GameObject _objectToPlace;
- Raycast: fires a single ray into the scene and returns intersection information.
// Create a standard Unity ray, originating from a point, pointing forward
var ray = new Ray(_rayOrigin.position, _rayOrigin.forward);
if (_raycastManager.Raycast(ray, out var hit))
{
_objectToPlace.transform.SetPositionAndRotation(hit.point, Quaternion.LookRotation(hit.normal, Vector3.up));
}
- PlaceBox: tries to place a given box on a flat and free surface.
- CheckBox: checks whether a given box overlaps with the environment.
Environment raycasting is only performed against live data in your field of view. Because of this limitation, the Raycast functions will return more details in the EnvironmentRaycastHitStatus enum, such as whether the ray is firing outside of your field of view, or whether the entire ray is being occluded by the environment.
Environment raycasting has an additional 3-4 frames delay needed to fetch the data from the Depth API, so it may not be perfectly in sync with occlusions in dynamic conditions. Environment raycasting provides a built-in headset movement compensation mechanism, so head movement doesn’t add an additional delay. In other words, the depth data used for raycasting is delayed by 3-4 frames, but raycasting results are always instant regardless of the headset or raycast ray position changes. For more information on the performance requirements of the Depth API, see
Depth API Overview.
