The Tobii Stream Engine API consists of the following modules.

tobii.h

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 API documentation includes example code snippets that shows 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.

Thread safety

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.

In the samples folder, you can find complete examples on how to use Stream Engine with multiple threads, such as background_thread_sample and game_loop_sample.

tobii_error_message

Function

Returns a printable error message.

Syntax

#include <tobii/tobii.h>
char const* tobii_error_message( tobii_error_t error );

Remarks

All other functions in the API returns an error code from the tobii_error_t enumeration. tobii_error_message translates from these error codes to a human readable message. If the value passed in the error parameter is not within the range of the tobii_error_t enum, a generic message is returned.

Return value

tobii_error_message returns a zero-terminated C string describing the specified error code. The string returned is statically allocated, so it should not be freed.

Example

#include <tobii/tobii.h>
#include <stdio.h>

int main()
{
    tobii_api_t* api;

    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    if( error != TOBII_ERROR_NO_ERROR ) printf( "%s\n", tobii_error_message( error ) );

    error = tobii_api_destroy( api );
    if( error != TOBII_ERROR_NO_ERROR ) printf( "%s\n", tobii_error_message( error ) );

    return 0;
}

tobii_get_api_version

Function

Query the current version of the API.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_get_api_version( tobii_version_t* version );

Remarks

tobii_get_api_version can be used to query the version of the stream engine dll currently used.

version is a pointer to an tobii_version_t variable to receive the current version numbers. It contains the following members:

Return value

If the call is successful, tobii_get_api_version returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_get_api_version returns one of the following:

Example

#include <tobii/tobii.h>
#include <stdio.h>

int main()
{
    tobii_version_t version;
    tobii_error_t error = tobii_get_api_version( &version );
    if( error == TOBII_ERROR_NO_ERROR )
        printf( "Current API version: %d.%d.%d\n", version.major, version.minor, 
            version.revision );

    return 0;
}

tobii_api_create

Function

Initializes the stream engine API, with optionally provided custom memory allocation and logging functions.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_api_create( tobii_api_t** api, 
    tobii_custom_alloc_t const* custom_alloc, tobii_custom_log_t const* custom_log );

Remarks

Before any other API function can be invoked (with the exception of tobii_error_message and tobii_get_api_version), the API needs to be set up for use, by calling tobii_api_create. The resulting tobii_api_t instance is passed explicitly to some functions, or implicitly to some by passing a device instance. When creating an API instance, it is possible, but not necessary, to customize the behavior by passing one or more of the optional parameters custom_alloc and custom_log.

api must be a pointer to a variable of the type tobii_api_t* that is, a pointer to a tobii_api_t-pointer. This variable will be filled in with a pointer to the created instance. tobii_api_t is an opaque type, and only its declaration is available in the API.

custom_alloc is used to specify a custom allocator for dynamic memory. A custom allocator is specified as a pointer to a tobii_custom_alloc_t instance, which has the following fields:

custom_alloc is an optional parameter, and may be NULL, in which case a default allocator is used.

NOTE: Stream engine does not guarantee thread safety on custom_alloc. If thread safety is a requirement, it should be satisfied in the implementation of custom_alloc. Default allocator runs thread safe.

custom_log is used to specify a custom function to handle log printouts. A custom logger is specified as a pointer to a tobii_custom_log_t instance, which has the following fields:

custom_log is an optional parameter, and may be NULL. In this case, no logging will be done.

NOTE: Stream engine does not guarantee thread safety on custom_log. If thread safety is a requirement, it should be satisfied in the implementation of custom_log.

Return value

If API instance creation was successful, tobii_api_create returns TOBII_ERROR_NO_ERROR. If creation failed, tobii_api_create returns one of the following:

See also

tobii_api_destroy(), tobii_device_create()

Example

#include <tobii/tobii.h>
#include <stdlib.h>
#include <stdio.h>
#include <assert.h>

// we will use custom_alloc to track allocations
typedef struct allocation_tracking
{
    int total_allocations;
    int current_allocations;
} allocation_tracking;

void* custom_malloc( void* mem_context, size_t size )
{
    allocation_tracking* tracking = (allocation_tracking*)mem_context;
    // both total allocations, and current allocations increase
    tracking->total_allocations++;
    tracking->current_allocations++;
    return malloc( size ); // pass through to C runtime
}

void custom_free( void* mem_context, void* ptr )
{
    allocation_tracking* tracking = (allocation_tracking*)mem_context;
    // only current allocations decrease, as free doesn't affect our total count
    tracking->current_allocations--;
    free( ptr ); // pass through to C runtime
}

void custom_logging( void* log_context, tobii_log_level_t level, char const* text )
{
    // log messages can be filtered by log level if desired
    if( level == TOBII_LOG_LEVEL_ERROR )
        printf( "[%d] %s\n", (int) level, text ); 
}

int main()
{
    allocation_tracking tracking;
    tracking.total_allocations = 0;
    tracking.current_allocations = 0;

    tobii_custom_alloc_t custom_alloc;
    custom_alloc.mem_context = &tracking;
    custom_alloc.malloc_func = &custom_malloc;
    custom_alloc.free_func = &custom_free;

    tobii_custom_log_t custom_log;
    custom_log.log_context = NULL; // we don't use the log_context in this example
    custom_log.log_func = &custom_logging;

    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, &custom_alloc, &custom_log );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );

    printf( "Total allocations: %d\n", tracking.total_allocations );
    printf( "Current allocations: %d\n", tracking.current_allocations );

    return 0;
}

tobii_api_destroy

Function

Destroys an API instance.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_api_destroy( tobii_api_t* api );

Remarks

When creating an instance with tobii_api_create, some system resources are acquired. When finished using the API (typically during the shutdown process), tobii_api_destroy should be called to destroy the instance and ensure that those resources are released.

tobii_api_destroy should only be called if tobii_api_create completed successfully.

api must be a pointer to a valid tobii_api_t instance as created by calling tobii_api_create.

Return value

If the call was successful, tobii_api_destroy returns TOBII_ERROR_NO_ERROR otherwise it can return one of the following:

