ELCApi.h File Reference

The file contains the C prototype declaration for all functions which are neccessary to control the EyeLogic software from an API client. More...

#include "ELCGazeSample.h"
#include "ELCEyeImage.h"
#include "ELCGazeEvent.h"

Classes
struct	ELCServerInfo
	connection information for an EyeLogic server More...
struct	ELCScreenConfig
	Screen configuration. More...
struct	ELCDeviceGeometry
	Geometric position of the device related to the active monitor. More...
struct	ELCDeviceConfig
	Device configuration. More...
struct	ELCValidationPointResult
	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	ELCValidationResult
	ValidationResult contains one ValidationPointResult struct per validation stimulus point of the performed valdation. More...

Enumerations
enum	ELCDeviceEvent {   EVENT_SCREEN_CHANGED, EVENT_CONNECTION_CLOSED, EVENT_DEVICE_CONNECTED, EVENT_DEVICE_DISCONNECTED,   EVENT_TRACKING_STOPPED }
	EyeLogic events. More...
enum	ELCReturnInit { INIT_SUCCESS, INIT_ALREADY_INITED }
	return values of elInitApi( ) More...
enum	ELCReturnConnect { CONNECT_SUCCESS, CONNECT_NOT_INITED, CONNECT_VERSION_MISMATCH, CONNECT_FAILURE }
	return values of elConnect( ) More...
enum	ELCReturnActiveScreen { ACTIVESCREEN_SUCCESS, ACTIVESCREEN_NOT_INITED, ACTIVESCREEN_NOT_FOUND, ACTIVESCREEN_FAILURE }
	return values of setActiveScreen( ) More...
enum	ELCReturnStreamEyeImages { EYEIMAGES_SUCCESS, EYEIMAGES_NOT_CONNECTED, EYEIMAGES_REMOTE_CONNECTION, EYEIMAGES_FAILURE }
	Return values of the elStreamEyeImages() function. More...
enum	ELCReturnNextData {   NEXTDATA_SUCCESS, NEXTDATA_PTR_IS_NULL, NEXTDATA_NOT_INITED, NEXTDATA_TIMEOUT,   NEXTDATA_CONNECTION_CLOSED }
	Return values of the getNextEvent/getNextGazeSample functions. More...
enum	ELCReturnStart {   START_SUCCESS, START_NOT_CONNECTED, START_DEVICE_MISSING, START_INVALID_FRAMERATE_MODE,   START_ALREADY_RUNNING_DIFFERENT_FRAMERATE, START_FAILURE }
	return values of elRequestTracking( ) More...
enum	ELCReturnCalibrate {   CALIB_SUCCESS, CALIB_NOT_CONNECTED, CALIB_NOT_TRACKING, CALIB_INVALID_CALIBRATION_MODE,   CALIB_ALREADY_BUSY, CALIB_FAILURE }
	return values of elCalibrate( ) More...
enum	ELCReturnValidate {   VALID_SUCCESS, VALID_NOT_CONNECTED, VALID_NOT_TRACKING, VALID_NOT_CALIBRATED,   VALID_ALREADY_BUSY, VALID_PTR_IS_NULL, VALID_FAILURE }
	return values of elValidate( ) More...

Functions
typedef	void (STDCALL *GazeSampleCallback)(const struct ELCGazeSample *sample)
	callback function type, new gaze sample More...
EXTERNC ELC_EXPORT enum ELCReturnInit STDCALL	elInitApi (const char *clientName)
	initialize the ELCApi. More...
EXTERNC ELC_EXPORT void STDCALL	elDestroyApi ()
	destroys the ELCApi. Call this once before shutting down. Be sure to unregister all callbacks before calling this method. More...
EXTERNC ELC_EXPORT void STDCALL	elRegisterDeviceEventCallback (DeviceEventCallback eventCallback)
	registers the callback receiver for events. Ensure that all callbacks are unregistered before destruction. More...
EXTERNC ELC_EXPORT void STDCALL	elRegisterGazeSampleCallback (GazeSampleCallback sampleCallback)
	registers the callback receiver for gaze samples. Ensure that all callbacks are unregistered before destruction. More...
EXTERNC ELC_EXPORT void STDCALL	elRegisterEyeImageCallback (EyeImageCallback eyeImageCallback)
	registers the callback receiver for eye images. Ensure that all callbacks are unregistered before destruction. More...
EXTERNC ELC_EXPORT void STDCALL	elRegisterGazeEventCallback (FixationStartCallback fixationStartCallback, FixationStopCallback fixationStopCallback)
	registers the callback receiver for gaze events. Ensure that all callbacks are unregistered before destruction. More...
