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,...) |
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()
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.<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()
INT16 eyelink_data_switch | ( | UINT16 | flags | ) |
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()
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.
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.
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.
0
if no data, SAMPLE_TYPE
if sample, else event type code.Example: See eyelink_get_next_data()
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.
0
if no data, SAMPLE_TYPE
if sample, else event type code.Example: See eyelink_get_next_data()
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()
.
0
if no data, SAMPLE_TYPE
if sample, else event type code.Example:
Output:
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.
buf | If NULL , saves data, else copies integer data into buffer. |
0
if no data, SAMPLE_TYPE
if sample, else event type.Example:
Output:
INT16 eyelink_get_sample | ( | ISAMPLE * | sample | ) |
Gets an integer (unconverted) sample from end of queue, discards any events encountered.
0
if no data. 1
if data retrieved.Example:
Output:
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.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:
Output:
This program illustrates the use of eyelink_newest_float_sample to get remote data online
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()
.
0
if no data, else SAMPLE_TYPE
.Example:
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.
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()
INT16 eyelink_node_send | ( | ELINKADDR | node, |
void FARTYPE * | data, | ||
UINT16 | dsize | ||
) |
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:
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.
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()
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.
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 FARTYPE * | 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()
INT16 eyelink_reset_data | ( | INT16 | clear | ) |
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()
INT16 eyelink_send_message_ex | ( | UINT32 | exectime, |
char FARTYPE * | msg | ||
) |
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: <pre>
INT16 eyelink_timed_command | ( | UINT32 | msec, |
char FARTYPE * | text | ||
) |
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.INT16 eyelink_wait_for_command_result | ( | UINT32 | timeout | ) |
Waits 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.INT16 eyelink_wait_for_data | ( | UINT32 | maxwait, |
INT16 | samples, | ||
INT16 | events | ||
) |
Counts total items in queue: samples, events, or both.
samples | If non-zero count the samples. |
events | If non-zero count the events. |
Example:
*/ 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.
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.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
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. 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.
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:
Output:
This program illustrates the use of eyelink_newest_float_sample to get remote data online
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
buf | Pointer to sample buffer type ISAMPLE . If NULL , just checks new-sample status. |
-1
if no samples, 0
if no new data, 1
if new 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>
Output:
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.
fmt | Similar to printf(), format string plus arguments. |
0
if successfully sent to tracker, else error code.Example:
Output:
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.
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.