See also

tobii_api_create(), tobii_device_destroy()

Example

See tobii_api_create()

tobii_enumerate_local_device_urls

Function

Retrieves the URLs for stream engine compatible devices currently connected to the system.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_enumerate_local_device_urls( tobii_api_t* api,
    tobii_device_url_receiver_t receiver, void* user_data );

Remarks

A system might have multiple devices connected, which the stream engine is able to communicate with. tobii_enumerate_local_device_urls iterates over all such devices found. It will only enumerate devices connected directly to the system, not devices connected on the network.

api must be a pointer to a valid tobii_api_t instance as created by calling tobii_api_create.

receiver is a function pointer to a function with the prototype:

void url_receiver( char const* url, void* user_data )

This function will be called for each device found during enumeration. It is called with the following parameters:

user_data custom pointer which will be passed unmodified to the receiver function.

Return value

If the enumeration is successful, tobii_enumerate_local_device_urls returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_enumerate_local_device_urls returns one of the following:

See also

tobii_device_create(), tobii_enumerate_local_device_urls_ex()

Example

#include <tobii/tobii.h>
#include <stdio.h>
#include <assert.h>

void url_receiver( char const* url, void* user_data )
{
    int* count = (int*) user_data;
    ++(*count);
    printf( "%d. %s\n", *count, url );
}

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    int count = 0;
    error = tobii_enumerate_local_device_urls( api, url_receiver, &count );        
    if( error == TOBII_ERROR_NO_ERROR )
        printf( "Found %d devices.\n", count );
    else
        printf( "Enumeration failed.\n" );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );
    return 0;
}

tobii_enumerate_local_device_urls_ex

Function

Retrieves the URLs for the stream engine compatible devices, of the specified generation, currently connected to the system.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_enumerate_local_device_urls_ex( tobii_api_t* api, 
    tobii_device_url_receiver_t receiver, void* user_data, 
    uint32_t device_generations );

Remarks

A system might have multiple devices connected, which the stream engine is able to communicate with. tobii_enumerate_local_device_urls_ex works similar to tobii_enumerate_local_device_urls(), but allows for more control. It only iterates over devices of the specified hardware generations, allowing for limiting the results and the processing required to enumerate devices which are not of interest for the application. It will only enumerate devices connected directly to the system, not devices connected on the network.

api must be a pointer to a valid tobii_api_t instance as created by calling tobii_api_create.

receiver is a function pointer to a function with the prototype:

void url_receiver( char const* url, void* user_data )

This function will be called for each device found during enumeration. It is called with the following parameters:

user_data custom pointer which will be passed unmodified to the receiver function.

device_generations is a bit-field specifying which hardware generations are to be included in the enumeration. It is created by bitwise OR-ing of the following constants:

Return value

If the enumeration is successful, tobii_enumerate_local_device_urls_ex returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_enumerate_local_device_urls_ex returns one of the following:

See also

tobii_device_create(), tobii_enumerate_local_device_urls()

Example

#include <tobii/tobii.h>
#include <stdio.h>
#include <assert.h>

void url_receiver( char const* url, void* user_data )
{
    int* count = (int*) user_data;
    ++(*count);
    printf( "%d. %s\n", *count, url );
}

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    int count = 0;
    error = tobii_enumerate_local_device_urls_ex( api, url_receiver, &count,
        TOBII_DEVICE_GENERATION_G5 | TOBII_DEVICE_GENERATION_IS4 );
    if( error == TOBII_ERROR_NO_ERROR )
        printf( "Found %d devices.\n", count );
    else
        printf( "Enumeration failed.\n" );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );
    return 0;
}

tobii_device_create

Function

Creates a device instance to be used for communicating with a specific device.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_device_create( tobii_api_t* api,
    char const* url, tobii_device_t** device );

Remarks

In order to communicate with a specific device, stream engine needs to keep track of internal states. tobii_device_create allocates and initializes this state, and is needed for all functions which communicates with a device. Creating a device will establish a connection to the tracker, and can be used to query the device for more information.

api must be a pointer to a valid tobii_api_t as created by calling tobii_api_create.

url is optional, so can either be NULL (in which case the first device that can be found will be used) or a valid device url as returned by tobii_enumerate_local_device_urls.

device must be a pointer to a variable of the type tobii_device_t* that is, a pointer to a tobii_device_t-pointer. This variable will be filled in with a pointer to the created device instance. tobii_device_t is an opaque type.

Return value

If the device is successfully created, tobii_device_create returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_device_create returns one of the following:

See also

tobii_device_destroy(), tobii_enumerate_local_device_urls(), tobii_api_create(), tobii_get_device_info(), tobii_get_feature_group()

Example

#include <tobii/tobii.h>
#include <stdio.h>
#include <assert.h>

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    // --> code to use the device would go here <--

    error = tobii_device_destroy( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );
    return 0;
}

tobii_device_destroy

Function

Destroy a device previously created through a call to tobii_device_destroy.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_device_destroy( tobii_device_t* device );

Remarks

tobii_device_destroy will disconnect from the device, perform cleanup and free the memory allocated by calling tobii_device_create.

NOTE: Make sure that no background thread is using the device, for example in the thread calling tobii_process_callbacks, before calling tobii_device_destroy in order to avoid the risk of encountering undefined behavior.

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

Return value

If the device is successfully created, tobii_device_create returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_device_create returns one of the following:

See also

tobii_device_create(), tobii_device_create_ex()

Example

See tobii_device_create()

tobii_wait_for_callbacks

Function

Puts the calling thread to sleep until there are new callbacks available to process.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_wait_for_callbacks( tobii_device_t* device );

Remarks

Stream engine does not use any threads to do processing or receive data. Instead, the function tobii_process_callbacks() have to be called regularly, to receive data from the device and process it. The typical use case is to implement your own thread to call tobii_process_callbacks from, and to avoid busy-waiting for data to become available, tobii_wait_for_callbacks can be called before each call to tobii_process_callbacks. It will sleep the calling thread until new data is available to process, after which tobii_process_callbacks should be called to process it.