EXTERNC ELC_EXPORT enum ELCReturnConnect STDCALL	elConnect ()
	return values of elConnect( ) More...
EXTERNC ELC_EXPORT enum ELCReturnConnect STDCALL	elConnectRemote (struct ELCServerInfo server)
	initialize connection to a remote server (method is blocking until connection established) More...
EXTERNC ELC_EXPORT int32_t STDCALL	elRequestServerList (int32_t blockingDurationMS, struct ELCServerInfo *serverList, int32_t serverListLength)
	Ping all running EyeLogic servers in the local network and wait some time for their response. More...
EXTERNC ELC_EXPORT void STDCALL	elDisconnect ()
	closes connection to the server
EXTERNC ELC_EXPORT bool STDCALL	elIsConnected ()
	whether a connection to the server is established
EXTERNC ELC_EXPORT bool STDCALL	elGetActiveScreen (struct ELCScreenConfig *screenConfig)
	obtain configuration of active screen More...
EXTERNC ELC_EXPORT int32_t STDCALL	elGetAvailableScreens (struct ELCScreenConfig *screenConfig, int32_t numScreenConfigs)
	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...
EXTERNC ELC_EXPORT enum ELCReturnActiveScreen STDCALL	elSetActiveScreen (char *screenID, struct ELCDeviceGeometry deviceGeometry)
	Make a screen connected to this machine to the active screen. More...
EXTERNC ELC_EXPORT bool STDCALL	elGetDeviceConfig (struct ELCDeviceConfig *deviceConfig)
	obtain configuration of active device More...
EXTERNC ELC_EXPORT enum ELCReturnStreamEyeImages STDCALL	elStreamEyeImages (bool enable)
	Enabled/disables eye image stream. If enabled, eye images are received from eye image listeners,. More...
EXTERNC ELC_EXPORT enum ELCReturnNextData STDCALL	elGetNextDeviceEvent (enum ELCDeviceEvent *event, int32_t timeoutMillis)
	Obtains the next unread event or blocks until a new event occurs or the given timeout is reached. More...
EXTERNC ELC_EXPORT enum ELCReturnNextData STDCALL	elGetNextGazeSample (struct ELCGazeSample *gazeSample, int32_t timeoutMillis)
	Obtains the next unread gazeSample or blocks until a new GazeSample is received or the given timeout is reached. More...
