tobii_research_eyetracker.h File Reference

Functionality for an eye tracker. More...

Go to the source code of this file.

Data Structures
struct	TobiiResearchTrackBox
struct	TobiiResearchDisplayArea
struct	TobiiResearchCalibrationData
struct	TobiiResearchGazeOutputFrequencies
struct	TobiiResearchEyeTrackingModes
struct	TobiiResearchHMDLensConfiguration

Typedefs
typedef enum TobiiResearchLicenseValidationResult	TobiiResearchLicenseValidationResult

Enumerations
enum	TobiiResearchCapabilities {   TOBII_RESEARCH_CAPABILITIES_NONE, TOBII_RESEARCH_CAPABILITIES_CAN_SET_DISPLAY_AREA = 1 << 0, TOBII_RESEARCH_CAPABILITIES_HAS_EXTERNAL_SIGNAL = 1 << 1, TOBII_RESEARCH_CAPABILITIES_HAS_EYE_IMAGES = 1 << 2,   TOBII_RESEARCH_CAPABILITIES_HAS_GAZE_DATA = 1 << 3, TOBII_RESEARCH_CAPABILITIES_HAS_HMD_GAZE_DATA = 1 << 4, TOBII_RESEARCH_CAPABILITIES_CAN_DO_SCREEN_BASED_CALIBRATION = 1 << 5, TOBII_RESEARCH_CAPABILITIES_CAN_DO_HMD_BASED_CALIBRATION = 1 << 6,   TOBII_RESEARCH_CAPABILITIES_HAS_HMD_LENS_CONFIG = 1 << 7, TOBII_RESEARCH_CAPABILITIES_CAN_DO_MONOCULAR_CALIBRATION = 1 << 8 }
enum	TobiiResearchLicenseValidationResult {   TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_OK, TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_TAMPERED, TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_INVALID_APPLICATION_SIGNATURE, TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_NONSIGNED_APPLICATION,   TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_EXPIRED, TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_PREMATURE, TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_INVALID_PROCESS_NAME, TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_INVALID_SERIAL_NUMBER,   TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_INVALID_MODEL, TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_UNKNOWN }

Functions
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_address (TobiiResearchEyeTracker *eyetracker, char **address)
	Gets the address (URI) of the eye tracker device. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_serial_number (TobiiResearchEyeTracker *eyetracker, char **serial_number)
	Gets the serial number of the eye tracker. All physical eye trackers have a unique serial number. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_device_name (TobiiResearchEyeTracker *eyetracker, char **device_name)
	Gets the name of the eye tracker. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_model (TobiiResearchEyeTracker *eyetracker, char **model)
	Gets the model of the eye tracker. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_firmware_version (TobiiResearchEyeTracker *eyetracker, char **fw_version)
	Gets the firmware version of the eye tracker. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_runtime_version (TobiiResearchEyeTracker *eyetracker, char **runtime_version)
	Gets the runtime build version of the eye tracker. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_capabilities (TobiiResearchEyeTracker *eyetracker, TobiiResearchCapabilities *capabilities)
	Gets the capabilities of the device. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_retrieve_calibration_data (TobiiResearchEyeTracker *eyetracker, TobiiResearchCalibrationData **data)
	Gets the calibration data used currently by the eye tracker. More...
TOBII_RESEARCH_API void TOBII_RESEARCH_CALL	tobii_research_free_calibration_data (TobiiResearchCalibrationData *data)
	Free memory allocation for the calibration data received via tobii_research_retrieve_calibration_data. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_apply_calibration_data (TobiiResearchEyeTracker *eyetracker, const TobiiResearchCalibrationData *data)
	Sets the provided calibration data to the eye tracker, which means it will be active calibration. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_all_gaze_output_frequencies (TobiiResearchEyeTracker *eyetracker, TobiiResearchGazeOutputFrequencies **frequencies)
	Gets an array of gaze output frequencies supported by the eye tracker. More...
