SR Research Support Site
Modules | Data Structures | Macros | Functions
Message and Command Sending/Receiving

Modules

 General Data Constants
 
 Sample Data Flags
 
 Eyelink Sample and Event Type Identifiers
 
 Read Data Flags
 
 Data Type Flags
 
 Event Data Flags
 
 Eyelink II/Eyelink I Marker flags
 
 Eyelink II specific flags
 
 Eyelink 1000 Remote specific target status flags
 

Data Structures

struct  ISAMPLE
 Integer sample data. More...
 
struct  FSAMPLE
 Floating-point sample. More...
 
struct  DSAMPLE
 Floating-point sample with floating point time. More...
 
struct  IEVENT
 Integer eye-movement events. More...
 
struct  FEVENT
 Floating-point eye event. More...
 
struct  DEVENT
 Floating-point eye event with floating point time. More...
 
struct  IMESSAGE
 Message events: usually text but may contain binary data. More...
 
struct  DMESSAGE
 Message events: usually text but may contain binary data with floating point time. More...
 
struct  IOEVENT
 Button, input, other simple events. More...
 
struct  DIOEVENT
 Button, input, other simple events with floating point time. More...
 
union  ALLF_DATA
 Union of message, io event and float sample and float event. More...
 
union  ALLD_DATA
 Union of message, io event and double sample and double event. More...
 

Macros

#define ALLDATADEF
 Union of message, io event and integer sample and integer event.
 

Functions

INT16 eyelink_node_send (ELINKADDR node, void FARTYPE *data, UINT16 dsize)
 
INT16 eyelink_node_receive (ELINKADDR node, void FARTYPE *data)
 
INT16 eyelink_send_command (char FARTYPE *text)
 
INT16 eyelink_command_result (void)
 
INT16 eyelink_timed_command (UINT32 msec, char FARTYPE *text)
 
INT16 eyelink_last_message (char FARTYPE *buf)
 
INT16 eyelink_send_message (char FARTYPE *msg)
 
INT16 eyelink_node_send_message (ELINKADDR node, char FARTYPE *msg)
 
INT16 eyelink_send_message_ex (UINT32 exectime, char FARTYPE *msg)
 
INT16 eyelink_node_send_message_ex (UINT32 exectime, ELINKADDR node, char FARTYPE *msg)
 
INT16 eyelink_read_request (char FARTYPE *text)
 
INT16 eyelink_read_reply (char FARTYPE *buf)
 
INT16 eyelink_position_prescaler (void)
 
INT16 eyelink_reset_data (INT16 clear)
 
void FARTYPE * eyelink_data_status (void)
 
INT16 eyelink_get_next_data (ALL_DATA *buf)
 
INT16 eyelink_get_last_data (ALL_DATA *buf)
 
INT16 eyelink_newest_sample (ISAMPLE *buf)
 
INT16 eyelink_get_float_data (ALLF_DATA *buf)
 
INT16 eyelink_get_all_float_data (ALLF_DATA *buf, int bufferlen)
 
INT16 eyelink_get_double_data (ALLD_DATA *buf)
 
INT16 eyelink_newest_float_sample (void FARTYPE *buf)
 
INT16 eyelink_newest_double_sample (void FARTYPE *buf)
 
INT16 eyelink_eye_available (void)
 
UINT16 eyelink_sample_data_flags (void)
 
UINT16 eyelink_event_data_flags (void)
 
UINT16 eyelink_event_type_flags (void)
 
INT16 eyelink_wait_for_data (UINT32 maxwait, INT16 samples, INT16 events)
 
INT16 eyelink_get_sample (ISAMPLE *sample)
 
INT16 eyelink_data_switch (UINT16 flags)
 
INT16 eyelink_data_start (UINT16 flags, INT16 lock)
 
INT16 eyelink_data_stop (void)
 
INT16 eyelink_wait_for_next_data (ALLF_DATA *buf, int bufferlen, UINT32 timeout)
 
INT16 eyelink_wait_for_new_sample (ISAMPLE *buf, UINT32 timeout)
 
INT16 eyelink_wait_for_new_float_sample (FSAMPLE *buf, UINT32 timeout)
 
INT16 eyelink_wait_for_new_double_sample (DSAMPLE *buf, UINT32 timeout)
 
INT16 eyelink_wait_for_command_result (UINT32 timeout)
 
INT16 eyelink_set_data_ready_notify (EYELINK_DATA_READY_NOTIFY notify_function)
 
EYELINK_DATA_READY_NOTIFY eyelink_get_data_ready_notify (void)
 
INT16 eyecmd_printf (const char *fmt,...)
 
INT16 eyemsg_printf (const char *fmt,...)
 
INT16 eyemsg_printf_ex (UINT32 exectime, const char *fmt,...)
 

Detailed Description

Function Documentation

INT16 eyecmd_printf ( const char *  fmt,
  ... 
)

The EyeLink tracker accepts text commands through the link. These commands may be used to configure the system, open data files, and so on.

Remarks
The function waits up to 500 msec. for a success or failure code to be returned from the tracker, then returns the error code NO_REPLY. If you need more time, use eyelink_timed_command() instead. Similar to eyemsg_printf() function, command string longer than 243 characters will be trimmed and thus command sending may fail.
Parameters
fmtSimilar to printf(), format string plus arguments.
Returns
0 if successfully executed, else error code.

Example:

1 // This program illustrates the use of eyecmd_printf()
2 
3 #include <eyelink.h>
4 
5 UINT32 t = current_msec();
6 int i, j;
7 
8 // Draws a box on the tracker screen
9 eyecmd_printf("draw_box %d %d %d %d 7", 100, 100, 300, 400);
10 
11 // Waits for a maximum of 1000 msec
12 while(current_msec()-t < 1000)
13 {
14  // Checks for result from command execution
15  i = eyelink_command_result();
16  // Used to get more information on tracker result
17  j = eyelink_last_message(buf);
18 
19  if (i == OK_RESULT)
20  {
21  eyemsg_printf("Command executed successfully: %s", j?buf:"");
22  break;
23  }
24  else if (i!=NO_REPLY)
25  {
26  eyemsg_printf("Error in executing command: %s", j?buf:"");
27  break;
28  }
29 }

Output:

1 MSG 5312110 Command executed successfully: OK
See also
eyemsg_printf(), eyelink_send_command() and eyelink_timed_command()
INT16 eyelink_command_result ( void  )

Check for and retrieves the numeric result code sent by the tracker from the last command.

Returns
NO_REPLY if no reply to last command.
OK_RESULT (0) if OK.
Other error codes represent tracker execution error.
Example: See eyelink_send_command()
See also
eyelink_wait_for_command_result() eyelink_last_message(), eyelink_send_command() and eyelink_timed_command()
INT16 eyelink_data_start ( UINT16  flags,
INT16  lock 
)

Switches tracker to Record mode, enables data types for recording to EDF file or sending to link. These types are set with a bitwise OR of these flags:

  • RECORD_FILE_SAMPLES (1) - only active if file open.
  • RECORD_FILE_EVENTS (2) - only active if file open.
  • RECORD_LINK_SAMPLES (4) - accept samples from link.
  • RECORD_LINK_EVENTS (8) - accept events from link.