EXTERNC ELC_EXPORT enum ELCReturnNextData STDCALL	elGetNextEyeImage (struct ELCEyeImage *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...
EXTERNC ELC_EXPORT enum ELCReturnStart STDCALL	elRequestTracking (int32_t frameRateModeInd)
	request tracking More...
EXTERNC ELC_EXPORT void STDCALL	elUnrequestTracking ()
	unrequest tracking More...
EXTERNC ELC_EXPORT enum ELCReturnCalibrate STDCALL	elCalibrate (int32_t calibrationModeInd)
	perform calibration (method is blocking until calibration finished) More...
EXTERNC ELC_EXPORT void STDCALL	elAbortCalibValidation ()
	abort a running calibration / validation
EXTERNC ELC_EXPORT enum ELCReturnValidate STDCALL	elValidate (struct ELCValidationResult *validationResult)
	perform validation (method is blocking until validation finished) - calibration must be performed prior More...

Detailed Description

The file contains the C prototype declaration for all functions which are neccessary to control the EyeLogic software from an API client.

Enumeration Type Documentation

ELCDeviceEvent

enum ELCDeviceEvent

EyeLogic events.

Enumerator
EVENT_SCREEN_CHANGED	a new screen has been set as active
EVENT_CONNECTION_CLOSED	connection to EyeLogic Server has closed
EVENT_DEVICE_CONNECTED	a new device has connected
EVENT_DEVICE_DISCONNECTED	device disconnected
EVENT_TRACKING_STOPPED	tracking has stopped

ELCReturnActiveScreen

enum ELCReturnActiveScreen

return values of setActiveScreen( )

Enumerator
ACTIVESCREEN_SUCCESS	active screen was set
ACTIVESCREEN_NOT_INITED	library needs to be initialized first, See also elInitApi
ACTIVESCREEN_NOT_FOUND	specified screen name was not found as a name of an available monitor
ACTIVESCREEN_FAILURE	active screen could not be changed

ELCReturnCalibrate

enum ELCReturnCalibrate

return values of elCalibrate( )

Enumerator
CALIB_SUCCESS	calibration successful
CALIB_NOT_CONNECTED	cannot calibrate: not connected to the server
CALIB_NOT_TRACKING	cannot calibrate: no device found or tracking not started
CALIB_INVALID_CALIBRATION_MODE	cannot start calibration: calibration mode is invalid or not supported
CALIB_ALREADY_BUSY	cannot start calibration: calibration or validation is already in progress
CALIB_FAILURE	calibration was not successful or aborted

ELCReturnConnect

enum ELCReturnConnect

return values of elConnect( )

Enumerator
CONNECT_SUCCESS	connection successfully established
CONNECT_NOT_INITED	connection failed: library needs to be initialized first, See also elInitApi
CONNECT_VERSION_MISMATCH	connection failed: API is build on a newer version than the server. Update the EyeLogicServer to the newest version.
CONNECT_FAILURE	connection failed: the server can not be found or is not responding

ELCReturnInit

enum ELCReturnInit

return values of elInitApi( )

Enumerator
INIT_SUCCESS	initializeation was successful
INIT_ALREADY_INITED	initialization was not successfull: was already initialized before

ELCReturnNextData

enum ELCReturnNextData

Return values of the getNextEvent/getNextGazeSample functions.

Enumerator
NEXTDATA_SUCCESS	new event or new GazeSample received
NEXTDATA_PTR_IS_NULL	input ptr is nullptr
NEXTDATA_NOT_INITED	library needs to be initialized first, See also elInitApi
NEXTDATA_TIMEOUT	timeout reached, no new event/GazeSample received
NEXTDATA_CONNECTION_CLOSED	connection to server closed, no new event/GazeSample received

ELCReturnStart

enum ELCReturnStart

return values of elRequestTracking( )

Enumerator
START_SUCCESS	start tracking successful
START_NOT_CONNECTED	not connected to the server
START_DEVICE_MISSING	cannot start tracking: no device found
START_INVALID_FRAMERATE_MODE	cannot start tracking: framerate mode is invalid or not supported
START_ALREADY_RUNNING_DIFFERENT_FRAMERATE	tracking already ongoing, but frame rate mode is different
START_FAILURE	some general failure occurred

ELCReturnStreamEyeImages

enum ELCReturnStreamEyeImages

Return values of the elStreamEyeImages() function.

Enumerator
EYEIMAGES_SUCCESS	setting streaming of eye images was successful
EYEIMAGES_NOT_CONNECTED	failed, not connected to the server
EYEIMAGES_REMOTE_CONNECTION	cannot stream eye images when connection to the server is a remote connection
EYEIMAGES_FAILURE	failure when trying to set eye image stream

ELCReturnValidate

enum ELCReturnValidate

return values of elValidate( )

Enumerator
VALID_SUCCESS	start validation successful
VALID_NOT_CONNECTED	cannot validate: not connected to the server
VALID_NOT_TRACKING	cannot validate: no device found or tracking not started
VALID_NOT_CALIBRATED	cannot start validation: validation mode is invalid or not supported
VALID_ALREADY_BUSY	cannot start validation: calibration or validation is already in progress
VALID_PTR_IS_NULL	input is nullptr
VALID_FAILURE	validation failure

Function Documentation

elCalibrate()

EXTERNC ELC_EXPORT enum ELCReturnCalibrate STDCALL elCalibrate

(

int32_t

calibrationModeInd

)

perform calibration (method is blocking until calibration finished)

Returns

success state

elConnect()

EXTERNC ELC_EXPORT enum ELCReturnConnect STDCALL elConnect

(

)

return values of elConnect( )

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,

Returns

success state

See also

elConnectRemote( ).

Returns

success state

elConnectRemote()

EXTERNC ELC_EXPORT enum ELCReturnConnect STDCALL elConnectRemote

(

struct ELCServerInfo

server

)

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

Parameters

server

Server to connect to

Returns

success state

See also

elAcquireServerList( ) to obtain IP address and port of a remote server

elDestroyApi()

EXTERNC ELC_EXPORT void STDCALL elDestroyApi

(

)

destroys the ELCApi. Call this once before shutting down. Be sure to unregister all callbacks before calling this method.

See also

elRegisterDeviceEventCallback( )

elRegisterGazeSampleCallback( )

elRegisterEyeImageCallback( )

elRegisterGazeEventCallback( )

elGetActiveScreen()

EXTERNC ELC_EXPORT bool STDCALL elGetActiveScreen

(

struct ELCScreenConfig *

screenConfig

)

obtain configuration of active screen

Parameters

screenConfig

is set to the config state upon success, set to 0-initialized struct if library is not initialized

Returns

true upon successfull config recovery, false upon unitialized library or screenConfig == nullptr

elGetAvailableScreens()

EXTERNC ELC_EXPORT int32_t STDCALL elGetAvailableScreens	(	struct ELCScreenConfig *	screenConfig,
		int32_t	numScreenConfigs
	)

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

elGetDeviceConfig()

EXTERNC ELC_EXPORT bool STDCALL elGetDeviceConfig

(

struct ELCDeviceConfig *

deviceConfig

)

obtain configuration of active device

Parameters

deviceConfig

is set to the config state upon success, set to 0-initialized struct if library is not initialized

Returns

true upon successfull config recovery, false upon unitialized library or screenConfig == nullptr

elGetNextDeviceEvent()

EXTERNC ELC_EXPORT enum ELCReturnNextData STDCALL elGetNextDeviceEvent	(	enum ELCDeviceEvent *	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

registerDeviceEventListener

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

elGetNextEyeImage()

EXTERNC ELC_EXPORT enum ELCReturnNextData STDCALL elGetNextEyeImage	(	struct ELCEyeImage *	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)

elGetNextGazeSample()

EXTERNC ELC_EXPORT enum ELCReturnNextData STDCALL elGetNextGazeSample	(	struct ELCGazeSample *	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

elInitApi()

EXTERNC ELC_EXPORT enum ELCReturnInit STDCALL elInitApi

(

const char *

clientName

)

initialize the ELCApi.

Call this once before calling any other function from this library.

Parameters

clientName

string identifier of the client (shown in the server tool window)

elRegisterDeviceEventCallback()

EXTERNC ELC_EXPORT void STDCALL elRegisterDeviceEventCallback

(

DeviceEventCallback

eventCallback

)

registers the callback receiver for events. Ensure that all callbacks are unregistered before destruction.

Parameters

eventCallback

this callback function is called on new events, may be null to unregister

elRegisterEyeImageCallback()

EXTERNC ELC_EXPORT void STDCALL elRegisterEyeImageCallback

(

EyeImageCallback

eyeImageCallback

)

registers the callback receiver for eye images. Ensure that all callbacks are unregistered before destruction.

Parameters

eyeImageCallback

this callback function is called on new eye images, may be null to unregister

elRegisterGazeEventCallback()

EXTERNC ELC_EXPORT void STDCALL elRegisterGazeEventCallback	(	FixationStartCallback	fixationStartCallback,
		FixationStopCallback	fixationStopCallback
	)

registers the callback receiver for gaze events. Ensure that all callbacks are unregistered before destruction.

Parameters

fixationStartCallback	called when the start of a fixation is detected, may be null to unregister
fixationStopCallback	called when the end of a fixation is detected, may be null to unregister

elRegisterGazeSampleCallback()

EXTERNC ELC_EXPORT void STDCALL elRegisterGazeSampleCallback

(

GazeSampleCallback

sampleCallback

)

registers the callback receiver for gaze samples. Ensure that all callbacks are unregistered before destruction.

Parameters

sampleCallback

this callback function is called on new gaze samples, may be null to unregister

elRequestServerList()

EXTERNC ELC_EXPORT int32_t STDCALL elRequestServerList	(	int32_t	blockingDurationMS,
		struct ELCServerInfo *	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

elRequestTracking()

EXTERNC ELC_EXPORT enum ELCReturnStart STDCALL elRequestTracking

(

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)

Returns

success state

elSetActiveScreen()

EXTERNC ELC_EXPORT enum ELCReturnActiveScreen STDCALL elSetActiveScreen	(	char *	screenID,
		struct ELCDeviceGeometry	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

elStreamEyeImages()

EXTERNC ELC_EXPORT enum ELCReturnStreamEyeImages STDCALL elStreamEyeImages

(

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.

elUnrequestTracking()

EXTERNC ELC_EXPORT void STDCALL elUnrequestTracking

(

)

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.

elValidate()

EXTERNC ELC_EXPORT enum ELCReturnValidate STDCALL elValidate

(

struct ELCValidationResult *

validationResult

)

perform validation (method is blocking until validation finished) - calibration must be performed prior

Parameters

validationResult

upon ReturnValidate::SUCCESS this struct will be filled with the validation results - may contain ELCInvalidValues. Contains all ELCInvalidValue for all other return values - unless return value is VALID_NOT_CONNECTED, in that case validationResult will be set to all-zeros.

Returns

success state

void()

typedef void

(

STDCALL *

GazeSampleCallback

)

const

callback function type, new gaze sample

callback function type, fixation stopped

callback function type, new fixation started

callback function type, new device event occured

callback function type, new eye image