tobii_research.h File Reference

Generic SDK functions. More...

Go to the source code of this file.

Data Structures
struct	TobiiResearchEyeTrackers
struct	TobiiResearchNormalizedPoint2D
struct	TobiiResearchPoint3D
struct	TobiiResearchSDKVersion

Macros
#define	TOBII_RESEARCH_API
#define	TOBII_RESEARCH_CALL

Typedefs
typedef struct TobiiResearchEyeTracker	TobiiResearchEyeTracker
typedef TobiiResearchPoint3D	TobiiResearchNormalizedPoint3D
typedef void(*	tobii_research_log_callback) (int64_t system_time_stamp, TobiiResearchLogSource source, TobiiResearchLogLevel level, const char *message)
	Log callback. More...

Enumerations
enum	TobiiResearchStatus {   TOBII_RESEARCH_STATUS_OK, TOBII_RESEARCH_STATUS_FATAL_ERROR, TOBII_RESEARCH_STATUS_INITIALIZE_FAILED, TOBII_RESEARCH_STATUS_TERMINATE_FAILED,   TOBII_RESEARCH_STATUS_LOCALBROWSER_CREATE_FAILED, TOBII_RESEARCH_STATUS_LOCALBROWSER_POLL_FAILED, TOBII_RESEARCH_STATUS_ZEROCONFBROWSER_CREATE_FAILED, TOBII_RESEARCH_STATUS_ZEROCONFBROWSER_POLL_FAILED,   TOBII_RESEARCH_STATUS_FILEBROWSER_CREATE_FAILED, TOBII_RESEARCH_STATUS_FILEBROWSER_POLL_FAILED, TOBII_RESEARCH_STATUS_INVALID_PARAMETER, TOBII_RESEARCH_STATUS_INVALID_OPERATION,   TOBII_RESEARCH_STATUS_UNINITIALIZED, TOBII_RESEARCH_STATUS_OUT_OF_BOUNDS, TOBII_RESEARCH_STATUS_DISPLAY_AREA_NOT_VALID, TOBII_RESEARCH_STATUS_BUFFER_TOO_SMALL,   TOBII_RESEARCH_STATUS_NOT_INITIALIZED, TOBII_RESEARCH_STATUS_ALREADY_INITIALIZED, TOBII_RESEARCH_STATUS_SAVED_LICENSE_FAILED_TO_APPLY, TOBII_RESEARCH_STATUS_SE_INTERNAL = 200,   TOBII_RESEARCH_STATUS_SE_INSUFFICIENT_LICENSE, TOBII_RESEARCH_STATUS_SE_NOT_SUPPORTED, TOBII_RESEARCH_STATUS_SE_NOT_AVAILABLE, TOBII_RESEARCH_STATUS_SE_CONNECTION_FAILED,   TOBII_RESEARCH_STATUS_SE_TIMED_OUT, TOBII_RESEARCH_STATUS_SE_ALLOCATION_FAILED, TOBII_RESEARCH_STATUS_SE_ALREADY_INITIALIZED, TOBII_RESEARCH_STATUS_SE_NOT_INITIALIZED,   TOBII_RESEARCH_STATUS_SE_INVALID_PARAMETER, TOBII_RESEARCH_STATUS_SE_CALIBRATION_ALREADY_STARTED, TOBII_RESEARCH_STATUS_SE_CALIBRATION_NOT_STARTED, TOBII_RESEARCH_STATUS_SE_ALREADY_SUBSCRIBED,   TOBII_RESEARCH_STATUS_SE_NOT_SUBSCRIBED, TOBII_RESEARCH_STATUS_SE_OPERATION_FAILED, TOBII_RESEARCH_STATUS_SE_CONFLICTING_API_INSTANCES, TOBII_RESEARCH_STATUS_SE_CALIBRATION_BUSY,   TOBII_RESEARCH_STATUS_SE_CALLBACK_IN_PROGRESS, TOBII_RESEARCH_STATUS_SE_TOO_MANY_SUBSCRIBERS, TOBII_RESEARCH_STATUS_SE_BUFFER_TOO_SMALL, TOBII_RESEARCH_STATUS_SE_FIRMWARE_NO_RESPONSE,   TOBII_RESEARCH_STATUS_FWUPGRADE_INTERNAL = 400, TOBII_RESEARCH_STATUS_FWUPGRADE_NOT_SUPPORTED, TOBII_RESEARCH_STATUS_FWUPGRADE_UNKNOWN_FIRMWARE_VERSION, TOBII_RESEARCH_STATUS_FWUPGRADE_CONNECTION_FAILED,   TOBII_RESEARCH_STATUS_FWUPGRADE_INVALID_PARAMETER, TOBII_RESEARCH_STATUS_FWUPGRADE_PACKAGE_DEVICE_MISMATCH, TOBII_RESEARCH_STATUS_FWUPGRADE_PARSE_RESPONSE, TOBII_RESEARCH_STATUS_FWUPGRADE_OPERATION_FAILED,   TOBII_RESEARCH_STATUS_FWUPGRADE_ALLOCATION_FAILED, TOBII_RESEARCH_STATUS_FWUPGRADE_FIRMWARE_NO_RESPONSE, TOBII_RESEARCH_STATUS_FWUPGRADE_DOWNGRADE_NOT_SUPPORTED, TOBII_RESEARCH_STATUS_UNKNOWN = 1000 }
enum	TobiiResearchLogSource { TOBII_RESEARCH_LOG_SOURCE_STREAM_ENGINE, TOBII_RESEARCH_LOG_SOURCE_SDK, TOBII_RESEARCH_LOG_SOURCE_FIRMWARE_UPGRADE }
enum	TobiiResearchLogLevel {   TOBII_RESEARCH_LOG_LEVEL_ERROR, TOBII_RESEARCH_LOG_LEVEL_WARNING, TOBII_RESEARCH_LOG_LEVEL_INFORMATION, TOBII_RESEARCH_LOG_LEVEL_DEBUG,   TOBII_RESEARCH_LOG_LEVEL_TRACE }