TOBII_RESEARCH_API void TOBII_RESEARCH_CALL	tobii_research_free_gaze_output_frequencies (TobiiResearchGazeOutputFrequencies *frequencies)
	Free memory allocation for the gaze output frequencies received via tobii_research_free_gaze_output_frequencies. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_gaze_output_frequency (TobiiResearchEyeTracker *eyetracker, float *gaze_output_frequency)
	Gets the gaze output frequency of the eye tracker. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_set_gaze_output_frequency (TobiiResearchEyeTracker *eyetracker, float gaze_output_frequency)
	Sets the gaze output frequency of the eye tracker. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_all_eye_tracking_modes (TobiiResearchEyeTracker *eyetracker, TobiiResearchEyeTrackingModes **modes)
	Gets a all eye tracking modes supported by the eye tracker. More...
TOBII_RESEARCH_API void TOBII_RESEARCH_CALL	tobii_research_free_eye_tracking_modes (TobiiResearchEyeTrackingModes *modes)
	Free memory allocation for the eye tracking modes received via tobii_research_get_all_eye_tracking_modes. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_eye_tracking_mode (TobiiResearchEyeTracker *eyetracker, char **eye_tracking_mode)
	Gets the eye tracking mode of the eye tracker. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_set_eye_tracking_mode (TobiiResearchEyeTracker *eyetracker, const char *eye_tracking_mode)
	Sets the eye tracking mode of the eye tracker. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_track_box (TobiiResearchEyeTracker *eyetracker, TobiiResearchTrackBox *track_box)
	Gets the track box of the eye tracker. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_apply_licenses (TobiiResearchEyeTracker *eyetracker, const void **license_key, size_t *license_keys_size, TobiiResearchLicenseValidationResult *validation_results, size_t number_of_licenses)
	Apply one or more licenses to unlock features of the eye tracker. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_clear_applied_licenses (TobiiResearchEyeTracker *eyetracker)
	Clears any previously applied licenses. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_display_area (TobiiResearchEyeTracker *eyetracker, TobiiResearchDisplayArea *display_area)
	Gets the size and corners of the display area. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_set_display_area (TobiiResearchEyeTracker *eyetracker, const TobiiResearchDisplayArea *display_area)
	Sets the display area of the eye tracker. It is strongly recommended to use Eye Tracker Manager to calculate the display area coordinates as the origin of the User Coordinate System differs between eye tracker models. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_set_device_name (TobiiResearchEyeTracker *eyetracker, const char *device_name)
	Changes the device name. This is not supported by all eye trackers. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_get_hmd_lens_configuration (TobiiResearchEyeTracker *eyetracker, TobiiResearchHMDLensConfiguration *lens_configuration)
	Gets the current lens configuration of the HMD based eye tracker. The lens configuration describes how the lenses of the HMD device are positioned. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_set_hmd_lens_configuration (TobiiResearchEyeTracker *eyetracker, const TobiiResearchHMDLensConfiguration *lens_configuration)
	Sets the lens configuration of the HMD based eye tracker. The lens configuration describes how the lenses of the HMD device are positioned. More...

Detailed Description

Functionality for an eye tracker.

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.

Typedef Documentation

TobiiResearchLicenseValidationResult

typedef enum TobiiResearchLicenseValidationResult TobiiResearchLicenseValidationResult

Specifies license validation result.

Enumeration Type Documentation

TobiiResearchCapabilities

enum TobiiResearchCapabilities

Defines the capabilities.

Enumerator
TOBII_RESEARCH_CAPABILITIES_NONE	No capabilities set.
TOBII_RESEARCH_CAPABILITIES_CAN_SET_DISPLAY_AREA	Indicates that the device can have display areas set.
TOBII_RESEARCH_CAPABILITIES_HAS_EXTERNAL_SIGNAL	Indicates that the device can deliver an external signal stream.
TOBII_RESEARCH_CAPABILITIES_HAS_EYE_IMAGES	Indicates that the device can deliver an eye image stream.
TOBII_RESEARCH_CAPABILITIES_HAS_GAZE_DATA	Indicates that the device can deliver a gaze data stream. Standard for all screen based eye trackers.
TOBII_RESEARCH_CAPABILITIES_HAS_HMD_GAZE_DATA	Indicates that the device can deliver a HMD gaze data stream.
TOBII_RESEARCH_CAPABILITIES_CAN_DO_SCREEN_BASED_CALIBRATION	Indicates that screen based calibration can be performed on the device.
TOBII_RESEARCH_CAPABILITIES_CAN_DO_HMD_BASED_CALIBRATION	Indicates that HMD based calibration can be performed on the device.
TOBII_RESEARCH_CAPABILITIES_HAS_HMD_LENS_CONFIG	Indicates that it's possible to get and set the HMD lens configuration on the device.
TOBII_RESEARCH_CAPABILITIES_CAN_DO_MONOCULAR_CALIBRATION	Indicates that monocular calibration can be performed on the device.