Remarks
If <lock> is nonzero, the recording may only be terminated through stop_recording() or eyelink_data_stop(), or by the Abort menu (\91Ctrl\92 \92Alt\92 \92A\92 keys on the eye tracker). If zero, the tracker 'ESC' key may be used to halt recording.
Parameters
flagsBitwise OR of flags to control what data is recorded. If 0, recording will be stopped.
lockIf nonzero, prevents 'ESC' key from ending recording.
Returns
0 if command sent OK, else link error.

Example:

1 // This program illustrates the use of eyelink_data_start() and eyelink_data_stop()
2 // functions for trial recording
3 
4 #include <eyelink.h>
5 
6 // data types requested for the EDF file and link data
7 INT16 file_samples, file_events, link_samples, link_events;
8 
9 ...
10 // Functions to set the file and link data type
11 // f(file_samples, file_events, link_samples, link_events);
12 ...
13 
14 // Checks whether we still have the connection
15 if(eyelink_is_connected()) return ABORT_EXPT;
16 
17 i = eyelink_data_start((file_samples?RECORD_FILE_SAMPLES:0) |
18  (file_events?RECORD_FILE_EVENTS:0) |
19  (link_samples?RECORD_LINK_SAMPLES:0) |
20  (link_events?RECORD_LINK_EVENTS:0) , 1);
21 
22 if(i) return i;
23 
24 // wait for mode change completion
25 i = eyelink_wait_for_mode_ready(500);
26 if(i==0) return TRIAL_ERROR;
27 
28 // Checks that recording started OK
29 if((i = check_recording())!=0)
30  return i;
31 ...
32  // Recording code here
33 ...
34 
35 // Stops data flow and ends recording
36 eyelink_data_stop();
37 // wait for mode change completion
38 eyelink_wait_for_mode_ready(500);
See also
eyelink_data_stop(), start_recording() and stop_recording()
void FARTYPE* eyelink_data_status ( void  )

Updates buffer status (data count, etc), returns pointer to internal ILINKDATA structure.

Returns
Pointer to ILINKDATA structure.

Example:

1 Example 1:
2 // This program illustrates the use of eyelink_data_status to retrieve the name of the current application
3 
4 ILINKDATA* current_data; // Stores the link state data
5 
6 // Sets up the EyeLink system and connect to tracker
7 if(open_eyelink_connection(0)) return -1;
8 
9 // Updates the link data
10 current_data = eyelink_data_status();
11 eyemsg_printf("the subject PC name %s ", current_data -> our_name);
1 Example 2:
2 
3 // Checks link state of tracker
4 int preview_tracker_connection(void)
5 {
6  UINT32 t, tt;
7  ILINKDATA *idata = eyelink_data_status();
8  // Accesses link status info
9 
10  // Forces tracker to send status and time
11  eyelink_request_time();
12  t = current_msec();
13  while(current_msec()- t < 500) // Waits for response
14  {
15  tt = eyelink_read_time(); // Will be nonzero if reply
16 
17  if(tt != 0)
18  { // Retrieves the current connection state
19  if(idata->link_flags & LINK_BROADCAST)
20  return LINK_BROADCAST;
21  if(idata->link_flags & LINK_CONNECTED)
22  return LINK_CONNECTED;
23  else
24  return 0;
25  }
26 
27  message_pump(NULL); // Keeps Windows happy
28  if(break_pressed())
29  return 1; // Stops if program terminated
30  }
31  return -1; // Failed (timed out)
32 }

Output:

1 MSG 15252571 the subject PC name GOLDBERG
See also
eyelink_in_data_block() and eyelink_reset_data()
INT16 eyelink_data_stop ( void  )

Places tracker in idle (off-line) mode, does not flush data from queue.

Remarks
Should be followed by a call to eyelink_wait_for_mode_ready().
Returns
0 if command sent OK, else link error.

Example: See eyelink_data_start()

See also
eyelink_data_start() and eyelink_wait_for_mode_ready()
INT16 eyelink_data_switch ( UINT16  flags)

Sets what data from tracker will be accepted and placed in queue.

Remarks
This does not start the tracker recording, and so can be used with eyelink_broadcast_open(). It also does not clear old data from the queue. The data is set with a bitwise OR of these flags: RECORD_LINK_SAMPLES - send samples on link. RECORD_LINK_EVENTS - send events on link.
Parameters
flagsBitwise OR flags.
Returns
0 if OK else link error.

Example: See eyelink_in_data_block()

See also
eyelink_in_data_block()
UINT16 eyelink_event_data_flags ( void  )

Returns the event data content flags.

Remarks
This will be 0 if the data being read from queue is not in a block with events.
Returns
Event data content flags: EVENT_VELOCITY if has velocity data. EVENT_PUPILSIZE if has pupil size data. EVENT_GAZERES if has gaze resolution. EVENT_STATUS if has status flags. EVENT_GAZEXY if has gaze xy position. EVENT_HREFXY if has head-ref xy position. EVENT_PUPILXY if has pupil xy position. FIX_AVG_ONLY if only avg. data to fixation events. START_TIME_ONLY if only start-time in start events. PARSEDBY_GAZE if how events were generated. PARSEDBY_HREF. PARSEDBY_PUPIL.

Example:

1 // This program illustrates the use of eyelink_get_sample()
2 
3 #include <eyelink.h>
4 #include <stdio.h>
5 int error;
6 
7 // Recording with link data enabled
8 error = start_recording(1,1,1,0);
9 if(error != 0) return error; // ERROR: couldn't start recording
10 
11 // Wait for link sample data
12 if(!eyelink_wait_for_data(100, 1, 0))
13 {
14  printf("ERROR: No link samples received!");
15  return -1;
16 }
17 
18 // gets event data/type content flag
19 emsg_printf("Event data%d Event type %d",
20  eyelink_event_data_flags(), eyelink_event_type_flags());

Output:

1 MSG 2689937 Event data 26316 Event type 29760
See also
eyelink_event_type_flags()
UINT16 eyelink_event_type_flags ( void  )

After at least one button or eye event has been read, can be used to check what type of events will be available.

Returns
A set of bit flags: LEFTEYE_EVENTS if has left eye events. RIGHTEYE_EVENTS if has right eye events. BLINK_EVENTS if has blink events. FIXATION_EVENTS if has fixation events. FIXUPDATE_EVENTS if has fixation updates. SACCADE_EVENTS if has saccade events. MESSAGE_EVENTS if has message events. BUTTON_EVENTS if has button events. INPUT_EVENTS if has input port events.

Example: See eyelink_event_data_flags()

See also
eyelink_event_data_flags()
INT16 eyelink_eye_available ( void  )

After calling eyelink_wait_for_block_start(), or after at least one sample or eye event has been read, can be used to check which eyes data is available for.

Returns
One of these constants, defined in EYE_DATA.H: LEFT_EYE if left eye data. RIGHT_EYE if right eye data. BINOCULAR if both left and right eye data. -1 if no eye data is available.

Example:

1 // This program illustrates the use of eyelink_eye_available()
2 
3 #include <eyelink.h>
4 
5 int eye_used = 0; // indicates which eye's data to display
6 
7 // Determines which eye(s) are available
8 eye_used = eyelink_eye_available();
9 
10 // Selects eye, add annotation to EDF file
11 switch(eye_used)
12 {
13  case RIGHT_EYE:
14  eyemsg_printf("EYE_USED 1 RIGHT");
15  break;
16  case BINOCULAR: // both eye's data present: use left eye only
17  eye_used = LEFT_EYE;
18  case LEFT_EYE:
19  eyemsg_printf("EYE_USED 0 LEFT");
20  break;
21 }

