# Tobii EyeTracking SDK for Unity 5 - Scripting Reference

SDK version: 2.0 Beta (Compatibility: Unity 5.4, 5.3 or 5.2)

Switch to Manual

## Contents

- EyeTracking static API
  - EyeTracking
  - EyeTracking.GetGazePoint
  - EyeTracking.GetGazeTrackingStatus
  - EyeTracking.GetFocusedObject
  - EyeTracking.GetUserPresence
  - EyeTracking.Initialize
  - EyeTracking.SetCurrentUserViewPointCamera
  - EyeTracking.UnsubscribeGazePointData
- Components
  - GazeAware
- Data Types and Enums
  - GazePoint
  - GazeTracking
  - GazeTrackingStatus
  - UserPresence
  - UserPresenceStatus
- Advanced API
  - DeviceStatus
  - EngineAvailability
  - EyeTrackingHost.GetEngineAvailability
  - EyeTrackingHost.GetInstance
  - FocusedObject
  - IDataProvider<GazePoint>
  - IDataProvider<GazePoint>.Last
  - IDataProvider<GazePoint>.GetFrameConsistentDataPoint
  - IDataProvider<GazePoint>.GetDataPointsSince
  - IDataProvider<GazePoint>.Start
  - IDataProvider<GazePoint>.Stop
  - IEyeTrackingHost
  - IEyeTrackingHost.DisplaySize
  - IEyeTrackingHost.EyeTrackingDeviceStatus
  - IEyeTrackingHost.GetGazePointDataProvider
  - IEyeTrackingHost.Initialize
  - IEyeTrackingHost.ScreenBounds
  - IEyeTrackingHost.Shutdown
  - IGazeFocus
  - IGazeFocusable
  - IRegisterGazeFocusable
  - IStateValue<T>
  - ITimestamped

# EYETRACKING STATIC API

The EyeTracking static API provides direct access to the most common and useful functionality of the Tobii EyeTracking Framework. This is a great starting point.

- EyeTracking
- EyeTracking.GetGazePoint
- EyeTracking.GetGazeTrackingStatus
- EyeTracking.GetFocusedObject
- EyeTracking.GetUserPresence
- EyeTracking.Initialize
- EyeTracking.SetCurrentUserViewPointCamera
- EyeTracking.UnsubscribeGazePointData

## EyeTracking

static class in `Tobii.EyeTracking` namespace
→ View in Manual

### Description

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

To get access to the static `EyeTracking` API, import the Tobii EyeTracking Framework unitypackage into your project and add the following using (at the top of the script file where you want to use Tobii EyeTracking):

    using Tobii.EyeTracking;

The `EyeTracking` static API provides simplified and straightforward access to eye tracker data and can be used for the most common use cases. For more advanced control over the data, use the underlying `IDataProvider<GazePoint>` directly.

The `EyeTracking` static API 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 easiest way to make an object gaze-aware is to add the `GazeAware` component to it (for an alternative way, see `IGazeFocusable`).

### Static Functions

Function name | Description
--- | ---
GetGazePoint | Gets the last (newest) `GazePoint`.
GetFocusedObject | Gets the game object with gaze focus.
GetUserPresence | Gets the user presence status.
GetGazeTrackingStatus | Gets the gaze tracking status.
Initialize | Initializes EyeTracking and starts the gaze point data provider.
SetCurrentUserViewPointCamera | Sets the camera used for gaze focus detection.
UnsubscribeGazePointData | Unsubscribes from gaze point data.

↑ Back to Top

## EyeTracking.GetGazePoint

static function on `EyeTracking`
`public static` `GazePoint` `GetGazePoint()`

→ View related entry in Manual

### Description

Gets the last `GazePoint`.

Once this value has been read in a frame, all other reads within that frame will retrieve the same value. A newer value cannot be read until the next frame. To get the newest possible value in the frame, use a data provider and read the `Last` property instead.

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

