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.
There are three things that an EyeLink graphics library should do.
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.
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.
EyeLink Developers Kit comes with a plug-in template that you can use as 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.
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.
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.
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.
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.
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.
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.