Output:

1 MSG 22157314 EYE_USED 0 LEFT
See also
eyelink_wait_for_block_start()
INT16 eyelink_get_all_float_data ( ALLF_DATA buf,
int  bufferlen 
)

Reads all the item in the queue and fetch them into a buffer. The events are converted to a floating-point format (FSAMPLE or FEVENT). This can handle both samples and events. The buffer type can be ALLF_DATA for both samples and events, FSAMPLE for a sample, or a specific event buffer.

Parameters
bufPointer to an array buffer for floating-point data: type is ALLF_DATA
bufferlenLength of the bufffer.
Returns
Number of items filled.

Example:

1 #define BSIZE 200
2 ALLF_DATA evnts[BSIZE];
3 int count =eyelink_get_all_float_data(evnts,BSIZE);
4 printf("Got items:%d\n", count);
See also
eyelink_get_last_data(), eyelink_get_next_data(), eyelink_newest_float_sample() eyelink_newest_double_sample() eyelink_get_double_data() and eyelink_newest_sample()
EYELINK_DATA_READY_NOTIFY eyelink_get_data_ready_notify ( void  )
INT16 eyelink_get_double_data ( ALLD_DATA buf)

Reads the last item fetched by eyelink_get_next_data() into a buffer. The event is converted to a floating-point format with floating point time (DSAMPLE or DEVENT). This can handle both samples and events. The buffer type can be ALLD_DATA for both samples and events, DSAMPLE for a sample, or a specific event buffer.

Parameters
bufPointer to buffer for floating-point data: type is ALLD_DATA or DSAMPLE.
Returns
0 if no data, SAMPLE_TYPE if sample, else event type code.

Example: See eyelink_get_next_data()

See also
eyelink_get_last_data(), eyelink_get_next_data(), eyelink_newest_float_sample() eyelink_newest_double_sample() eyelink_get_float_data() and eyelink_newest_sample()
INT16 eyelink_get_float_data ( ALLF_DATA buf)

Reads the last item fetched by eyelink_get_next_data() into a buffer. The event is converted to a floating-point format (FSAMPLE or FEVENT). This can handle both samples and events. The buffer type can be ALLF_DATA for both samples and events, FSAMPLE for a sample, or a specific event buffer.

Parameters
bufPointer to buffer for floating-point data: type is ALLF_DATA or FSAMPLE.
Returns
0 if no data, SAMPLE_TYPE if sample, else event type code.

Example: See eyelink_get_next_data()

See also
eyelink_get_last_data(), eyelink_get_next_data(), eyelink_newest_float_sample() eyelink_newest_double_sample() eyelink_get_double_data() and eyelink_newest_sample()
INT16 eyelink_get_last_data ( ALL_DATA buf)

Gets an integer (unconverted) copy of the last/newest link data (sample or event) seen by eyelink_get_next_data().

Parameters
bufPointer to buffer (ISAMPLE, IEVENT, or ALL_DATA type).
Returns
0 if no data, SAMPLE_TYPE if sample, else event type code.

Example:

1 ALLF_DATA evt; // buffer to hold sample and event data
2 int eye_used = -1; // indicates which eye's data to display
3 int i;
4 UINT32 prev_event_time = -1;
5 
6 i = eyelink_get_next_data(NULL); // Checks for data from link
7 if(i == ENDFIX) // only process ENDFIX events
8 {
9  eyelink_get_float_data(&evt); // get a copy of the ENDFIX event
10  if(evt.fe.eye == eye_used) // only process data from desired eye?
11  eyemsg_printf("NEXT Event: %ld %ld", evt.fe.sttime,
12  evt.fe.entime);
13 }
14 
15 // makes copy of last item from eyelink_get_next_data
16 i = eyelink_get_last_data(&evt);
17 if (i == ENDFIX && evt.fe.eye == eye_used
18  && evt.fe.entime != prev_event_time)
19 {
20  eyemsg_printf("LAST Event: %ld %ld", evt.fe.sttime, evt.fe.entime);
21  // Makes sure that we do not write out redundant information
22  prev_event_time = evt.fe.entime;
23 }

Output:

1 SFIX L 7812616
2 SFIX R 7812616
3 EFIX L 7812616 7813232 620 124.7 274.0 50
4 EFIX R 7812616 7813232 620 118.2 262.4 50
5 SSACC L 7813236
6 SSACC R 7813236
7 MSG 7813254 NEXT Event: 7812616 7813232
8 MSG 7813254 LAST Event: 7812616 7813232
See also
eyelink_get_float_data(), eyelink_get_next_data() and eyelink_newest_float_sample()
INT16 eyelink_get_next_data ( ALL_DATA buf)

Fetches next data item from link buffer. Usually called with <buf> = NULL, and returns the data item type. If the item is not wanted, simply ignore it. Otherwise, call eyelink_get_float_data() to read it into a buffer.

Parameters
bufIf NULL, saves data, else copies integer data into buffer.
Returns
0 if no data, SAMPLE_TYPE if sample, else event type.

Example:

1 // This program illustrates the use of eyelink_get_next_data() and eyelink_get_float_data()
2 
3 #include <eyelink.h>
4 
5 ALLF_DATA evt; // buffer to hold sample and event data
6 int eye_used = -1; // indicates which eye's data to display
7 int i;
8 
9 // Determines which eye(s) are available
10 eye_used = eyelink_eye_available();
11 
12 // Selects eye, add annotation to EDF file
13 switch(eye_used)
14 {
15  case RIGHT_EYE:
16  eyemsg_printf("EYE_USED 1 RIGHT");
17  break;
18  case BINOCULAR: // both eye's data present: use left eye only
19  eye_used = LEFT_EYE;
20  case LEFT_EYE:
21  eyemsg_printf("EYE_USED 0 LEFT");
22  break;
23 }
24 while(1)
25 {
26  // Check for data from link and process fixation update events
27  i = eyelink_get_next_data(NULL);
28  if(i == FIXUPDATE)
29  {
30  // get a copy of the FIXUPDATE event
31  eyelink_get_float_data(&evt);
32  // only process if it's from the desired eye?
33  if(evt.fe.eye == eye_used)
34  {
35  // Records the average position and duration of update
36  eyemsg_printf("Fixupdate: avg_x %8.2f, y %8.2f, dur %d",
37  evt.fe.gavx, evt.fe.gavy, evt.fe.entime-evt.fe.sttime);
38  }
39  }
40  ...
41  // Other code for drawing and exiting
42 }

Output:

1 MSG 30244970 Fixupdate: avg_x 863.10, y 244.10, dur 48
2 MSG 30245018 Fixupdate: avg_x 863.10, y 245.60, dur 48
3 MSG 30245070 Fixupdate: avg_x 863.10, y 247.30, dur 48
See also
eyelink_get_float_data(), eyelink_get_last_data(), eyelink_newest_float_sample() and eyelink_newest_sample()
INT16 eyelink_get_sample ( ISAMPLE sample)

Gets an integer (unconverted) sample from end of queue, discards any events encountered.