Functions
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_logging_subscribe (tobii_research_log_callback callback)
	Subscribes to logging. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_logging_unsubscribe ()
	Unsubscribes from logging. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_find_all_eyetrackers (TobiiResearchEyeTrackers **eyetrackers)
	Finds eye trackers connected to the computer or the network. More...
TOBII_RESEARCH_API void TOBII_RESEARCH_CALL	tobii_research_free_eyetrackers (TobiiResearchEyeTrackers *eyetrackers)
	Free memory allocation for the result received via tobii_research_find_all_eyetrackers. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_eyetracker (const char *address, TobiiResearchEyeTracker **eyetracker)
	Gets data for an eye tracker given an address. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_system_time_stamp (int64_t *time_stamp_us)
	Retrieves the time stamp from the system clock in microseconds. More...
TOBII_RESEARCH_API void TOBII_RESEARCH_CALL	tobii_research_free_string (char *str)
	Free memory allocation for a string allocated by the SDK. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_sdk_version (TobiiResearchSDKVersion *sdk_version)

Detailed Description

Generic SDK functions.

Copyright

COPYRIGHT 2019 - PROPERTY OF TOBII PRO AB

2019 TOBII PRO AB - KARLSROVAGEN 2D, DANDERYD 182 53, SWEDEN - All Rights Reserved.

NOTICE: All information contained herein is, and remains, the property of Tobii Pro AB and its suppliers, if any. The intellectual and technical concepts contained herein are proprietary to Tobii Pro AB and its suppliers and may be covered by U.S.and Foreign Patents, patent applications, and are protected by trade secret or copyright law. Dissemination of this information or reproduction of this material is strictly forbidden unless prior written permission is obtained from Tobii Pro AB.

Macro Definition Documentation

TOBII_RESEARCH_API

#define TOBII_RESEARCH_API

TOBII_RESEARCH_CALL

#define TOBII_RESEARCH_CALL

Typedef Documentation

tobii_research_log_callback

typedef void(* tobii_research_log_callback) (int64_t system_time_stamp, TobiiResearchLogSource source, TobiiResearchLogLevel level, const char *message)

Log callback.

Implement this and send as a parameter to tobii_research_logging_subscribe.

Parameters

system_time_stamp	The time stamp according to the computer's internal clock.
source	Source of log message.
level	Log message level.
message	The log message.

TobiiResearchEyeTracker

typedef struct TobiiResearchEyeTracker TobiiResearchEyeTracker

