SR Research Support Site
Functions
Setup EyeLink tracker

Functions

INT16 eyelink_abort (void)
 
INT16 eyelink_start_setup (void)
 
void eyelink_set_tracker_setup_default (INT16 mode)
 
INT16 eyelink_in_setup (void)
 
INT16 eyelink_target_check (INT16 FARTYPE *x, INT16 FARTYPE *y)
 
INT16 eyelink_target_checkf (float FARTYPE *x, float FARTYPE *y)
 
INT16 eyelink_accept_trigger (void)
 
INT16 eyelink_driftcorr_start (INT16 x, INT16 y)
 
INT16 eyelink_driftcorr_startf (float x, float y)
 
INT16 eyelink_cal_result (void)
 
INT16 eyelink_apply_driftcorr (void)
 
INT16 eyelink_cal_message (char FARTYPE *msg)
 
void exit_calibration (void)
 
INT16 do_tracker_setup (void)
 
INT16 do_drift_correct (INT16 x, INT16 y, INT16 draw, INT16 allow_setup)
 
INT16 do_drift_correctf (float x, float y, INT16 draw, INT16 allow_setup)
 

Detailed Description

These methods are used to setup the EyeLink tracker such as Camera Setup, Calibration, Drift Correction, Validation, etc.

Function Documentation

INT16 do_drift_correct ( INT16  x,
INT16  y,
INT16  draw,
INT16  allow_setup 
)

Performs a drift correction before a trial.

Remarks
When the 'ESC' key is pressed during drift correction, <allow_setup> determines the result. If 1, the EyeLink Setup menu is accessed. This will always clear the display, so redrawing of hidden stimuli may be required. Otherwise, the drift correction is aborted. Calling exit_calibration() from an event handler will cause any call to do_drift_correct() in progress to return immediately. In all cases, the return code will be 27 (ESC_KEY).
Parameters
xX Position of drift correction target.
yY Position of drift correction target.
drawIf 1, the drift correction will clear the screen to the target background color, draw the target, and clear the screen again when the drift correction is done. If 0, the fixation target must be drawn by the user.
allow_setupIf 1, accesses Setup menu before returning, else aborts drift correction.
Returns
0 if successful, 27 if 'ESC' key was pressed to enter Setup menu or abort.

Example:

1 // This program illustrates the use of do_drift_correction with drift correction target drawn by the user
2 
3 #include <eyelink.h>
4 
5 int target_shown = 0;
6 int draw_own_target = 1;
7 
8 while(1)
9 {
10  // Checks link often so we can exit if tracker stopped
11  if(!eyelink_is_connected())
12  return ABORT_EXPT;
13 
14  // If drift correct target is not drawn, we have to draw it here
15  if (draw_own_target && !target_shown)
16  {
17  // Code for drawing own drift correction target
18  target_shown = 1;
19  }
20 
21  // Performs drift correction with target drawn in the center
22  error = do_drift_correct(SCRWIDTH/2, SCRHEIGHT/2,
23  draw_own_target, 1);
24 
25  // repeat if ESC was pressed to access Setup menu
26  // Redawing the target may be necessary
27  if(error!=27)
28  break;
29  else
30  target_shown = 0;
31 }
See also
do_tracker_setup() and set_dcorr_sounds()
INT16 do_drift_correctf ( float  x,
float  y,
INT16  draw,
INT16  allow_setup 
)

Performs a drift correction before a trial. Same as do_drift_correct() except, this takes the x,y values as float.

Remarks
When the 'ESC' key is pressed during drift correction, <allow_setup> determines the result. If 1, the EyeLink Setup menu is accessed. This will always clear the display, so redrawing of hidden stimuli may be required. Otherwise, the drift correction is aborted. Calling exit_calibration() from an event handler will cause any call to do_drift_correct() in progress to return immediately. In all cases, the return code will be 27 (ESC_KEY).
Parameters
xX Position of drift correction target.
yY Position of drift correction target.
drawIf 1, the drift correction will clear the screen to the target background color, draw the target, and clear the screen again when the drift correction is done. If 0, the fixation target must be drawn by the user.
allow_setupIf 1, accesses Setup menu before returning, else aborts drift correction.
Returns
0 if successful, 27 if 'ESC' key was pressed to enter Setup menu or abort.

Example:

