SR Research Support Site
Programming Experiments

Programmers are strongly recommended to read this section carefully, and follow given instructions. Doing so will prevent future problems with upgrading to new development kit releases, and will make your experiments easier to modify in the future.

Important Programming Notes

The header files in this toolkit should never be modified, and only copies of the source files should be changed. Some files are designed as templates for creating your own experiments. These should be copied as new files in a new folder before being modified. If problems are found with any other files, contact SR Research Ltd. before making changes.

DO NOT under any circumstances edit or combine the header files. This will make future upgrades of the toolkit or EyeLink functions impossible. SR Research Ltd. will not support any code written in this way. It is important for researchers to supervise their programmers to prevent unsupportable software from being developed.

You should try to preserve the functionality of each source file from the examples while developing new experiments. Make as few changes as possible, and do not reorganize the files in any way. This code will be updated regularly, and you will be responsible for making any required changes to your modified files. If proper care is taken, file comparison utilities can be used to help find the differences. However, this will only work if the order of functions in the source code is not preserved, and if there is a match between functions in the old and new source files.

Programming Tools and Environment

The templates in this toolkit were programmed with Microsoft Visual Studio 2015. Simply click on .sln to open the project and build the sample experiments. Modifications to the project settings are expected if you are using other compilers.

Starting a New Project

The source code for each sample experiment template's project is stored in a folder in the C:\Users\Public\Documents\EyeLink\SampleExperiments\sdl\shared folder. The easiest way to start a new experiment is to copy all files from the project and the library folder together: this will prevent inadvertently editing the header files influencing your project. To create a new working copy:

Once an experiment has been developed, it will be almost certain that you will need to produce several variations of it. You should duplicate and rename the original project's folder for each new version of the project, to prevent older versions from being overwritten. This is also the safest way of backing up your work during development, as older versions can still be tested.

Building a New Project

Guide is given for building a new Visual Studio 2015 project.

Using Visual Studio 2015

Using Visual Studio 2015 to build a new project (add files, find header files, and link to static libraries) should follow the same steps as using Visual Studio 2008. The only difference is that directories editing in Tools > Options has been deprecated in Visual Studio 2015. In order to set paths for all projects, a user property sheet can be added to all projects. Though adding paths to each project separately is recommended for this case. Migrating solution files from Visual studios 2008 to Visual Studio 2015 is not required and Visual Studio 2015 solution files are provided in the Sample directories.

Building 64-bit applications in Visual Studio2008 and 2015

For editions other than Visual Studio 2008 Standard Edition or Visual Studio 2008 Shell, you may need to change the configuration of Visual Studio to add 64-bit support.

Steps can be followed to check or add 64-bit support to Visual Studio 2008:

In addition , please note that "64-bit tools are not available on Visual C++ Express by default. To enable 64-bit tools on Visual C++ Express, install the Windows Software Development Kit (SDK) in addition to Visual C++ Express."

Configure Visual C++ Projects using Visual Studio 2015 to Target 64-Bit Platforms

