Unity SDK for Desktop

DOCUMENTATION

Scripting API

SDK version: 3.0 Beta

Contents


TobiiAPI

static class in Tobii.Gaming namespace

The TobiiAPI is a static API that provides direct access to the most common and useful functionality of the Tobii Unity SDK framework.

→ View in Manual

Description

TobiiAPI is a static class with static methods to easily access data from a connected Tobii eye tracker.

To get access to TobiiAPI, import the Tobii Unity SDK into your project and add the following using (at the top of the script file where you want to use the Tobii API):

using Tobii.Gaming;

TobiiAPI provides simplified and straightforward access to eye tracker data and can be used for the most common use cases.

TobiiAPI also provides information about which UnityEngine.GameObject the user focuses using eye-gaze. Only gaze aware objects will be considered for gaze focus detection. The way to make an object gaze-aware is to add the GazeAware component to it.

Static Functions

Name Description
GetDisplayInfo Gets info about the eye tracked display monitor.
GetFocusedObject Gets the game object with gaze focus.
GetGazePoint Gets the last (newest) GazePoint.
GetGazePointsSince Gets the gaze points since a given GazePoint.
GetHeadPose Gets the last (newest) HeadPose
GetHeadPosesSince Gets the head poses since a given HeadPose.
GetUserPresence Gets the user presence status.
SetCurrentUserViewPointCamera Sets the camera used for gaze focus detection.
SubscribeGazePointData Subscribes to gaze point data.
SubscribeHeadPostData Subscribes to head pose data.
↑ Back to Section start ↑ Back to Top

TobiiAPI.GetDisplayInfo

static function on TobiiAPI

public static DisplayInfo GetDisplayInfo()

Returns

Type Description
DisplayInfo Value object with information about the eye tracked display monitor. Can be invalid, check IsValid before using.

Description

Gets a DisplayInfo value object with information about the eye tracked display monitor.

↑ Back to Section start ↑ Back to Top

TobiiAPI.GetFocusedObject

static function on TobiiAPI

public static UnityEngine.GameObject GetFocusedObject() → View related entry in Manual

Returns

Type Description
UnityEngine.GameObject The object the user is focused on by looking at it. Can be null if no object is focused.

Description

Gets the game object with gaze focus, or returns null if there is no game object with gaze focus.

Only game objects that are gaze-aware will be considered for gaze focus detection. The easiest way to make a game object gaze-aware is to add the GazeAware component to it. Another way is to implement your own custom gaze-aware component, see IGazeFocusable.

using Unity.Engine;
using Tobii.Gaming;

public class ExampleClass : MonoBehaviour
{
    void Update()
    {
        GameObject focusedObject = TobiiAPI.GetFocusedObject();
        if (null != focusedObject)
        {
            print("The focused game object is: " + focusedObject.name + " (ID: " + focusedObject.GetInstanceID() + ")");
        }
    }
}
↑ Back to Section start ↑ Back to Top

TobiiAPI.GetGazePoint

static function on TobiiAPI

public static GazePoint GetGazePoint()

→ View related entry in Manual

Returns

Type Description
GazePoint Where on the screen the user is looking. Can be invalid, check GazePoint.IsValid before using or use GazePoint.IsRecent() function to ensure that it’s both valid and recent.

Description

Gets the last GazePoint.

The TobiiAPI class is initialized lazily if TobiiAPI.SubscribeGazePointData() is not called first. This means that the data provider is started at the first call to this function (or the TobiiAPI.GetFocusedObject() function), and the function will return an invalid value for some frames until valid data is received from the eye tracker.

using Unity.Engine;
using Tobii.Gaming;

public class ExampleClass : MonoBehaviour
{
    void Update()
    {
        GazePoint gazePoint = TobiiAPI.GetGazePoint();
        if (gazePoint.IsRecent()) // Use IsValid property instead to process old but valid data
        {
            // Note: Values can be negative if the user looks outside the game view.
            print("Gaze point on Screen (X,Y): " + gazePoint.Screen.X + ", " + gazePoint.Screen.Y);
        }
    }
}
↑ Back to Section start ↑ Back to Top

