EyeLogic SDK  1.1.5
ELApi Class Referencefinal

main class for communication with the EyeLogic server More...

#include "ELApi.h"

Classes

struct  DeviceConfig
 Device configuration. More...
 
class  ELEventCallback
 
class  ELGazeSampleCallback
 
struct  ScreenConfig
 Screen configuration. More...
 

Public Types

enum  Event {
  SCREEN_CHANGED, CONNECTION_CLOSED, DEVICE_CONNECTED, DEVICE_DISCONNECTED,
  TRACKING_STOPPED
}
 
enum  ReturnConnect { SUCCESS, FAILURE, VERSION_MISMATCH }
 return values of connect( ) More...
 
enum  ReturnNextData {
  SUCCESS, SUCCESS, TIMEOUT, CONNECTION_CLOSED,
  CONNECTION_CLOSED
}
 Return values of the getNextEvent/getNextGazeSample functions. More...
 
enum  ReturnStart {
  SUCCESS, NOT_CONNECTED, DEVICE_MISSING, INVALID_FRAMERATE_MODE,
  ALREADY_RUNNING_DIFFERENT_FRAMERATE, FAILURE
}
 return values of requestTracking( ) More...
 
enum  ReturnCalibrate {
  SUCCESS, NOT_CONNECTED, NOT_TRACKING, INVALID_CALIBRATION_MODE,
  ALREADY_CALIBRATING, FAILURE
}
 return values of calibrate( ) More...
 

Public Member Functions

EL_EXPORT STDCALL ELApi (const char *clientName)
 constructor More...
 
EL_EXPORT STDCALL ~ELApi ()
 destructor
 
 ELApi (const ELApi &)=delete
 
ELApioperator= (const ELApi &)=delete
 
 ELApi (ELApi &&)=delete
 
ELApioperator= (ELApi &&)=delete
 
EL_EXPORT void STDCALL registerEventListener (ELEventCallback *callback)
 Registers the event listener. An existing listener will be overwritten. More...
 
EL_EXPORT void STDCALL registerGazeSampleListener (ELGazeSampleCallback *callback)
 Registers the gaze sample listener. An existing listener will be overwritten. More...
 
EL_EXPORT ReturnConnect STDCALL connect ()
 initialize connection to the server (method is blocking until connection established)
 
EL_EXPORT void STDCALL disconnect ()
 closes connection to the server
 
EL_EXPORT bool STDCALL isConnected () const
 whether a connection to the server is established
 
EL_EXPORT void STDCALL getScreenConfig (ScreenConfig &screenConfig) const
 obtain configuration of active screen
 
EL_EXPORT void STDCALL getDeviceConfig (DeviceConfig &deviceConfig) const
 obtain configuration of active device
 
EL_EXPORT ReturnNextData STDCALL getNextEvent (Event &event, int32_t timeoutMillis)
 Obtains the next unread event or blocks until a new event occurs or the given timeout is reached. More...
 
EL_EXPORT ReturnNextData STDCALL getNextGazeSample (ELGazeSample &gazeSample, int32_t timeoutMillis)
 Obtains the next unread gazeSample or blocks until a new GazeSample is received or the given timeout is reached. More...
 
EL_EXPORT ReturnStart STDCALL requestTracking (int32_t frameRateModeInd)
 request tracking More...
 
EL_EXPORT void STDCALL unrequestTracking ()
 unrequest tracking More...
 
EL_EXPORT ReturnCalibrate STDCALL calibrate (int32_t calibrationModeInd)
 perform calibration (method is blocking until calibration finished) More...
 

Detailed Description

main class for communication with the EyeLogic server

Member Enumeration Documentation

◆ Event

enum Event
strong

eye tracking event

Enumerator
SCREEN_CHANGED 

active screen or resolution has changed

CONNECTION_CLOSED 

connection to server has closed

DEVICE_CONNECTED 

a new device has connected

DEVICE_DISCONNECTED 

actual device has disconnected

TRACKING_STOPPED 

tracking has stopped

◆ ReturnCalibrate

enum ReturnCalibrate
strong

return values of calibrate( )

Enumerator
SUCCESS 

start calibration successful

NOT_CONNECTED 

cannot calibrate: not connected to the server

NOT_TRACKING 

cannot calibrate: no device found or tracking not started

INVALID_CALIBRATION_MODE 

cannot start calibration: calibration mode is invalid or not supported

ALREADY_CALIBRATING 

cannot start calibration: calibration is already in progress

FAILURE 

calibration failure

◆ ReturnConnect

enum ReturnConnect
strong

return values of connect( )

Enumerator
SUCCESS 

connection successully established

FAILURE 

connection could not be established: the server can not be found or is not responding

VERSION_MISMATCH 

connection could not be established: API is build on a newer version than the server. Update the EyeLogicServer to the newest version.

◆ ReturnNextData

Return values of the getNextEvent/getNextGazeSample functions.

Enumerator
SUCCESS 

