Skip to content

Instantly share code, notes, and snippets.

@mellii
Last active March 21, 2017 12:31
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save mellii/cb691cf7c67569853bf20739278d7691 to your computer and use it in GitHub Desktop.
Save mellii/cb691cf7c67569853bf20739278d7691 to your computer and use it in GitHub Desktop.

Tobii EyeTracking SDK for Unity 5 - Scripting Reference

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

Switch to Manual

Contents


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

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

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 GazePoints 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

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 GazePoints newer than the timestamped dataPoint.

Description

Gets all GazePoints 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:

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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment