SR Research Support Site
Eyelink Graphics Programming Using External Graphics Library

The plug-in design of new graphic component in the eyelink_core makes it possible for programmers to take advantage of any graphics environment that they have to use. Suppose we have a complex three-dimensional graphics to display to the participant. SDL may not be the greatest platform to perform such graphics. In this case, the user is not forced to use SDL as their development platform. EyeLink Developers Kit allows the user to create their own graphics development platform with their choice of graphics library. In addition, one can override an existing library's callback function to overcome a bug or to suit their needs.

If the user decides to implement his own graphics environment, the following needs to be done to set up the display environments for graphic operations, such as calibration, validation, and display of the eye image.

Roles of EyeLink Graphics library

There are three things that an EyeLink graphics library should do.

  1. Display calibration, validation, drift correct, and camera image screens on the display pc.
  2. Save display screens to disk for future analysis. This may be optional.
  3. Provide feedback about any input given by the user.

To achieve the duties of eyelink core graphics library, we use a generic set of callback functions. The callback functions are set and get using the structure HOOKFCNS in combination with the functions setup_graphic_hook_functions() and get_all_hook_functions(). The following structures are also used to support various aspects of the core graphics library.

  1. InputEvent
  2. HOOKFCNS
  3. EYECOLOR
  4. EYEPALETTE
  5. EYEPIXELFORMAT
  6. EYEBITMAP

Except for the InputEvent and HOOKFCNS structures, all other structures are used to transfer image data to the core graphics library to save images to disk.

Writing Your Own Core Graphics.

EyeLink Developers Kit comes with a plug-in template that you can use as starting point(C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\sdl\Extension\plugin). The plugin template also comes with project files that are intended for a dll. If you would like to use the template within your program, you may want to convert the project to an application.

SDL Core Graphics Sample

In this section we are going to go over a sample implementation of core graphics library. The source code and the project files can be found in C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\sdl\Extension\sdl_coregraphics.

File description of cal_graphics.c

This file implements Calibration Target Presentation Example and the Source code for cal_graphics.c can be viewed here. In most cases this is by far the most easiest to implement. This file includes implementation of target presentation as well as optional audio presentation, which may improve the speed and stability of calibrations by cueing the participant and make the experimenter's task easier.

If you do not need audio presentation you can safely set the following functions to NULL.

HOOKFCNS fcns;
memset(&fcns,0,sizeof(fcns));
fcns.cal_done_beep_hook = NULL;
fcns.dc_done_beep_hook = NULL;
fcns.dc_target_beep_hook = NULL;

In our implementation, for function, cal_target_beep(), cal_done_beep(), dc_target_beep(), dc_done_beep() just call the function cal_sound(). Both cal_target_beep() and cal_done_beep() will be called on calibration or validation procedure in the call to do_tracker_setup() while both the dc_target_beep() and dc_done_beep() will be called on drift correct procedure in the call to do_drift_correct().

The following functions implement the graphics presentation of calibration target.

In our implementation, we did not need to do anything in setup_cal_display(). So, in turn we did not do anything in exit_cal_display(). Both of these functions can be used to initialize and release resources that are needed with in a calibration session. For example, if you need to use a customized target, that use an SDL Surface, then you would initialize it in the setup_cal_display() and release it in exit_cal_display().

In the function draw_cal_target(), we draw the target at the requested location. The function clear_cal_display(), clears the entire screen. Since we did not use any fancy background, we implemented erase_cal_target() so that it clears the entire screen.

File description of cam_graphics.c

This file implements Calibration Camera Image Presentation Example and the Source code for cam_graphics.c can be viewed here.

In this file all camera setup features are implemented. If no camera setup features are needed, you can safely set the following callback functions to NULL.

HOOKFCNS fcns;
memset(&fcns,0,sizeof(fcns));
fcns.image_title_hook = NULL;

In our example, we implemented all the camera image functions except the image_title_hook.

For the implementation setup_image_display(), we create an RGB surface to hold the camera image. On the exit_image_display() we release the surface.

The draw_image_line() and set_image_palette() together make up the camera image. Once all the image lines are gathered, we draw the cross hair and display the image.

File description of graphics_main.c

All functions implemented in this file are miscellaneous functions except for get_input_key(). The Source code for graphics_main.c can be viewed here.

The get_input_key() provides eyelink_core.dll key events. The special keys and modifiers need to be set properly using eyelink's key value for the proper function of keyboard events. If this function is not implemented, you will not be able to control the tracker from Display PC.

The writeImage() writes the given images to disk. If you do not call el_bitmap_save_and_backdrop or el_bitmap_save, this can be ignored. Also, note this function is not set using the standard setup_graphic_hook_functions() to set the callback.

All the other functions are completely optional, however, see the implementation of init_expt_graphics() where we make calls to setup_graphic_hook_functions() to set the callbacks.


Copyright ©2002-2023, SR Research Ltd.