1 // This program illustrates the use of do_drift_correction with drift correction target drawn by the user
2 
3 #include <eyelink.h>
4 
5 int target_shown = 0;
6 int draw_own_target = 1;
7 
8 while(1)
9 {
10  // Checks link often so we can exit if tracker stopped
11  if(!eyelink_is_connected())
12  return ABORT_EXPT;
13 
14  // If drift correct target is not drawn, we have to draw it here
15  if (draw_own_target && !target_shown)
16  {
17  // Code for drawing own drift correction target
18  target_shown = 1;
19  }
20 
21  // Performs drift correction with target drawn in the center
22  error = do_drift_correctf(SCRWIDTH/2, SCRHEIGHT/2,
23  draw_own_target, 1);
24 
25  // repeat if ESC was pressed to access Setup menu
26  // Redawing the target may be necessary
27  if(error!=27)
28  break;
29  else
30  target_shown = 0;
31 }
See also
do_tracker_setup() and set_dcorr_sounds()
INT16 do_tracker_setup ( void  )

Switches the EyeLink tracker to the Setup menu, from which camera setup, calibration, validation, drift correction, and configuration may be performed. Pressing the 'ESC' key on the tracker keyboard will exit the Setup menu and return from this function. Calling exit_calibration() from an event handler will cause any call to do_tracker_setup() in progress to return immediately.

Returns
Always 0.

Example:

1 // This program shows an example of using the do_tracker_setup()
2 #include <eyelink.h>
3 
4 // Colors used for drawing calibration target and background
5 COLORREF target_foreground_color = RGB(0,0,0);
6 COLORREF target_background_color = RGB(255,255,255);
7 int i = SCRWIDTH/60; // Selects best size for calibration target
8 int j = SCRWIDTH/300; // Selects size for focal spot in target
9 if(j < 2) j = 2;
10 
11 // Sets diameter of target and of hole in middle of target
12 set_target_size(i, j);
13 
14 // Sets target color and display background color
15 set_calibration_colors(target_foreground_color, target_background_color);
16 
17 // Sets sounds for Setup menu (calibration, validation)
18 set_cal_sounds("", "", "");
19 // Sets sounds for drift correction
20 set_dcorr_sounds("", "off", "off");
21 
22 // Performs camera setup, calibration, validation, etc.
23 do_tracker_setup();
24 
25 ...
26 // Code for running the trials
See also
do_drift_correct(), set_cal_sounds(), set_calibration_colors() and set_target_size()
void exit_calibration ( void  )

This function should be called from an message or event handler if an ongoing call to do_drift_correct() or do_tracker_setup() should return immediately.

Example:

1 // The following code illustrates the use of exit_calibration(). This would usually be
2 // called from a message or event handler (see the w32_demo_window.c module) for an example.
3 #include <eyelink.h>
4 switch (message)
5 {
6 case WM_KEYDOWN:
7 case WM_CHAR:
8  {
9  // Process messages, translates key messages and queue
10  UINT16 key = process_key_messages(hwnd, message, wparam, lparam);
11  eyemsg_printf("key %d", key);
12 
13  // Checks the current tracker state. If it is in setup mode, pressing the PAGE_DOWN
14  // key would abort the setup process (i.e., drift-correction, calibration, validation)
15  if (key == 0x5100 && (eyelink_current_mode() & IN_SETUP_MODE))
16  exit_calibration();
17  break;
18  }
19  ...
20  // Other windows messages and events
21 }
See also
do_tracker_setup(), do_drift_correct() and eyelink_current_mode()
INT16 eyelink_abort ( void  )

Places EyeLink tracker in off-line (idle) mode.

Remarks
Use before attempting to draw graphics on the tracker display, transferring files, or closing link. Always call eyelink_wait_for_mode_ready() afterwards to ensure tracker has finished the mode transition. This function pair is implemented by the eyelink_exptkit library function set_offline_mode().
Returns
0 if mode switch begun, else link error.

Example:

1 // The following is the functional implementation of the stop_recording(), using the eyelink_abort()
2 
3 #include <eyelink.h>
4 
5 eyecmd_printf("heuristic_filter = ON");
6 eyelink_abort(); // stop data flow
7 eyelink_wait_for_mode_ready(500); // wait till finished mode switch
See also
eyelink_wait_for_mode_ready() and set_offline_mode()
INT16 eyelink_accept_trigger ( void  )

Triggers the EyeLink tracker to accept a fixation on a target, similar to the 'Enter' key or spacebar on the tracker.

Returns
NO_REPLY if drift correction not completed yet.
OK_RESULT (0) if success.
ABORT_REPLY (27) if 'ESC' key aborted operation.
-1 if operation failed.
1 if poor calibration or excessive validation error.

Example: See eyelink_driftcorr_start()

See also
eyelink_apply_driftcorr(), eyelink_current_mode(), eyelink_driftcorr_start() and eyelink_target_check()
INT16 eyelink_apply_driftcorr ( void  )

Applies the results of the last drift correction. This is not done automatically after a drift correction, allowing the message returned by eyelink_cal_message() to be examined first.

Returns
0 if command sent OK, else link error.

Example: See eyelink_driftcorr_start()

