When just getting started with the SDK you may skip this section for now and come back when done playing.

The following describes the actions to be performed by your application in order to setup the eye-tracker and collect eye-tracking data.

  1. Call eyevec_create() to create an (opaque) EyeVec structure.

  2. Either call eyevec_create_thread() to create an event queue monitoring thread, or call eyevec_create_waitable() to create a waitable event queue descriptor (to pass to your application’s event-loop wait function). More on this below.

  3. Call eyevec_initialize() to setup communication with the eyevec-control application.

  4. Call eyevec_open() to open the device.

  5. Perform configuration as far as necessary (select which events to receive, query and/or alter settings if desired, select whether to show/hide the user-interface automatically, etc.).

  6. Optionally call eyevec_open_data_file() in order to save calibration results etc. and eye-tracking data to an EyeVec data file.

  7. When ready to position the participant and to run a calibration, call eyevec_enter_setup_mode(). The eyevec-control user-interface will come up automatically if configured so, otherwise you need to call eyevec_show_control_window() explicitly. Then from the eyevec-control user-interface:

    1. Adjust participant features if necessary.

    2. Check/adjust other settings if desired.

    3. Run the baseline procedure. Repeat if necessary.

    4. Run the calibration procedure and check results. Repeat if necessary.

    5. Run the validation procedure and check results. Repeat if necessary.

    6. Use the Proceed button to signal your application the setup is done. Depending on the configuration the eyevec-control user-interface may become hidden. The eye-tracker has now entered data mode.

  8. For each (non-filler) stimulus presentation trial do the following:

    1. If a drift-check target is to be presented ahead of the stimulus, call eyevec_start_drift_check(). Wait until the drift-check procedure has completed (tracker mode will go from drift-check mode back to data mode) and proceed with recording and stimulus presentation as listed below. Note, if you want to to inspect the drift-check result call eyevec_get_drift_check_result().

    2. To start recording eye-tracking data call eyevec_start_recording(). The data will be available via events (if requested) and/or be saved to file (if requested).

    3. Start the actual stimulus presentation.

    4. To stop eye-tracking data call eyevec_stop_recording().

  9. To do a recalibration, between blocks of trials for example, just call eyevec_enter_setup_mode() again as described above (point 7).

  10. Finally call eyevec_close() to close the device.

  11. Call eyevec_cleanup() to terminate communication with the eyevec-control application.

  12. Call eyevec_destroy_thread() or eyevec_destroy_waitable() depending on whether you used the threaded or waitable interface.

  13. Call eyevec_destroy() to destroy the EyeVec structure.

The threaded v.s. waitable interface

The SDK offers two methods for receiving events from the eye-tracker, known throughout this manual as the threaded interface and the waitable interface.

Threaded

When using the threaded interface, initiated by calling eyevec_create_thread(), a thread will be created that monitors the eye-tracker’s event queue and calls the event specific callback functions as registered by your application.

This is very convenient to use as it does not require you to explicitly retrieve events from the event queue. Providing the appropriate callback functions is enough.

The downside is that the callback functions are called from the thread which means that interacting with the application from a callback function will require the use of a synchronization primitive such as a mutex.

Waitable

When using the waitable interface, initiated by calling eyevec_create_waitable(), an event queue descriptor (aka handle) will be created that can be watched by your application’s event-loop wait function (e.g. poll(2), select(2), WaitForSingleObject(), WaitForMultipleObjects()).

In this approach the descriptor will become ready as soon as there’s data in the eye-tracker’s event queue. Once the application notices the readiness of the descriptor eyevec_retrieve_event() should be called to retrieve the event from the queue. This event can be passed to a handler function which, if you like, could dispatch the event to an event specific event handling function (just as in the threaded case). When done with the event eyevec_release_event() should be called.

This method can be employed in any event-driven application that provides means to register a descriptor to be watched.