In addition to waiting for data, tobii_wait_for_callbacks will also periodically call tobii_update_timesync() to ensure synchronization of system and device timestamps. This means you will not have to call tobii_update_timesync() if you regularly call tobii_wait_for_callbacks.

tobii_wait_for_callbacks will not wait indefinitely. There is a timeout of some hundred milliseconds, after which tobii_wait_for_callbacks will return TOBII_ERROR_TIMED_OUT. This does not indicate a failure - it is given as an opportunity for the calling thread to perform its own internal housekeeping (like checking for exit conditions and the like). It is valid to immediately call tobii_wait_for_callbacks again to resume waiting.

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

Return value

If the operation is successful, tobii_wait_for_callbacks returns TOBII_ERROR_NO_ERROR. If the call fails, or if the wait times out, tobii_wait_for_callbacks returns one of the following:

See also

tobii_process_callbacks(), tobii_clear_callback_buffers()

Example

#include <tobii/tobii.h>
#include <stdio.h>
#include <assert.h>

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    int is_running = 1000; // in this sample, exit after some iterations
    while( --is_running > 0 )
    {
        error = tobii_wait_for_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR || error == TOBII_ERROR_TIMED_OUT );

        error = tobii_process_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR );
    }

    error = tobii_device_destroy( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );

    return 0;
}

tobii_process_callbacks

Function

Receives data packages from the device, and sends the data through any registered callbacks.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_process_callbacks( tobii_device_t* device );

Remarks

Stream engine does not do any kind of background processing, it doesn’t start any threads. It doesn’t use any asynchronous callbacks. This means that in order to receive data from the device, the application needs to manually request the callbacks to happen synchronously, and this is done by calling tobii_process_callbacks.

tobii_process_callbacks will receive any data packages that are incoming from the device, process them and call any subscribed callbacks with the data. No callbacks will be called outside of tobii_process_callbacks, so the application have full control over when to receive callbacks.

tobii_process_callbacks will not wait for data, and will early-out if there’s nothing to process. In order to maintain the connection to the device, tobii_process_callbacks should be called at least 10 times per second.

The recommended way to use tobii_process_callbacks, is to start a dedicated thread, and alternately call tobii_wait_for_callbacks and tobii_process_callbacks. See tobii_wait_for_callbacks() for more details.

If there is already a suitable thread to regularly run tobii_process_callbacks from (possibly interleaved with application specific operations), it is possible to do this without calling tobii_wait_for_callbacks(). In this scenario, time synchronization needs to be handled manually or the timestamps will start drifting. See tobii_update_timesync() for more details.

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

Return value

If the operation is successful, tobii_process_callbacks returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_process_callbacks returns one of the following:

See also

tobii_wait_for_callbacks(), tobii_clear_callback_buffers(), tobii_reconnect(), tobii_update_timesync()

Example

#include <tobii/tobii.h>
#include <stdio.h>
#include <assert.h>

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    int is_running = 1000; // in this sample, exit after some iterations
    while( --is_running > 0 )
    {
        // other parts of main loop would be executed here

        error = tobii_process_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR );
    }

    error = tobii_device_destroy( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );

    return 0;
}

tobii_clear_callback_buffers

Function

Removes all unprocessed entries from the callback queues.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_clear_callback_buffers( tobii_device_t* device );

Remarks

All the data that is received and processed are written into internal buffers used for the callbacks. In some circumstances, for example during initialization, you might want to discard any data that has been buffered but not processed, without having to destroy/recreate the device, and without having to implement the filtering out of unwanted data. tobii_clear_callback_buffers will clear all buffered data, and only data arriving after the call to tobii_clear_callback_buffers will be forwarded to callbacks.

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

Return value

If the operation is successful, tobii_clear_callback_buffers returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_clear_callback_buffers returns one of the following:

See also

tobii_wait_for_callbacks(), tobii_process_callbacks()

tobii_reconnect

Function

Establish a new connection after a disconnect.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_reconnect( tobii_device_t* device );

Remarks

When receiving the error code TOBII_ERROR_CONNECTION_FAILED, it is necessary to explicitly request reconnection, by calling tobii_reconnect.

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

Return value

See also

tobii_process_callbacks()

Example

See tobii_process_callbacks()

tobii_update_timesync

Function

Makes a manual re-synchronization of system timestamps and device timestamps.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_update_timesync( tobii_device_t* device );

Remarks

The clock on the device and the clock on the system it is connected to may drift over time, and therefore they need to be periodically re-synchronized. In the default usage scenario, when regularly calling tobii_wait_for_callbacks(), this re-sychronization is handled automatically at a pre-determined interval. When not using tobii_wait_for_callbacks, and instead relying on only tobii_process_callbacks, it is necessary to re-synchronize manually, which is done by calling tobii_update_timesync every ~30 seconds.

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

Return value

If the call to tobii_update_timesync is successful, tobii_update_timesync returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_update_timesync returns one of the following:

See also

tobii_wait_for_callbacks(), tobii_reconnect(), tobii_process_callbacks(), tobii_system_clock()

Example

#include <tobii/tobii.h>
#include <stdio.h>
#include <assert.h>

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    int is_running = 1000; // in this sample, exit after some iterations
    while( --is_running > 0 )
    {
        error = tobii_process_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR );

        error = tobii_update_timesync( device );
        assert( error == TOBII_ERROR_NO_ERROR );
    }

    error = tobii_device_destroy( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );
    return 0;
}

tobii_system_clock

Function

Returns the current system time, from the same clock used to time-stamp callback data.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_system_clock( tobii_api_t* api, int64_t* timestamp_us );

Remarks

Many of the data streams provided by the stream engine API, contains a timestamp value, measured in microseconds (us). The epoch is undefined, so these timestamps are only useful for calculating the time elapsed between a pair of values. To facilitate making comparisons between stream engine provided timestamps and application specific events, tobii_system_clock can be used to retrieve a timestamp using the same clock and same relative values as the timestamps used in stream engine callbacks.

