The Stream Engine SDK is a low-level SDK intended for advanced users wanting to have tight control over the system resources used by Stream Engine and least amount of signal latency. To get started with the StreamEngine SDK, head over to the getting started section. Below is a more detailed description of the different parts of the SDK.

Overview

The StreamEngine SDK consists of a dynamic library and six header files, each providing access to a separate set of functionality:

tobii.h – collects the core API functions of Stream Engine. It contains functions to initialize the API and establish a connection to a tracker, as well as enumerating connected devices and requesting callbacks for subscriptions. There are also functions for querying the current state of a tracker, and to query its capabilities.

Note that even though the header files are available, the type of license you have may restrict your access to certain functions.

The core API functions includes all you need to get started with using eye tracking for interactive use. If you wish to access more detailed eye tracking data streams and advanced functionality, please contact Tobii Sales via https://www.tobii.com/tech/contact/sales-form/

tobii_streams.h – functionality for managing data stream subscriptions. There are several types of data streams in the API, and tobii_streams.h contains functions to subscribe to and unsubscribe from these streams, as well as data structures describing the data packages.

tobii_wearable.h – functionality related to wearable devices, such as VR headsets. It contains a specialized data stream with different data from the regular streams, as well as functions to retrieve and modify the lens configuration of the device.

tobii_licensing.h – provide access to stream engine functionality restricted by license. The functionality made available by stream engine is controlled by license files generated by Tobii.

tobii_config.h – functionality to configure the state of the tracker, such as calibration and display area setup. To modify the state of the tracker, a license on, at least, config level is required.

tobii_advanced.h – advanced features, requiring a professional license to use.

Usage

The library creates no threads, so in order to drive the message pump inside stream engine, thereby propagating the stream data through to the main application, the tobii_device_process_callbacks ( and if used, tobii_engine_process_callbacks) must be called at an even interval and at least 10 times per second.

Memory is only allocated when calling the create functions for api, device & engine and are in turn freed when calling their respective destroy functions. In order to gain full control of memory allocation, custom memory allocators can be used which are passed to StreamEngine during initialization. The same goes for logging where a custom logging function can be passed during the same initialization call.

Please note that there can only be one callback registered to a stream at a time. To register a new callback, first unsubscribe from the stream, then resubscribe with the new callback function.

The Tobii Stream Engine API implements full thread safety across all API functions. However, it is up to the user to guarantee thread safety in code injected into Stream Engine, for example inside callbacks or if a custom memory allocator is supplied. It is not allowed to call Stream Engine API functions from within a callback invoked by Stream Engine. Attempting to do so will result in TOBII_ERROR_CALLBACK_IN_PROGRESS. A specific exception to this is tobii_system_clock which specifically is allowed to be called even from within a callback function.

Further reading

The Tobii Stream Engine API 4.1.0 – Reference Documentation includes example code snippets that show the use of each function, they don’t necessarily describe the best practice in which to use the API. For a more in-depth example of the best practices, see the samples that are supplied together with the stream engine library.