Though we had hoped that there would not be major changes from the 2.0 (Beta) version of the SDK to the next version, some unforseen circumstances (aren’t there always?) and a move to another underlying eye tracking engine put us in a position where we had to break hard with the previous version of the API no matter what we did. We therefore decided to make an overall review of the API and framework, and have made the total public API more convenient to use, with all relevant functionality directly available as functions on the static TobiiAPI
(previously EyeTracking
) class. Some functionality has been removed indefinately, some other functionality is missing but might be re-added later if/when made available from the underlying eye tracking engine.
// v2.0
using Tobii.EyeTracking;
// v3.0
using Tobii.Gaming;
// v2.0
GazePoint gazePoint = EyeTracking.GetGazePoint();
// v3.0
GazePoint gazePoint = TobiiAPI.GetGazePoint();
We have moved all relevant functions from the “Advanced API” to the static TobiiAPI
, making access to the ITobiiHost
reduntant. We have therefore made the ITobiiHost
and associated classes internal, put them in an internal namespace (Tobii.Gaming.Internal
) and folder called Internal
. These classes are no longer part of the public API. See next sections for more information.
Some functions have been split up to separate more specific functions. Some functionality that were only in the “Advanced API” have now been added to the static TobiiAPI.
// v2.0
EyeTracking.Initialize();
// v3.0
TobiiAPI.SubscribeGazePointData();
TobiiAPI.SubscribeHeadPoseData();
// v2.0
// "Advanced API"
GazePoint lastHandledGazePoint;
IDataProvider<GazePoint> gazePointDataProvider = EyeTrackingHost.GetGazePointDataProvider();
// ...
IEnumerable<GazePoint> newGazePoints = gazePointDataProvider.GetDataPointsSince(lastHandledGazePoint);
// v3.0
// Static TobiiAPI
GazePoint lastHandledGazePoint;
// ...
IEnumerable<GazePoint> newGazePoints = TobiiAPI.GetGazePointsSince(lastHandledGazePoint);
// v2.0
// "Advanced API"
IStateValue<Vector2> displaySize = EyeTrackingHost.GetInstance().DisplaySize;
if (displaySize.IsValid)
{
print("displaySize (width,height): " + displaySize.x + ", " + displaySize.y);
}
// v3.0
// Static TobiiAPI
DisplayInfo displayInfo = TobiiAPI.GetDisplayInfo();
if (displayInfo.IsValid)
{
print("displayInfo (width,height): " + displayInfo.DisplayWidthMm + ", " + displayInfo.DisplayHeightMm);
}
The 3.0 SDK is built on top of a different more low-level eye tracking engine than the 2.0 SDK. This means that some functionality that was available in 2.0 cannot be provided (at least yet) in the 3.0 version. Below are some examples of removed functions and functionality and what we suggest to use/do instead.
// v2.0
UnsubscribeGazePointData();
// v3.0
// (nothing)
// v2.0
IStateValue<UnityEngine.Rect> screenBounds = EyeTrackingHost.GetInstance().ScreenBounds;
// v3.0
// (nothing - we cannot get this information from the eye tracking engine we are now using,
// it might/should be added in a future version of the SDK)
The underlying eye tracking engine we are now using does not provide gaze tracking information. In order to know if the user’s eye-gaze is currently tracked, one has to instead check either the recentness of the latest gaze point or the user presence status. For convenience we have added a couple of utility functions to check if a gaze point is recent.
// v2.0
EyeTracking.GetGazeTrackingStatus();
// v3.0
GazePoint gazePoint = TobiiAPI.GetGazePoint();
if (gazePoint.IsRecent()) // default max age 500ms
{
// ...
}
float MaxAge = 0.2f // to check if newer than 200ms
if (gazePoint.IsRecent(MaxAge))
{
// ...
}
if (TobiiAPI.GetUserPresence().IsUserPresent)
{
// ...
}
It is no longer possible for us to read the status of the eye tracker if it is connected, setup and so forth. We suggest designing your code to always only act if there is recent (meaning also valid) data or a user present in front of the eye tracker.
// v2.0
EyeTracking.GetGazeTrackingStatus();
// v3.0
GazePoint gazePoint = TobiiAPI.GetGazePoint();
if (gazePoint.IsRecent())
{
// ...
}
if (TobiiAPI.GetUserPresence().IsUserPresent)
{
// ...
}