api must be a pointer to a valid tobii_api_t instance as created by calling tobii_api_create.

timestamp_us must be a pointer to a int64_t variable to receive the timestamp value.

Return value

If the operation is successful, tobii_system_clock returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_system_clock returns one of the following:

See also

tobii_api_create()

Example

#include <tobii/tobii.h>
#include <stdio.h>
#include <inttypes.h>
#include <assert.h>

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    int64_t time;
    error = tobii_system_clock( api, &time );
    if( error == TOBII_ERROR_NO_ERROR )
        printf( "timestamp: %" PRId64 "\n", time );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );

    return 0;
}

tobii_get_device_info

Function

Retrieves detailed information about the device, such as name and serial number.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_get_device_info( tobii_device_t* device, 
    tobii_device_info_t* device_info );

Remarks

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

device_info is a pointer to a tobii_device_info_t variable to receive the information. It contains the following fields, all containing zero-terminated ASCII strings:

Return value

If device info was successfully retrieved, tobii_get_device_info returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_get_device_info returns one of the following:

See also

tobii_device_create(), tobii_enumerate_local_device_urls()

Example

#include <tobii/tobii.h>
#include <assert.h>
#include <stdio.h>

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_info_t info;
    error = tobii_get_device_info( device, &info );
    assert( error == TOBII_ERROR_NO_ERROR );

    printf( "Serial number: %s\n", info.serial_number );

    error = tobii_device_destroy( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );
    return 0;
}

tobii_get_track_box

Function

Retrieves 3d coordinates of the track box frustum, given in millimeters from the device center.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_get_track_box( tobii_device_t* device, tobii_track_box_t* track_box );

Remarks

The track box is a volume in front of the tracker within which the user can be tracked.

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

track_box is a pointer to a tobii_track_box_t variable to receive the result. It contains the following fields, all being arrays of three floating point values, describing the track box frustum:

Return value

If track box coordinates were successfully retrieved, tobii_get_track_box returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_get_track_box returns one of the following:

Example

#include <tobii/tobii.h>
#include <stdio.h>
#include <assert.h>

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_track_box_t track_box;
    error = tobii_get_track_box( device, &track_box );
    assert( error == TOBII_ERROR_NO_ERROR );

    // print just a couple of values of the track box data
    printf( "Front upper left is (%f, %f, %f)\n",
        track_box.front_upper_left_xyz[ 0 ],
        track_box.front_upper_left_xyz[ 1 ],
        track_box.front_upper_left_xyz[ 2 ] );
    printf( "Back lower right is (%f, %f, %f)\n",
        track_box.back_lower_right_xyz[ 0 ],
        track_box.back_lower_right_xyz[ 1 ],
        track_box.back_lower_right_xyz[ 2 ] );

    error = tobii_device_destroy( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );
    return 0;
}

tobii_get_state_bool

Function

Gets the current value of a state in the tracker.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_get_state_bool( tobii_device_t* device, tobii_state_t state,
    tobii_state_bool_t* value );

Remarks

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

state is one of the enum values in tobii_state_t:

value must be a pointer to a valid tobii_state_bool_t instance. On success, value will be set to TOBII_STATE_BOOL_TRUE if the state is true, otherwise TOBII_STATE_BOOL_FALSE. value will remain unmodified if the call failed.

NOTE: This method relies on cached values which is updated when tobii_process_callbacks() is called, so it might not represent the true state of the device if some time have passed since the last call to tobii_process_callbacks().

Return value

If the call was successful TOBII_ERROR_NO_ERROR will be returned. If the call has failed one of the following error will be returned:

Example

#include <tobii/tobii.h>
#include <stdio.h>
#include <assert.h>

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_state_bool_t value;
    error = tobii_get_state_bool( device, TOBII_STATE_DEVICE_PAUSED, &value );
    assert( error == TOBII_ERROR_NO_ERROR );

    if( value == TOBII_STATE_BOOL_TRUE )
        printf( "Device is paused!" );
    else
        printf( "Device is running!" );

    tobii_device_destroy( device );
    tobii_api_destroy( api );

    return 0;
}

tobii_capability_supported

Function

Ask if a specific feature is supported or not.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_capability_supported( tobii_device_t* device, 
    tobii_capability_t capability, tobii_supported_t* supported );

Remarks

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

capability is one of the enum values in tobii_capability_t:

supported must be a pointer to a valid tobii_supported_t instance. If tobii_capability_supported is successfull, supported will be set to TOBII_SUPPORTED if the feature is supported, and TOBII_NOT_SUPPORTED if it is not.

Return value

If the call was successful TOBII_ERROR_NO_ERROR will be returned. If the call has failed one of the following error will be returned:

See also

tobii_stream_supported()

Example

#include <tobii/tobii.h>
#include <stdio.h>
#include <assert.h>

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_supported_t supported;
    error = tobii_capability_supported( device, TOBII_CAPABILITY_CALIBRATION_3D, &supported );
    assert( error == TOBII_ERROR_NO_ERROR );

    if( supported == TOBII_SUPPORTED )
        printf( "Device supports 3D calibration." );
    else
        printf( "Device does not support 3D calibration." );

    tobii_device_destroy( device );
    tobii_api_destroy( api );

    return 0;
}

tobii_stream_supported

Function

Ask if a specific stream is supported or not.

Syntax

#include <tobii/tobii.h>
tobii_error_t tobii_stream_supported( tobii_device_t* device, 
    tobii_stream_t stream, tobii_supported_t* supported );

Remarks

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

stream is one of the enum values in tobii_stream_t, each corresponding to one of the streams from tobii_streams.h, tobii_wearable.h and tobii_advanced.h

supported must be a pointer to a valid tobii_supported_t instance. If tobii_stream_supported is successfull, supported will be set to TOBII_SUPPORTED if the feature is supported, and TOBII_NOT_SUPPORTED if it is not.

Return value

If the call was successful TOBII_ERROR_NO_ERROR will be returned. If the call has failed one of the following error will be returned:

See also

tobii_capability_supported()

Example

