EyelinkToolbox

>Psychtoolbox>PsychHardware>EyelinkToolbox

EyelinkToolbox.

The EyelinkToolbox can be used to ceate eye-movement experiments and control the SR-Research Eyelink(c) gazetrackers (http://www.eyelinkinfo.com/) from within Matlab and Octave.

It is incorporated into the PsychToolbox (http://www.psychtoolbox.org/).

It provides an interface to the Eyelink Gazetracker.

It uses a very similar approach as the PsychToolBox and uses the functions provided by the PsychToolBox for graphics and sound.

How to start using it:

The EyelinkToolbox is a collection of m-files and a Mex file. The EyelinkToolbox core is the mex/dll-file called Eyelink. The EyelinkToolbox uses the same approach as the SCREEN mex/dll function provided in the PsychToolBox. Most of the Eyelink functions that are avaible in C are also available under Matlab. In addition, the EyelinkToolbox provides a number of wrapper functions to simplify creating an eye-tracking program. The main functionality of the EyelinkToolbox is demonstrated in a number of demos. This is probably where you want to start if you are new to the EyelinkToolbox.

To use Eyelink, you must also install the SR-Research runtime libraries, downloadable from the Support Section of their website (see above).

For a complete list of available functions type "Eyelink" in the command window. For an explanation of any particular eyelink function just add a question mark "?" after a command. E.g. for help on the function 'Initialize', try either of these equivalent forms:

Eyelink('Initialize?') Eyelink Initialize?

Contents of the EyelinkToolbox folder:

-Contents.m: this file.

-Changes.m: file that documents changes to the EyelinkToolbox

-EyelinkBasic Eyelink mex files and a collection of m-files that provide the core functionality of the toolbox.

-EyelinkDemos EyelinkShortDemos is the best place to start. Contains relatively simple demos. The SR-Research Demo folder is a slightly more elaborate example. The folder BRMIC contains the original example as shown in the EyelinkToolbox article in BRMIC (Cornelissen, Peters and Palmer 2002). It is obsolete in many ways but left in the toolbox for historic reasons.

-EyelinkOneLiners Handy routines that provide less essential functionality

We welcome any observations, suggestions that may help us improve this toolbox. If any particular function you need is still missing, let us know and we'll try to incorporate it into a next release. In case you decide to add or modify functions yourself, please send us the modified code. If you think you've found a bug, please tell us. It will help greatly if you can supply a minimal-length program that exhibits the bug. If you're interested in the c-source code of this project, it is part of the source code of the PsychToolbox (http://www.psychtoolbox.org/).

******Citing the use of the Eyelink Toolbox******

We would very much appreciate it if you would (also) cite the EyelinkToolbox paper when you have used the toolbox in your work. You could write something like:

We wrote our experiments in Matlab, using the Psychophysics and Eyelink Toolbox extensions (Kleiner 2007; Brainard, 1997; Pelli, 1997; Cornelissen, Peters & Palmer, 2002; see http://psychtoolbox.org).

Kleiner M, Brainard D, Pelli D, 2007, "What's new in Psychtoolbox-3?" Perception 36 ECVP Abstract Supplement.

Brainard, D. H. (1997) The Psychophysics Toolbox, Spatial Vision 10:433-436. Cornelissen, F.W., Peters. E., Palmer, J. (2002).

The Eyelink Toolbox: Eye tracking with MATLAB and the Psychophysics Toolbox. Behavior Research Methods, Instruments & Computers, 34, 613-617.

Pelli, D. G. (1997) The VideoToolbox software for visual psychophysics: Transforming numbers into movies, Spatial Vision 10:437-442. This toolbox is also actively supported and co-developed by SR-Research (http://www.eyelinkinfo.com), the manufacturer of the Eyelink gazetrackers. You can contact them about it. However, if your problem is likely of interest to other users as well, then please post questions on the PsychToolbox mailinglist, which is also monitored by SR-Research.

The EyelinkToolbox and its source code are copyright Enno Peters, Frans Cornelissen and John Palmer. Additional copyrights for some contributed functions are SR-Research and the respective individual developers of those functions.

(Type "Eyelink" or Eyelink('Version') for authors). The toolbox is freely useable and redistributable under the terms of the MIT license. The exact license text is included inside License.txt in the root folder of any Psychtoolbox-3 installation.

Disclaimer: we cannot be hold responsible for any damage that may (appear to) be caused by the use of this toolbox. Use at your own risk!

Frans W. Cornelissen 22nd July 2010 email: f.w.cornelissen@med.umcg.nl

Enno Peters, Frans Cornelissen and John Palmer Groningen, 27-11-2002

EyelinkDemos

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkdemos

EyelinkToolbox:EyelinkDemos Demos of eyelink toolbox functions and demos that may serve as a starting point for your own experiments

SR-ResearchDemos

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkdemos>sr-researchdemos

EyeLink systems allow for rich integration between a Display PC (the computer running Psychtoolbox) and the EyeLink Host PC via an ethernet connection using the EyeLink application programming interface (API). The API can be installed by downloading the EyeLink Developers Kit from our Support site:

https://https://www.sr-support.com/thread-13.html

You will also need to configure your Display PC network settings. See this link for more details:

https://https://www.sr-support.com/thread-58.html

Psychtoolbox interfaces with the EyeLink API via the 'Eyelink Toolbox' which can be found in the Psychtoolbox root folder > PsychHardware. You can add EyeLink integration code to your own Psychtoolbox script to interact with the Host PC so your experiment can:

• initialize an EyeLink connection
• open an EyeLink data file (edf) on the Host PC and name it
• set some EyeLink-specific parameters /change various default options
• put Host PC in 'Camera Setup' mode and allow for:
  • transfer of eye image to Display PC for ease of participant setup
  • presentation of targets on Display PC monitor for participant calibration / validation
• transfer text, image and/or other graphics to the Host PC at the beginning of each trial for experimenter feedback
• do a drift-check / correction
• start recording eye movement data at the beginning of each trial (or block)
• during a trial write messages in the edf file to mark time of events
• write messages in the edf file for rich integration with Data Viewer
• stop recording at the end of each trial (or block)
• towards the end of a session close the edf and transfer a copy to the Display PC
• close the EyeLink connection

EyeLink integration also allows for online access of eye movement data for gaze-contingent experiments.

In a typical task eye movements are recorded onto the EyeLink Host PC on a trial-by-trial basis: recording starts at the beginning of a trial and ends at the end of a trial. This allows for an optional drift-check/correction and for transferring of images to the Host PC between trials. However this trial-based recording might not be suitable for paradigms that require a fixed ITI. In such cases it is possible to record continuously throughout a block or session.

The following is a list of Psychtoolbox demos with EyeLink integration that are included with the EyeLink Toolbox:

SimplePicture > eyelink_simplepicture.m

A simple EyeLink integration demo that records eye movements while an image is presented on the screen. Each trial ends when the space bar or a button is pressed.

GazeContingent

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkdemos>sr-researchdemos>gazecontingent

EyelinkToolbox:EyelinkDemos:sr-researchdemos:gazecontingent Demos provided by SR-Research to demonstrate a few different ways of implementing gaze contingent functionality

GC Demos located in the following subfolders: ./FixWindowBufferedSamples ./FixWindowFastSamples ./GCBufferedEvents/BufferedEndSacEvents ./GCBufferedEvents/BufferedFixUpdateEvents ./GCFastSamples

FixWindowBufferedSamples

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkdemos>sr-researchdemos>gazecontingent>fixwindowbufferedsamples

EyelinkToolbox:EyelinkDemos:sr-researchdemos:gazecontingent:eyelink_fixwindowbufferedsamples EyeLink gaze-contingent demo that shows how to retrieve online gaze samples from a buffer. In each trial central crosshairs are shown until gaze is detected continuously within a central square window for 500ms or until the space bar is pressed. An image is then presented until the space bar is pressed to end the trial.

Usage: Eyelink_FixWindowBufferedSamples(screennumber)

FixWindowFastSamples

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkdemos>sr-researchdemos>gazecontingent>fixwindowfastsamples

EyelinkToolbox:EyelinkDemos:sr-researchdemos:gazecontingent:eyelink_fixwindowfastsamples EyeLink gaze-contingent demo showing how to retrieve fast gaze samples online. In each trial central crosshairs are shown until gaze is detected continuously within a central square window for 500ms or until the space bar is pressed. An image is then presented until the space bar is pressed to end the trial.

Usage: Eyelink_FixWindowFastSamples(screennumber)

BufferedEndSacEvents

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkdemos>sr-researchdemos>gazecontingent>gcbufferedevents>bufferedendsacevents

EyelinkToolbox:EyelinkDemos:sr-researchdemos:gazecontingent:gcbufferedevents:eyelink_bufferedendsacevents A simple EyeLink gaze-contingent demo showing how to retrieve online events from a buffer. In each trial an image is presented with a red gaze-contingent dot overlaid on top. The dot's location is updated online based on the end x y coordinates of each saccade detected. Each trial ends when the space bar is pressed.

Usage: Eyelink_BufferedEndSacEvents(screennumber)

BufferedFixUpdateEvents

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkdemos>sr-researchdemos>gazecontingent>gcbufferedevents>bufferedfixupdateevents

EyelinkToolbox:EyelinkDemos:sr-researchdemos:gazecontingent:gcbufferedevents:eyelink_bufferedfixupdateevents A simple EyeLink gaze-contingent demo showing how to retrieve online events from a buffer. In each trial an image is presented with a red gaze-contingent dot overlaid on top. The dot's location is based on the average x y coordinates of fixations updated online every 50ms via a FIXUPDATE event. See EyeLink Programmers Guide manual > Experiment Templates Overview > Control > Fixation Update Events Each trial ends when the space bar is pressed.

PursuitTarget

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkdemos>sr-researchdemos>pursuittarget

EyelinkToolbox:EyelinkDemos:sr-researchdemos:eyelink_pursuittarget A smooth pursuit EyeLink integration demo that records eye movements while a target moves sinusoidally across the screen. Each trial ends after 5s.

Illustrates how to: - change the drift-check/correction target location before each trial - create a moving target for Data Viewer's Play Back Animation view - create dynamic target location for Data Viewer's Temporal Graph view and sample reports - create target dynamic interest areas for Data Viewer

Usage: Eyelink_PursuitTarget(screennumber)

SimplePicture

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkdemos>sr-researchdemos>simplepicture

EyelinkToolbox:EyelinkDemos:sr-researchdemos:simplepicture Demo provided by SR-Research showing basic EyeLink integration conventions for tracking eye movements over top of a picture stimulus. This demo also shows how to use image files in place of the default calibration /validation/drift check/drift correct targets.

SimpleVideo

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkdemos>sr-researchdemos>simplevideo

EyelinkToolbox:EyelinkDemos:sr-researchdemos:eyelink_simplevideo Simple video demo with EyeLink integration and animated calibration / drift-check/correction targets. In each trial eye movements are recorded while a video stimulus is presented on the screen. Each trial ends when the space bar is pressed or the video stops playing. A different drift-check/correction animated target is used in each of the 2 trials.

Illustrates how a video file can be added for trial play back in Data Viewer's "Trial Play Back Animation" view.

Usage: Eyelink_SimpleVideo(screennumber)

StereoPicture

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkdemos>sr-researchdemos>stereopicture

EyelinkToolbox:EyelinkDemos:sr-researchdemos:eyelink_stereopicture EyeLink integration demo for stereo presentation. Records eye movements passively while presenting a stereo stimulus. Supports both split-screen mode and dual-monitor setup. Each trial ends when the space bar is pressed. Data Viewer integration with both left and right eyes superimposed on the same eye window view

Usage: Eyelink_StereoPicture(stereomode, screennumber)

EyelinkBasic

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkbasic

collection of essential functions for the eyelink toolbox EyelinkToolbox:EyelinkBasic

Eyelink

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkbasic

The EyelinkToolbox can be used to ceate eye-movement experiments and control the SR-Research Eyelink gazetrackers (http://www.eyelinkinfo.com/) from within Octave and Matlab.

It is incorporated into the PsychToolbox (http://www.psychtoolbox.org/) and uses the functions provided by the PsychToolbox for graphics and sound.

To use Eyelink, you must also install the SR-Research runtime libraries, downloadable from the Support Section of their website (see above).

For a complete list of available functions type "Eyelink" in the command window. For an explanation of any particular Eyelink function just add a question mark "?" after a command.

E.g. for 'Initialize', try either of these equivalent forms: Eyelink('Initialize?') Eyelink Initialize?

[optional arguments]: Brackets in the function list, e.g. [remport], indicate optional arguments, not matrices. Optional arguments must be in order, without omitting earlier ones.

If you need examples to get you started, check out the EyelinkDemos folder (help EyelinkDemos).

More information on this toolbox can be found in the file: EyelinkToolbox/contents.m (help EyelinkToolbox)

EyelinkCalDoneBeep

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkbasic

EyelinkCalTargetBeep

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkbasic

not sure yet about OSX sound routines

EyelinkClearCalDisplay

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkbasic

EyelinkDoDriftCorrect

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkbasic

USAGE: result=EyelinkDoDriftCorrect(el [, x, y, draw, allowsetup])

el: eyelink default values x,y: position of driftcorrection target draw: set to 1 to draw driftcorrection target allowsetup: set to 1 to allow to go in to go to trackersetup

Note that EyelinkDoDriftCorrect() internally uses Beeper() and Snd() to play auditory feedback tones if el.targetbeep=1 or el.feedbackbeep=1 and the el.callback function is set to the default PsychEyelinkDispatchCallback(). If you want to use PsychPortAudio in a script that also calls EyelinkDoDriftCorrect, then read "help Snd" for instructions on how to provide proper interoperation between PsychPortAudio and the feedback sounds created by Eyelink.

EyelinkDoDriftCorrection

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkbasic

success=EyelinkDoDriftCorrection(el [, x][, y][, draw][, allowsetup])

DO PRE-TRIAL DRIFT CORRECTION We repeat if ESC key pressed to do setup. Setup might also have erased any pre-drawn graphics.

Note that EyelinkDoDriftCorrection() internally uses Beeper() and Snd() to play auditory feedback tones if el.targetbeep=1 or el.feedbackbeep=1 and the el.callback function is set to the default PsychEyelinkDispatchCallback(). If you want to use PsychPortAudio in a script that also calls EyelinkDoDriftCorrection, then read "help Snd" for instructions on how to provide proper interoperation between PsychPortAudio and the feedback sounds created by Eyelink.

EyelinkDoTrackerSetup

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkbasic

USAGE: result=EyelinkDoTrackerSetup(el [, sendkey])

el: Eyelink default values

sendkey: set to go directly into a particular mode sendkey is optional and ignored if el.callback is defined for callback based tracker setup.

       'v', start validation
       'c', start calibration
       'd', start driftcorrection
       13, or el.ENTER\_KEY, show 'eye' setup image

Note that EyelinkDoTrackerSetup() internally uses Beeper() and Snd() to play auditory feedback tones if el.targetbeep=1 or el.feedbackbeep=1 and the el.callback function is set to the default PsychEyelinkDispatchCallback(). If you want to use PsychPortAudio in a script that also calls EyelinkDoTrackerSetup, then read "help Snd" for instructions on how to provide proper interoperation between PsychPortAudio and the feedback sounds created by Eyelink.

EyelinkDrawCalTarget

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkbasic

draw simple calibration target

USAGE: rect=EyelinkDrawCalTarget(el, x, y)

    el: eyelink default values
    x,y: position at which it should be drawn
    rect: 

EyelinkEraseCalTarget

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkbasic

erase calibration target

USAGE: erasecaltarget(el, rect)

    el: eyelink default values
    rect: rect that will be filled with background colour 

EyelinkGetKey

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkbasic

USAGE: [key, el]=EyelinkGetKey(el)

el: eyelink default values, also stores getkeytime (last time this function was used)

EyelinkInitDefaults

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkbasic

Initialize eyelink defaults and control code structure

USAGE: el=EyelinkInitDefaults([window])

   window is optional windowPtr.
   If set, pixel coordinates are send to eyetracker

and fill it with some sensible values. Note that these values are only used by the m-file versions of dotrackersetup and dodriftcorrect.

EyelinkTargetModeDisplay

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkbasic

USAGE: result=EyelinkTargetModeDisplay(el)

    el: Eyelink default values

History 15-05-01 fwc created first version 22-05-01 fwc little debugging 02-06-01 fwc removed use of global el, as suggested by John Palmer. 22-06-06 fwc OSX-ed

EyelinkUpdateDefaults

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkbasic

USAGE = EyelinkUpdateDefaults(el)

This function passes changes to the calibration defaults structure to the callback function. To be called after EyelinkInitDefaults if any changes are made to the output structure of that function.

el=EyelinkInitDefaults(window); el.backgroundColour = BlackIndex(window); EyelinkUpdateDefaults(el);

27-1-2011 NJ created 19-12-2012 IA Fix hardcoded callback

PsychEyelinkDispatchCallback

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkbasic

Retrieve live eye-image from Eyelink, show it in onscreen window.

This function is normally called from within the Eyelink() mex file. Normal user code only calls it once to supply the eyelink defaults struct. This is handled within the EyelinkInitDefaults.m file, so you generally should not have to worry about this. However, if you change settings in the el structure, you may need to call it yourself.

To define which onscreen window the eye image should be drawn to, call it with the return value from EyelinkInitDefaults, e.g., w=Screen('OpenWindow', ...); el=EyelinkInitDefaults(w); myEyelinkDispatchCallback(el);

to actually receive and display the images, register this function as eyelink's callback: if Eyelink('Initialize', 'myEyelinkDispatchCallback') ~=0 error('eyelink failed init') end result = Eyelink('StartSetup',1) %put the tracker into a mode capable of sending images then you must hit 'return' on the PTB computer, this key command will be sent to the tracker host to initiate sending of images.

This function fetches the most recent live image from the Eylink eye camera and displays it in the previously assigned onscreen window.

History: 15.3.2009 Derived from MemoryBuffer2TextureDemo.m (MK). 4.4.2009 Updated to use EyelinkGetKey + fixed eyelinktex persistence crash (edf). 11.4.2009 Cleaned up. Should be ready for 1st release, although still pretty alpha quality. (MK). 15.6.2010 Added some drawing routines to get standard behaviour back. Enabled use of the callback by default. Clarified in helptext that user normally should not have to worry about calling this file. (fwc) 20.7.2010 drawing of instructions, eye-image+title, playing sounds in seperate functions

1.2.2010 modified to allow for cross hair and fix bugs. (nj) 29.10.2018 Drop 'DrawDots' for calibration target. Some white-space fixes.

EyelinkOneLiners

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

EyelinkToolbox:EyelinkBasic essential functions for use with the eyelinktoolbox

geteventtype

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

EVENT types

EyelinkDummyModeDlg

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

Puts up a dialog asking to run in dummy mode.

EyelinkGetEyeTracked

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

get eye information and send message for EDF file returns el.RIGHT_EYE or el.LEFT_EYE +1, for array access

EyelinkGetTime

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

USAGE: eltime=EyelinkGetTime(el [, maxwait]) Get tracker time

el: is eyelinkdefault structure maxwait: specifies maximum time to wait for a tracker time event if omitted, will wait indefinetely

EyelinkInit

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

USAGE: [result dummy]=EyelinkInit([dummy=0][enableCallbacks=1])

Initialize Eyelink system and connection. Optional arguments:

dummy: Omit, or set to 0 to attempt real initialization, set to 1 to enforce to use initializedummy for dummy mode.

    If regular initialization fails, it will provide option
    for dummy initilization.

enableCallbacks: Set to 0 for operation without callbacks and without display of eye camera images on the Subject PC. Omit or set to 1 for callback and video display operations during tracker setup, drift correction with the default callback dispatcher function PsychEyelinkDispatchCallback.m. Provide namestring of your own dispatcher function if you want to enable callbacks and video display with a non-standard, customized dispatcher.

Optional return arguments:

Returns result=1 when succesful, 0 otherwise Returns dummy=1 when initialized in dummy mode, 0 otherwise.

RectSize

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

[width,height] = RectSize(rect)

Returns the rect's width and height.

10/10/2000 fwc wrote it based on PsychToolbox RectHeight/RectWidth

WindowCenter

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

[x,y] = WindowCenter(window)

Returns a window's center point.

26/03/2001 fwc made using on rectcenter

getmodestrs

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

testeyelinksounds

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

test for the presence of sounds used by eyelink toolbox

USAGE: err=testeyelinksounds(el)

    el: if not supplied, we use 'initeyelinkdefaults'
        to open a structure with eyelink default values

returns 0 when no errors, -1 if one or more are missing

EyelinkDummyModeDlg

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

Puts up a dialog asking to run in dummy mode.

EyelinkGetEyeTracked

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

get eye information and send message for EDF file returns el.RIGHT_EYE or el.LEFT_EYE +1, for array access

EyelinkGetTime

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

USAGE: eltime=EyelinkGetTime(el [, maxwait]) Get tracker time

el: is eyelinkdefault structure maxwait: specifies maximum time to wait for a tracker time event if omitted, will wait indefinetely

EyelinkInit

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

USAGE: [result dummy]=EyelinkInit([dummy=0][enableCallbacks=1])

Initialize Eyelink system and connection. Optional arguments:

dummy: Omit, or set to 0 to attempt real initialization, set to 1 to enforce to use initializedummy for dummy mode.

    If regular initialization fails, it will provide option
    for dummy initilization.

enableCallbacks: Set to 0 for operation without callbacks and without display of eye camera images on the Subject PC. Omit or set to 1 for callback and video display operations during tracker setup, drift correction with the default callback dispatcher function PsychEyelinkDispatchCallback.m. Provide namestring of your own dispatcher function if you want to enable callbacks and video display with a non-standard, customized dispatcher.

Optional return arguments:

Returns result=1 when succesful, 0 otherwise Returns dummy=1 when initialized in dummy mode, 0 otherwise.

RectSize

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

[width,height] = RectSize(rect)

Returns the rect's width and height.

10/10/2000 fwc wrote it based on PsychToolbox RectHeight/RectWidth

WindowCenter

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

[x,y] = WindowCenter(window)

Returns a window's center point.

26/03/2001 fwc made using on rectcenter

geteventtype

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

EVENT types

getmodestrs

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

testeyelinksounds

>Psychtoolbox>PsychHardware>EyelinkToolbox>eyelinkoneliners

test for the presence of sounds used by eyelink toolbox

USAGE: err=testeyelinksounds(el)

    el: if not supplied, we use 'initeyelinkdefaults'
        to open a structure with eyelink default values

returns 0 when no errors, -1 if one or more are missing

Eyelink('AcceptTrigger')

Psychtoolbox>Eyelink.{mex*} subfunction

[result = ] Eyelink('AcceptTrigger')

call to trigger acceptance of target fixation

Eyelink('ApplyDriftCorr')

Psychtoolbox>Eyelink.{mex*} subfunction

[result = ] Eyelink('ApplyDriftCorr')

apply correction from last drift correction

Eyelink('ButtonStates')

Psychtoolbox>Eyelink.{mex*} subfunction

result = Eyelink('ButtonStates')

reads the currently-known state of all buttons the bits in the returned value will be set (1) if corresponding button is pressed LSB is button 1, MSB is button 16 currently only 8 buttons available

Eyelink('CalMessage')

Psychtoolbox>Eyelink.{mex*} subfunction

[result, messageString] = Eyelink('CalMessage');

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

Eyelink('CalResult')

Psychtoolbox>Eyelink.{mex*} subfunction

result = Eyelink('CalResult')

check if drift correction, calibration done. Returns OK_RESULT, ABORT_RESULT, NO_REPLY. Reading result resets it to NO_REPLY.

Eyelink('CheckRecording')

Psychtoolbox>Eyelink.{mex*} subfunction

error = Eyelink('CheckRecording')

Check if we are recording: if not, report an error. Also calls record_abort_hide() if recording aborted. Returns 0 if recording in progress. Returns ABORT_EXPT if link disconnected. Handles recors abort menu if trial interrupted. Returns TRIAL_ERROR if other non-recording state.

Eyelink('CloseFile')

Psychtoolbox>Eyelink.{mex*} subfunction

[status =] Eyelink('CloseFile')

Closes EDF file on tracker hard disk. Returns 0 if success, else error code.

Eyelink('Command')

Psychtoolbox>Eyelink.{mex*} subfunction

[status =] Eyelink('Command', 'formatstring', [...])

link command formatting. use just like printf(). Only chars and ints allowed in arguments! returns command result, allows 500 msec. for command to finish.

Eyelink('CurrentMode')

Psychtoolbox>Eyelink.{mex*} subfunction

mode = Eyelink('CurrentMode')

returns current tracker state as bit flags -1 = disconnect, 0 = unknown

Eyelink('DriftCorrStart')

Psychtoolbox>Eyelink.{mex*} subfunction

[status = ] Eyelink('DriftCorrStart', x, y [,dtype=0][, dodraw=1][, allow_setup=0])

Start drift correction, specify target position with x and y. If the optional 'dtype' argument is zero, the routine eyelink_driftcorr_start() is called. If 'dtype' is one, do_drift_correct() is called. In that case, the argument 'dodraw' selects if Eyelink itself should draw the target (1), or if it is left to usercode. 'allow_setup' if set to 1, will allow eyelink to enter the setup menu if ESCape key is pressed. Otherwise, eyelink will terminate a running drift correction on press of the ESCape key.

Eyelink('EDKVersion')

Psychtoolbox>Eyelink.{mex*} subfunction

[edkVersionString] = Eyelink('EDKVersion')

Returns the eyelink_core library version number.

Eyelink('EyeAvailable')

Psychtoolbox>Eyelink.{mex*} subfunction

eyeused = Eyelink('EyeAvailable')

returns 0 (LEFT_EYE), 1 (RIGHT_EYE) or 2 (BINOCULAR) depending on what data is available returns -1 if none available. ONLY VALID AFTER STARTSAMPLES EVENT READ

Eyelink('GetFloatData')

Psychtoolbox>Eyelink.{mex*} subfunction

item = Eyelink('GetFloatData', type)

makes copy of last item. You have to supply the type (returned from Eyelink('getnextdatatype')). Returns the item.

Eyelink('GetFloatDataRaw')

Psychtoolbox>Eyelink.{mex*} subfunction

[item, raw] = Eyelink('GetFloatDataRaw', type [, eye])

makes copy of last item. You have to supply the type (returned from Eyelink('getnextdatatype')). Returns the item.

Eyelink('GetNextDataType')

Psychtoolbox>Eyelink.{mex*} subfunction

type = Eyelink('GetNextDataType')

returns item type of next queue item SAMPLE_TYPE if sample, 0 if none, else event code

Eyelink('GetQueuedData')

Psychtoolbox>Eyelink.{mex*} subfunction

[samples, events, drained] = Eyelink('GetQueuedData' [, eye])

static char synopsisString[] = dequeues all samples and events from the link. returns double matrices where columns are items and rows are fields from eyelink sample structs. return flag 'drained' indicates whether queue was emptied or if this function needs to be called again. if you include the eye argument (as LEFT_EYE or RIGHT_EYE as returned by EyelinkInitDefaults), samples will include raw fields for that eye. if you don't remove items from the queue often enough, the oldest items will be replaced by a LOSTDATAEVENT, which will appear in the sample records at the location where items were dropped (fields other than type will be set to MISSING_DATA). sample rows are as follows: 1: time of sample (when camera imaged eye, in milliseconds since tracker was activated) 2: type (always SAMPLE_TYPE or LOSTDATAEVENT as returned by EyelinkInitDefaults) 3: flags (bits indicating what types of data are present, and for which eye(s) - see eye_data.h) 4: left pupil center x (camera coordinates) 5: right pupil center x (camera coordinates) 6: left pupil center y (camera coordinates) 7: right pupil center y (camera coordinates) 8: left HEADREF x (angular gaze coordinates) 9: right HEADREF x (angular gaze coordinates) 10: left HEADREF y (angular gaze coordinates) 11: right HEADREF y (angular gaze coordinates) 12: left pupil size (arbitrary units, area or diameter as selected by pupil_size_diameter command) 13: right pupil size (arbitrary units, area or diameter as selected by pupil_size_diameter command) 14: left gaze position x (in pixel coordinates set by screen_pixel_coords command) 15: right gaze position x (in pixel coordinates set by screen_pixel_coords command) 16: left gaze position y (in pixel coordinates set by screen_pixel_coords command) 17: right gaze position y (in pixel coordinates set by screen_pixel_coords command) 18: angular resolution x (at gaze position in screen pixels per visual degree) 19: angular resolution y (at gaze position in screen pixels per visual degree) 20: status (error and status flags (only useful for EyeLink II and EyeLink1000, report CR status and tracking error). see eye_data.h.) 21: input (data from input port(s)) 22: button input data: high 8 bits indicate changes from last sample, low 8 bits indicate current state of buttons 8 (MSB) to 1 (LSB) 23: head-tracker data type (0=none) 24: head-tracker data (not prescaled) 1 25: head-tracker data (not prescaled) 2 26: head-tracker data (not prescaled) 3 27: head-tracker data (not prescaled) 4 28: head-tracker data (not prescaled) 5 29: head-tracker data (not prescaled) 6 30: head-tracker data (not prescaled) 7 31: head-tracker data (not prescaled) 8 if you request the raw sample fields, they will appear in the following additional rows: 32: raw x sensor position of the pupil 33: raw y sensor position of the pupil 34: raw x sensor position of the corneal reflection 35: raw y sensor position of the corneal reflection 36: raw pupil area 37: raw corneal reflection area 38: raw width of pupil 39: raw height of pupil 40: raw width of corneal reflection 41: raw height of corneal reflection 42: raw x position of tracking window on sensor 43: raw y position of tracking window on sensor 44: (raw pupil x) - (raw corneal reflection x) 45: (raw pupil y) - (raw corneal reflection y) 46: raw area of 2nd corneal reflection candidate 47: raw x sensor position of the 2nd corneal reflection candidate 48: raw y sensor position of the 2nd corneal reflection candidate About raw fields: Normal samples do not contain the corneal reflection data, but some (non-saccade-based) calibration methods require this information. The Eyelink 1000 can be configured to send this information as part of 'raw' samples, and this is required before use of this function. Sol Simpson at SR-Research emphasizes that this is not officially supported or guaranteed. 1. You need to install Eyelink.dll from the latest software developer kit at https://www.sr-support.com/forums/showthread.php?t=6 (windows) or https://www.sr-support.com/forums/showthread.php?t=15 (osx) and the latest tracker host software at https://www.sr-support.com/forums/showthread.php?t=179 2. Issue the commands: Eyelink('command','link_sample_data = LEFT,RIGHT,GAZE,AREA,GAZERES,HREF,PUPIL,STATUS,INPUT,HMARKER');

Eyelink('GetTrackerVersion')

Psychtoolbox>Eyelink.{mex*} subfunction

[version , versionString] = Eyelink('GetTrackerVersion')

Returns: 0 if not connected, 1 for EyeLink I, 2 for EyeLink II will be 'EYELINK I' or 'EYELINK II x.xx', where 'x.xx' is the software version

Eyelink('ImageModeDisplay')

Psychtoolbox>Eyelink.{mex*} subfunction

[result =] Eyelink('ImageModeDisplay')

This handles display of the EyeLink camera images. While in imaging mode, it continuously requests and displays the current camera image. It also displays the camera name and threshold setting. Keys on the subject PC keyboard are sent to the tracker so the experimenter can use it during setup. It will exit when the tracker leaves imaging mode or disconnects. RETURNS: 0 if OK, 32767 (Ox7FFF or TERMINATE_KEY) if pressed, -1 if disconnect

Eyelink('ImageTransfer')

Psychtoolbox>Eyelink.{mex*} subfunction

[status] = Eyelink('ImageTransfer', imagePath [, xPosition=0][, yPosition=0][, width=0][, height=0][, trackerXPosition=0][, trackerYPosition=0][, xferoptions=0]);

This function transfers a 24-bit or 32-bit bitmap to the tracker PC as backdrop for gaze cursors. 'width' and 'height' define image size. If set to zero will use bitmap height and width. 'xferoptions' Transfer options set with bitwise OR of the following constants, determines how bitmap is processed: 0 Averaging combined pixels 1 Choosing darkest and keep thin dark lines 2 Choosing darkest and keep thin white lines and control how bitmap size is reduced to fit tracker display 4 Maximizes contrast for clearest image 8 Disables the dithering of the image 16 Converts the image to grayscale (grayscale works best for EyeLinkI,text,etc.)

Eyelink('InitWindow')

Psychtoolbox>Eyelink.{mex*} subfunction

Eyelink('InitWindow')

initializes eyelink global window, port, device & pixel depth and rect variables

Eyelink('IsConnected')

Psychtoolbox>Eyelink.{mex*} subfunction

status = Eyelink('IsConnected')

checks if the eyelink is (still) connected returns 1 if connected -1 if dummy-connected 2 if broadcast-connected 0 if not connected

Eyelink('Message')

Psychtoolbox>Eyelink.{mex*} subfunction

[status =] Eyelink('Message', 'formatstring', [...])

link message formatting use just like printf() Only chars and ints allowed in arguments! returns any send error

Eyelink('NewFloatSampleAvailable')

Psychtoolbox>Eyelink.{mex*} subfunction

NewOrOld = Eyelink('NewFloatSampleAvailable')

checks if new (float) sample is available returns -1 if none or error, 0 if old, 1 if new

Eyelink('NewestFloatSample')

Psychtoolbox>Eyelink.{mex*} subfunction

sample = Eyelink('NewestFloatSample')

makes copy of most recent float sample received returns -1 if no new sample or error

Eyelink('NewestFloatSampleRaw')

Psychtoolbox>Eyelink.{mex*} subfunction

[sample, raw] = Eyelink('NewestFloatSampleRaw' [, eye])

makes copy of most recent float sample received returns -1 if no new sample or error

Eyelink('OpenFile')

Psychtoolbox>Eyelink.{mex*} subfunction

[status =] Eyelink('OpenFile', filename [, dontOpenExisting=0])

static char synopsisString[] = Opens an EDF file 'filename' on the tracker computer, closes any existing file. If the optional flag 'dontOpenExisting' is set to a non-zero value, then the file is only opened, and thereby created, if it doesn't already exist. Otherwise the function aborts with an error. Returns 0 if success, else error code ;

Eyelink('ReadFromTracker')

Psychtoolbox>Eyelink.{mex*} subfunction

[result, reply] = Eyelink('ReadFromTracker', VariableName);

Sends a text variable 'VariableName' name whose value is to be read and returned by the tracker as a text string. Returns text with reply to last read request.

Eyelink('ReadTime')

Psychtoolbox>Eyelink.{mex*} subfunction

[time =] Eyelink('ReadTime')

checks for reply to eyelink_request_time() returns: 0 if no reply, else time

Eyelink('ReceiveFile')

Psychtoolbox>Eyelink.{mex*} subfunction

[status =] Eyelink('ReceiveFile',['filename'], ['dest'], ['dest_is_path'])

If is omitted, tracker will send last opened data file. If is omitted, creates local file with source file name. Else, creates file using as name. If is supplied and non-zero uses source file name but adds as directory path. returns: file size if OK, 0 if file transfer was cancelled, negative = error code

Eyelink('RequestTime')

Psychtoolbox>Eyelink.{mex*} subfunction

[status =] Eyelink('RequestTime')

sends request for tracker time update returns: 0 if succesful, else link error code

Eyelink('SendKeyButton')

Psychtoolbox>Eyelink.{mex*} subfunction

[result =] Eyelink('SendKeyButton', code, mods, state)

sends key/button state chane to tracker code = KB_BUTTON, mods = number for button state is KB_PRESS, KB_RELEASE, or KB_REPEAT Returns: OK_RESULT or LINK_TERMINATED_RESULT

Eyelink('SetOfflineMode')

Psychtoolbox>Eyelink.{mex*} subfunction

Eyelink('SetOfflineMode')

enter tracker idle mode, wait till finished mode switch

Eyelink('Shutdown')

Psychtoolbox>Eyelink.{mex*} subfunction

Eyelink('Shutdown')

Shuts down the eyelink

Eyelink('StartRecording')

Psychtoolbox>Eyelink.{mex*} subfunction

[startrecording_error =] Eyelink('StartRecording' [,file_samples, file_events, link_samples, link_events] )

Start recording with data types requested

Eyelink('StartSetup')

Psychtoolbox>Eyelink.{mex*} subfunction

[result =] Eyelink('StartSetup' [, stype=0])

Enters setup mode. By default, eyelink_start_setup() is called. If the optional argument 'stype' is set to one, the routine do_tracker_setup() is called instead.

Eyelink('Stoprecording')

Psychtoolbox>Eyelink.{mex*} subfunction

Eyelink('Stoprecording')

Stop recording eye data (stop_recording).

Eyelink('TargetCheck')

Psychtoolbox>Eyelink.{mex*} subfunction

[result, tx, ty] = Eyelink('TargetCheck')

gets pixel X, Y of target returns 1 if visible, 0 if not

Eyelink('TimeOffset')

Psychtoolbox>Eyelink.{mex*} subfunction

[offset =] Eyelink('TimeOffset')

Returns the time difference (in msec) between the tracker time and display pc time.

Eyelink('TrackerMode')

Psychtoolbox>Eyelink.{mex*} subfunction

[mode =] Eyelink('TrackerMode')

Returns raw EyeLink mode numbers, as defined in eyelink.h

Eyelink('TrackerTime')

Psychtoolbox>Eyelink.{mex*} subfunction

[time =] Eyelink('TrackerTime')

Returns the current tracker time (in seconds) since the tracker application started.

Eyelink('Verbosity')

Psychtoolbox>Eyelink.{mex*} subfunction

oldlevel = Eyelink('Verbosity' [,level]);

Set level of verbosity for error/warning/status messages. 'level' optional, new level of verbosity. 'oldlevel' is the old level of verbosity. The following levels are supported: 0 = Shut up. 1 = Print errors, 2 = Print also warnings, 3 = Print also some info, 4 = Print more useful info (default), >5 = Be very verbose (mostly for debugging the driver itself).

Eyelink('WaitForModeReady')

Psychtoolbox>Eyelink.{mex*} subfunction

[result = ] Eyelink('WaitForModeReady', maxwait)

After a mode-change command is given to the EyeLink tracker, an additional 5 to 30 milliseconds may be needed to complete mode setup. Call this function after mode change functions to wait until they are finished setting up. maxwait is in milliseconds -- max duration to wait for the mode to change. Returns 0 if mode switching is done, else still waiting (assume a tracker error has occurred).