SR Research Support Site
Macros | Functions
Record control and data collection

Macros

#define RECORD_FILE_SAMPLES   1
 
#define RECORD_FILE_EVENTS   2
 
#define RECORD_LINK_SAMPLES   4
 
#define RECORD_LINK_EVENTS   8
 
#define DONE_TRIAL   0
 
#define TRIAL_OK   0
 
#define REPEAT_TRIAL   1
 
#define SKIP_TRIAL   2
 
#define ABORT_EXPT   3
 
#define TRIAL_ERROR   -1
 

Functions

INT16 eyelink_in_data_block (INT16 samples, INT16 events)
 
INT16 eyelink_wait_for_block_start (UINT32 maxwait, INT16 samples, INT16 events)
 
INT16 eyelink2_mode_data (INT16 *sample_rate, INT16 *crmode, INT16 *file_filter, INT16 *link_filter)
 
INT16 eyelink_mode_data (INT16 *sample_rate, INT16 *crmode, INT16 *file_filter, INT16 *link_filter)
 
INT16 start_recording (INT16 file_samples, INT16 file_events, INT16 link_samples, INT16 link_events)
 
INT16 check_recording (void)
 
void stop_recording (void)
 
INT16 check_record_exit (void)
 

Detailed Description

Functions and constants to control recording and data collection.

Macro Definition Documentation

#define ABORT_EXPT   3

return codes for trial result

#define DONE_TRIAL   0

return codes for trial result

#define RECORD_FILE_EVENTS   2

only active if file open

#define RECORD_FILE_SAMPLES   1

only active if file open

#define RECORD_LINK_EVENTS   8

accept events from link

#define RECORD_LINK_SAMPLES   4

accept samples from link

#define REPEAT_TRIAL   1

return codes for trial result

#define SKIP_TRIAL   2

return codes for trial result

#define TRIAL_ERROR   -1

Bad trial: no data, etc.

#define TRIAL_OK   0

return codes for trial result

Function Documentation

INT16 check_record_exit ( void  )

Checks if we are in Abort menu after recording stopped and returns trial exit code. Call this function on leaving a trial. It checks if the EyeLink tracker is displaying the Abort menu, and handles it if required. The return value from this function should be returned as the trial result code.

Returns
TRIAL_OK if no error.
REPEAT_TRIAL, SKIP_TRIAL, ABORT_EXPT if Abort menu activated.

Example: See start_recording()

See also
check_recording(), eyelink_abort(), start_recording() and stop_recording()
INT16 check_recording ( void  )

Check if we are recording: if not, report an error. Call this function while recording. It will return 0 if recording is still in progress, or an error code if not. It will also handle the EyeLink Abort menu by calling record_abort_handler(). Any errors returned by this function should be returned by the trial function. On error, this will disable realtime mode and restore the heuristic.

Returns
TRIAL_OK (0) if no error.
REPEAT_TRIAL, SKIP_TRIAL, ABORT_EXPT, TRIAL_ERROR if recording aborted.

Example: See start_recording()

See also
check_record_exit(), eyelink_abort(), start_recording() and stop_recording()
INT16 eyelink2_mode_data ( INT16 *  sample_rate,
INT16 *  crmode,
INT16 *  file_filter,
INT16 *  link_filter 
)
INT16 eyelink_in_data_block ( INT16  samples,
INT16  events 
)

Checks to see if framing events read from queue indicate that the data is in a block containing samples, events, or both.

Remarks
The first item in queue may not be a block start even, so this should be used in a loop while discarding items using eyelink_get_next_data(NULL). NOTE: this function did not work reliably in versions of the SLL before v2.0 (did not detect end of blocks).
Parameters
samplesIf non-zero, check if in a block with samples.
eventsIf non-zero, check if in a block with events.
Returns
0 if no data of either masked type is being sent.

Example:

1 // This program illustrates the use of eyelink_in_data_block in a broadcast connection.
2 // First a broadcast connection is opened and data reception from the tracker is reset.
3 // Following that, checks whether the block contains samples or events and make use of this information.
4 
5 #include <eyelink.h>
6 #include <stdio.h>
7 
8 // Initializes the link
9 if(open_eyelink_connection(-1))
10  return -1;
11 
12 ...
13 // Extra code here to check for the tracker status or
14 // wait for the go-signal from the other application
15 
16 // Starts the broadcast connection to the tracker
17 if(eyelink_broadcast_open())
18 {
19  printf("Cannot open broadcast connection to tracker");
20  return -1;
21 }
22 // Enables link data reception by EyeLink DLL
23 eyelink_reset_data(1);
24 
25 // NOTE: this function can discard some link data
26 eyelink_data_switch(RECORD_LINK_SAMPLES | RECORD_LINK_EVENTS);
27 
28 // Makes use of the link data
29 while(eyelink_is_connected())
30 {
31  if(escape_pressed() || break_pressed()) return;
32 
33  // check for new data item
34  i = eyelink_get_next_data(NULL);
35  if(i == 0) continue;
36 
37  // link data block available?
38  if(eyelink_in_data_block(1, 1))
39  {
40  ...
41  // Code to read the link data, etc.
42  }
43 }
See also
eyelink_data_status() and eyelink_wait_for_block_start()
INT16 eyelink_mode_data ( INT16 *  sample_rate,
INT16 *  crmode,
INT16 *  file_filter,
INT16 *  link_filter 
)

After calling eyelink_wait_for_block_start(), or after at least one sample or eye event has been read, returns EyeLink II extended mode data.