#include <tobii/tobii.h>
#include <stdio.h>
#include <assert.h>

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_supported_t supported;
    error = tobii_stream_supported( device, TOBII_STREAM_GAZE_POINT, &supported );
    assert( error == TOBII_ERROR_NO_ERROR );

    if( supported == TOBII_SUPPORTED )
        printf( "Device supports gaze point stream." );
    else
        printf( "Device does not support gaze point stream." );

    tobii_device_destroy( device );
    tobii_api_destroy( api );

    return 0;
}

tobii_streams.h

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.

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.

Do NOT call StreamEngine API functions from within the callback functions, due to risk of internal deadlocks. Generally one should finish the callback functions as quickly as possible and not make any blocking calls.

tobii_gaze_point_subscribe

Function

Start listening for gaze point data; the position on the screen that the user is currently looking at.

Syntax

#include <tobii/tobii_streams.h>
tobii_error_t tobii_gaze_point_subscribe( tobii_device_t* device,
    tobii_gaze_point_callback_t callback, void* user_data );

Remarks

This subscription is for receiving the point on the screen, in normalized (0 to 1) coordinates, that the user is currently looking at. The data is lightly filtered for stability.

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create.

callback is a function pointer to a function with the prototype:

void gaze_point_callback( tobii_gaze_point_t const* gaze_point, void* user_data )

This function will be called when there is a new gaze data available. It is called with the following parameters:

user_data custom pointer which will be passed unmodified to the callback.

Return value

If the operation is successful, tobii_gaze_point_subscribe returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_gaze_point_subscribe returns one of the following:

See also

tobii_gaze_point_unsubscribe(), tobii_process_callbacks(), tobii_system_clock()

Example

#include <tobii/tobii_streams.h>
#include <stdio.h>
#include <assert.h>

void gaze_point_callback( tobii_gaze_point_t const* gaze_point, void* user_data )
{
    if( gaze_point->validity == TOBII_VALIDITY_VALID )
        printf( "Gaze point: %f, %f\n",
            gaze_point->position_xy[ 0 ],
            gaze_point->position_xy[ 1 ] );
}

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_gaze_point_subscribe( device, gaze_point_callback, 0 );
    assert( error == TOBII_ERROR_NO_ERROR );

    int is_running = 1000; // in this sample, exit after some iterations
    while( --is_running > 0 )
    {
        error = tobii_wait_for_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR || error == TOBII_ERROR_TIMED_OUT );

        error = tobii_process_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR );
    }

    error = tobii_gaze_point_unsubscribe( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_device_destroy( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );
    return 0;
}

tobii_gaze_point_unsubscribe

Function

Stops listening to gaze point stream that was subscribed to by a call to tobii_gaze_point_subscribe()

Syntax

#include <tobii/tobii_streams.h>
tobii_error_t tobii_gaze_point_unsubscribe( tobii_device_t* device );

Remarks

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create.

Return value

If the operation is successful, tobii_gaze_point_unsubscribe returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_gaze_point_unsubscribe returns one of the following:

See also

tobii_gaze_point_subscribe()

Example

See tobii_gaze_point_subscribe()

tobii_gaze_origin_subscribe

Function

Start listening for gaze origin data. Gaze origin is a point on the users eye, reported in millimeters from the center of the display.

Syntax

#include <tobii/tobii_streams.h>
tobii_error_t tobii_gaze_origin_subscribe( tobii_device_t* device,
    tobii_gaze_origin_callback_t callback, void* user_data );

Remarks

This subscription is for receiving the origin of the gaze vector, measured in millimeters from the center of the display. Gaze origin is a point on the users eye, but the exact point of the origin varies by device. For example, it might be defined as the center of the pupil or the center of the cornea. The data is lightly filtered for stability.

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create.

callback is a function pointer to a function with the prototype:

void gaze_origin_callback( tobii_gaze_origin_t const* gaze_origin, void* user_data )

This function will be called when there is new gaze origin data available. It is called with the following parameters:

user_data custom pointer which will be passed unmodified to the callback.

Return value

If the operation is successful, tobii_gaze_origin_subscribe returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_gaze_origin_subscribe returns one of the following:

See also

tobii_eye_position_normalized_subscribe(), tobii_gaze_origin_unsubscribe(), tobii_process_callbacks(), tobii_system_clock()

Example

#include <tobii/tobii_streams.h>
#include <stdio.h>
#include <assert.h>

void gaze_origin_callback( tobii_gaze_origin_t const* gaze_origin, void* user_data )
{
    if( gaze_origin->left_validity == TOBII_VALIDITY_VALID )
        printf( "Left: %f, %f, %f ",
            gaze_origin->left_xyz[ 0 ],
            gaze_origin->left_xyz[ 1 ],
            gaze_origin->left_xyz[ 2 ] );

    if( gaze_origin->right_validity == TOBII_VALIDITY_VALID )
        printf( "Right: %f, %f, %f ",
            gaze_origin->right_xyz[ 0 ],
            gaze_origin->right_xyz[ 1 ],
            gaze_origin->right_xyz[ 2 ] );

    printf( "\n" );
}

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_gaze_origin_subscribe( device, gaze_origin_callback, 0 );
    assert( error == TOBII_ERROR_NO_ERROR );

    int is_running = 1000; // in this sample, exit after some iterations
    while( --is_running > 0 )
    {
        error = tobii_wait_for_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR || error == TOBII_ERROR_TIMED_OUT );

        error = tobii_process_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR );
    }

    error = tobii_gaze_origin_unsubscribe( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_device_destroy( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );
    return 0;
}

tobii_gaze_origin_unsubscribe

Function

Stops listening to gaze origin stream that was subscribed to by a call to tobii_gaze_origin_subscribe()

Syntax

#include <tobii/tobii_streams.h>
tobii_error_t tobii_gaze_origin_unsubscribe( tobii_device_t* device );

Remarks

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create.

Return value

If the operation is successful, tobii_gaze_origin_unsubscribe returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_gaze_origin_unsubscribe returns one of the following:

See also

tobii_gaze_origin_subscribe()

Example

See tobii_gaze_origin_subscribe()