If the data provider has been unsubscribed by calling `EyeTracking.UnsubscribeGazePointData()` a call to `EyeTracking.GetGazePoint()` will re-subscribe to the data provider and start it again if it was stopped. This means that for some frames the data might be invalid.

    using Unity.Engine;
    using Tobii.EyeTracking;

    public class ExampleClass : MonoBehaviour
    {
        void Update()
        {
            GazePoint gazePoint = EyeTracking.GetGazePoint();
            if (gazePoint.IsValid)
            {
                print("Gaze point on Screen (X,Y): " + gazePoint.Screen.X + ", " + gazePoint.Screen.Y);
            }
        }
    }

↑ Back to Top

## EyeTracking.GetGazeTrackingStatus

static function on `EyeTracking`
`public static` `GazeTracking` `GetGazeTrackingStatus()`

Get the gaze tracking status, which indicates if the user's eye-gaze is currently tracked or not by the eye tracker. This status can be used in combination with a data point's IsValid flag to know if a data point from `EyeTracking.GetGazePoint()` is recent and valid.

This status reflects the status of the eye tracker rather than of the EyeTracker Framework. Before a gaze point data provider has been initialized this status can return `GazeTrackingStatus.GazeTracked` even though `EyeTracking.GetGazePoint()` returns an invalid `GazePoint` in the same frame. To avoid this, call `EyeTracking.Initialize()` some frames before calling these functions.

    using Unity.Engine;
    using Tobii.EyeTracking;

    public class ExampleClass : MonoBehaviour
    {
        void Update()
        {
            GazeTracking gazeTracking = EyeTracking.GetGazeTrackingStatus();
            if (gazeTracking.IsTrackingEyeGaze)
            {
                print("The eye tracker is tracking the user's eye-gaze.");
            }

            print("Gaze tracking status is: " + gazeTracking.Status);
        }
    }

↑ Back to Top

## EyeTracking.GetFocusedObject

static function on `EyeTracking`
`public static UnityEngine.GameObject GetFocusedObject()`
→ View related entry in Manual

### Description

Gets the 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.EyeTracking;

    public class ExampleClass : MonoBehaviour
    {
        void Update()
        {
            GameObject focusedObject = EyeTracking.GetFocusedObject();
            if (null != focusedObject)
            {
                print("The focused game object is: " + focusedObject.name + " (ID: " + focusedObject.GetInstanceID() + ")");
            }
        }
    }

↑ Back to Top

## EyeTracking.GetUserPresence

static function on `EyeTracking`
`public static` `UserPresence` `GetUserPresence()`

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

The `UserPresence` property `IsUserPresent` is 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 `UserPresenceStatus.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` is false. If you need to avoid false negatives for these special cases, use the more detailed information in the `Status` property instead.

    using Unity.Engine;
    using Tobii.EyeTracking;

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

            print("User presence status is: " + userPresence.Status);
        }
    }

↑ Back to Top

## EyeTracking.Initialize

static function on `EyeTracking`
`public static void Initialize()`

### Description

Initializes EyeTracking and 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 `EyeTracking.GetGazePoint()` or `EyeTracking.GetFocusedObject()`, and there will be some frames before that method returns valid gaze points.

↑ Back to Top

## EyeTracking.SetCurrentUserViewPointCamera

static function on `EyeTracking`
`public static void SetCurrentUserViewPointCamera(Camera camera)`

### Parameters

Parameter 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:

- 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

↑ Back to Top

## EyeTracking.UnsubscribeGazePointData

static function on `EyeTracking`
`public static void UnsubscribeGazePointData()`

### Description

Unsubscribes from gaze point data.

Call this method to make the EyeTracking class unsubscribe from the gaze point data provider. If there are no other subscribers the data provider will be stopped completely, otherwise it will keep providing data to the other subscribers.

The EyeTracking class will re-subscribe to gaze point data at the next call to `EyeTracking.GetGazePoint()`.

↑ Back to Top

# COMPONENTS

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

## GazeAware

class in `Tobii.EyeTracking` 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 `EyeTracking.GetFocusedObject()`. Only game objects with the `GazeAware` component or some other component that implements the `IGazeFocusable` interface can get gaze focus.

### Properties

Property name | Type | Description
--- | --- | ---
HasGazeFocus | `bool` | True if the game object it is attached to has gaze focus, false otherwise

