AR Raycast Manager

The ARRaycastManager is a type of trackable manager.

Ray casting

Also known as hit testing, ray casting allows you to determine where a ray (defined by an origin and direction) intersects with a trackable. The current ray cast interface only tests against planes and points in the point cloud. The ray cast interface is similar to the one in the Unity Physics module, but since AR trackables don't necessarily have a presence in the physics world, AR Foundation provides a separate interface.

The raycast manager serves two purposes:

1. Provides an API to perform single raycasts.
2. Allows you to create a persistent ARRaycast. An ARRaycast is a type of trackable and is updated automatically until you remove it. Conceptually, it is similar to repeating the same raycast query each frame, but platforms with direct support for this feature can provide better results.

Single raycasts

There are two ray casting methods on the ARRaycastManager that perform single raycasts.

The first method takes a two-dimensional pixel position on the screen.

public bool Raycast(
    Vector2 screenPoint,
    List<ARRaycastHit> hitResults,
    TrackableType trackableTypes = TrackableType.All)

You can, for example, pass a touch position directly:

[SerializeField]
ARRaycastManager m_RaycastManager;

List<ARRaycastHit> m_Hits = new List<ARRaycastHit>();

void Update()
{
    if (Input.touchCount == 0)
        return;

    if (m_RaycastManager.Raycast(Input.GetTouch(0).position, m_Hits))
    {
        // Only returns true if there is at least one hit
    }
}

The second method takes an arbitrary Ray (a position and direction):

public bool Raycast(
    Ray ray,
    List<ARRaycastHit> hitResults,
    TrackableType trackableTypes = TrackableType.All)

The following table summarizes the other parameters:

Parameter	Description
hitResults	The results for both methods are stored in this List, which must not be null. This lets you reuse the same List object to avoid garbage-collected allocations.
trackableTypeMask	The type(s) of trackable(s) to hit test against. This is a flag, so multiple types can be bitwise OR'd together, for example, TrackableType.PlaneWithinPolygon | TrackableType.FeaturePoint

Determining what the raycast hit

If the raycast hits something, hitResults will be populated with a List of ARRaycastHits.

Use the hitType to determine what kind of thing the raycast hit. If it hit a trackable, e.g., a plane, then you can use the [ARRaycastHit.trackableId(xref:UnityEngine.XR.ARFoundation.ARRaycastHit.trackableId) property to look up the specific trackable from its manager:

ARPlaneManager m_PlaneManager;

void HandleRaycast(ARRaycastHit hit)
{
    // Determine if it is a plane
    if ((hit.hitType & TrackableType.Planes) != 0)
    {
        // Look up the plane by id
        var plane = m_PlaneManager.GetPlane(hit.trackableId);

        // Do something with 'plane':
        Debug.Log($"Hit a plane with alignment {plane.alignment}");
    }
    else
    {
        // What type of thing did we hit?
        Debug.Log($"Raycast hit a {hit.hitType}");
    }
}

Persistent raycasts

Persistent raycasts are a type of trackable. Each ARRaycast continues to update automatically until you remove it or disable the ARRaycastManager.

To add or remove a persistent raycast, call AddRaycast or RemoveRaycast on the ARRaycastManager component from script code.

Persistent raycasts must be created from a screen point:

public ARRaycast AddRaycast(Vector2 screenPoint, float estimatedDistance)

When you create a new ARRaycast, ARFoundation creates a new GameObject with an ARRaycast component on it. You can optionally provide a prefab in the "Raycast Prefab" field that will be instantiated for each ARRaycast, which allows you to extend the default behavior of each ARRaycast.