TobiiAPI.GetGazePointsSince

static function on TobiiAPI

public static IEnumerable<GazePoint> GetGazePointsSince(GazePoint gazePoint)

Parameters

Name Type Description
gazePoint GazePoint Typically an already handled gaze point. The function will return all gaze points newer than this gaze point, but at most 500 ms old. An invalid gaze point as parameter will return all data points newer than 500 ms.

Returns

Type Description
IEnumerable<GazePoint> All the GazePoints that have been received from the eye tracker since the supplied gaze point.

Description

Gets all GazePoints that have been received from the eye tracker since the supplied gaze point, but no older than 500 ms.

This function is useful when you want to do your own advanced filtering of the gaze point data and include all received gaze points in the calculation. If you use GetGazePoint() you will likely miss some points from the eye tracker, since the game and the eye tracker will probably not run in the exact same frequency.

You can save your last handled data point in the Update loop, and use it as a parameter for this function in the next Update loop to retrieve all new data points. For the first iteration, when the data point is invalid, the function will return all points received within the last 500 ms.

using System.Collections.Generic;
...

public class ExampleClass : MonoBehaviour
{
    private GazePoint _lastHandledPoint = GazePoint.Invalid;

    Update()
    {
        IEnumerable<GazePoint> pointsSinceLastHandled = TobiiAPI.GetGazePointsSince(_lastHandledPoint);
        foreach (point in pointsSinceLastHandled)
        {
            // handle each point that has arrived since previous Update()
            // ...
        }
        _lastHandledPoint = pointsSinceLastHandled.Last();
    }
}
↑ Back to Section start ↑ Back to Top

TobiiAPI.GetHeadPose

static function on TobiiAPI

public static HeadPose GetHeadPose()

→ View related entry in Manual

Returns

Type Description
HeadPose Where on the screen the user is looking. Can be invalid, check HeadPose.IsValid before using or HeadPose.IsRecent() to check that it’s both valid and recent.

Description

Gets the last HeadPose.

The TobiiAPI class is initialized lazily if TobiiAPI.SubscribeHeadPoseData() is not called first. This means that the data provider is started at the first call to this function, and the function will return an invalid value for some frames until valid data is received from the eye tracker.

using Unity.Engine;
using Tobii.Gaming;

public class ExampleClass : MonoBehaviour
{
    void Update()
    {
        HeadPose headPose = TobiiAPI.GetHeadPose();
        if (headPose.IsRecent())
        {
            print("HeadPose Position (X,Y,Z): " + headPose.Position.X + ", " + headPose.Position.Y + ", " + headPose.Position.Z);
            print("HeadPose Rotation (X,Y,Z): " + headPose.Rotation.eulerAngles.X + ", " + headPose.Rotation.eulerAngles.Y + ", " + headPose.Rotation.eulerAngles.Z);
        }
    }
}
↑ Back to Section start ↑ Back to Top

TobiiAPI.GetHeadPosesSince

static function on TobiiAPI

public static IEnumerable<HeadPose> GetHeadPosesSince(HeadPose headPose)

Parameters

Name Type Description
headPose HeadPose Typically an already handled head pose. The function will return all head poses newer than this head pose, but at most 500 ms old. An invalid head pose as parameter will return all data points newer than 500 ms.

Returns

Type Description
IEnumerable<HeadPose> All the HeadPoses that have been received from the eye tracker since the supplied head pose.

Description

Gets all HeadPoses that have been received from the eye tracker since the supplied head pose, but no older than 500 ms.

This function is useful when you want to do your own advanced filtering of the head pose data and include all received head poses in the calculation. If you use GetHeadPose() you will likely miss some points from the eye tracker, since the game and the eye tracker will probably not run in the exact same frequency.

You can save your last handled data point in the Update loop, and use it as a parameter for this function in the next Update loop to retrieve all new data points. For the first iteration, when the data point is invalid, the function will return all points received within the last 500 ms.

using System.Collections.Generic;
...

public class ExampleClass : MonoBehaviour
{
    private HeadPose _lastHandledPoint = HeadPose.Invalid;