TobiiResearchLicenseValidationResult

enum TobiiResearchLicenseValidationResult

Specifies license validation result.

Enumerator
TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_OK	The license is ok.
TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_TAMPERED	The license is tampered.
TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_INVALID_APPLICATION_SIGNATURE	The application signature is invalid.
TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_NONSIGNED_APPLICATION	The application has not been signed.
TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_EXPIRED	The license has expired.
TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_PREMATURE	The license is not yet valid.
TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_INVALID_PROCESS_NAME	The process name does not match the license.
TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_INVALID_SERIAL_NUMBER	The serial number does not match the license.
TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_INVALID_MODEL	The model does not match the license.
TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_UNKNOWN	The license validation returned an unexpected result.

Function Documentation

tobii_research_apply_calibration_data()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_apply_calibration_data	(	TobiiResearchEyeTracker *	eyetracker,
		const TobiiResearchCalibrationData *	data
	)

Sets the provided calibration data to the eye tracker, which means it will be active calibration.

This function should not be called during calibration. Also see tobii_research_retrieve_calibration_data.

        /* Read the calibration from file. */
        FILE *calibration_file = fopen(filename, "rb" );
        size_t file_size;
        if( !calibration_file ) {
           printf("Calibration file not found!\n");
           return;
        }
 
        fseek(calibration_file, 0, SEEK_END);
        file_size = (size_t)ftell(calibration_file);
 
        rewind(calibration_file);
 
        if(file_size <= 0) {
           printf("Calibration file is empty!\n");
           return;
        };
 
        TobiiResearchCalibrationData calibration_data_to_write;
 
        calibration_data_to_write.data = malloc(file_size);
        calibration_data_to_write.size = file_size;
 
        file_size = fread(calibration_data_to_write.data, calibration_data_to_write.size, 1, calibration_file);
 
        /* Don't apply empty calibrations. */
        if (file_size > 0) {
            printf("Applying calibration on eye tracker with serial number %s.\n", serial_number);
            tobii_research_apply_calibration_data(eyetracker, &calibration_data_to_write);
        }
        free(calibration_data_to_write.data);
        tobii_research_free_string(serial_number);
        fclose(calibration_file);

Parameters

eyetracker	Eye tracker object.
data	Calibration data.

Returns

A TobiiResearchStatus code.

Examples

calibration_data.c.

tobii_research_apply_licenses()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_apply_licenses	(	TobiiResearchEyeTracker *	eyetracker,
		const void **	license_key,
		size_t *	license_keys_size,
		TobiiResearchLicenseValidationResult *	validation_results,
		size_t	number_of_licenses
	)

Apply one or more licenses to unlock features of the eye tracker.

The validation_results array indicates whether all licenses were applied or not.

    #define NUM_OF_LICENSES 1
 
    char* license_key_ring[NUM_OF_LICENSES];
 
    FILE *license_file = fopen(license_file_path, "rb" );
 
    if( !license_file ) {
       printf("License not found!\n");
       return;
    }
    fseek(license_file, 0, SEEK_END);
    size_t file_size = (size_t)ftell(license_file);
 
    rewind(license_file);
    if(file_size <= 0) {
       printf("License is empty!\n");
       return;
    }
 
    license_key_ring[0] = (char*)malloc(file_size);
 
    if(license_key_ring[0]) {
       size_t read_bytes = fread( license_key_ring[0], sizeof(char), file_size, license_file );
       if (file_size != read_bytes) {
          printf("Failed to read license file!\n");
          return;
       }
    }
    fclose(license_file);
 
 
 
    printf("Applying license from %s.\n", license_file_path);
    TobiiResearchLicenseValidationResult validation_results;
 
    TobiiResearchStatus retval = tobii_research_apply_licenses(eyetracker, (const void**)license_key_ring, &file_size, &validation_results, NUM_OF_LICENSES);
 
    free(license_key_ring[0]);
 
 
    if (retval == TOBII_RESEARCH_STATUS_OK && validation_results == TOBII_RESEARCH_LICENSE_VALIDATION_RESULT_OK) {
        printf("Successfully applied license from list of keys.\n");
    }

