EyeTracker API

Classes

The user only has to interact with fixed interfaces offering different features. The EyeTracker interface is one of the most essential SR components. In this class diagram, only the user-facing classes are visualized.

• SRContext is an essential element of any SR application, it maintains a list of all SR components that are in use and cleans them up when the application ends. It also allows different components of the application to share the same Sense implementations.
• Sense is an interface used by the SRContext to keep track of any input or output devices.
• EyeTracker is an interface providing access to eyetracker data.
• EyePairStream connects EyeTracker implementations with user defined EyePairListener implementations.
• EyePairListener is an interface to be implemented by any components of the user's application that want to receive eyetracker data.
• SR_eyePair defines the actual eyetracker data.

EyeTracker Data

The SR_eyePair is at the center of the EyeTracker interface, this is what applications can subscribe to.

typedef struct {
    uint64_t frameId; 
    uint64_t time;    
    SR_point3d left;  
    SR_point3d right; 
} SR_eyePair;

EyeTracker usage

Application developers should define how to handle the EyeTracker data by implementing an EyePairListener. It is advisable to include an InputStream<SR::EyePairStream> member, this will come into play when the actual eye tracker is constructed.

class EyePairListenerImplementation : public SR::EyePairListener
{
public:
    // Ensures EyePairStream is cleaned up when Listener object is out of scope
    SR::InputStream<SR::EyePairStream> stream;
 
    // The accept function can process the eye position data as soon as it becomes available
    virtual void accept(const SR_eyePair& frame) override {
        // Use EyeTracker data
    }
};

To get access to eyetracker data, users will have to construct an SRContext and call the static factory function EyeTracker::create as follows:

int main() {
    // Create EyeTracker
    SR::SRContext context;
    SR::EyeTracker* eyeTracker = SR::EyeTracker::create(context);

Then we need to construct a listener that follows the desired way of processing the data. By calling set on the InputStream<SR::EyePairStream> field we ensure that the stream is destructed correctly when the EyePairListenerImplementation goes out of scope. When everything is set up context.initialize() starts using any newly constructed streams to listeners.

// Construct listener
EyePairListenerImplementation listener;
listener.stream.set(eyeTracker->openEyePairStream(&listener));
 
// Start tracking
context.initialize();

If the main function of our application returns, all deconstructors will be called and we will no longer receive data. We should ensure that the application remains open as long as we want.

    // Ensure that the program does not exit immediately.
    char inchar;
    std::cin >> inchar; //wait for key press
}

Prediction

To ensure that your application is as responsive as possible a specific EyeTracker implementation can be constructed. The following is a short description of relevant classes.

• PredictingEyeTracker is an implementation of the EyeTracker interface that offers more control over the filtering of the output values to the application developer.
• EyePairPredictor is an implementation of the PredictiveFilter<SR_eyePair, uint64_t> interface that defines how SR_eyePair data is filtered to provide accurate predictions.

PredictingEyeTracker usage

The PredictingEyeTracker::create function can be used in exactly the same way as the EyeTracker::create function but the PredictingEyeTracker will only provide output to connected EyePairListener instances when one of the predict functions is called.

An application might define the same type of EyePairListener.

class EyePairListenerImplementation : public SR::EyePairListener
{
public:
    // Ensures EyePairStream is cleaned up when Listener object is out of scope
    SR::InputStream<SR::EyePairStream> stream;
 
    // The accept function can process the eye position data as soon as it becomes available
    virtual void accept(const SR_eyePair& frame) override {
        // Use EyeTracker data
    }
};
 
int main() {
    // Create EyeTracker
    SR::SRContext context;

The EyeTracker::create call is replaced with PredictingEyeTracker::create.

SR::PredictingEyeTracker* eyeTracker = SR::PredictingEyeTracker::create(context);
 
// Construct listener
EyePairListenerImplementation listener;
listener.stream.set(eyeTracker->openEyePairStream(&listener));
 
// Start tracking
context.initialize();

To trigger the listener to receive new data the predict function can be called as follows.

    // Program loop
    while (true) {
        eyeTracker->predict(80);
 
        // Sleep in between predictions to simulate actual work being done in between frames
        using namespace std::chrono_literals;
        std::this_thread::sleep_for(16ms);
    }
}

Synchronous use of PredictingEyeTracker

In the above example, the work associated with filtering will be executed asynchronously. This can be useful to increase parallelization but might be difficult to control.

Since the PredictingEyeTracker is also an EyePairListener implementation. This still maintains a similar structure in your application. The developer does not have to define their own listener implementation in this case.

int main() {
    // Create EyeTracker
    SR::SRContext context;
 
    SR::PredictingEyeTracker* eyeTracker = SR::PredictingEyeTracker::create(context);
 
    // Start tracking
    context.initialize();
 
    // Program loop
    while (true) {
        SR_eyePair eyePair;
        eyeTracker->predict(80, eyePair);
 
        // Use EyeTracker data
 
        // Sleep in between predictions to simulate actual work being done in between frames
        using namespace std::chrono_literals;
        std::this_thread::sleep_for(16ms);
    }
}