README.TXT
Prexel Version 1.0-Beta
==================================================================




Support for Eye Selection
-------------------------


The current version of Presentation (9.10 10.20.04) does not 
allow a means to specify which eye should be tracked.  This is due 
to the way in which Presentation implements the start_data() function:

	start_data( int data_type, bool store_data )

This function triggers Presentation to call one of several Prexel functions
that instruct that begin collecting position, saccade, fixations, or blink data.
Unfortunately, there is no way to specify which eye to track using standard
Presentation functions.  This explains why previous versions of Prexel 
supported tracking for the left eye only.




A Workaround for Selecting Either or Both Eyes
----------------------------------------------


Note:  If you are interested in getting data for the left eye 
only then there is no need to use this workaround.  You can 
use Presentation and Prexel as usual and expect the same results.



Although Presentation does not support eye selection for tracking via the
use of the eye_tracker.start_data() function, the latest release 
of Prexel provides functionality for doing so by means of a workaround.  
The eye_tracker send_string() function has been implemented to provide 
a means of tracking the left, right, or both eyes.  The previous version 
of Prexel used the send_string() function to pass along messages to 
the eye tracker.  It still does this unless it receives one of the special 
eye-tracking message detailed below:

	send_string(string message)


Eye-tracking messages are one of:


"TRACK_LEFT_EYE"	-- indicates to store position data for the 
			   left eye only.


"TRACK_RIGHT_EYE"	-- indicates to store position data for the 
			   right eye only.

"TRACK_BOTH_EYES"	-- indicates to store position data for both 
			   eyes at the same time.


Note:  These eye-tracking messages are case sensitive


If the message is any other value it is passed along to the eye tracker
as usual.


Prior to calling the send_string() function you need to call the 
start_data() function or you will not be able to retrieve any data.  
This will set up tracking for the left eye by default.  Then, to override
tracking of the left eye, you need to use the send_string() function.

Here are some details to keep in mind:

1.  When the send_string() function is called no changes are made to the data 
    buffering.  If you indicated to turn buffering on with the start_data() 
    function, then buffering will remain when after calling the send_string() 
    function.  

2.  If you wish to track both eyes simultaneously and want real-time performance
    then it is recommended that you turn buffering off since you can only read 
    data from one eye at a time and you are likely to miss out on the most recent 
    samples collected for the other eye.

3.  If you wish to track both eyes, then you must call the 
    send_string("TRACK_BOTH_EYES") first.  DO NOT switch between the left and 
    right eyes by calling send_string("TRACK_LEFT_EYE") and 
    send_string("TRACK_RIGHT_EYE") without first calling 
    send_string("TRACK_BOTH_EYES").  Using these functions without doing so will 
    turn off data collection for the other (see point 4 about getting data for 
    both eyes).

4.  If you are tracking both eyes simultaneously, you will need to tell Prexel 
    which eye you would like to retrieve data from.  As noted above, you must 
    first call send_string("TRACK_BOTH_EYES") to let prexel know that want data 
    from both eyes.  Initially, a call to any of the data retrieval functions 
    will result in getting data for the left eye.  To switch to the right eye 
    make use send_string("TRACK_RIGHT_EYE") and then any of the corresponding
    data retrieval functions.  To read data from the left eye again use 
    send_string("TRACK_LEFT_EYE").  
    
    


PCL Examples:


Getting Positional Data
---------------------------


Since Presentation does not support reading data from more than one eye 
at a time you will need to read the data individually.  To do so, 
you must tell Prexel for which eye you would currently like to receive 
data from by using the send_string() function outlined above and 
then call last_position_data() or other eye_tracker data retrieval 
functions.


Here are examples for getting positional data:


GETTING DATA FROM THE RIGHT EYE ONLY

NOTE:  There is no need to use this procedure to if you wish to track 
       the left eye only.  You can use Presentation and Prexel in the 
       standard way.


#--begin PCL example 1 -- Reading Position Data From the Right Eye


	# construct a new eye_tracker object
	eye_tracker EyeLink = new eye_tracker("EyeTracker");

	# storage for position data
	eye_position_data eyePos;

	# as usual call the start_data function
	# by default this tracks the left eye
	EyeLink.start_data(dt_position, true);

	# use the send_string function to track the right eye instead
	EyeLink.send_string(“TRACK_RIGHT_EYE”);


	# now read the position data
	pos = EyeLink.last_position_data();

#--end PCL example 1



GETTING SIMULTANEOUS DATA FROM BOTH EYES

This example is slightly more complicated since Presentation
requires you to read data from eye at a time.
Therefore, you will need to notify Prexel which eye you want
data from before using any of Presentation's data retrieval
functions.


#--begin PCL example 2

	

	# construct a new eye_tracker object
	eye_tracker EyeLink = new eye_tracker("EyeTracker");

	# declare storage for position data
	eye_position_data eyePos;

	# as usual call the start_data function
	# by default this tracks the left eye
	# it's PROBABLY a good idea to turn off buffering
	# but experiment for yourself.
	EyeLink.start_data(dt_position, false);

	# use the send_string function to track the both eyes
	# after calling this Prexel will store data from both
	# eyes.  
	EyeLink.send_string(“TRACK_BOTH_EYES”);


	# Read the position information.  Calling last_position_data()
	# or any other data retrieval functions now will result in retrieving
	# data for the left eye until a call to send_string("TRACK_RIGHT_EYE") 
	# is recieved
	pos = EyeLink.last_position_data();

	# now get data from the right eye
	# you must tell Prexel that you want data from the right 
	# eye now.
	# Data from left eye will still be buffered after this call
	# if you chose to enable buffering in the start_data() function.
	EyeLink.send_string(“TRACK_RIGHT_EYE”);

	# now read the data from the right eye
	pos = EyeLink last_position_data();


	# read the left eye again
	# tell Prexel you want the left eye again
	EyeLink.send_string(“TRACK_LEFT_EYE”);

	# now read the left eye position data
	pos = EyeLink.last_position_data();

	# The Prexel package include a scenario that implements
	# functions to facilitate tracking both eyes (see the gaze_contingent
        # sample scenario.

#--end PCL example 2




--------
end README.txt