Parameters

eyetracker	Eye tracker object.
license_key	Licenses to apply.
license_keys_size	A list of license key sizes.
validation_results	Optional. Validation result for each license.
number_of_licenses	Number of licenses in license_key_ring.

Returns

A TobiiResearchStatus code.

Examples

apply_licenses.c.

tobii_research_clear_applied_licenses()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_clear_applied_licenses

(

TobiiResearchEyeTracker *

eyetracker

)

Clears any previously applied licenses.

Parameters

eyetracker

Eye tracker object.

Returns

A TobiiResearchStatus code.

tobii_research_free_calibration_data()

TOBII_RESEARCH_API void TOBII_RESEARCH_CALL tobii_research_free_calibration_data

(

TobiiResearchCalibrationData *

data

)

Free memory allocation for the calibration data received via tobii_research_retrieve_calibration_data.

Parameters

data	Calibration data to free.

Examples

calibration_data.c.

tobii_research_free_eye_tracking_modes()

TOBII_RESEARCH_API void TOBII_RESEARCH_CALL tobii_research_free_eye_tracking_modes

(

TobiiResearchEyeTrackingModes *

modes

)

Free memory allocation for the eye tracking modes received via tobii_research_get_all_eye_tracking_modes.

Parameters

modes

Eye tracker modes to free.

Examples

eye_tracking_modes.c.

tobii_research_free_gaze_output_frequencies()

TOBII_RESEARCH_API void TOBII_RESEARCH_CALL tobii_research_free_gaze_output_frequencies

(

TobiiResearchGazeOutputFrequencies *

frequencies

)

Free memory allocation for the gaze output frequencies received via tobii_research_free_gaze_output_frequencies.

Parameters

frequencies

Gaze output frequencies to free.

Examples

gaze_output_frequencies.c.

tobii_research_get_address()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_address	(	TobiiResearchEyeTracker *	eyetracker,
		char **	address
	)

Gets the address (URI) of the eye tracker device.

        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);

Parameters

eyetracker	Eye tracker object.
address	Address as string, should be freed when not in use by tobii_research_free_string.

Returns

A TobiiResearchStatus code.

Examples

call_eyetracker_manager_posix.c, call_eyetracker_manager_windows.c, and find_all_eyetrackers.c.

tobii_research_get_all_eye_tracking_modes()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_all_eye_tracking_modes	(	TobiiResearchEyeTracker *	eyetracker,
		TobiiResearchEyeTrackingModes **	modes
	)

Gets a all eye tracking modes supported by the eye tracker.

    char* initial_eye_tracking_mode = NULL;
 
    TobiiResearchStatus status = tobii_research_get_eye_tracking_mode(eyetracker, &initial_eye_tracking_mode);
 
    printf("The eye tracker's initial eye tracking mode is %s with status %i.\n", initial_eye_tracking_mode, status);
    {
        TobiiResearchEyeTrackingModes* all_eye_tracking_modes = NULL;
        size_t i = 0;
 
        status = tobii_research_get_all_eye_tracking_modes(eyetracker, &all_eye_tracking_modes);
 
        if (status == TOBII_RESEARCH_STATUS_OK) {
            for (; i < all_eye_tracking_modes->mode_count; i++) {
                status = tobii_research_set_eye_tracking_mode(eyetracker, all_eye_tracking_modes->modes[i]);
                printf("Eye tracking mode set to %s with status %i.\n", all_eye_tracking_modes->modes[i], status);
            }
 
            status = tobii_research_set_eye_tracking_mode(eyetracker, initial_eye_tracking_mode);
 
            printf("Eye tracking mode reset to %s with status %i.\n", initial_eye_tracking_mode, status);
 
            tobii_research_free_string(initial_eye_tracking_mode);
        } else {
            printf("tobii_research_get_all_eye_tracking_modes returned status %i.\n", status);
        }
 
        tobii_research_free_eye_tracking_modes(all_eye_tracking_modes);
    }

