Stream Engine

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 four header files, each providing access to a separate set of functionality:

The tobii.h header file 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.

The tobii_streams.h header file is used 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.

The tobii_wearable.h header file contains functions relating 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.

The tobii_engine.h header file is used for acquiring information about connected devices. It creates a dedicated connection to the Tobii engine, which runs as a service/daemon depending on the operating system. Using this interface the user can subscribe to events about added and removed tracker devices, as well as changes in individual tracker readiness states. The readiness states give the user information about which readiness state the tracker is currently in, i.e. if a firmware upgrade is in progress, a calibration is needed or if the tracker is ready for use. The use of tobii_engine api is not obligatory and may be used as additional plumbing in an application.

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 API 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.