tobii_eye_position_normalized_subscribe

Function

Start listening for normalized eye position data. Eye position is a point on the users eye, reported in normalized track box coordinates.

Syntax

#include <tobii/tobii_streams.h>
tobii_error_t tobii_eye_position_normalized_subscribe( tobii_device_t* device,
    tobii_eye_position_normalized_callback_t callback, void* user_data );

Remarks

This subscription is for receiving the position of the eyes, given in normalized (0 to 1) track box coordinates. The exact point on the eye varies by device. For example, the center of the pupil or the center of the cornea. The data is lightly filtered for stability. The track box is a the volume around the user that the device can track within.

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create.

callback is a function pointer to a function with the prototype:

void eye_position_normalized_callback( tobii_eye_position_normalized_t const* eye_position, void* user_data )

This function will be called when there is new normalized eye position data available. It is called with the following parameters:

user_data custom pointer which will be passed unmodified to the callback.

Return value

If the operation is successful, tobii_eye_position_normalized_subscribe returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_eye_position_normalized_subscribe returns one of the following:

See also

tobii_gaze_origin_subscribe(), tobii_eye_position_normalized_unsubscribe(), tobii_process_callbacks(), tobii_system_clock()

Example

#include <tobii/tobii_streams.h>
#include <stdio.h>
#include <assert.h>

void eye_position_callback( tobii_eye_position_normalized_t const* eye_pos, void* user_data )
{
    if( eye_pos->left_validity == TOBII_VALIDITY_VALID )
        printf( "Left: %f, %f, %f ",
            eye_pos->left_xyz[ 0 ],
            eye_pos->left_xyz[ 1 ],
            eye_pos->left_xyz[ 2 ] );

    if( eye_pos->right_validity == TOBII_VALIDITY_VALID )
        printf( "Right: %f, %f, %f ",
            eye_pos->right_xyz[ 0 ],
            eye_pos->right_xyz[ 1 ],
            eye_pos->right_xyz[ 2 ] );

    printf( "\n" );
}

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_eye_position_normalized_subscribe( device, eye_position_callback, 0 );
    assert( error == TOBII_ERROR_NO_ERROR );

    int is_running = 1000; // in this sample, exit after some iterations
    while( --is_running > 0 )
    {
        error = tobii_wait_for_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR || error == TOBII_ERROR_TIMED_OUT );

        error = tobii_process_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR );
    }

    error = tobii_eye_position_normalized_unsubscribe( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_device_destroy( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );
    return 0;
}

tobii_eye_position_normalized_unsubscribe

Function

Stops listening to normalized eye position stream that was subscribed to by a call to tobii_eye_position_normalized_subscribe()

Syntax

#include <tobii/tobii_streams.h>
tobii_error_t tobii_eye_position_normalized_unsubscribe( 
    tobii_device_t* device );

Remarks

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create.

Return value

If the operation is successful, tobii_eye_position_normalized_unsubscribe returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_eye_position_normalized_unsubscribe returns one of the following:

See also

tobii_eye_position_normalized_subscribe()

Example

See tobii_eye_position_normalized_subscribe()

tobii_user_presence_subscribe

Function

Start listening for user presence notifications, reporting whether there is a person in front of the device.

Syntax

#include <tobii/tobii_streams.h>
tobii_error_t tobii_user_presence_subscribe( tobii_device_t* device,
    tobii_user_presence_callback_t callback, void* user_data );

Remarks

This subscription is for being notified when a user is detected by the device, and when a user is no longer detected.

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create.

callback is a function pointer to a function with the prototype:

void presence_callback( tobii_user_presence_status_t status, int64_t timestamp_us, 
    void* user_data )

This function will be called when there is a change in presence state. It is called with the following parameters:

user_data custom pointer which will be passed unmodified to the callback.

Return value

If the operation is successful, tobii_user_presence_subscribe returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_user_presence_subscribe returns one of the following:

See also

tobii_user_presence_unsubscribe(), tobii_process_callbacks(), tobii_system_clock()

Example

#include <tobii/tobii_streams.h>
#include <stdio.h>
#include <assert.h>

void presence_callback( tobii_user_presence_status_t status, int64_t timestamp_us, void* user_data )
{
    switch( status )
    {
        case TOBII_USER_PRESENCE_STATUS_UNKNOWN:
            printf( "User presence status is unknown.\n" );
            break;
        case TOBII_USER_PRESENCE_STATUS_AWAY:
            printf( "User is away.\n" );
            break;
        case TOBII_USER_PRESENCE_STATUS_PRESENT:
            printf( "User is present.\n" );
            break;
    }
}

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_user_presence_subscribe( device, presence_callback, 0 );
    assert( error == TOBII_ERROR_NO_ERROR );

    int is_running = 1000; // in this sample, exit after some iterations
    while( --is_running > 0 )
    {
        error = tobii_wait_for_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR || error == TOBII_ERROR_TIMED_OUT );

        error = tobii_process_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR );
    }

    error = tobii_user_presence_unsubscribe( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_device_destroy( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );
    return 0;
}

tobii_user_presence_unsubscribe

Function

Stops listening to presence stream that was subscribed to by a call to tobii_user_presence_subscribe().

Syntax

#include <tobii/tobii_streams.h>
tobii_error_t tobii_user_presence_unsubscribe( tobii_device_t* device );

Remarks

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create.

Return value

If the operation is successful, tobii_user_presence_unsubscribe returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_user_presence_unsubscribe returns one of the following:

See also

tobii_user_presence_subscribe()

Example

See tobii_user_presence_subscribe()

tobii_head_pose_subscribe

Function

Start listening to the head pose stream, which reports the position and rotation of the user’s head.

Syntax

#include <tobii/tobii_streams.h>
tobii_error_t TOBII_CALL tobii_head_pose_subscribe( tobii_device_t* device,
    tobii_head_pose_callback_t callback, void* user_data );

Remarks

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create.

callback is a function pointer to a function with the prototype:

void head_pose_callback( tobii_head_pose_t const* head_pose, void* user_data )