Parameters

eyetracker	Eye tracker object.
modes	Eye tracking modes.

Returns

A TobiiResearchStatus code.

Examples

eye_tracking_modes.c.

tobii_research_get_all_gaze_output_frequencies()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_all_gaze_output_frequencies	(	TobiiResearchEyeTracker *	eyetracker,
		TobiiResearchGazeOutputFrequencies **	frequencies
	)

Gets an array of gaze output frequencies supported by the eye tracker.

    float initial_gaze_output_frequency;
 
    TobiiResearchStatus status = tobii_research_get_gaze_output_frequency(eyetracker, &initial_gaze_output_frequency);
 
    printf("The eye tracker's initial gaze output frequency is %f Hz with status %i.\n",
            initial_gaze_output_frequency, status);
    {
        TobiiResearchGazeOutputFrequencies* frequencies = NULL;
        size_t i = 0;
        status = tobii_research_get_all_gaze_output_frequencies(eyetracker, &frequencies);
 
        if (status == TOBII_RESEARCH_STATUS_OK) {
            for(; i < frequencies->frequency_count; i++) {
                status = tobii_research_set_gaze_output_frequency(eyetracker, frequencies->frequencies[i]);
                printf("Gaze output frequency set to %f Hz with status %i.\n", frequencies->frequencies[i], status);
            }
            tobii_research_set_gaze_output_frequency(eyetracker, initial_gaze_output_frequency);
 
            printf("Gaze output frequency reset to %f Hz.\n", initial_gaze_output_frequency);
        } else {
            printf("tobii_research_get_all_gaze_output_frequencies returned status %i.\n", status);
        }
 
        tobii_research_free_gaze_output_frequencies(frequencies);
    }
 

Parameters

eyetracker	Eye tracker object.
frequencies	Gaze output frequencies.

Returns

A TobiiResearchStatus code.

Examples

gaze_output_frequencies.c.

tobii_research_get_capabilities()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_capabilities	(	TobiiResearchEyeTracker *	eyetracker,
		TobiiResearchCapabilities *	capabilities
	)

Gets the capabilities of the device.

Parameters

eyetracker	Eye tracker object.
capabilities	Bit array where each bit set indicates a supported capability, see TobiiResearchCapabilities.

Returns

A TobiiResearchStatus code.

tobii_research_get_device_name()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_device_name	(	TobiiResearchEyeTracker *	eyetracker,
		char **	device_name
	)

Gets the name of the eye tracker.

        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);

Parameters

eyetracker	Eye tracker object.
device_name	Device name as string, should be freed when not in use by tobii_research_free_string.

Returns

A TobiiResearchStatus code.

Examples

create_eyetracker.c, find_all_eyetrackers.c, and set_device_name.c.

tobii_research_get_display_area()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_display_area	(	TobiiResearchEyeTracker *	eyetracker,
		TobiiResearchDisplayArea *	display_area
	)

Gets the size and corners of the display area.

    TobiiResearchDisplayArea display_area;
    TobiiResearchStatus status = tobii_research_get_display_area(eyetracker, &display_area);
 
    char* serial_number = NULL;
    tobii_research_get_serial_number(eyetracker, &serial_number);
 
    printf("Got display area from tracker with serial number %s with status %i:\n", serial_number, status);
    tobii_research_free_string(serial_number);
 
    printf("Bottom Left: (%f, %f, %f)\n",
            display_area.bottom_left.x,
            display_area.bottom_left.y,
            display_area.bottom_left.z);
    printf("Bottom Right: (%f, %f, %f)\n",
            display_area.bottom_right.x,
            display_area.bottom_right.y,
            display_area.bottom_right.z);
    printf("Height: %f\n", display_area.height);
    printf("Top Left: (%f, %f, %f)\n",
            display_area.top_left.x,
            display_area.top_left.y,
            display_area.top_left.z);
    printf("Top Right: (%f, %f, %f)\n",
            display_area.top_right.x,
            display_area.top_right.y,
            display_area.top_right.z);
    printf("Width: %f\n", display_area.width);
 
    // To set the display area it is possible to either use a previously saved instance of
    // the type TobiiResearchDisplayArea, or create a new one as shown below.
    TobiiResearchDisplayArea new_display_area;
    // For simplicity we are using the same values that are already set on the eye tracker.
    memcpy(&new_display_area.top_left, &display_area.top_left, sizeof(display_area.top_left));
    memcpy(&new_display_area.top_right, &display_area.top_right, sizeof(display_area.top_right));
    memcpy(&new_display_area.bottom_left, &display_area.bottom_left, sizeof(display_area.bottom_left));
 
    status = tobii_research_set_display_area(eyetracker, &new_display_area);
 