↑ Back to Top

# DATA TYPES AND ENUMS

This section describes the data types and enums used with the static `EyeTracking` API. Additional types and enums are described in the advanced API.

- GazePoint
- GazeTracking
- GazeTrackingStatus
- UserPresence
- UserPresenceStatus

## GazePoint

value type in `Tobii.EyeTracking` 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 either `IsValid` or `IsWithinScreenBounds`. Invalid points will be returned by the EyeTracking framework during startup and shutdown, a few frames after calling `EyeTracking.GetGazePoint()` (or `EyeTracking.Initialize()`) 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 `SequentialID` can be used to uniquely identify a `GazePoint` and also which point is the newest. A newer point will have a `SequentialID` that is greater than an older point.

Two `GazePoint`s can have the same `Timestamp` if they were received in the same frame.

`IsWithinScreenBounds` will flicker between true and false when the user looks close to the edges of the game view. If you need a more stable check around the edges, use `IsValid` and check against `Screen.height` and `Screen.width` with some small margin.

### Properties

Property name | Type | Description
--- | --- | ---
GUI | `Vector2` | The gaze point in GUI space (where (0,0) is upper left corner)
IsValid | `bool` | True if the point is valid, false otherwise
IsWithinScreenBounds | `bool` | True if the point is valid and within `Screen.height` and `Screen.width`, false otherwise
Screen | `Vector2` | The gaze point in screen space (where (0,0) is lower left corner)
SequentialID | `double` | A sequential ID, where a newer the point has a greater value than an older point
Timestamp | `float` | The `Time.time` timestamp of the frame when the gaze point was received from the eye tracker
Viewport | `Vector2` | The gaze point in viewport space

### Static properties

Property name | Description
--- | ---
Invalid | Creates a value representing an invalid `GazePoint`

↑ Back to Top

## GazeTracking

value type in `Tobii.EyeTracking` namespace

### Description

Value type holding eye-gaze tracking status information. See also `EyeTracking.GetGazeTrackingStatus()`.

### Properties

Property name | Type | Description
--- | --- | ---
IsTrackingEyeGaze | `bool` | True if the user's eye-gaze is tracked, false otherwise
Status | `GazeTrackingStatus` | The status as an enum value (gives more detailed information)

↑ Back to Top

## GazeTrackingStatus

enum in `Tobii.EyeTracking` namespace

### Description

Describes possible gaze tracking statuses. See also `EyeTracking.GetGazeTrackingStatus()`.

### Values

Value name | Description
--- | ---
Unknown | Gaze tracking status is unknown, the system might for example be initializing
GazeTracked | The user's eye-gaze is tracked
GazeNotTracked | The user's eye-gaze is not tracked
NotSupported | Gaze tracking status is not supported on the Togii Engine version the user has

↑ Back to Top

## UserPresence

value type in `Tobii.EyeTracking` namespace

### Description

Value type holding user presence status information.

`IsUserPresent` can give false negatives for example during initialization when the user presence status is `UserPresenceStatus.Unknown`.

See also `EyeTracking.GetUserPresence()`.

### Properties

Property name | Type | Description
--- | --- | ---
IsUserPresent | `bool` | True if `Status` is `UserPresenceStatus.Present`, false otherwise
Status | `UserPresenceStatus` | The status as an enum (gives more detailed information)

↑ Back to Top

## UserPresenceStatus

enum in `Tobii.EyeTracking` namespace

### Description

Describes possible user presence statuses. See also `EyeTracking.GetUserPresence()`.

### Values

Value 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 Top

# ADVANCED API FEATURES

The advanced API provides additional features as well as the features of the static API, but for some features they assume familiarity with more advanced C# language features and object oriented programming. The entry point to the advanced API is the `EyeTrackingHost.GetInstance()` function, which returns an `IEyeTrackingHost`.