Please note that only Release configuration is provided in the solution, however you can copy the release configuration to Debug to build as well. Provided solution file (eg. sdlexamples2015.sln for SDL examples, sdl2examples2015.sln for SDL2 examples or gdiexsamples2015.sln for GDI examples , can be opened in VS2015 and it will load all the sample experiments from respective folder. Each projects can be build separately or all at once by building the entire solution.

When you return to the Properties dialog box, the "Platform" drop-down should now read "x64."

From Visual Studio 2015, either all the projects can be build by building the whole solution or each of the projects can be build separately. Also, each sample project has it's corresponding VS2015 project file with the extension .vcxproj and the postfix of the name also indicates _vs2015. By opening this project file directly into Visual Studios also will create a solution file for that project. This way, a sample experiment project can be copied and modified to fit for the new project.

Planning the Experiment

Before beginning the implementation of a new experiment, be sure that the overall design of the experiment is clear. Be aware of how each trial is to be terminated, and what the important display elements of each trial are. If randomization is to be built into the experiment, understand how it is to be produced.

In many cases, the experiment will need to be developed in several stages, starting from a basic trial, which will be used to refine timing and graphics. After initial testing, the design can be refined to create the final experiment. However, the requirements for the basic trial will probably not change.

The most important points to determine before beginning a project are:

Developing and Debugging New Experiments

The quickest way to develop a new experiment is to start with one of the experiment templates, and create a single trial. You may want to place your graphics code in a function, and call it directly instead of from within a trial, to simplify development.

Begin by implementing the graphics for a typical trial, as these are the most time-critical element. Read the time from current_msec() or current_usec() before and after drawing, in order to compute total drawing time. Note that many profiling tools may not give the correct results when measuring the timing of graphics calls, due to context switches in the Windows kernel. In fact, running under a debugger will almost certainly disable real-time mode, so once the graphics seem to be working run the application using the "execute" command or outside the Visual Studio environment to measure delays.

At this stage of development, you do not need a participant or even the EyeLink tracker to develop and test your code. There are two ways to simplify development, while retaining the use of the EyeLink support functions and timing.

Simulated Link Mode

The link connection can be simulated for early development work, or when the EyeLink tracker is not available. By calling open_eyelink_connection() with an argument of 1 instead of 0, your program will not attempt to connect to the EyeLink tracker, but simply initializes the eyelink_core library. Try this with one of the sample programs, and note that 'Esc' exits the camera setup mode as usual, while the spacebar can be used for drift correction and 'Esc' can be used to end trials.

In the simulated mode, all the millisecond and microsecond timing functions are available for benchmarking the graphics. Most EyeLink commands will return a plausible result in the simulation mode, except that real-time data is not available from the link. Your code can test if the link is simulated by calling eyelink_is_connected() as usual. This will return -1 instead of 1 indicating that the connection is simulated.

Mouse Simulation Mode

When real data is needed for development, or recording is needed to test the inclusion of data messages, you can still work without a participant. Change the argument to calling open_eyelink_connection() back to 0, and restart the EyeLink tracker in mouse-simulation mode (Toggle the "Mouse Simulation" button in the Set Options screen for EyeLink II, 1000, or 1000 Plus; not supported on EyeLink Portable Duo). This allows you to run the experiment with all eye tracking and button functions available, but without the need to set up and monitor a participant. All tracker functions (except camera image display) are available in mouse mode, including EDF file recording, calibration, drift correction and realtime data.

You can skip calibrations in this mode (press 'Esc' as soon as the display blanks on the Display PC and the EyeLink display shows the calibration menu), or allow the tracker to automatically step through the calibration sequence. Use the Host PC's mouse to simulate gaze during recording, by moving the cursor into the gaze window of the Host PC, and clicking the left mouse button to produce a "saccade" to this position. Hold the left mouse button down to continuously move the point of gaze. A blink is produced when the right mouse button is held down.

Once the experiment has been debugged using the mouse, test the program with yourself and at least with one other person as a participant. This will help to identify any problems such as flickers in the display, problems with graphics, or problems with the experimental design. Be sure to analyze the resulting data files at this point (e.g., using EyeLink Data Viewer), to detect problems such as missing data or messages.

Converting Existing Experiments

Read this section if you are porting existing non-eye tracking experiments to EyeLink. The EyeLink Developers Kit was designed to simplify the procedure of adding eye movement analysis to existing experiments. This involves adding calls to perform setup and drift correction, start and stop recording, and adding messages to record trial data. Modular code with separate functions for trials and blocks will make the conversion easier: you should split up functions that have more than 200 lines, and separate out randomization, graphics, and data recording code into separate functions.

In addition, any special timing code in your experiment should be replaced with calls to the EyeLink current_msec() function. You don't need to use timer toolbox functions directly. Replace any special code for user input with calls to the eyelink_last_button_press() function, which detects the presses of the eye tracker buttons. These buttons are logged directly into the EDF file. You should never use the keyboard for participant response in reaction-time experiments, as the delays introduced by the operating system are highly variable.

Modify your trials to perform a drift correction at their start instead of displaying a fixation point. Ideally, you should separate the drawing code from the old experiment and include it in a new function. Then call it from within the recording loop, or draw into a bitmap before the trial begins. Finally display the drawing during the trial (as in the cases of most other example templates). You can make any display changes required for animation or masking from within the recording loop and draw directly to the display.

Most non-eye tracking experiments create an output file and write the results of each trial into this file. Instead, you should write this data into the EDF file by sending data messages using eyemsg_printf(). This will integrate eye data, experiment events, and participant responses in the same file. Place trial condition data in a "TRIALID" message before the start of the trial, and end each trial with a "TRIAL OK" message. Send messages to mark display onset or display changes, and to record participant responses. Compute the reaction time by analyzing the EDF file later. If you must analyze eye-movement data on-line (for example, to give feedback to the participant), play back the last trial (as in playback_trial.c of the eyedata template) rather than trying to analyze data during recording.


Copyright ©2002-2024, SR Research Ltd.