Parameters

eyetracker	Eye tracker object.
display_area	The eye tracker's display area.

Returns

A TobiiResearchStatus code.

Examples

get_and_set_display_area.c.

tobii_research_get_eye_tracking_mode()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_eye_tracking_mode	(	TobiiResearchEyeTracker *	eyetracker,
		char **	eye_tracking_mode
	)

Gets the eye tracking mode of the eye tracker.

    char* initial_eye_tracking_mode = NULL;
 
    TobiiResearchStatus status = tobii_research_get_eye_tracking_mode(eyetracker, &initial_eye_tracking_mode);
 
    printf("The eye tracker's initial eye tracking mode is %s with status %i.\n", initial_eye_tracking_mode, status);

Parameters

eyetracker	Eye tracker object.
eye_tracking_mode	The current eye tracking mode.

Returns

A TobiiResearchStatus code.

Examples

eye_tracking_modes.c.

tobii_research_get_firmware_version()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_firmware_version	(	TobiiResearchEyeTracker *	eyetracker,
		char **	fw_version
	)

Gets the firmware version of the eye tracker.

Parameters

eyetracker	Eye tracker object.
fw_version	Firmware version as string, should be freed when not in use by tobii_research_free_string.

Returns

A TobiiResearchStatus code.

tobii_research_get_gaze_output_frequency()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_gaze_output_frequency	(	TobiiResearchEyeTracker *	eyetracker,
		float *	gaze_output_frequency
	)

Gets the gaze output frequency of the eye tracker.

    float initial_gaze_output_frequency;
 
    TobiiResearchStatus status = tobii_research_get_gaze_output_frequency(eyetracker, &initial_gaze_output_frequency);
 
    printf("The eye tracker's initial gaze output frequency is %f Hz with status %i.\n",
            initial_gaze_output_frequency, status);

Parameters

eyetracker	Eye tracker object.
gaze_output_frequency	The current gaze output frequency.

Returns

A TobiiResearchStatus code.

Examples

gaze_output_frequencies.c.

tobii_research_get_hmd_lens_configuration()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_hmd_lens_configuration	(	TobiiResearchEyeTracker *	eyetracker,
		TobiiResearchHMDLensConfiguration *	lens_configuration
	)

Gets the current lens configuration of the HMD based eye tracker. The lens configuration describes how the lenses of the HMD device are positioned.

    TobiiResearchHMDLensConfiguration lens_configuration;
    TobiiResearchStatus status = tobii_research_get_hmd_lens_configuration(eyetracker, &lens_configuration);
 
    char* serial_number = NULL;
    tobii_research_get_serial_number(eyetracker, &serial_number);
 
    printf("Got lens configuration from tracker with serial number %s with status %i:\n", serial_number, status);
    tobii_research_free_string(serial_number);
 
    printf("Left: (%f, %f, %f)\n",
            lens_configuration.left.x,
            lens_configuration.left.y,
            lens_configuration.left.z);
    printf("Right: (%f, %f, %f)\n",
            lens_configuration.right.x,
            lens_configuration.right.y,
            lens_configuration.right.z);
 

Parameters

eyetracker	Eye tracker object.
lens_configuration	The eye tracker's lens_configuration.

Returns

A TobiiResearchStatus code.

Examples

get_hmd_lens_configuration.c, and set_hmd_lens_configuration.c.

tobii_research_get_model()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_model	(	TobiiResearchEyeTracker *	eyetracker,
		char **	model
	)

Gets the model of the eye tracker.

Parameters

eyetracker	Eye tracker object.
model	Model as string, should be freed when not in use by tobii_research_free_string.

Returns

