SDK version: 2.0 Beta (Compatibility: Unity 5.4, 5.3, and 5.2)
- EyeTracking static API
- Components
- Data Types and Enums
- 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
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
static class in Tobii.EyeTracking
namespace
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
).
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. |
static function on EyeTracking
public static
GazePoint
GetGazePoint()
→ View related entry in Manual
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);
}
}
}
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);
}
}
static function on EyeTracking
public static UnityEngine.GameObject GetFocusedObject()
→ View related entry in Manual
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() + ")");
}
}
}
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);
}
}
static function on EyeTracking
public static void Initialize()
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.
static function on EyeTracking
public static void SetCurrentUserViewPointCamera(Camera camera)
Parameter name | Type | Description |
---|---|---|
camera | UnityEngine.Camera |
The camera that defines the user's current view point |
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
static function on EyeTracking
public static void UnsubscribeGazePointData()
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()
.
This section describes components that can be used out-of-the-box to add eye-gaze features to game objects.
class in Tobii.EyeTracking
namespace / Inherits from: UnityEngine.MonoBehaviour
/ Implements: IGazeFocusable
→ View related entry in Manual
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.
Property name | Type | Description |
---|---|---|
HasGazeFocus | bool |
True if the game object it is attached to has gaze focus, false otherwise |
This section describes the data types and enums used with the static EyeTracking
API. Additional types and enums are described in the advanced API.
value type in Tobii.EyeTracking
namespace
→ View related entry in Manual
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.
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 |
Property name | Description |
---|---|
Invalid | Creates a value representing an invalid GazePoint |
value type in Tobii.EyeTracking
namespace
Value type holding eye-gaze tracking status information. See also EyeTracking.GetGazeTrackingStatus()
.
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) |
enum in Tobii.EyeTracking
namespace
Describes possible gaze tracking statuses. See also EyeTracking.GetGazeTrackingStatus()
.
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 |
value type in Tobii.EyeTracking
namespace
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()
.
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) |
enum in Tobii.EyeTracking
namespace
Describes possible user presence statuses. See also EyeTracking.GetUserPresence()
.
Value name | Description |
---|---|
Unknown | User presence is unknown, the system might for example be initializing |
Present | User is present |
NotPresent | User is not present |
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
enum in Tobii.EyeTracking
namespace [Advanced]
Describes possible eye tracking device statuses. See also IEyeTrackingHost.EyeTrackingDeviceStatus
.
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 |
enum in Tobii.EyeTracking
namespace [Advanced]
Describes possible engine availability states. See also EyeTrackingHost.GetEngineAvailability()
.
Value name | Description |
---|---|
NotAvailable | Tobii Engine is not available (not installed) |
NotRunning | Tobii Engine is installed but not running |
Running | Tobii Engine is running |
static function on EyeTrackingHost
[Advanced]
public static
EngineAvailability
GetEngineAvailability()
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.
static function on EyeTrackingHost
[Advanced]
public static
IEyeTrackingHost
GetInstance()
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.
value type in Tobii.EyeTracking
namespace
Value type holding information about a focused game object. See also IGazeFocus
.
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. |
Function name | Description |
---|---|
Invalid | Creates an invalid FocusedObject (with a null GameObject ) |
Function name | Description |
---|---|
Equals | Returns true if a given FocusedObject equals this FocusedObject , false otherwise. |
interface in Tobii.EyeTracking
namespace [Advanced]
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()
.
Property name | Type | Description |
---|---|---|
Last | GazePoint |
Gets the last (newest) GazePoint . Can change at any time during a frame. |
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 |
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();
}
}
property on IDataProvider<GazePoint>
[Advanced]
GazePoint
Last { get; }
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.
function on IDataProvider<GazePoint>
[Advanced]
public
GazePoint
GetFrameConsistentDataPoint()
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.
function on IDataProvider<GazePoint>
[Advanced]
public IEnumerable<
GazePoint
> GetDataPointsSince(
ITimestamped
dataPoint)
Parameter name | Type | Description |
---|---|---|
dataPoint | ITimestamped |
The function will return GazePoint s newer than the timestamped dataPoint. |
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.
function on IDataProvider<GazePoint>
[Advanced]
void Start(int subscriberId)
Parameter name | Type | Description |
---|---|---|
subscriberId | int |
A unique subscriber ID for the calling script/class |
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.
function on IDataProvider<GazePoint>
[Advanced]
void Stop(int subscriberId)
Parameter name | Type | Description |
---|---|---|
subscriberId | int |
A unique subscriber ID for the calling script/class |
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.
interface in Tobii.EyeTracking
namespace [Advanced]
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 withEyeTrackingDeviceStatus
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 |
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 |
property on IEyeTrackingHost
[Advanced]
IStateValue
<Vector2> DisplaySize { get; }
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.
property on IEyeTrackingHost
[Advanced]
DeviceStatus
EyeTrackingDeviceStatus { get; }
→ View related entry in Manual
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)
{
//...
}
function on IEyeTrackingHost
[Advanced]
IDataProvider<GazePoint>
GetGazePointDataProvider()
Gets a provider of GazePoint
data. See IDataProvider<GazePoint>
for code example of usage.
function on IEyeTrackingHost
[Advanced]
void Initialize()
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.
property on IEyeTrackingHost
[Advanced]
IStateValue
<UnityEngine.Rect> ScreenBounds { get; }
Gets the engine state Screen Bounds in pixels. This is the eye-tracked display monitor's screen size in physical (desktop) pixels.
function on IEyeTrackingHost
[Advanced]
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.
interface in Tobii.EyeTracking
namespace [Advanced]
→ View related entry in Manual
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;
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. |
interface in Tobii.EyeTracking
namespace [Advanced]
→ View related entry in Manual
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;
}
}
Property name | Type | Description |
---|---|---|
gameObject | UnityEngine.GameObject |
The game object the component is tied to |
Function name | Description |
---|---|
UpdateGazeFocus | Called when the focusable object's gaze focus is changed |
interface in Tobii.EyeTracking
namespace [Advanced]
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.
Function name | Description |
---|---|
RegisterFocusableComponent | Registers the supplied IGazeFocusable component so that its GameObject can get gaze focus |
UnregisterFocusableComponent | Unregisters the supplied IGazeFocusable component |
interface in Tobii.EyeTracking
namespace [Advanced]
Value type holding information about a state value.
If IsValid
is false, the Value
can be null
if the type T is nullable.
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 |
interface in Tobii.EyeTracking
namespace [Advanced]
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.
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 |