Parameters
sample_rateNULL, or pointer to variable to be filled with samples per second.
crmodeNULL, or pointer to variable to be filled with CR mode flag (0 if pupil-only mode, else pupil-CR mode).
file_filterNULL, or pointer to variable to be filled with filter level to be applied to file samples (0 = off, 1 = std, 2 = double filter).
link_filterNULL, or pointer to variable to be filled with filter level to be applied to link and analog output samples (0 = off, 1 = std, 2 = double filter).
Returns
If no data available -1 else 0.

Example:

1 // This program illustrates the use of eyelink2_mode_data to check the sample rate and tracking
2 // mode of the application
3 
4 #include <eyelink.h>
5 #include <stdio.h>
6 
7 int is_eyelink2;
8 
9 // waits till a block of samples, events, or both is begun
10 if(!eyelink_wait_for_block_start(2000, 1, 1))
11 {
12  printf("ERROR: No sample or event been detected!");
13  return -1;
14 }
15 
16 // Gets tracker version
17 is_eyelink2 = (2 == eyelink_get_tracker_version(NULL));
18 
19 // For EyeLink II, determine sample rate and tracking mode
20 if(is_eyelink2 && !eyelink2_mode_data(&sample_rate, &crmode, NULL, NULL))
21 {
22  eyemsg_printf("Sample rate: %d", sample_rate);
23  eyemsg_printf("Tracking mode: %s", crmode?"CR":"Pupil only");
24 }

Output:

1 MSG 1151024 Sample rate: 250
2 MSG 1151024 Tracking mode: CR
INT16 eyelink_wait_for_block_start ( UINT32  maxwait,
INT16  samples,
INT16  events 
)

Reads and discards events in data queue until in a recording block. Waits for up to <timeout> milliseconds for a block containing samples, events, or both to be opened. Items in the queue are discarded until the block start events are found and processed. This function will fail if both samples and events are selected but only one of link samples and events were enabled by start_recording().

Remarks
This function did not work in versions previous to 2.0.
Parameters
maxwaitTime in milliseconds to wait.
samplesIf non-zero, check if in a block with samples.
eventsIf non-zero, check if in a block with events.
Returns
0 if time expired without any data of masked types available.

Example:

1 // This program illustrates the use of eyelink_wait_for_block_start
2 
3 #include <eyelink.h>
4 #include <stdio.h>
5 
6 // Starts recording with both sample and events to the file and link
7 if(start_recording(1,1,1,1)!= 0)
8  return -1; // ERROR: couldn't start recording
9 
10 // record for 100 msec before displaying stimulus
11 begin_realtime_mode(100);
12 
13 // wait for link sample data
14 if(!eyelink_wait_for_block_start(100, 1, 0))
15 {
16  printf("ERROR: No link samples received!");
17  return TRIAL_ERROR;
18 }
19 
20 // determine which eye(s) are available
21 eye_used = eyelink_eye_available();
22 switch(eye_used) // select eye, add annotation to EDF file
23 {
24  case RIGHT_EYE:
25  eyemsg_printf("EYE_USED 1 RIGHT");
26  break;
27  case BINOCULAR: // both eye's data present: use left eye only
28  eye_used = LEFT_EYE;
29  case LEFT_EYE:
30  eyemsg_printf("EYE_USED 0 LEFT");
31  break;
32 }
INT16 start_recording ( INT16  file_samples,
INT16  file_events,
INT16  link_samples,
INT16  link_events 
)

Starts the EyeLink tracker recording, sets up link for data reception if enabled.

Remarks
Recording may take 10 to 30 milliseconds to begin from this command. The function also waits until at least one of all requested link data types have been received. If the return value is not zero, return the result as the trial result code.
Parameters
file_samplesIf 1, writes samples to EDF file. If 0, disables sample recording.
file_eventsIf 1, writes events to EDF file. If 0, disables event recording.
link_samplesIf 1, sends samples through link. If 0, disables link sample access.
link_eventsIf 1, sends events through link. If 0, disables link event access.
Returns
0 if successful, else trial return code.

Example:

1 // This program illustrates the use of start_recording(), stop_recording(), checking_recording(),
2 // and check_record_exit()
3 
4 #include <eyelink.h>
5 
6 // Starts data recording to EDF file
7 // Records samples and events to EDF file only in this example
8 // Returns error code if failed
9 error = start_recording(1,1,0,0);
10 if(error != 0) return error;
11 
12 // Sets up for realtime execution
13 begin_realtime_mode(100);
14 
15 ...
16 // Display drawing code here
17 
18 // Trial loop
19 while(1)
20 {
21  // Checks if recording aborted
22  if((error=check_recording())!=0) return error;
23  ...
24  // Other code for display updates, timing, key or button
25  // response handling
26 }
27 
28 // Ensures we release realtime lock
29 end_realtime_mode();
30 // Records additional 100 msec of data
31 pump_delay(100);
32 // halt recording, return when tracker finished mode switch
33 stop_recording();
34 
35 while(getkey()); // dump any accumulated key presses
36 
37 // Call this at the end of the trial, to handle special conditions
38 return check_record_exit();
See also
check_record_exit(), check_recording(), eyelink_data_start() and stop_recording()
void stop_recording ( void  )

Stops recording, resets EyeLink data mode.

Remarks
Call 50 to 100 msec after an event occurs that ends the trial. This function waits for mode switch before returning.

Example: See start_recording()

See also
eyelink_data_stop(), set_offline_mode() and start_recording()

Copyright ©2002-2021, SR Research Ltd.