    Update()
    {
        IEnumerable<HeadPose> pointsSinceLastHandled = TobiiAPI.GetHeadPosesSince(_lastHandledPoint);
        foreach (point in pointsSinceLastHandled)
        {
            // handle each point that has arrived since previous Update()
            // ...
        }
        _lastHandledPoint = pointsSinceLastHandled.Last();
    }
}
↑ Back to Section start ↑ Back to Top

TobiiAPI.GetUserPresence

static function on TobiiAPI

public static UserPresence GetUserPresence()

Returns

Type Description
UserPresence User presence status, indicating if there is a user in front of the eye tracker.

Description

Get the user presence, which indicates if there is a user present in front of the screen/eye tracker.

The UserPresence extension method IsUserPresent() returns true if the system detects a user in front of the eye tracker. It is false if the system cannot detect a user in front of the eye tracker, but it is also false if the user presence status is UserPresence.Unknown. This means that this property can give false negatives if the user presence status is unknown. For example during initializing, or if eye tracking has been disabled by the user, the user can be in front of the eye tracker but IsUserPresent() returns false. If you need to avoid false negatives for these special cases, check enum value instead.

using Unity.Engine;
using Tobii.Gaming;

public class ExampleClass : MonoBehaviour
{
    void Update()
    {
        UserPresence userPresence = TobiiAPI.GetUserPresence();
        if (userPresence.IsUserPresent())
        {
            print("A user is present in front of the screen.");
        }

        print("User presence status is: " + userPresence);
    }
}
↑ Back to Section start ↑ Back to Top

TobiiAPI.SetCurrentUserViewPointCamera

static function on TobiiAPI

public static void SetCurrentUserViewPointCamera(Camera camera)

Parameters

Name Type Description
camera UnityEngine.Camera The camera that defines the user’s current view point.

Description

Sets the camera that defines the user’s current view point. The camera is used for gaze focus detection.

By default Camera.main is used for gaze focus detection to decide which game object the user’s eye-gaze is focused on. If the main camera is not the camera that defines the user’s current view point, this function can be used to override the main camera with a custom camera.

To decide which camera corresponds to the user’s view point, it should fulfill the following:

↑ Back to Section start ↑ Back to Top

TobiiAPI.SubscribeGazePointData

static function on TobiiAPI

public static void SubscribeGazePointData()

Description

Starts the gaze point data provider.

Use this method if you want to initialize the gaze point data provider explicitly rather than to use the default lazy initialization. If this method is not used, the gaze point data provider will be initialized and started at the first call to TobiiAPI.GetGazePoint() or TobiiAPI.GetFocusedObject(), and there will be some frames before that method returns valid gaze points.

↑ Back to Section start ↑ Back to Top

TobiiAPI.SubscribeHeadPoseData

static function on TobiiAPI

public static void SubscribeHeadPoseData()

Description

Starts the head pose data provider.

Use this method if you want to initialize the head pose data provider explicitly rather than to use the default lazy initialization. If this method is not used, the head pose data provider will be initialized and started at the first call to TobiiAPI.GetHeadPose(), and there will be some frames before that method returns valid gaze points.

↑ Back to Section start ↑ Back to Top

COMPONENTS

This section describes components that can be used out-of-the-box to add eye-gaze features to game objects.

↑ Back to Top

GazeAware

class in Tobii.Gaming namespace / Inherits from: UnityEngine.MonoBehaviour / Implements: IGazeFocusable → View related entry in Manual

Description

Makes the game object it is attached to gaze-aware, meaning aware of the user’s eye-gaze on it.

The HasGazeFocus property indicates if the user is currently looking at the game object or not. Which gaze-aware game object that currently has gaze focus can also be queried by calling TobiiAPI.GetFocusedObject(). Only game objects with the GazeAware component or some other component that implements the IGazeFocusable interface can get gaze focus.

Properties

Name Type Description
HasGazeFocus bool True if the game object it is attached to has gaze focus, false otherwise.
↑ Back to Section start ↑ Back to Top

DATA TYPES AND ENUMS