A TobiiResearchStatus code.

Examples

create_eyetracker.c.

tobii_research_get_runtime_version()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_runtime_version	(	TobiiResearchEyeTracker *	eyetracker,
		char **	runtime_version
	)

Gets the runtime build version of the eye tracker.

Parameters

eyetracker	Eye tracker object.
runtime_version	Runtime build version as string, should be freed when not in use by tobii_research_free_string.

Returns

A TobiiResearchStatus code.

tobii_research_get_serial_number()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_serial_number	(	TobiiResearchEyeTracker *	eyetracker,
		char **	serial_number
	)

Gets the serial number of the eye tracker. All physical eye trackers have a unique serial number.

        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);

Parameters

eyetracker	Eye tracker object.
serial_number	Serial number as string, should be freed when not in use by tobii_research_free_string.

Returns

A TobiiResearchStatus code.

Examples

calibration.c, calibration_data.c, create_eyetracker.c, external_signal.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_hmd_lens_configuration.c, time_synchronization_data.c, and user_position_guide.c.

tobii_research_get_track_box()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_get_track_box	(	TobiiResearchEyeTracker *	eyetracker,
		TobiiResearchTrackBox *	track_box
	)

Gets the track box of the eye tracker.

    TobiiResearchTrackBox track_box;
 
    TobiiResearchStatus status = tobii_research_get_track_box(eyetracker, &track_box);
 

Parameters

eyetracker	Eye tracker object.
track_box	Track box coordinates.

Returns

A TobiiResearchStatus code.

Examples

get_track_box.c.

tobii_research_retrieve_calibration_data()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_retrieve_calibration_data	(	TobiiResearchEyeTracker *	eyetracker,
		TobiiResearchCalibrationData **	data
	)

Gets the calibration data used currently by the eye tracker.

This data can be saved to a file for later use. See tobii_research_apply_calibration_data

    /* Save the calibration to file. */
    char* filename = "saved_calibration.bin";
    char* serial_number = NULL;
 
    FILE* f = fopen(filename, "wb");
 
    TobiiResearchCalibrationData* calibration_data = NULL;
    TobiiResearchStatus status = tobii_research_retrieve_calibration_data(eyetracker, &calibration_data);
 
    if (status != TOBII_RESEARCH_STATUS_OK)
        return;
 
    tobii_research_get_serial_number(eyetracker, &serial_number);
 
    /* None is returned on empty calibration. */
    if (calibration_data->size != 0) {
 
        printf("Saving calibration to file for eye tracker with serial number %s.\n", serial_number);
        fwrite(calibration_data->data, calibration_data->size, 1, f);
    } else {
        printf("No calibration available for eye tracker with serial number %s.\n", serial_number);
    }
 
    fclose(f);
    tobii_research_free_calibration_data(calibration_data);
 

Parameters

eyetracker	Eye tracker object.
data	Calibration data.

Returns

A TobiiResearchStatus code.

Examples

calibration_data.c.

tobii_research_set_device_name()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_set_device_name	(	TobiiResearchEyeTracker *	eyetracker,
		const char *	device_name
	)

Changes the device name. This is not supported by all eye trackers.

    TobiiResearchStatus status = tobii_research_set_device_name(eyetracker, "A new name");

Parameters

eyetracker	Eye tracker object.
device_name	The eye tracker's desired name.

Returns

A TobiiResearchStatus code.

Examples

set_device_name.c.

tobii_research_set_display_area()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_set_display_area	(	TobiiResearchEyeTracker *	eyetracker,
		const TobiiResearchDisplayArea *	display_area
	)

