Tobii XR Devzone > Develop > Tobii XR SDK > Documentation >

API Reference

Table of Contents

TobiiXR

TobiiXR is the entry point that exposes focused objects and provides access to core eye tracking data.


TobiiXR.Start(TobiiXR_Settings)

The Start() function initializes TobiiXR according to the provided settings object (see Tobii XR Settings). This function only needs to be called once per application. If you are using the TobiiXR Initializer prefab this function is already being called for you. If you want to change configuration of TobiiXR after it has started, you can call Start() again. Start() will internally call Stop() if it is needed.

If you access data from TobiiXR without calling Start(), G2OM will not start, and the IGazeFocusable interface will not be called. Calling GetEyeTrackingData and FocusedObjects will not cause an error but they will only return default values.

Example

This example shows how to manually initialize TobiiXR from your own bootstrapper using only code. Ensure this script is executed before any scripts that are using TobiiXR.

using Tobii.XR;
using UnityEngine;

public class MyBootstrapper : MonoBehaviour
{
    void Awake()
    {
        var settings = new TobiiXR_Settings();
        TobiiXR.Start(settings);
    }
}

TobiiXR.Stop()

The Stop() function closes the connection to the eye tracker and shuts down G2OM.


TobiiXR.FocusedObjects

This property gives you access to a list of the latest candidates being focused on as determined by G2OM. The list is sorted by the likelihood that this is the object you are focusing on. The list will be empty if no object are considered to be focused. A FocusedCandidate contains the hit GameObject as well as information about the ray which hit the GameObject.

Example

This example shows how to create a Component that retrieves the currently focused object every frame.

public class FocusManager : MonoBehaviour
{
    private void Update()
    {
        // Check whether TobiiXR has any focused objects.
        if (TobiiXR.FocusedObjects.Count > 0)
        {
            var focusedGameObject = TobiiXR.FocusedObjects[0].GameObject;
            // Do something with the focused game object
        }
    }
}

Only GameObjects containing at least one component implementing the IGazeFocusable interface will appear in the FocusedObjects list.

The IGazeFocusable component attached to your focusable game objects will also be notified whenever it gains or loses focus.

Example

This example shows how to create a Component that will be called every time the GameObject gains or loses focus.

using Tobii.G2OM;

public class HighlightAtGaze : MonoBehaviour, IGazeFocusable
{
    //The method of the "IGazeFocusable" interface, which will be called when this object receives or loses focus
    public void GazeFocusChanged(bool hasFocus)
    {
        //This object either received or lost focused this frame, as indicated by the hasFocus parameter.
    }
}

TobiiXR.GetEyeTrackingData(TobiiXR_TrackingSpace)

Gets the eye tracking data captured at the start of the Update phase.

Parameters

Determines in what TobiiXR_TrackingSpace the data will be returned. The following values are supported:

Name Description
Local The local eye tracking space shares origin with the XR camera. Data reported in this space is unaffected by head movements and is well suited for use cases where you need eye tracking data relative to the head, like avatar eyes.
World World space is the main tracking space used by Unity. Eye tracking data in world space uses the same tracking space as objects in your scene and is useful when computing what object is being focused on by the user.

To get eye tracking data in world space coordinates, it needs to be fused with head pose data and this is done using historic data in the Core API (read more about fusing eye tracking and head pose data in the Coordinate Systems page).

Returns

Definition of TobiiXR_EyeTrackingData:

Name Type Description
Timestamp float The timestamp for when the data was received, measured in seconds since application start.
ConvergenceDistance float The distance along the combined gaze ray where the eyes converge, measured in meters. For most eye tracking systems, the accuracy of this signal is low at distances of more than 1 meter.
ConvergenceDistanceIsValid bool The validity of ConvergenceDistance. Do not use the value of ConvergenceDistance if this is false.
GazeRay TobiiXR_GazeRay Struct containing the gaze ray for left and right eye combined.
IsLeftEyeBlinkDataValid bool True if the blink data is valid, indicates if blink signal is supported by the current device. Added in Tobii XR SDK 3.2.1.
IsLeftEyeBlinking bool Value indicating if the left eye is closed (true) or open (false).
IsRightEyeBlinkDataValid bool True if the blink data is valid, indicates if blink signal is supported by the current device. Added in Tobii XR SDK 3.2.1.
IsRightEyeBlinking bool Value indicating if the right eye is closed (true) or open (false).

Definition of TobiiXR_GazeRay:

Name Type Description
Origin Vector3 The origin point of the gaze ray.
Direction Vector3 The normalized direction vector for the direction of the gaze ray.
IsValid bool The validity of the TobiiXR_GazeRay. Do not use Origin or Direction of this data if this is false.

Any data where the validity bool, e.g. ConvergenceDistanceIsValid or TobiiXR_GazeRay.IsValid is false, should not be used.

Example

With TobiiXR.GetEyeTrackingData(TobiiXR_TrackingSpace) you can directly get access to the latest data from the eye tracker device in one of the available tracking spaces.

private void Update ()
{
    // Get eye tracking data in world space
    var eyeTrackingData = TobiiXR.GetEyeTrackingData(TobiiXR_TrackingSpace.World);

    // Check if gaze ray is valid
    if(eyeTrackingData.GazeRay.IsValid)
    {
        // The origin of the gaze ray is a 3D point
        var rayOrigin = eyeTrackingData.GazeRay.Origin;

        // The direction of the gaze ray is a normalized direction vector
        var rayDirection = eyeTrackingData.GazeRay.Direction;
    }

    // For social use cases, data in local space may be easier to work with
    var eyeTrackingDataLocal = TobiiXR.GetEyeTrackingData(TobiiXR_TrackingSpace.Local);

    // The EyeBlinking bool is true when the eye is closed
    var isLeftEyeBlinking = eyeTrackingDataLocal.IsLeftEyeBlinking;
    var isRightEyeBlinking = eyeTrackingDataLocal.IsRightEyeBlinking;

    // Using gaze direction in local space makes it easier to apply a local rotation
    // to your virtual eye balls.
    var eyesDirection = eyeTrackingDataLocal.GazeRay.Direction;
}

TobiiXR.Internal

For advanced and internal use only. Do not access this field before TobiiXR.Start has been called.

Do not save a reference to the fields exposed by this class since TobiiXR will recreate them when restarted.