Opaque representation of an eye tracker struct.

TobiiResearchNormalizedPoint3D

typedef TobiiResearchPoint3D TobiiResearchNormalizedPoint3D

Represents a normalized x-, y- and z-coordinate point in a three-dimensional space.

Enumeration Type Documentation

TobiiResearchLogLevel

enum TobiiResearchLogLevel

Log level.

Enumerator
TOBII_RESEARCH_LOG_LEVEL_ERROR	Error message.
TOBII_RESEARCH_LOG_LEVEL_WARNING	Warning message.
TOBII_RESEARCH_LOG_LEVEL_INFORMATION	Information message.
TOBII_RESEARCH_LOG_LEVEL_DEBUG	Debug message.
TOBII_RESEARCH_LOG_LEVEL_TRACE	Trace message.

TobiiResearchLogSource

enum TobiiResearchLogSource

Source of log message.

Enumerator
TOBII_RESEARCH_LOG_SOURCE_STREAM_ENGINE	The log message is from stream engine.
TOBII_RESEARCH_LOG_SOURCE_SDK	The log message is from the SDK.
TOBII_RESEARCH_LOG_SOURCE_FIRMWARE_UPGRADE	The log message is from the firmware upgrade module.

TobiiResearchStatus

enum TobiiResearchStatus

Status codes returned by the SDK.