This function will be called when there is new head pose data to be sent to the subscriber. It is called with the following parameters:

user_data custom pointer which will be passed unmodified to the notification callback.

Return value

If the operation is successful, tobii_head_pose_subscribe returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_head_pose_subscribe returns one of the following:

See also

tobii_head_pose_unsubscribe()

Example

#include <tobii/tobii_streams.h>
#include <stdio.h>
#include <assert.h>

void head_pose_callback( tobii_head_pose_t const* head_pose, void* user_data )
{
    if( head_pose->position_validity == TOBII_VALIDITY_VALID )
        printf( "Position: (%f, %f, %f)\n",
            head_pose->position_xyz[ 0 ],
            head_pose->position_xyz[ 1 ],
            head_pose->position_xyz[ 2 ] );

    printf( "Rotation:\n" );
    for( int i = 0; i < 3; ++i )
        if( head_pose->rotation_validity_xyz[ i ] == TOBII_VALIDITY_VALID )
            printf( "%f\n", head_pose->rotation_xyz[ i ] );
}

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_head_pose_subscribe( device, head_pose_callback, 0 );
    assert( error == TOBII_ERROR_NO_ERROR );

    int is_running = 1000; // in this sample, exit after some iterations
    while( --is_running > 0 )
    {
        error = tobii_wait_for_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR || error == TOBII_ERROR_TIMED_OUT );

        error = tobii_process_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR );
    }

    error = tobii_head_pose_unsubscribe( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_device_destroy( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );
    return 0;
}

tobii_head_pose_unsubscribe

Function

Stops listening to the head pose stream that was subscribed to by a call to tobii_head_pose_subscribe().

Syntax

#include <tobii/tobii_streams.h>
tobii_error_t TOBII_CALL tobii_head_pose_unsubscribe( tobii_device_t* device );

Remarks

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create.

Return value

If the operation is successful, tobii_head_pose_unsubscribe returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_head_pose_unsubscribe returns one of the following:

See also

tobii_head_pose_subscribe()

Example

See tobii_head_pose_subscribe()

tobii_notifications_subscribe

Function

Start listening to the notifications stream, which reports state changes for a device.

Syntax

#include <tobii/tobii_streams.h>
tobii_error_t tobii_notifications_subscribe( tobii_device_t* device,
    tobii_notifications_callback_t callback, void* user_data );

Remarks

As the device is a shared resource, which may be in use by multiple client applications, notifications are used to inform when a state change have occured on the device, as an effect of another client performing some operation (such as starting a calibration, or changing the display area).

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create.

callback is a function pointer to a function with the prototype:

void notification_callback( tobii_notification_t const* notification, void* user_data )

This function will be called when there is a new notification to be sent to the subscriber. It is called with the following parameters:

user_data custom pointer which will be passed unmodified to the notification callback.

Return value

If the operation is successful, tobii_notifications_subscribe returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_notifications_subscribe returns one of the following:

See also

tobii_notifications_unsubscribe(), tobii_process_callbacks()

Example

#include <tobii/tobii_streams.h>
#include <stdio.h>
#include <assert.h>

void notifications_callback( tobii_notification_t const* notification, void* user_data )
{
    if( notification->type == TOBII_NOTIFICATION_TYPE_CALIBRATION_STATE_CHANGED )
    {
        if( notification->value.state == TOBII_STATE_BOOL_TRUE )
            printf( "Calibration started\n" );
        else
            printf( "Calibration stopped\n" );
    }

    if( notification->type == TOBII_NOTIFICATION_TYPE_FRAMERATE_CHANGED )
        printf( "Framerate changed\nNew framerate: %f\n", notification->value.float_ );
}

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_notifications_subscribe( device, notifications_callback, 0 );
    assert( error == TOBII_ERROR_NO_ERROR );

    int is_running = 1000; // in this sample, exit after some iterations
    while( --is_running > 0 )
    {
        error = tobii_wait_for_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR || error == TOBII_ERROR_TIMED_OUT );

        error = tobii_process_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR );
    }

    error = tobii_notifications_unsubscribe( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_device_destroy( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );
    return 0;
}

tobii_notifications_unsubscribe

Function

Stops listening to notifications stream that was subscribed to by a call to tobii_notifications_subscribe()

Syntax

#include <tobii/tobii_streams.h>
tobii_error_t tobii_notifications_unsubscribe( tobii_device_t* device );

Remarks

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create.

Return value

If the operation is successful, tobii_notifications_unsubscribe returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_notifications_unsubscribe returns one of the following:

See also

tobii_notifications_subscribe()

Example

See tobii_notifications_subscribe()

tobii_wearable.h

tobii_wearable.h 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.

tobii_wearable_data_subscribe

Function

Start listening for eye tracking data from wearable device, such as VR headsets.

Syntax

#include <tobii/tobii_wearable.h>
tobii_error_t tobii_wearable_data_subscribe( tobii_device_t* device,
    tobii_wearable_data_callback_t callback, void* user_data );

Remarks

All coordinates are expressed in a left-handed Cartesian system.

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

callback is a function pointer to a function with the prototype:

void wearable_callback( tobii_wearable_data_t const* data, void* user_data )

This function will be called when there is new data available. It is called with the following parameters:

user_data custom pointer which will be passed unmodified to the callback function.

Return value

If the operation is successful, tobii_wearable_data_subscribe() returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_wearable_data_subscribe returns one of the following:

See also

tobii_wearable_data_unsubscribe(), tobii_process_callbacks()

Example

#include <tobii/tobii_wearable.h>
#include <stdio.h>
#include <assert.h>

