The EyeLink system and this Developers Kit are based on experience gained through actual research in diverse areas, including saccadic tasks, smooth pursuit, reading, and gaze contingent displays. This experience makes it possible for SR Research to write this manual aiming at providing the knowledge required for programmers to write the desired experiment program that produces valid experiment data. This toolkit contains samples for a variety of experiments, and the EyeLink Developers Kit library is designed to simplify implementation of almost any experimental task.
In addition, SR Research has studied each platform to which the EyeLink Developers Kit has been ported, and has determined the best way to present graphics, control program flow, and to achieve reproducible timing. This manual and the included example source code will help you to write experiments without spending hundreds of hours in reading books and testing different methods. However, some knowledge of graphic programming and of the C language is required.
A typical experiment using the EyeLink eye tracker system will use some variation of the following sequence of operations:
|
For each trial, the experiment will do the following steps:
|
This sequence of operations is the core of almost all types of experiments. A real-world experiment would probably add practice trials, instruction screens, randomization, and so on.
During recording, all eye-tracking data and events are usually written into the EDF file, which is saved on the eye tracker's hard disk, and may be copied to the Display PC at the end of the experiment. Your experiment will also add messages to the EDF file which to identify trial conditions and to timestamp important events (such as participant responses and display changes) for data analysis. The EDF file may be processed directly using the EyeLink Data Viewer application, or converted to an ASC file and processed with your own software.
Several simple experiments are included in the EyeLink Developers Kit, including all source code. These experiments will be discussed in detail throughout this manual. Each is an example of the basic operations needed to implement the most useful eye-tracking research: simple and complex static and dynamic displays, on-line data playback, real-time data transfer, gaze-contingent displays, and gaze-controlled computer interfaces.
For now, we will go through the simplest of the demonstration experiments included in the EyeLink Developers Kit, called simple. This includes four trials, each of which prints a single word at the center of the display. Start the EyeLink tracker, then go to the C:\Users\Public\Documents\EyeLink\SampleExperiments\sdl\simple folder and execute simple on the Display PC. The program first asks for a file name for the EDF file that will be created on the EyeLink Host computer's hard disk. Enter 1 to 8 characters from the keyboard for the EDF file name. You may press "Esc" or click "Cancel" if you do not want to keep the EDF file (all recorded data will be discarded).
The Windows display then blanks, and the tracker displays the camera setup screen. From this screen, the experimenter can perform camera setup, calibration, and validation. These may be practiced with the track application included with the EyeLink Developers Kit. Instructions for the camera setup, calibration and validation are included in the EyeLink User Manual. All data collection and messaging operations are implemented by eyelink_core.dll and all other graphic operations, such as calibration, validation, and display of the eye image on the Display PC, are implemented by the eyelink_core_graphics.dll.
When the eye tracker has been set up and the participant calibrated, press the 'Esc' key on either the EyeLink PC or the Display PC to exit the camera setup mode. The experiment will immediately proceed to the first trial, and display a drift correction fixation target. Press the space bar on the Display PC or EyeLink tracker while fixating the target to perform the drift correction. Pressing the 'Esc' key during drift correction will switch the tracker to the camera setup screen to re-calibrate or correct setup problems. Drift correction will resume after the camera setup screen is exited with the 'Esc' key.
The screen now shows the stimulus for the first trial, a small text message. The tracker displays the participant's gaze position, overlaid on graphics indicating the stimulus position. Press a button on the EyeLink button box, or press the 'Esc' key on the Display PC keyboard to end the trial. The experiment will immediately proceed to the next trial. You may also hold down the 'Ctrl-C' key combination or press 'ALT-F4' on the Display PC to terminate trials and the experiment.
After the final trial, you will be prompted for a local name for the EDF file recorded during the experiment. Unless you press the 'Esc' key or select "Cancel", the file will be transferred from the EyeLink computer to the Display PC. The experiment then disconnects from the tracker and exits.
The width and height parameters should be used together to override the default screen resolution (which uses the current display settings). The tracker parameter allows the user to use an alternative address for the tracker. The default address for the tracker is 100.1.1.1.
The interaction of the EyeLink tracker and your experiment is fairly sophisticated: for example, in the camera setup mode it is possible to perform calibration or validation, display a camera image on the Display PC to aid participant setup, and record data with the experiment following the display of relevant graphics. Large files can be transferred over the link, and should the EyeLink tracker software terminate, the experiment application is automatically terminated as well. Keys pressed on the Display PC keyboard are transferred to the EyeLink PC and operate the tracker during setup. The buttons pressed on the tracker button box may be used to control the execution of the experiment on the Display PC.
All of these operations are implemented through the eyelink_core DLL library. Each of the above operations required just one line of code in your program. Almost all of the source code you'll write is for the experiment itself: control of trials, presentation and generation of stimuli, and error handling.
Some of the features in the EyeLink Developers Kit library are:
A complete list of EyeLink Developers Kit routines are grouped into functional groups and given below.
Programmers may also want to look at the eyelink.h, core_expt.h, gdi_expt.h, sdl_expt.h and sdl2_expt.h C header files in the SR Research\Eyelink\Includes\eyelink directory.
The eyelink_core DLL library handles the details of interfacing to the eye tracker, and of performing tasks such as calibration and setup. Its internal millisecond and microsecond clocks solve the problem of timekeeping for experiments. The major remaining problem for programmers is the proper display of stimuli.
The eyelink_core_graphics DLL library is built on top of SDL and associated libraries. This allows the user to get the best graphics performance on a given system and still it is simple to use. For example, in windows, SDL wraps DirectX. This allows the user to use hardware-accelerated blit and flip. The hardware assisted blit can be much faster than a software blit. For example, a full screen blit at 1920 x 1080 x 32 in a decent video card can be performed in less than a few milliseconds, whereas the same operation may take up to 100 milliseconds in a software blit. SDL provides hardware flips if the configuration environment allows it. The hardware flip can be used to pinpoint the exact time when the display is made visible to the participant. In addition, SDL supports alpha blending and color keys.
With SDL graphics, the exact time the display is modified can be recorded by sending a time stamped message to the eye tracker when drawing is completed. Some of the uncertainty caused by the delay between drawing and display on the monitor may be removed by waiting for the start of the monitor's refresh before drawing. However, we do not know how long to wait for the next refresh. So, Eyelink SDK modified the original SDL library to provide a new API function SDL_FlipEx(). This will not return till the real next retrace. That is, this function will return as soon as the image is displayed on the screen.
To accurately mark the time of onset, we need to place a display onset message in the EDF file. The method we will use in our examples is fast, accurate, and can be used with any drawing method that is sufficiently fast (including bitmap display, as we will see next). This technique requires the following steps:
The best method in SDL for rapidly displaying complex graphics at the start of the trial is to use an SDL Surface that is initialized with SDL_CreateRGBSurface(). This is like an invisible display stored in memory, which can be used to draw images, and write texts. Most of the experiments (except the "Simple" template) use this mechanism to display images and texts on the screen.
Once the stimulus has been drawn to an SDL Surface, it can be rapidly blitted to the display, if the video driver supports hardware acceleration, you will be able to blit full screens to the display in less than 3 msec in a decent video card. For most video cards and display resolutions, this can be done in much less than one refresh period (1000ms/refresh rate).