Parameters
samplePointer to buffer (ISAMPLE or ALL_DATA type).
Returns
0 if no data. 1 if data retrieved.

Example:

1 // This program illustrates the use of eyelink_get_sample()
2 
3 #include <eyelink.h>
4 
5 ISAMPLE isample; // INTEGER SAMPLE DATA
6 int eye_used = 0; // indicates which eye's data to display
7 float x, y; // gaze position
8 int i;
9 
10 // wait for link sample data
11 if(!eyelink_wait_for_block_start(100, 1, 0))
12 {
13  end_trial();
14  return TRIAL_ERROR;
15 }
16 
17 // determine which eye(s) are available
18 eye_used = eyelink_eye_available();
19 switch(eye_used) // select eye, add annotation to EDF file
20 {
21 case RIGHT_EYE:
22  eyemsg_printf("EYE_USED 1 RIGHT");
23  break;
24 case BINOCULAR: // both eye's data present: use left eye only
25  eye_used = LEFT_EYE;
26 case LEFT_EYE:
27  eyemsg_printf("EYE_USED 0 LEFT");
28  break;
29 }
30 
31 while(1)
32 {
33  // get an integer copy of sample: skips any events
34  i = eyelink_get_sample(&isample);
35  if(i)
36  {
37  // convert the integer eye data to float data
38  // eyelink_position_prescaler() is used as a divisor
39  if (x!=MISSING_DATA)
40  x = ((float) isample.gx[eye_used])/
41  ((float) eyelink_position_prescaler());
42  else
43  x = (float) MISSING_DATA;
44 
45  if (y!=MISSING_DATA)
46  y = ((float) isample.gy[eye_used])/
47  ((float) eyelink_position_prescaler());
48  else
49  y = (float) MISSING_DATA;
50 
51  eyemsg_printf("Sample: %ld %6.2f %6.2f", isample.time, x, y);
52  }
53 
54  ...
55  // Code for exiting, display drawing etc.
56 }

Output:

1 MSG 14839670 Sample: 14839666 539.20 372.60
2 MSG 14839670 Sample: 14839668 539.20 372.60
3 MSG 14839674 Sample: 14839670 539.20 372.60
4 MSG 14839674 Sample: 14839672 539.20 372.60
5 MSG 14839678 Sample: 14839674 547.90 367.60
6 MSG 14839678 Sample: 14839676 556.60 362.50
7 MSG 14839682 Sample: 14839678 565.30 357.40
8 MSG 14839682 Sample: 14839680 574.10 352.30
9 MSG 14839686 Sample: 14839682 582.80 347.20
10 MSG 14839686 Sample: 14839684 591.50 342.00
11 MSG 14839690 Sample: 14839686 600.30 336.80
12 MSG 14839690 Sample: 14839688 609.00 331.60
13 MSG 14839694 Sample: 14839690 617.80 326.40
14 MSG 14839694 Sample: 14839692 626.60 321.20
15 MSG 14839698 Sample: 14839694 635.30 315.90
16 MSG 14839698 Sample: 14839696 644.10 310.70
17 MSG 14839702 Sample: 14839698 652.90 305.40
18 MSG 14839702 Sample: 14839700 661.70 300.00
19 MSG 14839706 Sample: 14839702 670.50 294.70
20 MSG 14839706 Sample: 14839704 679.30 289.40
21 MSG 14839710 Sample: 14839706 688.10 284.00
22 MSG 14839710 Sample: 14839708 696.90 278.60
23 MSG 14839714 Sample: 14839710 705.80 273.20
24 MSG 14839714 Sample: 14839712 714.60 267.70
25 MSG 14839718 Sample: 14839714 723.40 262.30
26 MSG 14839718 Sample: 14839716 732.30 256.80
27 MSG 14839722 Sample: 14839718 741.20 251.30
28 MSG 14839722 Sample: 14839720 750.00 245.80
See also
eyelink_get_float_data(), eyelink_get_last_data(), eyelink_get_next_data(), eyelink_newest_float_sample() and eyelink_newest_sample()
INT16 eyelink_last_message ( char FARTYPE *  buf)

Checks for and gets the last packet received, stores the data and the node address sent from.

Parameters
bufString buffer to return text message.
Returns
0 if no message since last command sent, otherwise length of string.

Example: See eyelink_timed_command()

See also
eyelink_send_command() and eyelink_timed_command()
INT16 eyelink_newest_double_sample ( void FARTYPE *  buf)

Check if a new sample has arrived from the link. This is the latest sample, not the oldest sample that is read by eyelink_get_next_data(), and is intended to drive gaze cursors and gaze-contingent displays. Typically the function is called with a NULL buffer pointer, to test if new data has arrived. If a value of 1 is returned, the function is called with a DSAMPLE buffer to get the new sample.

Parameters
bufPointer to sample buffer type DSAMPLE. If NULL, just checks new-sample status.
Returns
-1 if no samples, 0 if no new data, 1 if new sample.
See also
eyelink_get_float_data(), eyelink_get_last_data(), eyelink_get_next_data(), eyelink_get_sample() eyelink_newest_float_sample() and eyelink_newest_sample()
INT16 eyelink_newest_float_sample ( void FARTYPE *  buf)

Check if a new sample has arrived from the link. This is the latest sample, not the oldest sample that is read by eyelink_get_next_data(), and is intended to drive gaze cursors and gaze-contingent displays. Typically the function is called with a NULL buffer pointer, to test if new data has arrived. If a value of 1 is returned, the function is called with a FSAMPLE buffer to get the new sample.

Parameters
bufPointer to sample buffer type FSAMPLE. If NULL, just checks new-sample status.
Returns
-1 if no samples, 0 if no new data, 1 if new sample.

Example:

1 Example 1:
2  // This program illustrates the use of eyelink_newest_float_sample
3  #include <eyelink.h>
4 
5  ALLF_DATA evt; // buffer to hold sample and event data
6  int eye_used = 0; // indicates which eye's data to display
7  float x, y; // gaze position
8 
9  // Recording with link data enabled
10  error = start_recording(1,1,1,0);
11  if(error != 0) return error; // ERROR: couldn't start recording
12 
13  // Determines which eye(s) are available
14  eye_used = eyelink_eye_available();
15 
16  // Selects eye, add annotation to EDF file
17  switch(eye_used)
18  {
19  case RIGHT_EYE:
20  eyemsg_printf("EYE_USED 1 RIGHT");
21  break;
22  case BINOCULAR: // both eye's data present: use left eye only
23  eye_used = LEFT_EYE;
24  case LEFT_EYE:
25  eyemsg_printf("EYE_USED 0 LEFT");
26  break;
27  }
28  while (1)
29  {
30  // check for new sample update
31  if(eyelink_newest_float_sample(NULL)>0)
32  {
33  // get the sample
34  eyelink_newest_float_sample(&evt);
35 
36  x = evt.fs.gx[eye_used];
37  y = evt.fs.gy[eye_used];
38 
39  // make sure pupil is present
40  if(x!=MISSING_DATA && y!=MISSING_DATA && evt.fs.pa[eye_used]>0)
41  eyemsg_printf("Sample: %ld %8.2f %8.2f",
42  evt.fs.time, x, y);
43  }
44  ...
45  // Code for exiting, display drawing etc.
46  }
Output: 
1 MSG 23701980 EYE_USED 0 LEFT
2 MSG 23703426 Sample: 23703424 412.90 217.90
3 MSG 23703430 Sample: 23703426 433.20 216.20
4 MSG 23703430 Sample: 23703428 453.40 214.40
5 MSG 23703434 Sample: 23703430 473.60 212.60
6 MSG 23703434 Sample: 23703432 493.80 210.80
7 MSG 23703438 Sample: 23703434 514.00 209.00
8 MSG 23703438 Sample: 23703436 534.20 207.10
9 MSG 23703442 Sample: 23703438 554.30 205.20
10 MSG 23703442 Sample: 23703440 574.40 203.30
11 MSG 23703446 Sample: 23703442 594.50 201.30
12 MSG 23703446 Sample: 23703444 614.60 199.30
13 MSG 23703450 Sample: 23703446 634.70 197.20
14 MSG 23703450 Sample: 23703448 634.70 197.20
This program illustrates the use of eyelink_newest_float_sample to get remote data online
    
