Scripting API

SDK version: 3.0 Beta

Contents

• TobiiAPI
  • GetDisplayInfo
  • GetFocusedObject
  • GetGazePoint
  • GetGazePointsSince
  • GetHeadPose
  • GetHeadPosesSince
  • GetUserPresence
  • SetCurrentUserViewPointCamera
  • SubscribeGazePointData
  • SubscribeHeadPoseData
• Components
  • GazeAware
• Data Types and Enums
  • DisplayInfo
  • GazePoint
  • HeadPose
  • UserPresence

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

TobiiAPI.GetDisplayInfo

static function on TobiiAPI

public static DisplayInfo GetDisplayInfo()

Returns

Description

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

TobiiAPI.GetFocusedObject

static function on TobiiAPI

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

Returns

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() + ")");
        }
    }
}

TobiiAPI.GetGazePoint

static function on TobiiAPI

public static GazePoint GetGazePoint()

→ View related entry in Manual

Returns

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);
        }
    }
}

TobiiAPI.GetGazePointsSince

static function on TobiiAPI

public static IEnumerable<GazePoint> GetGazePointsSince(GazePoint gazePoint)

Parameters

Returns

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();
    }
}

TobiiAPI.GetHeadPose

static function on TobiiAPI

public static HeadPose GetHeadPose()

→ View related entry in Manual

Returns

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);
        }
    }
}

TobiiAPI.GetHeadPosesSince

static function on TobiiAPI

public static IEnumerable<HeadPose> GetHeadPosesSince(HeadPose headPose)

Parameters

Returns

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();
    }
}

TobiiAPI.GetUserPresence

static function on TobiiAPI

public static UserPresence GetUserPresence()

Returns

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);
    }
}

TobiiAPI.SetCurrentUserViewPointCamera

static function on TobiiAPI

public static void SetCurrentUserViewPointCamera(Camera camera)

Parameters

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:

• given the current GazePoint gazePoint
• when calling camera.ScreenPointToRay(gazePoint.Screen)
• the resulting ray into world space should be a continuation of the “ray” from the user’s eyes to the gaze point on the display monitor

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.

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.

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

DATA TYPES AND ENUMS

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

• GazePoint
• HeadPose
• UserPresence

↑ Back to Top

DisplayInfo

value type in Tobii.Gaming namespace

Description

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

Properties

Static properties

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

Static properties

Functions

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

Static properties

Functions

UserPresence

enum in Tobii.Gaming namespace

Description

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

Values

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.