Instructions for Implementing TOBIIXtra.x32

INSTALLING THE TOBII DIRECTOR XTRA:

Step 1: Copy the TOBIIXtra.x32 file into your Xtras\Scripting directory.
Typical file path for this directory is:
      C:\Program Files\Macromedia\Director MX 2004\Configuration\Xtras\Scripting
but may vary on your machine.

Step 2: Modify your xtrainfo.txt file to include the line:
[#nameW32:"TOBIIXtra.x32"]
Typical file path for this file is:
      C:\Program Files\Macromedia\Director MX 2004\Configuration\xtrainfo.txt
but may vary on your machine.

Step 3: Make sure that the file cv.dll is on the system path. (The 
dll is part of the Tobii SDK, and on our machine is found in 
C:\Program Files\Tobii\Tobii Eye Tracker SDK 1.1.0\bin (but may vary 
on your machine.) If you do not already have a copy of the Tobii SDK 
installed, you may need to download it from their website.


USING THE XTRA IN YOUR DIRECTOR PROGRAMS:

Step 1:  (Do this for EVERY Director movie in which you wish to have 
access to the Xtra.)  From the Modify menu, choose Modify -->  Movie 
--> Xtras, select TOBIIXtra.x32 from the list that appears, and click 
the "Add" button.  (If you do not see the TOBIIXtra.x32 in the list 
of available Xtras, check to make sure that you installed the Xtra 
into the correct folder as instructed above.)

Step 2: At the start of your experiment, you need to have a script 
execute the following code:
     global tobii
           tobii = new xtra("TOBIIXtra")
            res = tobii.TOBII_CV_Init("xxx.xxx.xx.xx", XXXX)

This code opens the connection between the Xtra and Tobii Clearview 
by creating a tobii object and telling it where to send its 
information.  (In our lab, we typically place this code within the 
"on prepareMovie" script.)

NOTE: YOU MUST REPLACE THE "xxx.xxx.xx.xx" in the code above with the 
IP address of the computer on which TOBII is running, and replace the 
XXXX with the four digit port number to which you wish to send data. 
(In our lab, we use the single computer setup, so Director and Tobii 
are running on the same machine. We still need to include this code 
to tell the computer to send information to itself.)


COMMANDS THAT WORK WITH THE XTRA, AND WHAT THEY DO:

Once you have established the connection between Director and the 
TOBII Clearview data stream as outlined above, you can use the 
following commands anywhere in your Lingo scripts to interact with 
the TOBII Clearview software. (NOTE: You will need to declare global 
tobii as one of your global variables in any script in which you want 
to use these commands):

res = TOBII_CV_Start()
      this tells Clearview to start recording eye tracking data. 
(NOTE: this command is equivalent to clicking the "Start" button in 
the Clearview software interface "Recording Information" window.)

res = TOBII_CV_Stop()
      this tells Clearview to stop recording eye tracking data. (NOTE: 
this command is equivalent to using the F10 button in Clearview to 
stop recording, and will require user interaction with a Clearview 
dialog box asking if you wish to save the data.)

res = tobii.TOBII_CV_Log_Event("message text")
       this inserts whatever message text you send into its own column 
in the data stream, time-stamped (in Clearview time format) with the 
time at which this method was called by your script. The message text 
parameter you send must either be a String in quotes, as shown here, 
or may be (without quotes) a variable name or any other expression as 
long as it evaluates to a String.

  res = TOBII_CV_Close()
       this closes the connection between the Xtra and Tobii Clearview.


ERROR CODES:
The following error codes may be helpful with troubleshooting your 
programs... All of the methods above EXCEPT CV_Init() and CV_Close() 
return an integer representing the following errors:

0   CV_ERR_NO_ERROR
1   CV_ERR_INVALID_STATE
2   CV_ERR_SERVER_COMMUNICATION
3   CV_ERR_INTERNAL
4   CV_ERR_MEMORY
5   CV_ERR_BAD_PARAMETER

CV_Init() returns the port number you've passed it, if successful.
(if it returns garbage, you were not successful.)

CV_Close() does not return anything (returns void).


The TOBIIXtra.x32 was created in 2005 by: Edward Longhurst, Dept. of 
Brain & Cognitive Sciences, University of Rochester, Rochester, NY, 
14627.