This section describes the data types and enums used with the TobiiAPI.

↑ Back to Top

DisplayInfo

value type in Tobii.Gaming namespace

Description

The DisplayInfo struct contains information about the eye-tracked display monitor.

Properties

Name Type Description
DisplayWidthMm float The width in millimeters of the eye-tracked display monitor.
DisplayHeightMm float The height in millimeters of the eye-tracked display monitor.
IsValid float True if the info object is valid, false otherwise.

Static properties

Name Description
Invalid Creates a value representing an invalid DisplayInfo instance.
↑ Back to Section start ↑ Back to Top

GazePoint

value type in Tobii.Gaming namespace

→ View related entry in Manual

Description

A GazePoint represents a point on the screen where the user is looking (or where the user’s eye-gaze intersects with the screen plane).

Always check if a GazePoint is valid before using it, checking IsValid property or use IsRecent() function to ensure that it’s both valid and recent. Invalid points will be returned by the Tobii Unity SDK framework during startup and shutdown, a few frames after calling TobiiAPI.GetGazePoint() (or TobiiAPI.SubsribeGazePointData()) for the first time, and if the data provider is stopped for some reason. Invalid points will always be returned on unsupported standalone platforms, currently Mac and Linux.

The PreciseTimestamp can be used to compare the timestamps between two GazePoints with high accuracy.

Properties

Name Type Description
GUI Vector2 Gaze point in GUI space (where (0,0) is upper left corner).
IsValid bool True if the point is valid, false otherwise.
PreciseTimestamp long Precise timestamp of the gaze point.
Screen Vector2 Gaze point in screen space (where (0,0) is lower left corner).
Timestamp float Time.unscaledTime timestamp of the gaze point.
Viewport Vector2 Gaze point in viewport space.

Static properties

Name Description
Invalid Creates a value representing an invalid GazePoint
↑ Back to Section start ↑ Back to Top

Functions

Name Description
IsRecent Returns true if the point is valid and recent, false otherwise.
IsRecent(float maxAge) Returns true if the point is valid and no older than maxAge seconds, false otherwise.

HeadPose

value type in Tobii.Gaming namespace

→ View related entry in Manual

Description

A HeadPose represents the head position and rotation of the user’s head.

Always check if a HeadPose is valid before using it. Invalid points will be returned by the Tobii Unity SDK framework during startup and shutdown, a few frames after calling TobiiAPI.GetHeadPose() (or TobiiAPI.SubscribeHeadPoseData()) for the first time, and if the data provider is stopped for some reason. Invalid points will always be returned on unsupported standalone platforms, currently Mac and Linux.

The PreciseTimestamp can be used to compare the timestamps between two HeadPoses with high accuracy.

Properties

Name Type Description
IsValid bool True if the head pose is valid, false otherwise.
Position Vector3 (X, Y, Z) position of the head of the user, in millimeters from the center of the eye tracked display monitor’s screen area.
PreciseTimestamp long The precise timestamp of the head pose.
Rotation Quaternion Rotation of the head of the user, expressed using Quternion. Use eulerAngles property of the Quaternion to convert it to euler angles.
Timestamp float The Time.unscaledTime timestamp of the gaze point.

Static properties

Name Description
Invalid Creates a value representing an invalid HeadPose

Functions

Name Description
IsRecent Returns true if the head pose is valid and recent, false otherwise.
IsRecent(float maxAge) Returns true if the head pose is valid and no older than maxAge seconds, false otherwise.
↑ Back to Section start ↑ Back to Top

UserPresence

enum in Tobii.Gaming namespace

Description

Describes possible user presence statuses. See also TobiiAPI.GetUserPresence().

Values

Name Description
Unknown User presence is unknown, the system might for example be initializing
Present User is present
NotPresent User is not present
↑ Back to Section start ↑ Back to Top

Extension Method

IsUserPresent

extension method for UserPresence

public static bool IsUserPresent(this UserPresence userPresence)

Returns true if UserPresence is UserPresence.Present, false otherwise.

IsUserPresent() can give false negatives for example during initialization when the user presence status is UserPresence.Unknown.