SDK version: 3.0 Beta
static class in Tobii.Gaming
namespace
The TobiiAPI is a static API that provides direct access to the most common and useful functionality of the Tobii Unity SDK framework.
TobiiAPI
is a static class with static methods to easily access data from a connected Tobii eye tracker.
To get access to TobiiAPI
, import the Tobii Unity SDK into your project and add the following using (at the top of the script file where you want to use the Tobii API):
using Tobii.Gaming;
TobiiAPI
provides simplified and straightforward access to eye tracker data and can be used for the most common use cases.
TobiiAPI
also provides information about which UnityEngine.GameObject
the user focuses using eye-gaze. Only gaze aware objects will be considered for gaze focus detection. The way to make an object gaze-aware is to add the GazeAware
component to it.
Name | Description |
---|---|
GetDisplayInfo | Gets info about the eye tracked display monitor. |
GetFocusedObject | Gets the game object with gaze focus. |
GetGazePoint | Gets the last (newest) GazePoint . |
GetGazePointsSince | Gets the gaze points since a given GazePoint . |
GetHeadPose | Gets the last (newest) HeadPose |
GetHeadPosesSince | Gets the head poses since a given HeadPose . |
GetUserPresence | Gets the user presence status. |
SetCurrentUserViewPointCamera | Sets the camera used for gaze focus detection. |
SubscribeGazePointData | Subscribes to gaze point data. |
SubscribeHeadPostData | Subscribes to head pose data. |
↑ Back to Section start | ↑ Back to Top |
static function on TobiiAPI
public static
DisplayInfo
GetDisplayInfo()
Type | Description |
---|---|
DisplayInfo |
Value object with information about the eye tracked display monitor. Can be invalid, check IsValid before using. |
Gets a DisplayInfo
value object with information about the eye tracked display monitor.
↑ Back to Section start | ↑ Back to Top |
static function on TobiiAPI
public static UnityEngine.GameObject GetFocusedObject()
→ View related entry in Manual
Type | Description |
---|---|
UnityEngine.GameObject |
The object the user is focused on by looking at it. Can be null if no object is focused. |
Gets the game object with gaze focus, or returns null if there is no game object with gaze focus.
Only game objects that are gaze-aware will be considered for gaze focus detection. The easiest way to make a game object gaze-aware is to add the GazeAware
component to it. Another way is to implement your own custom gaze-aware component, see IGazeFocusable
.
using Unity.Engine;
using Tobii.Gaming;
public class ExampleClass : MonoBehaviour
{
void Update()
{
GameObject focusedObject = TobiiAPI.GetFocusedObject();
if (null != focusedObject)
{
print("The focused game object is: " + focusedObject.name + " (ID: " + focusedObject.GetInstanceID() + ")");
}
}
}
↑ Back to Section start | ↑ Back to Top |
static function on TobiiAPI
public static
GazePoint
GetGazePoint()
→ View related entry in Manual
Type | Description |
---|---|
GazePoint |
Where on the screen the user is looking. Can be invalid, check GazePoint.IsValid before using or use GazePoint.IsRecent() function to ensure that it’s both valid and recent. |
Gets the last GazePoint
.
The TobiiAPI
class is initialized lazily if TobiiAPI.SubscribeGazePointData()
is not called first. This means that the data provider is started at the first call to this function (or the TobiiAPI.GetFocusedObject()
function), and the function will return an invalid value for some frames until valid data is received from the eye tracker.
using Unity.Engine;
using Tobii.Gaming;
public class ExampleClass : MonoBehaviour
{
void Update()
{
GazePoint gazePoint = TobiiAPI.GetGazePoint();
if (gazePoint.IsRecent()) // Use IsValid property instead to process old but valid data
{
// Note: Values can be negative if the user looks outside the game view.
print("Gaze point on Screen (X,Y): " + gazePoint.Screen.x + ", " + gazePoint.Screen.y);
}
}
}
↑ Back to Section start | ↑ Back to Top |
static function on TobiiAPI
public static IEnumerable<GazePoint> GetGazePointsSince(
GazePoint
gazePoint)
Name | Type | Description |
---|---|---|
gazePoint | GazePoint |
Typically an already handled gaze point. The function will return all gaze points newer than this gaze point, but at most 500 ms old. An invalid gaze point as parameter will return all data points newer than 500 ms. |
Type | Description |
---|---|
IEnumerable<GazePoint> |
All the GazePoint s that have been received from the eye tracker since the supplied gaze point. |
Gets all GazePoint
s that have been received from the eye tracker since the supplied gaze point, but no older than 500 ms.
This function is useful when you want to do your own advanced filtering of the gaze point data and include all received gaze points in the calculation. If you use GetGazePoint()
you will likely miss some points from the eye tracker, since the game and the eye tracker will probably not run in the exact same frequency.
You can save your last handled data point in the Update loop, and use it as a parameter for this function in the next Update loop to retrieve all new data points. For the first iteration, when the data point is invalid, the function will return all points received within the last 500 ms.
using System.Collections.Generic;
...
public class ExampleClass : MonoBehaviour
{
private GazePoint _lastHandledPoint = GazePoint.Invalid;
Update()
{
IEnumerable<GazePoint> pointsSinceLastHandled = TobiiAPI.GetGazePointsSince(_lastHandledPoint);
foreach (point in pointsSinceLastHandled)
{
// handle each point that has arrived since previous Update()
// ...
}
_lastHandledPoint = pointsSinceLastHandled.Last();
}
}
↑ Back to Section start | ↑ Back to Top |
static function on TobiiAPI
public static
HeadPose
GetHeadPose()
→ View related entry in Manual
Type | Description |
---|---|
HeadPose |
Where on the screen the user is looking. Can be invalid, check HeadPose.IsValid before using or HeadPose.IsRecent() to check that it’s both valid and recent. |
Gets the last HeadPose
.
The TobiiAPI
class is initialized lazily if TobiiAPI.SubscribeHeadPoseData()
is not called first. This means that the data provider is started at the first call to this function, and the function will return an invalid value for some frames until valid data is received from the eye tracker.
using Unity.Engine;
using Tobii.Gaming;
public class ExampleClass : MonoBehaviour
{
void Update()
{
HeadPose headPose = TobiiAPI.GetHeadPose();
if (headPose.IsRecent())
{
print("HeadPose Position (X,Y,Z): " + headPose.Position.x + ", " + headPose.Position.y + ", " + headPose.Position.z);
print("HeadPose Rotation (X,Y,Z): " + headPose.Rotation.eulerAngles.x + ", " + headPose.Rotation.eulerAngles.y + ", " + headPose.Rotation.eulerAngles.z);
}
}
}
↑ Back to Section start | ↑ Back to Top |
static function on TobiiAPI
public static IEnumerable<HeadPose> GetHeadPosesSince(
HeadPose
headPose)
Name | Type | Description |
---|---|---|
headPose | HeadPose |
Typically an already handled head pose. The function will return all head poses newer than this head pose, but at most 500 ms old. An invalid head pose as parameter will return all data points newer than 500 ms. |
Type | Description |
---|---|
IEnumerable<HeadPose> |
All the HeadPose s that have been received from the eye tracker since the supplied head pose. |
Gets all HeadPose
s that have been received from the eye tracker since the supplied head pose, but no older than 500 ms.
This function is useful when you want to do your own advanced filtering of the head pose data and include all received head poses in the calculation. If you use GetHeadPose()
you will likely miss some points from the eye tracker, since the game and the eye tracker will probably not run in the exact same frequency.
You can save your last handled data point in the Update loop, and use it as a parameter for this function in the next Update loop to retrieve all new data points. For the first iteration, when the data point is invalid, the function will return all points received within the last 500 ms.
using System.Collections.Generic;
...
public class ExampleClass : MonoBehaviour
{
private HeadPose _lastHandledPoint = HeadPose.Invalid;
Update()
{
IEnumerable<HeadPose> pointsSinceLastHandled = TobiiAPI.GetHeadPosesSince(_lastHandledPoint);
foreach (point in pointsSinceLastHandled)
{
// handle each point that has arrived since previous Update()
// ...
}
_lastHandledPoint = pointsSinceLastHandled.Last();
}
}
↑ Back to Section start | ↑ Back to Top |
static function on TobiiAPI
public static
UserPresence
GetUserPresence()
Type | Description |
---|---|
UserPresence |
User presence status, indicating if there is a user in front of the eye tracker. |
Get the user presence, which indicates if there is a user present in front of the screen/eye tracker.
The UserPresence
extension method IsUserPresent()
returns true if the system detects a user in front of the eye tracker. It is false if the system cannot detect a user in front of the eye tracker, but it is also false if the user presence status is UserPresence.Unknown
. This means that this property can give false negatives if the user presence status is unknown. For example during initializing, or if eye tracking has been disabled by the user, the user can be in front of the eye tracker but IsUserPresent()
returns false. If you need to avoid false negatives for these special cases, check enum value instead.
using Unity.Engine;
using Tobii.Gaming;
public class ExampleClass : MonoBehaviour
{
void Update()
{
UserPresence userPresence = TobiiAPI.GetUserPresence();
if (userPresence.IsUserPresent())
{
print("A user is present in front of the screen.");
}
print("User presence status is: " + userPresence);
}
}
↑ Back to Section start | ↑ Back to Top |
static function on TobiiAPI
public static void SetCurrentUserViewPointCamera(Camera camera)
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:
GazePoint gazePoint
camera.ScreenPointToRay(gazePoint.Screen)
↑ Back to Section start | ↑ Back to Top |
static function on TobiiAPI
public static void SubscribeGazePointData()
Starts the gaze point data provider.
Use this method if you want to initialize the gaze point data provider explicitly rather than to use the default lazy initialization. If this method is not used, the gaze point data provider will be initialized and started at the first call to TobiiAPI.GetGazePoint()
or TobiiAPI.GetFocusedObject()
, and there will be some frames before that method returns valid gaze points.
↑ Back to Section start | ↑ Back to Top |
static function on TobiiAPI
public static void SubscribeHeadPoseData()
Starts the head pose data provider.
Use this method if you want to initialize the head pose data provider explicitly rather than to use the default lazy initialization. If this method is not used, the head pose data provider will be initialized and started at the first call to TobiiAPI.GetHeadPose()
, and there will be some frames before that method returns valid gaze points.
↑ Back to Section start | ↑ Back to Top |
This section describes components that can be used out-of-the-box to add eye-gaze features to game objects.
class in Tobii.Gaming
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 TobiiAPI.GetFocusedObject()
. Only game objects with the GazeAware
component or some other component that implements the IGazeFocusable
interface can get gaze focus.
Name | Type | Description |
---|---|---|
HasGazeFocus | bool |
True if the game object it is attached to has gaze focus, false otherwise. |
↑ Back to Section start | ↑ Back to Top |
This section describes the data types and enums used with the TobiiAPI
.
value type in Tobii.Gaming
namespace
The DisplayInfo
struct contains information about the eye-tracked display monitor.
Name | Type | Description |
---|---|---|
DisplayWidthMm | float |
The width in millimeters of the eye-tracked display monitor. |
DisplayHeightMm | float |
The height in millimeters of the eye-tracked display monitor. |
IsValid | float |
True if the info object is valid, false otherwise. |
Name | Description |
---|---|
Invalid | Creates a value representing an invalid DisplayInfo instance. |
↑ Back to Section start | ↑ Back to Top |
value type in Tobii.Gaming
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 IsValid
property or use IsRecent()
function to ensure that it’s both valid and recent. Invalid points will be returned by the Tobii Unity SDK framework during startup and shutdown, a few frames after calling TobiiAPI.GetGazePoint()
(or TobiiAPI.SubsribeGazePointData()
) for the first time, and if the data provider is stopped for some reason. Invalid points will always be returned on unsupported standalone platforms, currently Mac and Linux.
The PreciseTimestamp
can be used to compare the timestamps between two GazePoint
s with high accuracy.
Name | Type | Description |
---|---|---|
GUI | Vector2 |
Gaze point in GUI space (where (0,0) is upper left corner). |
IsValid | bool |
True if the point is valid, false otherwise. |
PreciseTimestamp | long |
Precise timestamp of the gaze point. |
Screen | Vector2 |
Gaze point in screen space (where (0,0) is lower left corner). |
Timestamp | float |
Time.unscaledTime timestamp of the gaze point. |
Viewport | Vector2 |
Gaze point in viewport space. |
Name | Description |
---|---|
Invalid | Creates a value representing an invalid GazePoint |
↑ Back to Section start | ↑ Back to Top |
Name | Description |
---|---|
IsRecent | Returns true if the point is valid and recent, false otherwise. |
IsRecent(float maxAge) | Returns true if the point is valid and no older than maxAge seconds, false otherwise. |
value type in Tobii.Gaming
namespace
→ View related entry in Manual
A HeadPose
represents the head position and rotation of the user’s head.
Always check if a HeadPose
is valid before using it. Invalid points will be returned by the Tobii Unity SDK framework during startup and shutdown, a few frames after calling TobiiAPI.GetHeadPose()
(or TobiiAPI.SubscribeHeadPoseData()
) for the first time, and if the data provider is stopped for some reason. Invalid points will always be returned on unsupported standalone platforms, currently Mac and Linux.
The PreciseTimestamp
can be used to compare the timestamps between two HeadPose
s with high accuracy.
Name | Type | Description |
---|---|---|
IsValid | bool |
True if the head pose is valid, false otherwise. |
Position | Vector3 |
(X, Y, Z) position of the head of the user, in millimeters from the center of the eye tracked display monitor’s screen area. |
PreciseTimestamp | long |
The precise timestamp of the head pose. |
Rotation | Quaternion |
Rotation of the head of the user, expressed using Quternion . Use eulerAngles property of the Quaternion to convert it to euler angles. |
Timestamp | float |
The Time.unscaledTime timestamp of the gaze point. |
Name | Description |
---|---|
Invalid | Creates a value representing an invalid HeadPose |
Name | Description |
---|---|
IsRecent | Returns true if the head pose is valid and recent, false otherwise. |
IsRecent(float maxAge) | Returns true if the head pose is valid and no older than maxAge seconds, false otherwise. |
↑ Back to Section start | ↑ Back to Top |
enum in Tobii.Gaming
namespace
Describes possible user presence statuses. See also TobiiAPI.GetUserPresence()
.
Name | Description |
---|---|
Unknown | User presence is unknown, the system might for example be initializing |
Present | User is present |
NotPresent | User is not present |
↑ Back to Section start | ↑ Back to Top |
extension method for UserPresence
public static bool IsUserPresent(this UserPresence userPresence)
Returns true if UserPresence
is UserPresence.Present
, false otherwise.
IsUserPresent()
can give false negatives for example during initialization when the user presence status is UserPresence.Unknown
.