Eyelink Programmer's Guide
Total Page:16
File Type:pdf, Size:1020Kb
EyeLink Programmer’s Guide Version 3.0 Copyright ©2006, SR Research Ltd. Contents 1 Introduction 1 1.1 Organization of This Document ............................... 1 2 Getting Started 3 2.1 Upgrading to ELSDK with GDI graphics .......................... 3 2.2 Using ELSDK with SDL graphics .............................. 4 3 Overview of Experiments 5 3.1 Outline of a Typical Windows Experiment .......................... 5 3.2 EyeLink Operation in Experiments .............................. 6 3.3 Features of the ELSDK Library ................................ 7 3.4 Displays and Experiments .................................. 9 4 Programming Experiments 11 4.1 Important Programming Notes ................................ 11 4.2 Programming Tools and Environment ............................ 11 4.3 Starting a New Project .................................... 12 4.4 Planning the Experiment ................................... 12 4.5 Developing and Debugging New Experiments ........................ 13 4.6 Converting Existing Experiments ............................... 14 5 Developer’s Toolkit Files 15 5.1 Libraries and Files ...................................... 15 6 EyeLink Programming Conventions 17 6.1 Standard Messages ...................................... 17 7 EyeLink Data Types 19 7.1 Basic Portable Data Types .................................. 19 7.2 Link Data Types ........................................ 19 ii CONTENTS 8 Issues for Programming Experiments 25 8.1 Issues for DOS Programmers ................................. 25 8.2 Issues for Windows Programmers .............................. 25 8.3 Windows Timing Issues .................................... 26 8.4 Hardware I/O under Windows ................................ 27 8.5 Message Pumps and Loops .................................. 28 8.6 Windows Key Support .................................... 28 8.7 Terminating the Program ................................... 29 9 Graphics Programming using SDL 31 9.1 Resolutions and Colors .................................... 32 9.2 Drawing Speed ........................................ 32 9.3 Display Mode Information .................................. 32 9.4 Adapting to Display Resolutions ............................... 33 9.5 Synchronization with Display Refresh ............................ 33 9.6 Full-Screen Window ..................................... 33 10 Graphics Programming using GDI 35 10.1 Displays and Experiments .................................. 35 10.2 Graphics Modes ........................................ 37 10.3 Full-Screen Window ..................................... 40 10.4 Windows Graphics Fundamentals .............................. 41 10.5 Drawing With Bitmaps .................................... 43 11 Eyelink Graphics Programming Using External Graphics Library 47 11.1 Roles of EyeLink Graphics library .............................. 47 11.2 Writing Your Own Core Graphics. .............................. 48 11.3 Source code for cam_graphics.c ............................... 50 11.4 Source code for cal_graphics.c ................................ 55 11.5 Source code for graphics_main.c ............................... 59 12 Controlling Calibration 63 12.1 Calibration Colors ....................................... 63 12.2 Calibration Target Appearance ................................ 63 12.3 Calibration Sounds ...................................... 64 12.4 Recording Abort Blanking .................................. 64 13 Connections and Multiple Computer Configurations 65 13.1 Connection Types ....................................... 66 Copyright ©2006, SR Research Ltd. CONTENTS iii 13.2 Finding Trackers and Remotes ................................ 67 13.3 Inter-Remote Communication ................................ 67 14 Experiment Templates Overview 69 14.1 Template Types ........................................ 69 15 "Simple" Template 71 15.1 Source Files for "Simple" ................................... 71 15.2 Analysis of "main.c" ..................................... 72 15.3 Analysis of "trials.c" ..................................... 77 15.4 Control by Scripts ....................................... 80 15.5 Analysis of "trial.c" ...................................... 81 15.6 Drift Correction ........................................ 81 15.7 Starting Recording ...................................... 82 15.8 Starting Realtime Mode .................................... 83 15.9 Drawing the Subject Display ................................. 84 15.10Recording Loop ........................................ 85 15.11Cleaning Up and Reporting Trial Results ........................... 87 15.12Extending "trial.c" ...................................... 87 16 "TEXT" Template 89 16.1 Source Files for "Text" .................................... 89 16.2 Differences from "Simple" .................................. 89 16.3 Analysis of "trials.c" ..................................... 90 16.4 Analysis of "trial.c" ...................................... 91 17 "PICTURE" Template 93 17.1 Source Files for "Picture" ................................... 93 17.2 Differences from "Text" .................................... 93 17.3 Analysis of "trials.c" ..................................... 94 18 "EYEDATA" Template 97 18.1 Source Files for "Eyedata" .................................. 97 18.2 Differences from "Text" and "Picture" ............................ 98 18.3 Analysis of "data_trials.c" .................................. 98 18.4 Analysis of "data_trial.c" ................................... 99 18.5 Analysis of "playback_trial.c" ................................ 101 19 "GCWINDOW" Template 107 Copyright ©2006, SR Research Ltd. iv CONTENTS 19.1 Gaze-Contingent Window Issues ............................... 107 19.2 Source Files for "GCWindow" ................................ 109 19.3 Analysis of "trials.c" ..................................... 109 19.4 Other Gaze-contingent Paradigms .............................. 113 20 "CONTROL" Template 115 20.1 Source Files for "Control" .................................. 115 20.2 Analysis of "trial.c" ...................................... 115 21 "DYNAMIC" Template 121 21.1 Source Files for "Dynamic" .................................. 121 21.2 Analysis of "targets.c" .................................... 122 21.3 Analysis of "trial.c" ...................................... 124 21.4 Analysis of "trials.c" ..................................... 125 21.5 Adapting the "Dynamic" template .............................. 132 22 COMM SIMPLE and COMM LISTENER Templates 133 22.1 Source Files for "Comm_simple" ............................... 133 22.2 Analysis of "comm_simple_main.c" ............................. 134 22.3 Analysis of "comm_simple_trial.c" .............................. 136 22.4 Source Files for "Comm_listener" .............................. 136 22.5 Analysis of "comm_listener_main.c" ............................. 137 22.6 Analysis of "comm_listener_loop.c" ............................. 139 22.7 Analysis of "comm_listener_record.c" ............................ 141 22.8 Extending the "comm_simple" and "comm_listener" Templates ............... 143 23 "BROADCAST" Template 145 23.1 Source Files for "broadcast" ................................. 146 23.2 Analysis of "broadcast_main.c" ................................ 146 23.3 Analysis of "broadcast_record.c" ............................... 151 23.4 Extending "broadcast" .................................... 153 24 ASC File Analysis 155 24.1 Creating ASC files with EDF2ASC .............................. 155 24.2 Analyzing ASC Files ..................................... 155 24.3 Functions defined by "read_asc.c" .............................. 156 24.4 A Sample ASC Analysis Application ............................. 162 25 Useful EyeLink Commands 167 Copyright ©2006, SR Research Ltd. CONTENTS v 25.1 Useful EyeLink Commands .................................. 167 25.2 Calibration Setup ....................................... 168 25.3 Configuring Key and Buttons ................................. 170 25.4 Display Setup ......................................... 172 25.5 File Open and Close ...................................... 173 25.6 Tracker Configuration ..................................... 174 25.7 Drawing Commands ..................................... 176 25.8 File Data Control ....................................... 179 25.9 Link Data Control ....................................... 181 25.10Parser Configuration ..................................... 183 26 Function List 185 26.1 Initialize EyeLink Library .................................. 185 26.2 Access Local Time ...................................... 198 26.3 Access Tracker Time ..................................... 202 26.4 Setup EyeLink tracker .................................... 206 26.5 Keyboard Input Functions .................................. 215 26.6 Data file utilities ........................................ 220 26.7 Application/Thread priority control .............................. 224 26.8 Graphics display options ................................... 226 26.9 Extract extended data from samples and events ....................... 230 26.10Time stamped messages to log file .............................. 232 26.11Online velocity and acceleration calculation ......................... 233 26.12Utility function to save bitmaps ................................ 235 26.13Record control and data collection .............................. 238 26.14Accessing and reporting error messages ........................... 244