1 Example 2:
2  // "HTARGET" should be included in the data list
3  eyecmd_printf("file_sample_data = LEFT,RIGHT,GAZE,AREA,HTARGET,GAZERES,STATUS,INPUT");
4  eyecmd_printf("link_sample_data = LEFT,RIGHT,GAZE,GAZERES,AREA,HTARGET,STATUS,INPUT");
5 
6 
7  // The remote data is accessed through the hdata member of the sample data structure.
8  // The first 4 values of evt.hdata structure are: target x, target y, target distance in mm*10.0, and target flags.
9 
10  // check for new samples
11  if(eyelink_newest_float_sample(NULL)>0)
12  {
13  eyelink_newest_float_sample(&evt); // get the sample
14 
15  eyemsg_printf("remote data %d %d %d %x", evt.fs.hdata[0], evt.fs.hdata[1], evt.fs.hdata[2], evt.fs.hdata[3]);
16  }
See also
eyelink_get_float_data(), eyelink_get_last_data(), eyelink_get_next_data(), eyelink_get_sample() eyelink_newest_double_sample() and eyelink_newest_sample()
INT16 eyelink_newest_sample ( ISAMPLE buf)

Gets an integer (unconverted) copy of the last/newest link data (sample or event) seen by eyelink_get_next_data().

Parameters
bufPointer to buffer (ISAMPLE, ALL_DATA type).
Returns
0 if no data, else SAMPLE_TYPE.

Example:

1 ISAMPLE isample;
2 float x, y; // gaze position
3 
4 if(eyelink_newest_sample(NULL)>0) // check for new sample update
5 {
6  eyelink_newest_sample(&isample);
7 
8  if (x!=MISSING_DATA)
9  x = ((float) isample.gx[eye_used])/((float) eyelink_position_prescaler()); // yes: get gaze position from sample
10  else
11  x = (float) MISSING_DATA;
12 
13  if (y!=MISSING_DATA)
14  y = ((float) isample.gy[eye_used])/((float) eyelink_position_prescaler());
15  else
16  y = (float) MISSING_DATA;
17 
18  ...
19  // code for processing the sample
20  ...
21 }
See also
eyelink_get_float_data(), eyelink_get_last_data(), eyelink_get_next_data(), eyelink_get_sample() and eyelink_newest_float_sample()
INT16 eyelink_node_receive ( ELINKADDR  node,
void FARTYPE *  data 
)

Checks for and gets the last packet received, stores the data and the node address sent from.

Remarks
Data can only be read once, and is overwritten if a new packet arrives before the last packet has been read.
Parameters
nodeAddress of the sender.
dataPointer to a buffer to hold the data.
Returns
0 if successful, otherwise link error.

Example: See eyelink_node_send()

See also
eyelink_get_float_data(), eyelink_open_node() and eyelink_node_send()
INT16 eyelink_node_send ( ELINKADDR  node,
void FARTYPE *  data,
UINT16  dsize 
)

Sends a given data to the given node.

Parameters
nodeELINKADDR node address.
dataPointer to buffer containing data to send.
dsizeNumber of bytes of data. Maximum ELREMBUFSIZE bytes.
Returns
0 if successful, otherwise link error.

Example:

1 // The following two code pieces show the exchanges of messaging between two
2 // remote applications (SENDER and LISTENER). In the first program, the SENDER sends
3 // a "START_RECORD" message to the LISTENER application and wait for an "echo" message.
4 // The second program shows the LISTENER application receives the "START_RECORD" message
5 // and sends an "echo" message
6 
7 #include <eyelink.h>
8 
9 ELINKADDR listener_address; // Address of the listener application
10 char text_message[256], echo_message[256];
11 
12 ...
13 // Code for retrieving the listener's address; See COMM_SIMPLE
14 ...
15 
16 sprintf(text_message, "START_RECORD");
17 eyelink_node_send(listener_address, text_message, 40);
18 
19 // Now checks for the echo response from the listener
20 while (1)
21 {
22  // get the message from the listener application
23  k = eyelink_node_receive(listener_address, echo_message);
24  if (k > 0 && strstr(echo_message, text_message))
25  break;
26  ...
27  // Other code for error handling
28  ...
29 }
1 // This program shows the LISTENER application receives the "START_RECORD" message and sends an "echo" message
2 
3 #include <eyelink.h>
4 
5 ELINKADDR sender_address; // Address of the sender application
6 char text_message[256], echo_message[256];
7 
8 // get the message from the sender application
9 k = eyelink_node_receive(sender_address, text_message);
10 
11 if(k > 0 && !_strnicmp(text_message, "START_RECORD", 12))
12 {
13  eyemsg_printf(text_message);
14  error = start_recording(1,1,1,1); // Starts recording
15  if(error != 0)
16  return error; // Return error code if failed
17 
18  sprintf(echo_message, "ECHO %s", text_message);
19  // Sends the echo message to the sender application
20  eyelink_node_send(sender_address, echo_message, 60);
21 }
See also
eyelink_get_node(), eyelink_node_receive() and eyelink_open_node()
INT16 eyelink_node_send_message ( ELINKADDR  node,
char FARTYPE *  msg 
)

Sends a text message the connected eye tracker. The text will be added to the EDF file.

Remarks
NEW (v2.1): If the link is initialized but not connected to a tracker, the message will be sent to the tracker set by set_eyelink_address().
Parameters
msgText to send to the tracker.
nodeAddress of the tracker.
Returns
0 if no error, else link error code.

Example: See eyelink_quiet_mode()

See also
eyelink_send_message(), eyelink_quiet_mode() and set_eyelink_address()
INT16 eyelink_node_send_message_ex ( UINT32  exectime,
ELINKADDR  node,
char FARTYPE *  msg 
)

Send a data file message to any or all trackers with time offset.

Parameters
exectimetime offset. If the offset is 0, this function is the same as eyelink_node_send_message()
nodeNode address
msgMessage to be sent
Returns
OK_RESULT or LINK_TERMINATED_RESULT.
See also
eyelink_node_send_message()
INT16 eyelink_position_prescaler ( void  )

Returns the divisor used to convert integer eye data to floating point data.

Returns
Divisor (usually 10).

Example:

1 // This program uses the eyecmd_printf() and eyelink_position_prescaler() to set
2 // and retrieve the screen_write_prescale value. See eyelink_get_sample() for
3 // another example of using eyelink_position_prescaler()
4 
5 #include <eyelink.h>
6 UINT32 start_time;
7 
8 // Sets the value by which gaze position data is multiplied before writing to EDF file or link as integer
9 eyecmd_printf("screen_write_prescale = 10");
10 
11 
12 if (eyelink_wait_for_command_result() == OK_RESULT)
13  {
14  // Checks out the value set
15  eyemsg_printf("Position scalar %d",
16  eyelink_position_prescaler());
17 
18  }
INT16 eyelink_read_reply ( char FARTYPE *  buf)

Returns text with reply to last read request.

Parameters
bufString to contain text.
Returns
OK_RESULT (0) if response received.
NO_REPLY if no response yet.

Example: See eyelink_read_request()

See also
eyelink_read_request()
INT16 eyelink_read_request ( char FARTYPE *  text)

Sends a text variable name whose value is to be read and returned by the tracker as a text string.

Remarks
NEW (v2.1): If the link is initialized but not connected to a tracker, the message will be sent to the tracker set by set_eyelink_address(). However, these requests will be ignored by tracker versions older than EyeLink I v2.1 and EyeLink II v1.1.
Parameters
textString with message to send.
Returns
0 if success, otherwise link error code.

Example:

1 // This code illustrates the use of eyelink_read_request() to get the coordinate information of the screen coordinate
2 
3 int read_tracker_pixel_coords(void)
4 {
5  char buf[100] = "";
6  UINT32 t;
7 
8  // Checks whether we are still connected
9  if(!eyelink_is_connected() || break_pressed())
10  return 1;
11 
12  // Tries to retrieve the info about screen_pixel_coords
13  eyelink_read_request("screen_pixel_coords");
14 
15  t = current_msec();
16  // Waits for a maximum of 500 msec
17  while(current_msec()-t < 500)
18  {
19  if(eyelink_read_reply(buf) == OK_RESULT)
20  {
21  eyemsg_printf("%s", buf);
22  return 0;
23  }
24  message_pump(NULL); // Keeps Windows happy
25  if(!eyelink_is_connected) return 1;
26  if(break_pressed()) return 1;
27  }
28  return -1; // Timed out
29 }

Output:

1 MSG 374986 0.000000,0.000000,1023.000000,767.000000
See also
eyelink_read_reply()
INT16 eyelink_reset_data ( INT16  clear)

Prepares link buffers to receive new data. If <clear> is nonzero, removes old data from buffer.

Parameters
clearIf clear is non-zero, any buffer data is discarded.
Returns
Always returns 0.

Example: See eyelink_in_data_block()

See also
eyelink_data_status() and eyelink_in_data_block()
UINT16 eyelink_sample_data_flags ( void  )

Gets sample data content flag (0 if not in sample block).

INT16 eyelink_send_command ( char FARTYPE *  text)

Sends a command to the connected eye tracker.

Remarks
If eyelink_send_commnd() is used, the text command will be executed, and a result code returned that can be read with eyelink_command_result() or eyelink_wait_for_command_result().
Parameters
textString command to send.
Returns
0 if successful, otherwise link error.

Example:

1 // This program illustrates the use of eyelink_send_command
2 
3 #include <eyelink.h>
4 
5 UINT32 t;
6 int i, j;
7 char buf[256];
8 
9 // Change the assignment of the button functions so that pressing
10 // button 1 will accept target fixation
11 i=eyelink_send_command("button_function 1 'accept_target_fixation'");
12 // Used to get more information on tracker result
13 j = eyelink_last_message(buf);
14 
15 if (i == OK_RESULT)
16 {
17  eyemsg_printf("Command executed successfully: %s", j?buf:"");
18  break;
19 }
20 else if (i!=NO_REPLY)
21 {
22  eyemsg_printf("Error in executing command: %s", j?buf:"");
23  break;
24 }

Output:

1 MSG 4608038 Command executed successfully: OK
See also
eyelink_command_result(), eyelink_wait_for_command_result() and eyelink_timed_command()
INT16 eyelink_send_message ( char FARTYPE *  msg)

Sends a text message the connected eye tracker. The text will be added to the EDF file.

Parameters
msgText to send to the tracker.
Returns
0 if no error, else link error code.

Example: See eyelink_quiet_mode()

See also
eyelink_node_send_message(), eyelink_quiet_mode() and set_eyelink_address()
INT16 eyelink_send_message_ex ( UINT32  exectime,
char FARTYPE *  msg 
)

Send a data file message string to connected tracker with time offset.

Parameters
exectimetime offset. If the offset is 0, this function is the same as eyelink_send_message()
msgMessage to be sent
Returns
OK_RESULT or LINK_TERMINATED_RESULT.
See also
eyemsg_printf_ex(), eyelink_send_message()
INT16 eyelink_set_data_ready_notify ( EYELINK_DATA_READY_NOTIFY  notify_function)

The api can be configured, so that it is not necessary to keep looping and checking for when the data is available. This function allows to set the notification callback function. The callback will be called as soon as an event or sample available.

Parameters
notify_functionpointer to the callback function

The callback function takes in an argument and returns nothing. Callback function should return very quickly. If this takes too long, then the data receive packets may be dropped. The argument value of 1 means event is available and the argument value of 2 means sample is available on the link

    \b Example:
    <pre>
1 void notify_when_sample_is_ready(int type)
2 {
3  // This function will be called when a sample or event is availbe.
4  if(type ==1) printf("Event is ready \n");
5  else if(type ==2) printf("Sample is ready \n");
6 }
7 
8 
9 
10 {
11  ... // some other implementation
12  eyelink_set_data_ready_notify(notify_when_sample_is_ready);
13  ... // some more implementation.
14 }
See also
eyelink_get_data_ready_notify(), eyelink_get_float_data(), eyelink_get_last_data(), eyelink_get_next_data(), eyelink_get_sample() eyelink_newest_double_sample() eyelink_wait_for_new_double_sample() eyelink_wait_for_new_float_sample() and eyelink_newest_sample()
INT16 eyelink_timed_command ( UINT32  msec,
char FARTYPE *  text 
)

Sends a command to the connected eye tracker, wait for reply.