void wearable_callback( tobii_wearable_data_t const* wearable,
    void* user_data )
{
    if( wearable->left.gaze_direction_validity )
    {
        printf( "Left gaze direction: (%f, %f, %f)\n",
            wearable->left.gaze_direction_normalized_xyz[ 0 ],
            wearable->left.gaze_direction_normalized_xyz[ 1 ],
            wearable->left.gaze_direction_normalized_xyz[ 2 ] );
    }
    else
        printf( "Left gaze direction: INVALID\n" );

    if( wearable->right.gaze_direction_validity )
    {
        printf( "Right gaze direction: (%f, %f, %f)\n",
            wearable->right.gaze_direction_normalized_xyz[ 0 ],
            wearable->right.gaze_direction_normalized_xyz[ 1 ],
            wearable->right.gaze_direction_normalized_xyz[ 2 ] );
    }
    else
        printf( "Right gaze direction: INVALID\n" );
}

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_wearable_data_subscribe( device, wearable_callback, 0 );
    assert( error == TOBII_ERROR_NO_ERROR );

    int is_running = 1000; // in this sample, exit after some iterations
    while( --is_running > 0 )
    {
        error = tobii_wait_for_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR || error == TOBII_ERROR_TIMED_OUT );

        error = tobii_process_callbacks( device );
        assert( error == TOBII_ERROR_NO_ERROR );
    }

    error = tobii_wearable_data_unsubscribe( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_device_destroy( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );
    return 0;
}

tobii_wearable_data_unsubscribe

Function

Stops listening to the wearable data stream that was subscribed to by a call to tobii_wearable_data_subscribe().

Syntax

#include <tobii/tobii_wearable.h>
tobii_error_t TOBII_CALL tobii_wearable_data_unsubscribe( tobii_device_t* device );

Remarks

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

Return value

If the operation is successful, tobii_wearable_data_unsubscribe() returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_wearable_data_unsubscribe returns one of the following:

See also

tobii_wearable_data_subscribe()

tobii_get_lens_configuration

Function

Retrieves the current lens configuration in the tracker.

Syntax

#include <tobii/tobii_wearable.h>
tobii_error_t TOBII_CALL tobii_get_lens_configuration( tobii_device_t* device,
    tobii_lens_configuration_t* lens_config );

Remarks

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

lens_config must be a pointer to a valid tobii_lens_configuration_t. Upon success, it will be populated with the relevant data. It will remain unmodified upon failure. It is a pointer to a struct containing the following data:

Return value

If the operation is successful, tobii_get_lens_configuration() returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_get_lens_configuration returns one of the following:

See also

tobii_set_lens_configuration()

Example

#include <tobii/tobii_wearable.h>
#include <stdio.h>
#include <assert.h>

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_lens_configuration_t lens_config;
    error = tobii_get_lens_configuration( device, &lens_config );
    assert( error == TOBII_ERROR_NO_ERROR );

    printf( "VR lens offset (left): (%f, %f, %f)\n",
        lens_config.left_xyz[ 0 ],
        lens_config.left_xyz[ 1 ],
        lens_config.left_xyz[ 2 ] );

    printf( "VR lens offset (right): (%f, %f, %f)\n",
        lens_config.right_xyz[ 0 ],
        lens_config.right_xyz[ 1 ],
        lens_config.right_xyz[ 2 ] );

    error = tobii_device_destroy( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );
    return 0;
}

tobii_set_lens_configuration

Function

Sets the current lens configuration in the tracker.

Syntax

#include <tobii/tobii_wearable.h>
tobii_error_t TOBII_CALL tobii_set_lens_configuration( tobii_device_t* device,
  tobii_lens_configuration_t const* lens_config );

Remarks

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

lens_config must be a pointer to a valid tobii_lens_configuration_t. Upon success, the values have been written to the tracker. They should correspond to the physical attributes of the headset that they represent.

Return value

If the operation is successful, tobii_get_lens_configuration() returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_get_lens_configuration returns one of the following:

See also

tobii_get_lens_configuration()

Example

#include <tobii/tobii_wearable.h>
#include <stdio.h>
#include <assert.h>

int main()
{
    tobii_api_t* api;
    tobii_error_t error = tobii_api_create( &api, NULL, NULL );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_device_t* device;
    error = tobii_device_create( api, NULL, &device );
    assert( error == TOBII_ERROR_NO_ERROR );

    tobii_lens_configuration_writable_t writable;
    error = tobii_lens_configuration_writable( device, &writable );
    assert( error == TOBII_ERROR_NO_ERROR );

    if( writable == TOBII_LENS_CONFIGURATION_WRITABLE )
    {
        tobii_lens_configuration_t lens_config;
        //Add 32 mm offset for each lens on the X-axis
        lens_config.left_xyz[ 0 ] = 32.0;
        lens_config.right_xyz[ 0 ] = -32.0;

        lens_config.left_xyz[ 1 ] = 0.0;
        lens_config.right_xyz[ 1 ] = 0.0;

        lens_config.left_xyz[ 2 ] = 0.0;
        lens_config.right_xyz[ 2 ] = 0.0;

        error = tobii_set_lens_configuration( device, &lens_config );
        assert( error == TOBII_ERROR_NO_ERROR );
    }
    else
        printf( "Unable to write lens configuration to tracker\n" );


    error = tobii_device_destroy( device );
    assert( error == TOBII_ERROR_NO_ERROR );

    error = tobii_api_destroy( api );
    assert( error == TOBII_ERROR_NO_ERROR );
    return 0;
}

tobii_lens_configuration_writable

Function

Query the tracker whether it is possible to write a new lens configuration to it or not.

Syntax

#include <tobii/tobii_wearable.h>
tobii_error_t TOBII_CALL tobii_lens_configuration_writable( tobii_device_t* device,
    tobii_lens_configuration_writable_t* writable );

Remarks

device must be a pointer to a valid tobii_device_t instance as created by calling tobii_device_create or tobii_device_create_ex.

writable must be a pointer to a valid tobii_lens_configuration_writable_t.

On success, writable will be assigned a value that tells whether the tracker can write a new lens configuration. TOBII_LENS_CONFIGURATION_WRITABLE if it is writable and TOBII_LENS_CONFIGURATION_NOT_WRITABLE if not.

Return value

If the operation is successful, tobii_lens_configuration_writable() returns TOBII_ERROR_NO_ERROR. If the call fails, tobii_lens_configuration_writable returns one of the following:

See also

tobii_get_lens_configuration(), tobii_set_lens_configuration()