Sets the display area of the eye tracker. It is strongly recommended to use Eye Tracker Manager to calculate the display area coordinates as the origin of the User Coordinate System differs between eye tracker models.

    TobiiResearchDisplayArea display_area;
    TobiiResearchStatus status = tobii_research_get_display_area(eyetracker, &display_area);
 
    char* serial_number = NULL;
    tobii_research_get_serial_number(eyetracker, &serial_number);
 
    printf("Got display area from tracker with serial number %s with status %i:\n", serial_number, status);
    tobii_research_free_string(serial_number);
 
    printf("Bottom Left: (%f, %f, %f)\n",
            display_area.bottom_left.x,
            display_area.bottom_left.y,
            display_area.bottom_left.z);
    printf("Bottom Right: (%f, %f, %f)\n",
            display_area.bottom_right.x,
            display_area.bottom_right.y,
            display_area.bottom_right.z);
    printf("Height: %f\n", display_area.height);
    printf("Top Left: (%f, %f, %f)\n",
            display_area.top_left.x,
            display_area.top_left.y,
            display_area.top_left.z);
    printf("Top Right: (%f, %f, %f)\n",
            display_area.top_right.x,
            display_area.top_right.y,
            display_area.top_right.z);
    printf("Width: %f\n", display_area.width);
 
    // To set the display area it is possible to either use a previously saved instance of
    // the type TobiiResearchDisplayArea, or create a new one as shown below.
    TobiiResearchDisplayArea new_display_area;
    // For simplicity we are using the same values that are already set on the eye tracker.
    memcpy(&new_display_area.top_left, &display_area.top_left, sizeof(display_area.top_left));
    memcpy(&new_display_area.top_right, &display_area.top_right, sizeof(display_area.top_right));
    memcpy(&new_display_area.bottom_left, &display_area.bottom_left, sizeof(display_area.bottom_left));
 
    status = tobii_research_set_display_area(eyetracker, &new_display_area);
 

Parameters

eyetracker	Eye tracker object.
display_area	The eye tracker's desired display area.

Returns

A TobiiResearchStatus code.

Examples

get_and_set_display_area.c.

tobii_research_set_eye_tracking_mode()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_set_eye_tracking_mode	(	TobiiResearchEyeTracker *	eyetracker,
		const char *	eye_tracking_mode
	)

Sets the eye tracking mode of the eye tracker.

            status = tobii_research_set_eye_tracking_mode(eyetracker, initial_eye_tracking_mode);
 
            printf("Eye tracking mode reset to %s with status %i.\n", initial_eye_tracking_mode, status);
 
            tobii_research_free_string(initial_eye_tracking_mode);

Parameters

eyetracker	Eye tracker object.
eye_tracking_mode	The eye tracking mode.

Returns

A TobiiResearchStatus code.

Examples

eye_tracking_modes.c.

tobii_research_set_gaze_output_frequency()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_set_gaze_output_frequency	(	TobiiResearchEyeTracker *	eyetracker,
		float	gaze_output_frequency
	)

Sets the gaze output frequency of the eye tracker.

            tobii_research_set_gaze_output_frequency(eyetracker, initial_gaze_output_frequency);
 
            printf("Gaze output frequency reset to %f Hz.\n", initial_gaze_output_frequency);
        } else {
            printf("tobii_research_get_all_gaze_output_frequencies returned status %i.\n", status);
        }
 

Parameters

eyetracker	Eye tracker object.
gaze_output_frequency	The gaze output frequency.

Returns

A TobiiResearchStatus code.

Examples

gaze_output_frequencies.c.

tobii_research_set_hmd_lens_configuration()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_set_hmd_lens_configuration	(	TobiiResearchEyeTracker *	eyetracker,
		const TobiiResearchHMDLensConfiguration *	lens_configuration
	)

Sets the lens configuration of the HMD based eye tracker. The lens configuration describes how the lenses of the HMD device are positioned.

 
    TobiiResearchHMDLensConfiguration lens_configuration;
    lens_configuration.left.x = 32.0f;
    lens_configuration.left.y = 0.0f;
    lens_configuration.left.z = 0.0f;
 
    lens_configuration.right.x = -32.0f;
    lens_configuration.right.y = 0.0f;
    lens_configuration.right.z = 0.0f;
 
    TobiiResearchStatus status = tobii_research_get_hmd_lens_configuration(eyetracker, &lens_configuration);
 
    char* serial_number = NULL;
    tobii_research_get_serial_number(eyetracker, &serial_number);
 
    printf("Set lens configuration from tracker with serial number %s with status %i:\n", serial_number, status);
    tobii_research_free_string(serial_number);
 

Parameters

eyetracker	Eye tracker object.
lens_configuration	The eye tracker's desired lens_configuration.

Returns

A TobiiResearchStatus code.

Examples

set_hmd_lens_configuration.c.