Enumerator
TOBII_RESEARCH_STATUS_OK	No error.
TOBII_RESEARCH_STATUS_FATAL_ERROR	Fatal error. This should normally not happen.
TOBII_RESEARCH_STATUS_INITIALIZE_FAILED	Failed to initialize the API. This is a fatal error.
TOBII_RESEARCH_STATUS_TERMINATE_FAILED	Failed to terminate the API.
TOBII_RESEARCH_STATUS_LOCALBROWSER_CREATE_FAILED	Failed to create browser for finding local devices.
TOBII_RESEARCH_STATUS_LOCALBROWSER_POLL_FAILED	Failed to poll local devices.
TOBII_RESEARCH_STATUS_ZEROCONFBROWSER_CREATE_FAILED	Failed to create zero configuration browser.
TOBII_RESEARCH_STATUS_ZEROCONFBROWSER_POLL_FAILED	Failed to poll devices from zero configuration browser.
TOBII_RESEARCH_STATUS_FILEBROWSER_CREATE_FAILED	Failed to create browser that looks for devices in file.
TOBII_RESEARCH_STATUS_FILEBROWSER_POLL_FAILED	Failed to poll devices from file browser.
TOBII_RESEARCH_STATUS_INVALID_PARAMETER	An invalid parameter was given to the method.
TOBII_RESEARCH_STATUS_INVALID_OPERATION	The operation was invalid.
TOBII_RESEARCH_STATUS_UNINITIALIZED	Internal core error code. Should never be returned by the SDK.
TOBII_RESEARCH_STATUS_OUT_OF_BOUNDS	A parameter is out of bounds.
TOBII_RESEARCH_STATUS_DISPLAY_AREA_NOT_VALID	The display area is not valid. Please configure the eye tracker.
TOBII_RESEARCH_STATUS_BUFFER_TOO_SMALL	The buffer is too small.
TOBII_RESEARCH_STATUS_NOT_INITIALIZED	tobii_research_initialize has not been called.
TOBII_RESEARCH_STATUS_ALREADY_INITIALIZED	tobii_research_initialize has already been called.
TOBII_RESEARCH_STATUS_SAVED_LICENSE_FAILED_TO_APPLY	The license saved on the device failed to apply when connecting. It has probably expired.
TOBII_RESEARCH_STATUS_SE_INTERNAL	Internal stream engine error.
TOBII_RESEARCH_STATUS_SE_INSUFFICIENT_LICENSE	The operation requires a higher license type.
TOBII_RESEARCH_STATUS_SE_NOT_SUPPORTED	The operations isn't supported in the current context.
TOBII_RESEARCH_STATUS_SE_NOT_AVAILABLE	The device is unavailable.
TOBII_RESEARCH_STATUS_SE_CONNECTION_FAILED	Connection to the device failed.
TOBII_RESEARCH_STATUS_SE_TIMED_OUT	The operation timed out.
TOBII_RESEARCH_STATUS_SE_ALLOCATION_FAILED	Failed to allocate memory.
TOBII_RESEARCH_STATUS_SE_ALREADY_INITIALIZED	The API is already initialized.
TOBII_RESEARCH_STATUS_SE_NOT_INITIALIZED	The API isn't initialized.
TOBII_RESEARCH_STATUS_SE_INVALID_PARAMETER	An invalid parameter was given to the method.
TOBII_RESEARCH_STATUS_SE_CALIBRATION_ALREADY_STARTED	Calibration has already started.
TOBII_RESEARCH_STATUS_SE_CALIBRATION_NOT_STARTED	Calibration isn't started.
TOBII_RESEARCH_STATUS_SE_ALREADY_SUBSCRIBED	Already subscribed.
TOBII_RESEARCH_STATUS_SE_NOT_SUBSCRIBED	Not subscribed.
TOBII_RESEARCH_STATUS_SE_OPERATION_FAILED	Operation failed.
TOBII_RESEARCH_STATUS_SE_CONFLICTING_API_INSTANCES	Conflicting api instances.
TOBII_RESEARCH_STATUS_SE_CALIBRATION_BUSY	Calibration busy.
TOBII_RESEARCH_STATUS_SE_CALLBACK_IN_PROGRESS	Callback in progress.
TOBII_RESEARCH_STATUS_SE_TOO_MANY_SUBSCRIBERS	Too many users subscribed to a stream.
TOBII_RESEARCH_STATUS_SE_BUFFER_TOO_SMALL	The buffer is too small.
TOBII_RESEARCH_STATUS_SE_FIRMWARE_NO_RESPONSE	No response from firmware.
TOBII_RESEARCH_STATUS_FWUPGRADE_INTERNAL	Internal error.
TOBII_RESEARCH_STATUS_FWUPGRADE_NOT_SUPPORTED	Firmware upgrade is not supported.
TOBII_RESEARCH_STATUS_FWUPGRADE_UNKNOWN_FIRMWARE_VERSION	Unknown firmware version.
TOBII_RESEARCH_STATUS_FWUPGRADE_CONNECTION_FAILED	Connection failed.
TOBII_RESEARCH_STATUS_FWUPGRADE_INVALID_PARAMETER	Invalid parameter.
TOBII_RESEARCH_STATUS_FWUPGRADE_PACKAGE_DEVICE_MISMATCH	Device mismatch. The firmware package is not meant for the device.
TOBII_RESEARCH_STATUS_FWUPGRADE_PARSE_RESPONSE	Parse response.
TOBII_RESEARCH_STATUS_FWUPGRADE_OPERATION_FAILED	The firmware upgrade operation failed.
TOBII_RESEARCH_STATUS_FWUPGRADE_ALLOCATION_FAILED	Memory allocation failed during firmware upgrade.
TOBII_RESEARCH_STATUS_FWUPGRADE_FIRMWARE_NO_RESPONSE	The firmware failed to respond during firmware upgrade.
TOBII_RESEARCH_STATUS_FWUPGRADE_DOWNGRADE_NOT_SUPPORTED	The firmware downgrade operation is not supported.
TOBII_RESEARCH_STATUS_UNKNOWN	Unknown error. This is a fatal error.

Function Documentation

tobii_research_find_all_eyetrackers()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_find_all_eyetrackers

(

TobiiResearchEyeTrackers **

eyetrackers

)

Finds eye trackers connected to the computer or the network.

The eye trackers can be used in any tobii_research function that requires an eye tracker.

    TobiiResearchEyeTrackers* eyetrackers = NULL;
 
    TobiiResearchStatus result;
    size_t i = 0;
 
    result = tobii_research_find_all_eyetrackers(&eyetrackers);
 
    if (result != TOBII_RESEARCH_STATUS_OK) {
        printf("Finding trackers failed. Error: %d\n", result);
        return result;
    }
 
    for (i = 0; i < eyetrackers->count; i++) {
        TobiiResearchEyeTracker* eyetracker = eyetrackers->eyetrackers[i];
        char* address = NULL;
        char* serial_number = NULL;
        char* device_name = NULL;
 
        tobii_research_get_address(eyetracker, &address);
        tobii_research_get_serial_number(eyetracker, &serial_number);
        tobii_research_get_device_name(eyetracker, &device_name);
 
        printf("%s\t%s\t%s\n", address, serial_number, device_name);
 
        tobii_research_free_string(address);
        tobii_research_free_string(serial_number);
        tobii_research_free_string(device_name);
    }
    printf("Found %d Eye Trackers \n\n", (int)eyetrackers->count);
    tobii_research_free_eyetrackers(eyetrackers);
 