- DeviceStatus
- EngineAvailability
- EyeTrackingHost.GetEngineAvailability
- EyeTrackingHost.GetInstance
- FocusedObject
- IDataProvider<GazePoint>
- IDataProvider<GazePoint>.Last
- IDataProvider<GazePoint>.GetFrameConsistentDataPoint
- IDataProvider<GazePoint>.GetDataPointsSince
- IDataProvider<GazePoint>.Start
- IDataProvider<GazePoint>.Stop
- IEyeTrackingHost
- IEyeTrackingHost.DisplaySize
- IEyeTrackingHost.EyeTrackingDeviceStatus
- IEyeTrackingHost.GetGazePointDataProvider
- IEyeTrackingHost.Initialize
- IEyeTrackingHost.ScreenBounds
- IEyeTrackingHost.Shutdown
- IGazeFocus
- IGazeFocusable
- IRegisterGazeFocusable
- IStateValue<T>
- ITimestamped

## DeviceStatus

enum in `Tobii.EyeTracking` namespace [Advanced]

### Description

Describes possible eye tracking device statuses. See also `IEyeTrackingHost.EyeTrackingDeviceStatus`.

### Values

Value name | Description
--- | ---
Disabled | The eye tracking device is disabled by the user (it might be unplugged)
NotAvailable | The eye tracking device is unavailable
Pending | Connection to the eye tracking device is pending (initializing or connecting)
Tracking | The eye tracking device is tracking (that is, trying to track the user's eye-gaze)
Unknown | The eye tracking device is in an unknown state

↑ Back to Top

## EngineAvailability

enum in `Tobii.EyeTracking` namespace [Advanced]

### Description

Describes possible engine availability states. See also `EyeTrackingHost.GetEngineAvailability()`.

### Values

Value name | Description
--- | ---
NotAvailable | Tobii Engine is not available (not installed)
NotRunning | Tobii Engine is installed but not running
Running | Tobii Engine is running

↑ Back to Top

## EyeTrackingHost.GetEngineAvailability

static function on `EyeTrackingHost` [Advanced]
`public static` `EngineAvailability` `GetEngineAvailability()`

### Description

Engine availability on the current system and platform.

Use this method to check if there is a Tobii Engine runtime available or not. Useful query for games that build standalone for Linux and Mac, to block or not use Tobii EyeTracking features on these platforms.

↑ Back to Top

## EyeTrackingHost.GetInstance

static function on `EyeTrackingHost` [Advanced]
`public static` `IEyeTrackingHost` `GetInstance()`

### Description

This is the access point for all advanced API features in the Tobii EyeTracking Framework for Unity. It should always be used to access the features on the `IEyeTrackingHost`, it should never be used to store a reference to the eye tracking host since that could lead to unexpected behavior during startup, shutdown and on unsupported platforms.

It returns an `IEyeTrackingHost` and the implementation depends on where in the application life cycle the game is, and on which platform. During startup and shutdown, and on unsupported standalone platforms (currently Mac and Linux), this method returns a stub implementation of the eye tracking host. The stub implementation can be used as the real implementation, but it will only deliver invalid gaze data, states and gaze focus objects. Make sure your game is implemented in a way so that it can handle invalid data. In most cases there is an `IsValid` flag that can be checked before using a value.

↑ Back to Top

## FocusedObject

value type in `Tobii.EyeTracking` namespace

### Description

Value type holding information about a focused game object. See also `IGazeFocus`.

### Properties

Property name | Type | Description
--- | --- | ---
IsValid | `bool` | True if the `FocusedObject` is valid and its properties not null, false otherwise.
Key | `int` | A unique integer key that can be used to identify or index this `FocusedObject`
GameObject | `UnityEngine.GameObject` | Focused `UnityEninge.GameObject`. Null if `FocusedObject` is invalid.

### Static Functions

Function name | Description
--- | ---
Invalid | Creates an invalid `FocusedObject` (with a null `GameObject`)

### Public Functions

Function name | Description
--- | ---
Equals | Returns true if a given `FocusedObject` equals this `FocusedObject`, false otherwise.

↑ Back to Top

## IDataProvider<GazePoint>

interface in `Tobii.EyeTracking` namespace [Advanced]

### Description

A `IDataProvider<GazePoint>` provides functions for controlling and accessing a stream of `GazePoint` data from the eye tracker. It offers more control and functionality than the `EyeTracking.GetGazePoint()` function in the static API.

For performance reasons, there is only one GazePoint data provider instance implementing the `IDataProvider<GazePoint>` in the framework. This provider is shared between all client scripts/classes who will request the provider to be started and stopped using their unique token ID's. The provider is retrieved by calling `EyeTrackingHost.GetInstance().GetGazePointDataProvider()`.

### Properties

Property name | Type | Description
--- | --- | ---
Last | `GazePoint` | Gets the last (newest) `GazePoint`. Can change at any time during a frame.

### Functions

Function name | Description
--- | ---
GetFrameConsistentDataPoint | Gets the last `GazePoint` that can be consistently read in the frame
GetDataPointsSince | Gets data points received since an `ITimestamped` gaze point
Start | Starts the data provider
Stop | Requests to stops the data provider

### Access and Usage

    using Tobii.EyeTracking;
    using System.Collections.Generic;
    ...

    public class ExampleClass : MonoBehaviour
    {
        private IDataProvider<GazePoint> _gazePointProvider;
        private ITimestamped _lastHandledPoint;

        OnStart()
        {
            _gazePointProvider = EyeTrackingHost.GetInstance().GetGazePointDataProvider();
        }

        OnEnable()
        {
            // Start the provider with the game object's instance ID as a unique token
            _gazePointProvider.Start(gameObject.GetInstanceID());
        }

        OnDisable()
        {
            // Request to stop the provider for this unique token
            _gazePointProvider.Stop(gameObject.GetInstanceID());
        }

        Update()
        {
            // Handle single gaze point:
            GazePoint last = _gazePointProvider.Last; // the last data point received from the eye tracker
            GazePoint frameConsistent = _gazePointProvider.GetFrameConsistentDataPoint() // same as EyeTracking.GetGazePoint()
            // ...

            // Or handle all gaze points from the eye tracker:
            IEnumerable<GazePoint> pointsSinceLastHandled = _gazePointProvider.GetDataPointsSince(_lastHandledPoint);
            foreach (point in pointsSinceLastHandled)
            {
                // handle each point that has arrived since previous Update()
                // ...
            }
            _lastHandledPoint = pointsSinceLastHandled.Last();
        }
    }

↑ Back to Top

## IDataProvider<GazePoint>.Last

property on `IDataProvider<GazePoint>` [Advanced]
`GazePoint` `Last { get; }`

### Description

Gets the last `GazePoint` that has been received from the eye tracker.

This value can change at any time during a frame. If you want two separate scripts to be guaranteed to act on the same value in the same frame, use the `GetFrameConsistentDataPoint` property instead.

See `IDataProvider<GazePoint>` for a code sample.

↑ Back to Top

## IDataProvider<GazePoint>.GetFrameConsistentDataPoint

function on `IDataProvider<GazePoint>` [Advanced]
`public` `GazePoint` `GetFrameConsistentDataPoint()`

### Description

Gets the last `GazePoint` that can be read consistently in the frame. When this function or the `Last` property has been called in a frame from any script, all the following calls in the same frame to this function will return that same value no matter if the `Last` property is changed to a newer value.

This is the same value as returned by `EyeTracking.GetGazePoint()` in the static API.

See `IDataProvider<GazePoint>` for a code sample.

↑ Back to Top

## IDataProvider<GazePoint>.GetDataPointsSince

function on `IDataProvider<GazePoint>` [Advanced]
`public IEnumerable<``GazePoint``> GetDataPointsSince(``ITimestamped` `dataPoint)`

### Parameters

Parameter name | Type | Description
--- | --- | ---
dataPoint | `ITimestamped` | The function will return `GazePoint`s newer than the timestamped dataPoint.

### Description

Gets all `GazePoint`s that have been received from the eye tracker since the supplied `ITimestamped` 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 `Last` or `GetFrameConsistentDataPoint` you will likely miss some points since the game and the eye tracker will probably not run in the exact same frequency.

The `GazePoint` data type implements the `ITimestamped` interface, meaning that this function will take a `GazePoint` as a parameter. By saving the last handled gaze point from the previous Update loop, this point can be used as a parameter for the next Update loop and all gaze points that were received from the eye tracker since then can be retrieved using this function.

See `IDataProvider<GazePoint>` for a code sample.

↑ Back to Top

## IDataProvider<GazePoint>.Start

function on `IDataProvider<GazePoint>` [Advanced]
`void Start(int subscriberId)`

### Parameters

Parameter name | Type | Description
--- | --- | ---
subscriberId | `int` | A unique subscriber ID for the calling script/class

### Description

Asynchronous request to start the data provider. After the data provider has been started data will continuously be updated in the `Last` property in the frequency it is received from the eye tracker. Since the function is asynchronous, and it will take a few frames until the first data is received from the eye tracker.

The function takes a unique subscriber ID as a parameter. For performance reasons, there is only one GazePoint data provider instance implementing the `IDataProvider<GazePoint>` in the framework. This provider is shared between all client scripts/classes who will request the provider to be started and stopped using their unique token ID's. To get a unique ID, you can use `gameObject.GetInstanceID()` if the client is a `MonoBehaviour` script. For a non-MonoBehaviour class, you can create a `UnityEngine.GameObject` as a private field and use its instance ID.

See `IDataProvider<GazePoint>` for a code sample.

↑ Back to Top

## IDataProvider<GazePoint>.Stop

function on `IDataProvider<GazePoint>` [Advanced]
`void Stop(int subscriberId)`

### Parameters

Parameter name | Type | Description
--- | --- | ---
subscriberId | `int` | A unique subscriber ID for the calling script/class

### Description

Asynchronous requests to stop the data provider. If there are no other clients that are currently requesting the provider to keep providing data, the provider will stop the stream of data from the the eye tracker and stop updating the `Last` property.

The function takes a unique subscriber ID as a parameter. For the data provider to work as expected, every client script/class should have its own unique ID and call the `Start` and `Stop` function with this ID. See `Start` for more info.

See `IDataProvider<GazePoint>` for a code sample.

↑ Back to Top

## IEyeTrackingHost

interface in `Tobii.EyeTracking` namespace [Advanced]

### Description

This interface describes the advanced API features that can be accessed using the static function `EyeTrackingHost.GetInstance()`.

For more information about:

- User Presence, see `EyeTracking.GetUserPresence()`
- Gaze Focus, see `IGazeFocus`
- Gaze Tracking, see `EyeTracking.GetGazeTrackingStatus()` and compare with `EyeTrackingDeviceStatus`

### Properties

Property name | Type | Description
--- | --- | ---
IsInitialized | `bool` | True if the host is initialized, false otherwise
DisplaySize | `IStateValue``<Vector2>` | Size of the eye tracked screen, in mm (width, height)
EngineVersion | `System.Version` | Tobii Engine version installed on the system the game is running on
EyeTrackingDeviceStatus | `DeviceStatus` | The eye tracking status of the eye tracker
GazeFocus | `IGazeFocus` | Gets the gaze focus handler
GazeTracking | `GazeTracking` | Status of the eye-gaze tracking
ScreenBounds | `IStateValue``<UnityEngine.Rect>` | Bounds of the eye tracked screen, in desktop pixels
UserPresence | `UserPresence` | Status of user presence in front of the screen
UserProfileName | `IStateValue``<string>` | Name of the current calibration user profile
UserProfileNames | `IStateValue``<string[]>` | A list of available calibration user profiles

### Functions

Function name | Description
--- | ---
GetGazePointDataProvider | Gets a `GazePoint` data provider
Initialize | Initializes the eye tracking host
Shutdown | Signals the eye tracking host that the game is shutting down
SetCurrentProfile | Sets the current calibration user profile

↑ Back to Top

## IEyeTrackingHost.DisplaySize

property on `IEyeTrackingHost` [Advanced]
`IStateValue` `<Vector2> DisplaySize { get; }`

### Description

Gets the engine state Display Size as a `UnityEngine.Vector2` (width, height), in millimeters. This is the screen size in millimeters of the display monitor set up for eye tracking.

↑ Back to Top

## IEyeTrackingHost.EyeTrackingDeviceStatus

property on `IEyeTrackingHost` [Advanced]
`DeviceStatus` `EyeTrackingDeviceStatus { get; }`

→ View related entry in Manual

### Description

The eye tracking status of the eye tracker device.

If this property returns a status of `DeviceStatus.Tracking` it means that the eye tracker is connected, up and running and trying to track the user's eye-gaze. Whenever it succeeds to track the eye-gaze, it will calculate a gaze point on the screen. No gaze point will be calculated if the eye-gaze cannot be tracked for the moment, for example if the user's eyes are closed or partly closed by a blink. (To follow the instantaneous status of the eye tracker's tracking of the eye-gaze, use the `GazeTracking` state).

Any other device status than `DeviceStatus.Tracking` means that no eye tracking data can be expected - the eye tracker could for example not be connected, be initializing, or eye tracking could be disabled by the user.

Note that this status will always return an invalid value the first time it is called. A valid value will be returned within some frames after that first call.

    DeviceStatus deviceStatus = EyeTrackingHost.GetInstance().EyeTrackingDeviceStatus;
    if (DeviceStatus.Tracking == deviceStatus)
    {
        //...
    }

↑ Back to Top

## IEyeTrackingHost.GetGazePointDataProvider

function on `IEyeTrackingHost` [Advanced]
`IDataProvider<GazePoint>` `GetGazePointDataProvider()`

### Description

Gets a provider of `GazePoint` data. See `IDataProvider<GazePoint>` for code example of usage.

↑ Back to Top

## IEyeTrackingHost.Initialize

function on `IEyeTrackingHost` [Advanced]
`void Initialize()`

### Description

Initializes the `IEyeTrackingHost` and connection to the Tobii Engine.

This function is automatically called when the `IEyeTrackingHost` `MonoBehaviour` instance is enabled (from the `Start()` function). It only needs to be called explicitly if you need to access a function or property on the `IEyeTrackingHost` before the `Start` message has been processed by all game objects in the scene.

↑ Back to Top

## IEyeTrackingHost.ScreenBounds

property on `IEyeTrackingHost` [Advanced]
`IStateValue` `<UnityEngine.Rect> ScreenBounds { get; }`

### Description

Gets the engine state Screen Bounds in pixels. This is the eye-tracked display monitor's screen size in physical (desktop) pixels.

↑ Back to Top

## IEyeTrackingHost.Shutdown

function on `IEyeTrackingHost` [Advanced]

### Description

Signals that the game application is shutting down. This will clear all settings and data providers. After this method has been called `EyeTrackingHost.GetInstance()` will return a stub implementation that only provides invalid states and data points, making sure no inconsistent data or behavior during shutdown.

↑ Back to Top

## IGazeFocus

interface in `Tobii.EyeTracking` namespace [Advanced]
→ View related entry in Manual

### Description

Defines the public interface of the gaze focus handler.

The gaze focus handler is responsible for calculating and keeping track of which object the user is focusing his or her eye-gaze on. Only gaze-aware objects can get gaze focus. The gaze focus handler automatically keeps track of objects that have the `GazeAware` component. (Custom gaze-aware components implementing `IGazeFocusable` should register themselves using the `IRegisterGazeFocusable` interface).

See `EyeTracking.SetCurrentUserViewPointCamera()` for more information about the settable camera.

    IGazeFocus gazeFocusHandler = EyeTrackingHost.GetInstance().GazeFocus;

### Properties

Property name | Type | Description
--- | --- | ---
Camera | `UnityEngine.Camera` | Settable camera that defines the user's current view point
FocusedObject | `FocusedObject` | Gets the currently focused object. Invalid if no object is focused.

↑ Back to Top

## IGazeFocusable

interface in `Tobii.EyeTracking` namespace [Advanced]
→ View related entry in Manual

### Description

Defines a component that can be registered in the gaze focus handler so that the `UnityEngine.GameObject` it belongs to can be focused using eye-gaze. (See also `IGazeFocus`.)

When an `IGazeFocusable` object is looked at, its `UpdateGazeFocus` function is called with `hasFocus` set to `true`. This value can then be read in the update loop of the game object to react to being looked at.

If you don't want each game object to react on its own to being looked at, you can centralize the handling using `IGazeFocus.FocusedObject` (or `EyeTracking.GetFocusedObject()`).

IGazeFocusable is implemented by the `GazeAware` component. Implement this interface if you want to create your own custom gaze-aware component. The custom gaze-aware component must register and unregister itself to and from the gaze focus handler, see 'IRegisterGazeFocusable' and the source code for the 'GazeAware' component below:

    // This is the source code for the GazeAware component
    // Use this as a starting point to implement a custom gaze-aware component
    // The HazGazeFocus property is optional as long as the 'hasFocus' value is handled
    // somehow, but the register/unregister code is essential.

    public class GazeAware : MonoBehaviour, IGazeFocusable
    {
        public bool HasGazeFocus { get; private set; }

        void OnEnable()
        {
            GazeFocusHandler().RegisterFocusableComponent(this);
        }

        void OnDisable()
        {
            GazeFocusHandler().UnregisterFocusableComponent(this);
        }

        /// <summary>
        /// Function called from the gaze focus handler when the gaze focus for
        /// this object changes.
        /// </summary>
        /// <remarks>Since the implementation is explicit, it will not be
        /// visible on instances of this component (unless cast to
        /// <see cref="IGazeFocusable"/>).
        /// </remarks>
        /// <param name="hasFocus">True if the game object has gaze focus,
        /// false otherwise.</param>
        void IGazeFocusable.UpdateGazeFocus(bool hasFocus)
        {
            HasGazeFocus = hasFocus;
        }

        private IRegisterGazeFocusable GazeFocusHandler()
        {
            return (IRegisterGazeFocusable)EyeTrackingHost.GetInstance().GazeFocus;
        }
    }

### Properties

Property name | Type | Description
--- | --- | ---
gameObject | `UnityEngine.GameObject` | The game object the component is tied to

### Public Functions

Function name | Description
--- | ---
UpdateGazeFocus | Called when the focusable object's gaze focus is changed

↑ Back to Top

## IRegisterGazeFocusable

interface in `Tobii.EyeTracking` namespace [Advanced]

### Description

Registration API on the gaze focus handler for registering and unregistering `IGazeFocusable` objects/components. Only game objects with registered `IGazeFocusable` components can get gaze focus.

Used by the `GazeAware` component to register and unregister itself at OnEnable and OnDisable respectively.

Use this API to register custom GazeAware components that implement the `IGazeFocusable` interface.

    // get the gaze focus handler with the registration API:
    var gazeFocusHandler = (IRegisterGazeFocusable)EyeTrackingHost.GetInstance().GazeFocus;

    // register 'this' as a custom gaze-aware component - requires that 'this' implements IGazeFocusable
    gazeFocusHandler.RegisterFocusableComponent(this);

See also the `GazeAware` component source code.

### Public Functions

Function name | Description
--- | ---
RegisterFocusableComponent | Registers the supplied `IGazeFocusable` component so that its `GameObject` can get gaze focus
UnregisterFocusableComponent | Unregisters the supplied `IGazeFocusable` component

↑ Back to Top

## IStateValue<T>

interface in `Tobii.EyeTracking` namespace [Advanced]

### Description

Value type holding information about a state value.

If `IsValid` is false, the `Value` can be `null` if the type T is nullable.

### Properties

Property name | Type | Description
--- | --- | ---
IsValid | `bool` | True if the state value is valid, false otherwise
Value | `T` | State value. Can be `null` if the state value is invalid

↑ Back to Top

## ITimestamped

interface in `Tobii.EyeTracking` namespace [Advanced]

### Description

Value type holding information about a timestamped data point.

The `SequentialId` can be used to compare if a data point is newer than another. A higher value means a newer value.

The `Timestamp` cannot be used to compare if a data point is newer than another since more than one data point can be received in the same frame and have the same `Time.time` timestamp.

### Properties

Property name | Type | Description
--- | --- | ---
IsValid | `bool` | True if valid, false otherwise
SequentialId | `double` | SequentialId for the data point. A higher value means a newer value
Timestamp | `float` | The `Time.time` timestamp of the frame when the data point was received from the eye tracker