Remarks
If eyelink_send_command() is used, the text command will be executed, and a result code returned that can be read with eyelink_command_result() or eyelink_wait_for_command_result().
Parameters
textString command to send.
msecMaximum milliseconds to wait for reply.
Returns
OK_RESULT (0) if OK.
NO_REPLY if timed out.
LINK_TERMINATED_RESULT if cannot send.
other error codes represent tracker execution error.
Example:
1 // This program illustrates the use of eyelink_timed_command
2 
3 #include <eyelink.h>
4 
5 INT16 error;
6 char buf[256];
7 
8 // send command string to tracker, wait for reply
9 error = eyelink_timed_command(1000, "button_function 5
10  'accept_target_fixation'");
11 
12 // Checks for the command result
13 if (error)
14 {
15  eyelink_last_message(buf);
16  eyemsg_printf("Error in executing the command: %s", buf);
17 }
See also
eyelink_wait_for_command_result(), eyelink_command_result() and eyelink_send_command()
INT16 eyelink_wait_for_command_result ( UINT32  timeout)

Waits for and retrieves the numeric result code sent by the tracker from the last command.

Returns
NO_REPLY if no reply to last command.
OK_RESULT (0) if OK.
Other error codes represent tracker execution error.
Example:
1 // This program uses the eyecmd_printf() and eyelink_position_prescaler() to set
2 // and retrieve the screen_write_prescale value. See eyelink_get_sample() for
3 // another example of using eyelink_position_prescaler()
4 
5 #include <eyelink.h>
6 UINT32 start_time;
7 
8 // Sets the value by which gaze position data is multiplied before writing to EDF file or link as integer
9 eyecmd_printf("screen_write_prescale = 10");
10 
11 
12 if (eyelink_wait_for_command_result() == OK_RESULT)
13  {
14  // Checks out the value set
15  eyemsg_printf("Position scalar %d",
16  eyelink_position_prescaler());
17 
18  }
See also
eyelink_last_message(), eyelink_send_command() and eyelink_timed_command()
INT16 eyelink_wait_for_data ( UINT32  maxwait,
INT16  samples,
INT16  events 
)

Counts total items in queue: samples, events, or both.

Parameters
samplesIf non-zero count the samples.
eventsIf non-zero count the events.
Returns
Total number of samples and events is in the queue.

Example:

1 // This program uses eyelink_data_count() to check whether the desired sample/event data
2 // have arrived after the start_recording()
3 
4 // Check whether the desired sample/event data have arrived. This function should be
5 // called after start_recording()
6 // link_samples: Whether samples should be sent over the link
7 // link_events: Whether events should be sent over the link
8 
9 int check_sample_event_status(int link_samples, int link_events)
10 {
11  UINT32 t = current_time();
12  int i;
13 
14  // Checks the sample and event availability in 300 msec
15  while(current_time() < t + 300)
16  {
17  int arrived = 1;
18  // check that recording still OK
19  if((i=check_recording())!=0) return i;
20 
21  // Checks whether the samples, if set, have arrived
22  if(link_samples)
23  if(eyelink_data_count(1,0)==0)
24  arrived = 0;
25 
26  // Checks whether the samples, if set, have arrived
27  if(link_events)
28  if(eyelink_data_count(0,1)==0)
29  arrived = 0;
30 
31  // Exit if desired data type(s) have arrived
32  if(arrived) return 0;
33  }
34 
35  // If the desired data type(s) didn't arrive within 300 msec
36  return -1;
37 }
 */
INT16  eyelink_data_count(INT16 samples, INT16 events);
/* maxwait = 0 to just test                                 */
/*!
        Waits for data to be received from the eye tracker.  Can wait for an event, a sample, or
        either.  Typically used after record start to check if data is being sent.
        
Parameters
maxwaitTime in milliseconds to wait for data.
samplesIf 1, return when first sample available.
eventsIf 1, return when first event available.
Returns
1 if data is available. 0 if timed out.
Example:
1 // This program illustrates the use of eyelink_wait_for_data()
2 
3 #include <eyelink.h>
4 #include <stdio.h>
5 int error;
6 
7 // Recording with link data enabled
8 error = start_recording(1,1,1,0);
9 if(error != 0) return error; // ERROR: couldn't start recording
10 
11 // Wait for link sample data
12 if(!eyelink_wait_for_data(100, 1, 0))
13 {
14  printf("ERROR: No link samples received!");
15  return -1;
16 }
        
See also
eyelink_wait_for_block_start()
INT16 eyelink_wait_for_new_double_sample ( DSAMPLE buf,
UINT32  timeout 
)

Waits for a new sample to arrive on the link. Exactly the same as eyelink_wait_for_new_float_sample() except the data type is DSAMPLE

Parameters
bufPointer to sample buffer type DSAMPLE. If NULL, just checks new-sample status.
Returns
-1 if no samples, 0 if no new data, 1 if new sample.
See also
eyelink_get_float_data(), eyelink_get_last_data(), eyelink_get_next_data(), eyelink_get_sample() eyelink_newest_double_sample() eyelink_wait_for_new_sample() eyelink_wait_for_new_float_sample() and eyelink_newest_sample()
INT16 eyelink_wait_for_new_float_sample ( FSAMPLE buf,
UINT32  timeout 
)

Waits for a new sample to arrive on the link. This is the latest sample, not the oldest sample that is read by eyelink_get_next_data(), and is intended to drive gaze cursors and gaze-contingent displays.

If the function is called with NULL buffer pointer, then the behaviour is exactly the same as eyelink_newest_float_sample(). If a FSAMPLE buffer is given then, the function call will block till the next sample is available and then return. If sample cannot be gathered, the function will timeout. If it times out the return value will be -1.

Parameters
bufPointer to sample buffer type FSAMPLE. If NULL, just checks new-sample status.
Returns
-1 if no samples, 0 if no new data, 1 if new sample.

Example:

1 Example 1:
2  // This program illustrates the use of eyelink_newest_float_sample
3  #include <eyelink.h>
4 
5  FSAMPLE sample; // buffer to hold sample and event data
6  int eye_used = 0; // indicates which eye's data to display
7  float x, y; // gaze position
8 
9  // Recording with link data enabled
10  error = start_recording(1,1,1,0);
11  if(error != 0) return error; // ERROR: couldn't start recording
12 
13  // Determines which eye(s) are available
14  eye_used = eyelink_eye_available();
15 
16  // Selects eye, add annotation to EDF file
17  switch(eye_used)
18  {
19  case RIGHT_EYE:
20  eyemsg_printf("EYE_USED 1 RIGHT");
21  break;
22  case BINOCULAR: // both eye's data present: use left eye only
23  eye_used = LEFT_EYE;
24  case LEFT_EYE:
25  eyemsg_printf("EYE_USED 0 LEFT");
26  break;
27  }
28  while (1)
29  {
30  // check for new sample update
31  if(eyelink_wait_for_new_float_sample(&sample)>0)
32  {
33 
34 
35  x = sample.gx[eye_used];
36  y = sample.gy[eye_used];
37 
38  // make sure pupil is present
39  if(x!=MISSING_DATA && y!=MISSING_DATA && evt.fs.pa[eye_used]>0)
40  eyemsg_printf("Sample: %ld %8.2f %8.2f",
41  evt.fs.time, x, y);
42  }
43  ...
44  // Code for exiting, display drawing etc.
45  }
Output: 
1 MSG 23701980 EYE_USED 0 LEFT
2 MSG 23703426 Sample: 23703424 412.90 217.90
3 MSG 23703430 Sample: 23703426 433.20 216.20
4 MSG 23703430 Sample: 23703428 453.40 214.40
5 MSG 23703434 Sample: 23703430 473.60 212.60
6 MSG 23703434 Sample: 23703432 493.80 210.80
7 MSG 23703438 Sample: 23703434 514.00 209.00
8 MSG 23703438 Sample: 23703436 534.20 207.10
9 MSG 23703442 Sample: 23703438 554.30 205.20
10 MSG 23703442 Sample: 23703440 574.40 203.30
11 MSG 23703446 Sample: 23703442 594.50 201.30
12 MSG 23703446 Sample: 23703444 614.60 199.30
13 MSG 23703450 Sample: 23703446 634.70 197.20
14 MSG 23703450 Sample: 23703448 634.70 197.20
This program illustrates the use of eyelink_newest_float_sample to get remote data online
    
1 Example 2:
2  // "HTARGET" should be included in the data list
3  eyecmd_printf("file_sample_data = LEFT,RIGHT,GAZE,AREA,HTARGET,GAZERES,STATUS,INPUT");
4  eyecmd_printf("link_sample_data = LEFT,RIGHT,GAZE,GAZERES,AREA,HTARGET,STATUS,INPUT");
5 
6 
7  // The remote data is accessed through the hdata member of the sample data structure.
8  // The first 4 values of evt.hdata structure are: target x, target y, target distance in mm*10.0, and target flags.
9 
10  // check for new samples
11  if(eyelink_wait_for_new_float_sample(&sample)>0)
12  {
13 
14 
15  eyemsg_printf("remote data %d %d %d %x", sample.hdata[0], sample.hdata[1], sample.hdata[2], sample.hdata[3]);
16  }
See also
eyelink_get_float_data(), eyelink_get_last_data(), eyelink_get_next_data(), eyelink_get_sample() eyelink_newest_double_sample() eyelink_wait_for_new_double_sample() eyelink_wait_for_new_sample() and eyelink_newest_sample()
INT16 eyelink_wait_for_new_sample ( ISAMPLE buf,
UINT32  timeout 
)

Waits for a new sample to arrive on the link. Exactly the same as eyelink_wait_for_new_float_sample() except the data type is ISAMPLE

Parameters
bufPointer to sample buffer type ISAMPLE. If NULL, just checks new-sample status.
Returns
-1 if no samples, 0 if no new data, 1 if new sample.
See also
eyelink_get_float_data(), eyelink_get_last_data(), eyelink_get_next_data(), eyelink_get_sample() eyelink_newest_double_sample() eyelink_wait_for_new_double_sample() eyelink_wait_for_new_float_sample() and eyelink_newest_sample()
INT16 eyelink_wait_for_next_data ( ALLF_DATA buf,
int  bufferlen,
UINT32  timeout 
)

Waits for the data till timeout or any data available and fetches next n number of data items from link buffer. Returns the number of items fetched if buffer given. If no return buffer is given returns the last item's type. The returned items are already converted to float data and can be used directly.

@param buf        If \c NULL, saves data, else copies float data into buffer.  Buffer should be of bufferlen times ALLF_DATA.
@param bufferlen  length of ALLF_DATA array. eg. 5 would mean, array of 5 elements of type ALLF_DATA
@param timeout        0 means to use default time out. At the moment, default time out is set to 20ms. 
If longer timeout is required use units of 20 ms. eg. if 2 is given, the function will wait for up to 40ms for data.  If NULL buffer is
given, the function assumes no timeout. 
@param buf 
@return \c 0 if no data, \c SAMPLE_TYPE or else event type if NULL buffer is given.
            \c n number of items copied if buffer is given.  
@remark
    If eyelink_wait_for_next_data(NULL,0,0) then it the same as calling eyelink_get_next_data(NULL)

\b Example:
<pre>
1 // This program illustrates the use of eyelink_wait_for_next_data()
2 
3 #include <eyelink.h>
4 
5 
6 int len = 5;
7 int returned_datalen=0;
8 ALLF_DATA evt[5]; // buffer to hold sample and event data
9 int eye_used = -1; // indicates which eye's data to display
10 int i;
11 
12 // Determines which eye(s) are available
13 eye_used = eyelink_eye_available();
14 
15 // Selects eye, add annotation to EDF file
16 switch(eye_used)
17 {
18  case RIGHT_EYE:
19  eyemsg_printf("EYE_USED 1 RIGHT");
20  break;
21  case BINOCULAR: // both eye's data present: use left eye only
22  eye_used = LEFT_EYE;
23  case LEFT_EYE:
24  eyemsg_printf("EYE_USED 0 LEFT");
25  break;
26 }
27 
28 // Makes sure that the tracker connection is still alive
29 while(eyelink_is_connected())
30 {
31  // handle the error or abort situations
32  if(getkey()==27 || !eyelink_is_connected())
33  break;
34  returned_datalen = eyelink_wait_for_next_data(evt, len, 0);
35  for( i =0; i < returned_datalen; i++)
36  {
37  // Check for data from link and process fixation update events
38  if(evt[i].fe.type == FIXUPDATE)
39  {
40  //We have a FIXUPDATE event.
41  // only process if it's from the desired eye?
42  if(evt[i].fe.eye == eye_used)
43  {
44  // Records the average position and duration of update
45  eyemsg_printf("Fixupdate: avg_x %8.2f, y %8.2f, dur %d",
46  evt[i].fe.gavx, evt[i].fe.gavy, evt[i].fe.entime-evt[i].fe.sttime);
47  }
48  }
49  ...
50  // Other code for drawing and exiting
51  }
52 }

Output:

1 MSG 30244970 Fixupdate: avg_x 863.10, y 244.10, dur 48
2 MSG 30245018 Fixupdate: avg_x 863.10, y 245.60, dur 48
3 MSG 30245070 Fixupdate: avg_x 863.10, y 247.30, dur 48
See also
eyelink_get_float_data(), eyelink_get_last_data(), eyelink_newest_float_sample() eyelink_get_next_data() and eyelink_newest_sample()
INT16 eyemsg_printf ( const char *  fmt,
  ... 
)

This sends a text message to the EyeLink tracker, which timestamps it and writes it to the EDF data file. Messages are useful for recording trial conditions, subject responses, or the time of important events. This function is used with the same formatting methods as printf(), allowing numbers to be included. Avoid end-of-line characters ("\n") at end of messages. Please note that texts longer than 243 characters will be trimmed.

Parameters
fmtSimilar to printf(), format string plus arguments.
Returns
0 if successfully sent to tracker, else error code.

Example:

1 // This program illustrates the use of eyemsg_printf()
2 
3 #include <eyelink.h>
4 char program_name[100] = "Windows Sample Experiment 2.0";
5 
6 // Add a message to the EDF file
7 eyemsg_printf("RECORDED BY %s", program_name);

Output:

1 MSG 2248248 RECORDED BY Windows Sample Experiment 2.0
See also
eyecmd_printf()
INT16 eyemsg_printf_ex ( UINT32  exectime,
const char *  fmt,
  ... 
)

This allows us to send messages to the Eyelink tracker to be logged into the data file with a time offset. Use it just like printf() to format the message text. Similar to eyemsg_printf() function, texts longer than 243 characters will be trimmed.

Parameters
exectimetime offset that reflects in the message's time stamp
fmtprintf format string
Returns
0 if OK, else error code.

Example:

1 if(open_eyelink_connection(0) !=0)
2  return 0;
3 open_data_file("msgtest.edf");
4 
5 eyemsg_printf("hello");
6 msec_delay(100);
7 eyemsg_printf_ex(-100,"hello1");
8 msec_delay(100);
9 
10 eyemsg_printf_ex(100,"hello2");
11 msec_delay(100);
12 eyemsg_printf("hello3");
13 msec_delay(100);
14 close_data_file();
15 receive_data_file("",".",1);

As you can see in the edf file data generated by the above code, both Message1 and Message2 has the same time stamp and message3 and message4 has the same time stamp.

1 MSG 8004932 Message1
2 MSG 8004932 Message2
3 MSG 8005232 Message3
4 MSG 8005232 Message4

Copyright ©2002-2021, SR Research Ltd.