See also
eyelink_accept_trigger(), eyelink_cal_result(), eyelink_current_mode(), eyelink_driftcorr_start() and eyelink_target_check()
INT16 eyelink_cal_message ( char FARTYPE *  msg)

Returns text associated with result of last calibration, validation, or drift correction. This usually specifies errors or other statistics.

Parameters
msgBuffer to return back the message.
Returns
0 if no message since last command sent, else length of string.

Example:

1 // This programs illustrates the use of eyelink_cal_message()
2 #include <eyelink.h>
3 char message[256];
4 
5 // Performs a drift correction
6 while(1)
7 { // Check link often so we can exit if tracker stopped
8  if(!eyelink_is_connected()) return ABORT_EXPT;
9 
10  // Performs drift correction with target pre-drawn
11  error = do_drift_correct(SCRWIDTH/2, SCRHEIGHT/2, 1, 1);
12 
13  // repeat if ESC was pressed to access Setup menu
14  if(error!=27) break;
15 }
16 // Retrieves and writes out the calibration result message
17 eyelink_cal_message(message);
18 eyemsg_printf(message);

Output:

1 MSG 1896559 DRIFTCORRECT R RIGHT at 320,40 OFFSET 0.11 deg. -1.0,-4.0 pix.
2 MSG 1896560 drift_correction: 0.11 -1.00 -4.00
See also
eyelink_accept_trigger(), eyelink_apply_driftcorr() and eyelink_cal_result()
INT16 eyelink_cal_result ( void  )

Checks for a numeric result code returned by calibration, validation, or drift correction.

Returns
NO_REPLY if drift correction not completed yet.
OK_RESULT (0) if success.
ABORT_REPLY (27) if 'ESC' key aborted operation.
-1 if operation failed.
1 if poor calibration or excessive validation error.
Example: See eyelink_driftcorr_start()
See also
eyelink_accept_trigger(), eyelink_apply_driftcorr(), eyelink_cal_message() and eyelink_driftcorr_start()
INT16 eyelink_driftcorr_start ( INT16  x,
INT16  y 
)

Sets the position of the drift correction target, and switches the tracker to drift-correction mode. Should be followed by a call to eyelink_wait_for_mode_ready().

Parameters
xX position of the target.
yY position of the target.
Returns
0 if command sent OK, else link error.

Example:

1 // This program illustrates the use of eyelink_driftcorr_start() for the
2 // implementation of a drift correction mechanism
3 
4 #include <eyelink.h>
5 
6 unsigned key;
7 int result = 0;
8 int x, y; // position of the drift correction target
9 
10 if(eyelink_is_connected())
11 {
12  eyecmd_printf("heuristic_filter = ON");
13  ...
14  // Code to draw the target here
15  while(getkey()) {}; // dump the keys
16 
17  eyelink_driftcorr_start(x, y); // start the drift correction
18  do {
19  result = eyelink_cal_result();
20 
21  key = getkey();
22  switch(key)
23  {
24  case TERMINATE_KEY: // breakout code
25  return TERMINATE_KEY;
26  case 0: // no key
27  case JUNK_KEY: // no key
28  break;
29  case ESC_KEY: // ESC key: we flag abort from our end
30  result = 27;
31  break;
32  case 32: // Spacebar: we trigger ourselves
33  eyelink_accept_trigger();
34  break;
35  default:
36  eyelink_send_keybutton(key,0,KB_PRESS);
37  break;
38  }
39  } while(result == NO_REPLY);
40 
41  // Applies the drift correction result
42  if (result != 27 && result != -1)
43  eyelink_apply_driftcorr();
44  else
45  ; // Other code for handling
46 
47  return result;
48 }
See also
eyelink_accept_trigger() and eyelink_send_keybutton()
INT16 eyelink_driftcorr_startf ( float  x,
float  y 
)

Sets the position of the drift correction target, and switches the tracker to drift-correction mode. Should be followed by a call to eyelink_wait_for_mode_ready(). Same as eyelink_driftcorr_start() except the x,y parameters take floating point values.

Parameters
xX position of the target.
yY position of the target.
Returns
0 if command sent OK, else link error.

Example:

1 // This program illustrates the use of eyelink_driftcorr_start() for the
2 // implementation of a drift correction mechanism
3 
4 #include <eyelink.h>
5 
6 unsigned key;
7 int result = 0;
8 int x, y; // position of the drift correction target
9 
10 if(eyelink_is_connected())
11 {
12  eyecmd_printf("heuristic_filter = ON");
13  ...
14  // Code to draw the target here
15  while(getkey()) {}; // dump the keys
16 
17  eyelink_driftcorr_start(x, y); // start the drift correction
18  do {
19  result = eyelink_cal_result();
20 
21  key = getkey();
22  switch(key)
23  {
24  case TERMINATE_KEY: // breakout code
25  return TERMINATE_KEY;
26  case 0: // no key
27  case JUNK_KEY: // no key
28  break;
29  case ESC_KEY: // ESC key: we flag abort from our end
30  result = 27;
31  break;
32  case 32: // Spacebar: we trigger ourselves
33  eyelink_accept_trigger();
34  break;
35  default:
36  eyelink_send_keybutton(key,0,KB_PRESS);
37  break;
38  }
39  } while(result == NO_REPLY);
40 
41  // Applies the drift correction result
42  if (result != 27 && result != -1)
43  eyelink_apply_driftcorr();
44  else
45  ; // Other code for handling
46 
47  return result;
48 }
See also
eyelink_accept_trigger() and eyelink_send_keybutton()
INT16 eyelink_in_setup ( void  )

