Data Structures | |
| struct | FSAMPLE |
| Floating-point sample. More... | |
| struct | FSAMPLE2 |
| Floating-point sample. More... | |
| struct | DSAMPLE |
| Floating-point sample with floating point time. More... | |
| struct | DSAMPLE2 |
| Floating-point sample with floating point time. More... | |
| struct | FEVENT |
| Floating-point eye event. More... | |
| struct | FEVENT2 |
| Floating-point eye event. More... | |
| struct | DEVENT |
| Floating-point eye event with floating point time. More... | |
| struct | DEVENT2 |
| Floating-point eye event with floating point time. More... | |
| struct | IMESSAGE |
| Message events: usually text but may contain binary data. More... | |
| struct | DMESSAGE |
| Like IMESSAGE but 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 | ALL_DATA |
| Union of message, io event and integer sample and integer event. More... | |
| union | ALLF_DATA |
| Union of message, io event and float sample and float event. The FEVENT2 (fe2) and FSAMPLE2 (fs2) members contain additional data for the EyeLink 3. This defaults to 0 or MISSING if used with a preceding model of camera. More... | |
| union | ALLD_DATA |
| Union of message, io event and double sample and double event. The DEVENT2 (fe2) and DSAMPLE2 (fs2) members contain additional data for the EyeLink 3. This defaults to 0 or MISSING if used with a preceding model of camera. More... | |
| 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.
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.| fmt | Similar to printf(), format string plus arguments. |
0 if successfully executed, else error code.Example:
Output:
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.
NO_REPLY if no reply to last command.OK_RESULT (0) if OK.eyelink_send_command() Counts total items in queue: samples, events, or both.
| samples | If non-zero count the samples. |
| events | If non-zero count the events. |
Example:
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.<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. | flags | Bitwise OR of flags to control what data is recorded. If 0, recording will be stopped. |
| lock | If nonzero, prevents 'ESC' key from ending recording. |
0 if command sent OK, else link error.Example:
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.
ILINKDATA structure.Example:
Output:
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.
eyelink_wait_for_mode_ready(). 0 if command sent OK, else link error.Example: See eyelink_data_start()
eyelink_data_start() and eyelink_wait_for_mode_ready() Sets what data from tracker will be accepted and placed in queue.
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. | flags | Bitwise OR flags. |
0 if OK else link error.Example: See eyelink_in_data_block()
eyelink_in_data_block() | UINT16 eyelink_event_data_flags | ( | void | ) |
Returns the event data content flags.
0 if the data being read from queue is not in a block with events. 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:
Output:
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.
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()
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.
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:
Output:
eyelink_wait_for_block_start() Reads all the item in the queue and fetch them into a buffer. The events are converted to a floating-point format (FSAMPLE, FSAMPLE2, FEVENT, or FEVENT2). 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. Note that FSAMPLE2 & FEVENT2 both contain extra data for the EyeLink 3 that defaults to 0 or MISSING with preceding camera models.
| buf | Pointer to an array buffer for floating-point data: type is ALLF_DATA |
| bufferlen | Length of the bufffer. |
Example:
| EYELINK_DATA_READY_NOTIFY eyelink_get_data_ready_notify | ( | void | ) |
Returns the current notification callback function.
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, DSAMPLE2, DEVENT, or DEVENT2). 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. Note that DSAMPLE2 & DEVENT2 both contain extra data for the EyeLink 3 that defaults to 0 or MISSING with preceding camera models.
0 if no data, SAMPLE_TYPE if sample, else event type code.Example: See eyelink_get_next_data()
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. The fe2 and fs2 members of ALLF_DATA contain extra data for the EyeLink 3 that default to 0 or missing when used with preceding camera models.
0 if no data, SAMPLE_TYPE if sample, else event type code.Example: See eyelink_get_next_data()
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.
| buf | If NULL, saves data, else copies integer data into buffer. |
0 if no data, SAMPLE_TYPE if sample, else event type.Example:
Output:
eyelink_get_float_data(), and eyelink_newest_float_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.
| buf | String buffer to return text message. |
0 if no message since last command sent, otherwise length of string.Example: See eyelink_timed_command()
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.
| buf | Pointer to sample buffer type DSAMPLE. If NULL, just checks new-sample status. |
-1 if no samples, 0 if no new data, 1 if new sample.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 DSAMPLE2 buffer to get the new sample. DSAMPLE2 contains extra data for the EyeLink 3 that defaults to 0 or MISSING with preceding camera models.
| buf | Pointer to sample buffer type DSAMPLE2. If NULL, just checks new-sample status. |
-1 if no samples, 0 if no new data, 1 if new 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.
| buf | Pointer to sample buffer type FSAMPLE. If NULL, just checks new-sample status. |
-1 if no samples, 0 if no new data, 1 if new sample.Example 1:
Output:
Example 2:
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 FSAMPLE2 buffer to get the new sample. FSAMPLE2 contains extra data for the EyeLink 3 that defaults to 0 or MISSING with preceding camera models.
| buf | Pointer to sample buffer type FSAMPLE2. If NULL, just checks new-sample status. |
-1 if no samples, 0 if no new data, 1 if new sample.Example 1:
Output:
Example 2:
Checks for and gets the last packet received, stores the data and the node address sent from.
| node | Address of the sender. |
| data | Pointer to a buffer to hold the data. |
0 if successful, otherwise link error.Example: See eyelink_node_send()
Sends a given data to the given node.
| node | ELINKADDR node address. |
| data | Pointer to buffer containing data to send. |
| dsize | Number of bytes of data. Maximum ELREMBUFSIZE bytes. |
0 if successful, otherwise link error.Example 1:
Example 2:
eyelink_get_node(), eyelink_node_receive() and eyelink_open_node() Sends a text message the connected eye tracker. The text will be added to the EDF file.
set_eyelink_address(). | msg | Text to send to the tracker. |
| node | Address of the tracker. |
0 if no error, else link error code.Example: See eyelink_quiet_mode()
Send a data file message to any or all trackers with time offset.
| exectime | time offset. If the offset is 0, this function is the same as eyelink_node_send_message() |
| node | Node address |
| msg | Message to be sent |
OK_RESULT or LINK_TERMINATED_RESULT. | INT16 eyelink_position_prescaler | ( | void | ) |
| INT16 eyelink_read_reply | ( | char FARTYPE * | buf | ) |
Returns text with reply to last read request.
| buf | String to contain text. |
OK_RESULT (0) if response received.NO_REPLY if no response yet.Example: See eyelink_read_request()
eyelink_read_request() | INT16 eyelink_read_request | ( | char const * | text | ) |
Sends a text variable name whose value is to be read and returned by the tracker as a text string.
set_eyelink_address(). However, these requests will be ignored by tracker versions older than EyeLink I v2.1 and EyeLink II v1.1. | text | String with message to send. |
0 if success, otherwise link error code.Example:
Output:
eyelink_read_reply() Prepares link buffers to receive new data. If <clear> is nonzero, removes old data from buffer.
| clear | If clear is non-zero, any buffer data is discarded. |
0.Example: See eyelink_in_data_block()
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.
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().| text | String command to send. |
0 if successful, otherwise link error.Example:
Output:
| INT16 eyelink_send_message | ( | char FARTYPE * | msg | ) |
Sends a text message the connected eye tracker. The text will be added to the EDF file.
| msg | Text to send to the tracker. |
0 if no error, else link error code.Example: See eyelink_quiet_mode()
Send a data file message string to connected tracker with time offset.
| exectime | time offset. If the offset is 0, this function is the same as eyelink_send_message() |
| msg | Message to be sent |
OK_RESULT or LINK_TERMINATED_RESULT. | 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.
| notify_function | pointer 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:
Sends a command to the connected eye tracker, wait for reply.
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(). | text | String command to send. |
| msec | Maximum milliseconds to wait for reply. |
OK_RESULT (0) if OK.NO_REPLY if timed out.LINK_TERMINATED_RESULT if cannot send.Waits for and retrieves the numeric result code sent by the tracker from the last command.
| timeout | Amount of time to wait for, in milliseconds. |
NO_REPLY if no reply to last command.OK_RESULT (0) if OK.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.
| maxwait | Time in milliseconds to wait for data. |
| samples | If 1, return when first sample available. |
| events | If 1, return when first event available. |
1 if data is available. 0 if timed out.Example:
eyelink_wait_for_block_start() 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
| buf | Pointer to sample buffer type DSAMPLE. If NULL, just checks new-sample status. |
| timeout | Number of attempts to make at waiting for a new sample. |
-1 if no samples, 0 if no new data, 1 if new sample.Waits for a new sample to arrive on the link. Exactly the same as eyelink_wait_for_new_float_sample2() except the data type is DSAMPLE2. As with FSAMPLE2, this contains extra data for the EyeLink 3, which defaults to 0 or MISSING with preceding camera models.
| buf | Pointer to sample buffer type DSAMPLE2. If NULL, just checks new-sample status. |
| timeout | value in milliseconds to wait for a sample. |
-1 if no samples, 0 if no new data, 1 if new sample.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.
| buf | Pointer to sample buffer type FSAMPLE. If NULL, just checks new-sample status. |
| timeout | Number of attempts to make at waiting for a new sample. |
-1 if no samples, 0 if no new data, 1 if new sample.Example 1:
Output:
Example 2:
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. The difference between eyelink_wait_for_new_float_sample and eyelink_wait_for_new_float_sample2 is that it fills an FSAMPLE2 that has more fields than an FSAMPLE. These contain EyeLink 3 specific data that defaults to 0 or MISSING with preceding camera models.
If the function is called with a NULL buffer pointer, then the behaviour is exactly the same as eyelink_newest_float_sample(). If an FSAMPLE2 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.
| buf | Pointer to sample buffer type FSAMPLE2. If NULL, just checks new-sample status. |
| timeout | value in milliseconds to wait for a sample. |
-1 if no samples, 0 if no new data, 1 if new sample.Example 1:
Output:
Example 2:
Blocks upon the appearance of data in the link buffer. Returns when data is available, or when an internal timer has expired. Data from the link buffer will be loaded into a return buffer, if it is provided. The primary advantage of this function is that it reduces the consumption of processor time, in comparison with busy waiting in a loop that repeatedly calls eyelink_get_next_data at the maximum rate.
| buf | Address to the first element of an array of ALLFDATA objects. In other words, this is the pointer to a memory buffer with a size that is an integer multiple of sizeof( ALLFDATA ). NULL may be given instead to indicate that no data should be removed and returned from the link buffer. |
| bufferlen | The number of elements in 'buf'. This parameter is ignored when 'buf' is NULL; set it to zero in this case. |
| timeout | Duration of the timer. The value is taken to be a multiple of 10 milliseconds; i.e. the unit of measurement is centiseconds. Thus, a value of 5 cs will cause the timer to expire after 50 milliseconds. A value of zero will start a default timer of 20 cs. |
0 when the timer expires before data arrives in the link buffer. \c SAMPLE_TYPE or the event type (e.g. \c ENDSACC, \c STARTFIX,
etc.) when 'buf' is \c NULL.
<tt>1 <= N <= bufferlen</tt> when 'buf' is the address of a memory
buffer. \N is the number of items that were copied from the link
buffer into the 'buf' array.
eyelink_get_next_data(NULL) when 'buf' is NULL and data appears in the link buffer prior to the expiry of the timer. Indeed, a call to eyelink_wait_for_next_data(NULL,0,0) is exactly equivalent. The implication is that the first available item of data in the link buffer will be ready for retrieval by a subsequent call to eyelink_get_float_data.The fe2 and fs2 members of ALLF_DATA contain extra data for the EyeLink 3 that defaults to 0 or MISSING with older camera models.
Example 1
This program illustrates how to wait for link data that is copied into an array buffer.
Output from a test run of the code shown above.
Example 2
Block on the arrival of new link data and then process link items in the conventional way. This approach has the advantage of being able to process an arbitrary number of data items without any requirement to allocate an array.
Waits for a new double data to arrive on the link. Exactly the same as eyelink_wait_for_next_data() except the data type is ALLD_DATA
| buf | If NULL, saves data, else copies double data into buffer. Buffer should be of bufferlen times ALLD_DATA. Note, fe2 and fs2 members of ALLF_DATA contain extra data for the EyeLink 3 that defaults to 0 or MISSING with preceding camera models. |
| bufferlen | length of ALLD_DATA array. eg. 5 would mean, array of 5 elements of type ALLD_DATA |
| 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. |
0 if no data, SAMPLE_TYPE or else event type if NULL buffer is given. n number of items copied if buffer is given. | 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. In general avoid end-of-line characters ("\n") at end of messages. Multiple messages can be sent to the tracker with "\n" delimiter with a single call. Please note that texts longer than 243 characters will be split into multiple messages and sent to the tracker.
| fmt | Similar to printf(), format string plus arguments. |
0 if successfully sent to tracker, else error code.Example:
Output:
eyecmd_printf() 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.
| exectime | time offset that reflects in the message's time stamp |
| fmt | printf format string |
0 if OK, else error code.Example:
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.