new event or new GazeSample received

SUCCESS 

connection successully established

TIMEOUT 

timeout reached, no new event/GazeSample received

CONNECTION_CLOSED 

connection to server closed, no new event/GazeSample received

CONNECTION_CLOSED 

connection to server has closed

◆ ReturnStart

enum ReturnStart
strong

return values of requestTracking( )

Enumerator
SUCCESS 

start tracking successful

NOT_CONNECTED 

not connected to the server

DEVICE_MISSING 

cannot start tracking: no device found

INVALID_FRAMERATE_MODE 

cannot start tracking: framerate mode is invalid or not supported

ALREADY_RUNNING_DIFFERENT_FRAMERATE 

tracking already ongoing, but frame rate mode is different

FAILURE 

some general failure occurred

Constructor & Destructor Documentation

◆ ELApi()

EL_EXPORT STDCALL ELApi ( const char *  clientName)

constructor

Parameters
clientNamestring identifier of the client (shown in the server tool window), may be null

Member Function Documentation

◆ calibrate()

EL_EXPORT ReturnCalibrate STDCALL calibrate ( int32_t  calibrationModeInd)

perform calibration (method is blocking until calibration finished)

Parameters
calibrationModeIndindex of the requested calibration method (0 ... #calibrationMethods-1)

◆ getNextEvent()

EL_EXPORT ReturnNextData STDCALL getNextEvent ( Event event,
int32_t  timeoutMillis 
)

Obtains the next unread event or blocks until a new event occurs or the given timeout is reached.

The last incoming event is buffered internally and can be obtained by calling this method in a consecutive order. If there is no new event, the method blocks until an event occurs or the given timeout is reached. The method returns SUCCESS if and only if a new event is provided which was not returned before. Therefore, by checking the return value, you can assure to not handle any event twice.

If you want to catch events in a loop, be careful to not wait too long between the calls to this method. Otherwise, you may miss events. If you want to be 100% sure to not miss any event, consider to use the ELEventCallback mechanism.

See also
registerEventListener
Parameters
eventIf this method returns SUCCESS, this data structure is filled with the new (yet unhandled) event. In all other cases, this data structure is filled with the event which was returned last.
timeoutMillisduration in milliseconds, method returns at the latest after this time. May be 0 if the method should return immediatly.
Returns
whether an event was received (SUCCESS) or the method terminated without a new event

◆ getNextGazeSample()

EL_EXPORT ReturnNextData STDCALL getNextGazeSample ( ELGazeSample gazeSample,
int32_t  timeoutMillis 
)

Obtains the next unread gazeSample or blocks until a new GazeSample is received or the given timeout is reached.

The last incoming GazeSample is buffered internally and can be obtained by calling this method in a consecutive order. If there is no new GazeSample, the method blocks until a GazeSample arrives or the given timeout is reached. The method returns SUCCESS if and only if a new GazeSample is provided which was not returned before. Therefore, by checking the return value, you can assure to not handle any GazeSample twice.

If you want to catch GazeSamples in a loop, be careful to not wait too long between the calls to this method (at least once per frame). Otherwise, you may miss GazeSamples. If you want to be 100% sure to not miss any GazeSample, consider to use the ELGazeSampleCallback mechanism.

See also
registerGazeSampleListener
Parameters
gazeSampleIf this method returns SUCCESS, this data structure is filled with the new (yet unhandled) GazeSample. In all other cases, this data structure is filled with the GazeSample which was returned last.
timeoutMillisduration in milliseconds, method returns at the latest after this time. May be 0 if the method should return immediatly.
Returns
whether a GazeSample was received (SUCCESS) or the method terminated without a new GazeSample

◆ registerEventListener()

EL_EXPORT void STDCALL registerEventListener ( ELEventCallback callback)

Registers the event listener. An existing listener will be overwritten.

Parameters
callbackthis instance will be notified of all events published by the ELApi. If null, the current callback is removed/unregistered. Ensure that the listener is unregistered before its destruction.

◆ registerGazeSampleListener()

EL_EXPORT void STDCALL registerGazeSampleListener ( ELGazeSampleCallback callback)

Registers the gaze sample listener. An existing listener will be overwritten.

Parameters
callbackthis instance will be notified of all gaze samples published by the ELApi. If null, the current callback is removed/unregistered. Ensure that the listener is unregistered before its destruction.

◆ requestTracking()

EL_EXPORT ReturnStart STDCALL requestTracking ( int32_t  frameRateModeInd)

request tracking

If tracking is not yet ongoing, tracking is started in the device. If tracking is already running (e.g. started from another client) with the same frame-rate as requested, all gaze samples are reported to this client as well.

Parameters
frameRateModeIndindex of the requested frame rate mode (0 ... #frameRateModes-1)

◆ unrequestTracking()

EL_EXPORT void STDCALL unrequestTracking ( )

unrequest tracking

Note that the tracking device may continue if other processes still request tracking. Check the EyeLogic server window to observe the actual state.