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

#include "ELApi.h"

Classes
struct	DeviceConfig
	Device configuration. More...

struct	DeviceGeometry
	Geometric position of the device related to the active monitor. More...

class	ELEventCallback
	Callback interface for events related to the eye tracker. More...

class	ELEyeImageCallback
	Callback interface for EyeImages. More...

class	ELGazeSampleCallback
	Callback interface for gaze samples. More...

struct	ELValidationPointResult
	ValidationPointResult holds the results of the validation ( total deviation between true point position and calculated POR of the left and right eye POR in [px] and [deg] ) of the validation point at position ( validationPointPxX, validationPointPxY ) [px]. More...

struct	ELValidationResult
	ValidationResult contains one ValidationPointResult struct per validation stimulus point of the performed valdation. More...

struct	ScreenConfig
	Screen configuration. More...

struct	ServerInfo
	connection information for an EyeLogic server More...

Public Types
enum	Event { SCREEN_CHANGED, CONNECTION_CLOSED, DEVICE_CONNECTED, DEVICE_DISCONNECTED, TRACKING_STOPPED }
	eye tracking event More...

enum	ReturnConnect { SUCCESS, FAILURE, VERSION_MISMATCH }
	return values of connect( ) More...

enum	ReturnSetActiveScreen { SUCCESS, NOT_FOUND, FAILURE }
	return values of setActiveScreen( ) More...

enum	ReturnStreamEyeImages { SUCCESS, NOT_CONNECTED, REMOTE_CONNECTION, FAILURE }
	Return values of the streamEyeImages() function. More...

enum	ReturnNextData { SUCCESS, TIMEOUT, 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_BUSY, FAILURE }
	return values of calibrate( ) More...

enum	ReturnValidate { SUCCESS, NOT_CONNECTED, NOT_TRACKING, NOT_CALIBRATED, ALREADY_BUSY, FAILURE }
	return values of validate( ) More...

Public Member Functions
EL_EXPORT STDCALL	ELApi (const char *clientName)
	constructor More...

EL_EXPORT STDCALL	~ELApi ()
	destructor

	ELApi (const ELApi &)=delete

ELApi &	operator= (const ELApi &)=delete

	ELApi (ELApi &&)=delete