Parameters

eyetrackers

Pointers to found eye trackers will be stored in this struct.

Returns

A TobiiResearchStatus code.

Examples

find_all_eyetrackers.c.

tobii_research_free_eyetrackers()

TOBII_RESEARCH_API void TOBII_RESEARCH_CALL tobii_research_free_eyetrackers

(

TobiiResearchEyeTrackers *

eyetrackers

)

Free memory allocation for the result received via tobii_research_find_all_eyetrackers.

Parameters

eyetrackers

Eye trackers to free.

Examples

find_all_eyetrackers.c.

tobii_research_free_string()

TOBII_RESEARCH_API void TOBII_RESEARCH_CALL tobii_research_free_string

(

char *

str

)

Free memory allocation for a string allocated by the SDK.

Parameters

str	String to free.

Examples

calibration.c, calibration_data.c, call_eyetracker_manager_posix.c, call_eyetracker_manager_windows.c, create_eyetracker.c, external_signal.c, eye_tracking_modes.c, find_all_eyetrackers.c, gaze_data.c, get_and_set_display_area.c, get_hmd_lens_configuration.c, get_track_box.c, hmd_calibration.c, set_device_name.c, set_hmd_lens_configuration.c, time_synchronization_data.c, and user_position_guide.c.

tobii_research_get_eyetracker()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_eyetracker	(	const char *	address,
		TobiiResearchEyeTracker **	eyetracker
	)

Gets data for an eye tracker given an address.

 
// ex address = "tet-tcp://12.13.14.15"
 
    TobiiResearchEyeTracker* eyetracker = NULL;
    TobiiResearchStatus status = tobii_research_get_eyetracker(address, &eyetracker);
    char* serial_number = NULL;
    char* device_name = NULL;
    char* model = NULL;
    tobii_research_get_serial_number(eyetracker, &serial_number);
    tobii_research_get_device_name(eyetracker, &device_name);
    tobii_research_get_model(eyetracker, &model);
 
    printf("Get Eye tracker with status: %i\n", status);
    printf("Address: %s\n", address);
    printf("Model: %s\n", model);
    printf("Name (It's OK if this is empty): %s\n", device_name);
    printf("Serial number: %s\n", serial_number);
 
    tobii_research_free_string(serial_number);
    tobii_research_free_string(device_name);
    tobii_research_free_string(model);

Parameters

address	Address of eye tracker to get data for.
eyetracker	Eye tracker object returned.

Returns

A TobiiResearchStatus code.

Examples

call_eyetracker_manager_posix.c, call_eyetracker_manager_windows.c, and create_eyetracker.c.

tobii_research_get_sdk_version()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_sdk_version

(

TobiiResearchSDKVersion *

sdk_version

)

Gets the SDK version.

Parameters

sdk_version

Version of the SDK.

Returns

A TobiiResearchStatus code.

tobii_research_get_system_time_stamp()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_system_time_stamp

(

int64_t *

time_stamp_us

)

Retrieves the time stamp from the system clock in microseconds.

    int64_t system_time_stamp;
    TobiiResearchStatus status = tobii_research_get_system_time_stamp(&system_time_stamp);
 
    printf("The system time stamp in microseconds is %" PRId64 " with status %i.\n", system_time_stamp, status);

Parameters

time_stamp_us

The time stamp of the system in microseconds.

Returns

A TobiiResearchStatus code.

Examples

get_system_time_stamp.c.

tobii_research_logging_subscribe()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_logging_subscribe

(

tobii_research_log_callback

callback

)

Subscribes to logging.

Parameters

callback

Callback that will receive log messages.

Returns

A TobiiResearchStatus code.

tobii_research_logging_unsubscribe()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_logging_unsubscribe

(

)

Unsubscribes from logging.

Returns

A TobiiResearchStatus code.