Checks if tracker is still in a Setup menu activity (includes camera image view, calibration, and validation). Used to terminate the subject setup loop.

Returns
0 if no longer in setup mode.

Example:

1 // This program illustrates the use of eyelink_in_setup
2 
3 #include <eyelink.h>
4 
5 int current_mode;
6 int prev_mode =0;
7 UINT start_time = current_msec();
8 
9 // Checks for 10 seconds
10 while(current_msec() < start_time + 10000)
11 {
12  if(!eyelink_is_connected())
13  return -1;
14 
15  current_mode =eyelink_in_setup();
16  if (current_mode!=prev_mode)
17  eyemsg_printf("%s", current_mode?"In setup":"Not in setup");
18 
19  prev_mode = current_mode;
20 }

Output:

1 MSG 905992 In setup
2 MSG 909596 Not in setup
See also
eyelink_current_mode()
void eyelink_set_tracker_setup_default ( INT16  mode)

sets the default mode to enter when eyelink_start_setup is called.

Remarks
eyelink_start_setup() internally called by do_tracker_setup() and do_drift_correct()
Parameters
mode1 -> start in image mode. 0 -> start in menu mode
INT16 eyelink_start_setup ( void  )

Enters setup mode

INT16 eyelink_target_check ( INT16 FARTYPE *  x,
INT16 FARTYPE *  y 
)

Returns the current target position and state.

Parameters
xPointer to variable to hold target X position.
yPointer to variable to hold target Y position.
Returns
1 if target is visible, 0 if not.

Example:

1 INT16 target_mode_display(void)
2 {
3  int target_visible = 0; // target currently drawn
4  INT16 tx; // new target position
5  INT16 ty;
6 
7  INT16 otx=MISSING; // current target position
8  INT16 oty=MISSING;
9 
10  unsigned key; // local key pressed
11  int i;
12  int result = NO_REPLY;
13 
14  // LOOP WHILE WE ARE DISPLAYING TARGETS
15  while(eyelink_current_mode() & IN_TARGET_MODE)
16  {
17  if(!eyelink_is_connected()) return -1;
18  key = getkey();
19  // HANDLE LOCAL KEY PRESS
20  if(key)
21  {
22  switch(key)
23  {
24  case TERMINATE_KEY: // breakout key code
25  clear_cal_display();
26  return TERMINATE_KEY;
27  case 32: // Spacebar: accept fixation
28  eyelink_accept_trigger();
29  break;
30  case 0: // No key
31  case JUNK_KEY: // No key
32  break;
33  case ESC_KEY: if(eyelink_is_connected()==-1) goto exit;
34  default: // Echo to tracker for remote control
35  if(allow_local_control)
36  eyelink_send_keybutton(key,0,KB_PRESS);
37  break;
38  }
39  }
40 
41  result = eyelink_cal_result();
42  if(result != NO_REPLY) break;
43 
44  // HANDLE TARGET CHANGES
45  i = eyelink_target_check(&tx, &ty);
46  // erased or moved: erase target
47  if( (target_visible && i==0) || tx!=otx || ty!=oty)
48  {
49  erase_cal_target();
50  target_visible = 0;
51  }
52  // redraw if visible
53  if(!target_visible && i)
54  {
55  draw_cal_target(tx, ty);
56 
57  target_visible = 1;
58  otx = tx; // record position for future tests
59  oty = ty;
60  }
61  }
62 
63 exit:
64 
65  if(target_visible)
66  erase_cal_target(); // erase target on exit
67 
68  clear_cal_display();
69  return result;
70 }
See also
eyelink_accept_trigger(), eyelink_apply_driftcorr(), eyelink_current_mode() and eyelink_driftcorr_start()
INT16 eyelink_target_checkf ( float FARTYPE *  x,
float FARTYPE *  y 
)

Returns the current target position and state. Same as eyelink_target_check() except this function returns data in floating point values.

Parameters
xPointer to variable to hold target X position.
yPointer to variable to hold target Y position.
Returns
1 if target is visible, 0 if not.

Copyright ©2002-2021, SR Research Ltd.