ELApi &	operator= (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 void STDCALL	registerEyeImageListener (ELEyeImageCallback *callback)
	Registers the eye image listener. An existing listener will be overwritten. More...

EL_EXPORT ReturnConnect STDCALL	connect ()
	initialize connection to the server (method is blocking until connection established). The connection is only established for a local server (running on this machine). For connections to a remote server, More...

EL_EXPORT ReturnConnect STDCALL	connectRemote (ServerInfo server)
	initialize connection to a remote server (method is blocking until connection established) More...

EL_EXPORT int32_t STDCALL	requestServerList (int32_t blockingDurationMS, ServerInfo *serverList, int32_t serverListLength)
	Ping all running EyeLogic servers in the local network and wait some time for their response. More...

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	getActiveScreen (ScreenConfig &screenConfig) const
	obtain configuration of active screen

EL_EXPORT int32_t STDCALL	getAvailableScreens (ScreenConfig *screenConfig, int32_t numScreenConfigs) const
	Get a list of screens connected to the local machine. If there are more screens than 'numScreenConfigs' found, then only the first 'numScreenConfigs' ones are filled. More...

EL_EXPORT ReturnSetActiveScreen STDCALL	setActiveScreen (const char *screenID, DeviceGeometry deviceGeometry)
	Make a screen connected to this machine to the active screen. More...

EL_EXPORT void STDCALL	getDeviceConfig (DeviceConfig &deviceConfig) const
	obtain configuration of active device

EL_EXPORT ReturnStreamEyeImages STDCALL	streamEyeImages (bool enable)
	Enabled/disables eye image stream. If enabled, eye images are received from eye image listeners,. More...

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 ReturnNextData STDCALL	getNextEyeImage (ELEyeImage &eyeImage, int32_t timeoutMillis)
	Obtains the next unread eye image or blocks until a new eye image 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...

EL_EXPORT void STDCALL	abortCalibValidation ()
	abort a running calibration

EL_EXPORT ReturnValidate STDCALL	validate (ELValidationResult &validationResult)
	perform validation (method is blocking until validation 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_BUSY	cannot start calibration: calibration or validation 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

enum ReturnNextData

strong

Return values of the getNextEvent/getNextGazeSample functions.

Enumerator
SUCCESS	new event or new GazeSample received
TIMEOUT	timeout reached, no new event/GazeSample received
CONNECTION_CLOSED	connection to server closed, no new event/GazeSample received

◆ ReturnSetActiveScreen

enum ReturnSetActiveScreen

strong

return values of setActiveScreen( )

Enumerator
SUCCESS	active screen was set
NOT_FOUND	specified screen name was not found as a name of an available monitor
FAILURE	active screen could not be changed

◆ 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

◆ ReturnStreamEyeImages

enum ReturnStreamEyeImages

strong

Return values of the streamEyeImages() function.

Enumerator
SUCCESS	setting streaming of eye images was successful
NOT_CONNECTED	failed, not connected to the server
REMOTE_CONNECTION	cannot stream eye images when connection to the server is a remote connection
FAILURE	failure when trying to set eye image stream

◆ ReturnValidate

enum ReturnValidate

strong

return values of validate( )

Enumerator
SUCCESS	start validation successful
NOT_CONNECTED	cannot validate: not connected to the server
NOT_TRACKING	cannot validate: no device found or tracking not started
NOT_CALIBRATED	cannot start validation: validation mode is invalid or not supported
ALREADY_BUSY	cannot start validation: calibration or validation is already in progress
FAILURE	validation failure

Constructor & Destructor Documentation

◆ ELApi()

EL_EXPORT STDCALL ELApi ( const char * clientName )

constructor

Parameters

clientName string 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

calibrationModeInd index of the requested calibration method (0 ... #calibrationMethods-1)

◆ connect()

EL_EXPORT ReturnConnect STDCALL connect ( )

initialize connection to the server (method is blocking until connection established). The connection is only established for a local server (running on this machine). For connections to a remote server,

See also: connectRemote( ).

◆ connectRemote()

EL_EXPORT ReturnConnect STDCALL connectRemote ( ServerInfo server )

initialize connection to a remote server (method is blocking until connection established)

Parameters

server Server to connect to

See also: acquireServerList( ) to obtain IP address and port of a remote server

◆ getAvailableScreens()

EL_EXPORT int32_t STDCALL getAvailableScreens	(	ScreenConfig *	screenConfig,
		int32_t	numScreenConfigs
	)		const

Get a list of screens connected to the local machine. If there are more screens than 'numScreenConfigs' found, then only the first 'numScreenConfigs' ones are filled.

Parameters

screenConfig	pre-allocated array, will be filled with screen configurations
numScreenConfigs	number of entries of screenConfig

Returns: number of filled screen configurations. will be <= numScreenConfigs

◆ 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

event	If 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.
timeoutMillis	duration 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

◆ getNextEyeImage()

EL_EXPORT ReturnNextData STDCALL getNextEyeImage	(	ELEyeImage &	eyeImage,
		int32_t	timeoutMillis
	)

Obtains the next unread eye image or blocks until a new eye image is received or the given timeout is reached.

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

Parameters

eyeImage	If this method returns SUCCESS, this data structure is filled with the new (yet unhandled) eye image. In all other cases, this data structure is filled with the eye image which was returned last.
timeoutMillis	duration in milliseconds, method returns at the latest after this time. May be 0 if the method should return immediatly.

Returns: whether an eye iage was received (SUCCESS)

◆ 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

gazeSample	If 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.
timeoutMillis	duration 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

callback this 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.

◆ registerEyeImageListener()

EL_EXPORT void STDCALL registerEyeImageListener ( ELEyeImageCallback * callback )

Registers the eye image listener. An existing listener will be overwritten.

Note: Eye images must be enabled to receive those callbacks

See also: streamEyeImages()

Parameters

callback this instance will be notified of all eye images 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

callback this 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.

◆ requestServerList()

EL_EXPORT int32_t STDCALL requestServerList	(	int32_t	blockingDurationMS,
		ServerInfo *	serverList,
		int32_t	serverListLength
	)

Ping all running EyeLogic servers in the local network and wait some time for their response.

Parameters

blockingDurationMS	waiting duration in milliseconds. Method returns after this time, or if 'serverListLength' many servers responded.
serverList	pre-allocated array of length 'serverListLength'. Will be filled with responding EyeLogic servers.
serverListLength	Lenght of pre-allocated serverList array

Returns: number of entries, written to the server list

◆ 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

frameRateModeInd index of the requested frame rate mode (0 ... #frameRateModes-1)

◆ setActiveScreen()

EL_EXPORT ReturnSetActiveScreen STDCALL setActiveScreen	(	const char *	screenID,
		DeviceGeometry	deviceGeometry
	)

Make a screen connected to this machine to the active screen.

Recording is from now on performed on the new active screen. Remember to perform a calibration on the new screen, otherwise it remains in an uncalibrated state.

Parameters

screenID	ID of the new active screen on this machine (even works if the connection to the server is remote). If null, the primary screen of this machine is set as active.
deviceGeometry	Geometry of the device which is mounted to the screen.

Returns: success/error code

◆ streamEyeImages()

EL_EXPORT ReturnStreamEyeImages STDCALL streamEyeImages ( bool enable )

Enabled/disables eye image stream. If enabled, eye images are received from eye image listeners,.

See also: registerEyeImageListener() and; getNextEyeImage(). Note, that enabling eye images can lead to noticable CPU load and a loss of gaze samples. Always disable it before running your experiment. Eye images can not be received via remote connections.

◆ 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.

◆ validate()

EL_EXPORT ReturnValidate STDCALL validate ( ELValidationResult & validationResult )

perform validation (method is blocking until validation finished)

Parameters

validationResult upon ReturnValidate::SUCCESS this struct will be filled with the validation results - may contain ELInvalidValues. Contains all ELInvalidValues for all other return values.

Classes

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Event

◆ ReturnCalibrate

◆ ReturnConnect

◆ ReturnNextData

◆ ReturnSetActiveScreen

◆ ReturnStart

◆ ReturnStreamEyeImages

◆ ReturnValidate

Constructor & Destructor Documentation

◆ ELApi()

Member Function Documentation

◆ calibrate()

◆ connect()

◆ connectRemote()

◆ getAvailableScreens()

◆ getNextEvent()

◆ getNextEyeImage()

◆ getNextGazeSample()

◆ registerEventListener()

◆ registerEyeImageListener()

◆ registerGazeSampleListener()

◆ requestServerList()

◆ requestTracking()

◆ setActiveScreen()

◆ streamEyeImages()

◆ unrequestTracking()

◆ validate()