For more complex display such as screens of text or pictures, drawing takes too long to complete in one (or even two) display refresh periods. This makes the drawing process visible, and there is no clear stimulus onset for reaction time measurement. The code in the text template draws to a bitmap, then copies it to the display, reducing the time to make the display visible. This also has the advantage of making the trial code more general: almost any stimulus can be displayed given its bitmap.
These are the files used to build text. Those that are the same as for simple are marked with an asterisk. (Standard EyeLink Developers Kit header files are the same as those used for simple, and are not listed here).
main.c | WinMain() function for windows non console compilation and main() for other compilations, setup and shutdown link and graphics, open EDF file. |
trials.c | Called to run a block of trials for the "text" template. Performs system setup at the start of each block, then runs the trials. Handles standard return codes from trials to allow trial skip, repeat, and experiment abort. This file can be modified for your experiments, by replacing the trial instance code. |
trial.c | Implements a trial with simple graphics that can be draw in one screen refresh, and therefore doesn't need display blanking. You should be able to use this by replacing the drawing code, message code, and handling any participant responses. |
The only difference in the main.c is the inclusion of "text.h" header file, instead of "simple.h" in the previous example. The block loop and trial setup code (trials.c) and the trial loop code (trial.c) are also changed. The latter two files will be discussed below, but here is an outline of the differences from the equivalent files for simple:
The discussion of trial.c is especially important, as it forms the basis of later templates that use bitmaps.
The function do_text_trial()
is used to setup and run the text-reading trials. This first creates an SDL_Surface and calls graphic_printf()
with the long text and alignment parameters. Following this, the bitmap_save_and_backdrop()
function saves the entire bitmap as a file in the specified path ("images"), and transfers the image to the tracker PC as backdrop for gaze cursors. Note that you can manipulate the file-saving option of the function so that the existing files could be either overwritten (set the sv_options as 0) or not to be overwritten (SV_NOREPLACE). The trial title and "TRIALID" message report the page number (and thus the progress of the experiment). The "!V TRIAL_VAR" message is recorded to report a trial variable and value for the given trial when analyzing data with EyeLink Data Viewer.
char *pages[4] = { text1, text2, text3, text4 };// Given trial number, execute trials Returns trial result codeint do_text_trial(int num){SDL_Surface *bitmap = NULL;int i;char image_fn[100]; // image file name;// Must be offline to draw to EyeLink screeneyecmd_printf("clear_screen 0");// This supplies the title at the bottom of the eyetracker displayeyecmd_printf("record_status_message 'TEXT, PAGE %d/%d' ", num, NTRIALS);// Always send a TRIALID message before starting to record.// It marks the start of the trial and should precede any other messageseyemsg_printf("TRIALID PAGE%d", num);// !V TRIAL_VAR message is recorded for EyeLink Data Viewer analysis// It specifies a trial variable and value for the given trial// This must be specified within the scope of an individual trial (i.e., after// "TRIALID" and before "TRIAL_RESULT")eyemsg_printf("!V TRIAL_VAR page %d", num);sprintf(image_fn, "test%d.png", num); // get the image file name// IMGLOAD command is recorded for EyeLink Data Viewer analysis// It displays a default image on the overlay mode of the trial viewer screen.// Writes the image filename + path infoeyemsg_printf("!V IMGLOAD FILL %s", image_fn);get_new_font(NULL, SCRHEIGHT/25, 0);bitmap = SDL_CreateRGBSurface(SDL_SWSURFACE,SCRWIDTH, SCRHEIGHT,dispinfo.bits,0,0,0,0);set_margin(SCRWIDTH/20,SCRHEIGHT/20,SCRWIDTH/20,SCRHEIGHT/20);set_line_spacing(((double)(SCRHEIGHT)/15.0)/(double) get_font_height());SDL_FillRect(bitmap,NULL,SDL_MapRGB(bitmap->format, target_background_color.r, target_background_color.g, target_background_color.b));graphic_printf(bitmap,target_foreground_color,WRAP,0,0,pages[num-1]);// Save bitmap and transfer to the tracker pc.// Since it takes a long to save the bitmap to the file, the// value of sv_options should be set as SV_NOREPLACE to save timebitmap_save_and_backdrop(bitmap, 0, 0, 0, 0, image_fn,get_output_folder(),SV_NOREPLACE, 0,0, BX_NODITHER|BX_GRAYSCALE);i = bitmap_recording_trial(bitmap, 20000L);SDL_FreeSurface(bitmap);return i;}
Finally, the bitmap is passed to bitmap_recording_trial()
for the actual recording. After recording is completed, the bitmap is deleted. That's all there is to it - the same trial function can be used to present almost any stimulus drawn to the bitmap.
The function bitmap_recording_trial()
performs straightforward recording and presentation of bitmaps. The code is almost identical to simple_recording_trial()
, except that drawing of text is replaced by copying the bitmap to the display.
// COPY BITMAP to the back bufferSDL_BlitSurface(gbm,NULL,window, NULL);// asynchronously flip flip does not return till the next retraceFlip(window);trial_start = current_msec();SDL_BlitSurface(gbm,NULL,window, NULL);display_time = current_msec() - trial_start;