Interface to the features exposed by the Interaction Library SDK C# binding. More...

Inheritance diagram for IInteractionLib:

Adapters
Adapters are the abstraction layer between the Interaction Library and the eyetracking data provider. The Interaction Library ships with a default adapter for Tobii consumer eyetracking devices so setting an adapter is NOT required to use the Interaction Library. Setting a custom adapter can however be useful e.g. when testing by supplying a "fake" adapter implementation that generates controlled test data.
Result	SetAdapter (IntPtr adapterFunctions)
	Sets a custom adapter for this InteractionLib instance, or removes the current adapter. More...

Display Properties and Coordinate Transforms
In order for the interaction library to function properly, you need to setup the appropriate coordinate system for your environment. This coordinate system will be used for all interactor operations, and all display based coordinates in data streams. Important: If you are using a UI binding with the Interaction Library it should set all of these values for you! If you are, you can skip this section. If not, or if you are developing a UI binding, read on. For most use cases: Use CoordinateTransformAddOrUpdateDisplayArea() to add dpi scaling and location information on all screens in the system. To use window local coordinates, use CoordinateTransformSetOriginOffset() with your window position (in system virtual screen coordinates). Special cases: If you are sure you only have one display you can use an abbreviated call to CoordinateTransformAddOrUpdateDisplayArea() where you don't need any knowledge about the system virtual coordinate system layout or display ids (see below). The same applies if you are sure the application will stay on one display, and that display is the one that the tracking device is mounted on (or at least the tracking device exclusively used by the current adapter). If you have no means to get information about displays (eg. because you are in sandboxed environment), use CoordinateTransformSetDisplayDensity() instead so that interaction library can perform proper gaze focus calculations. If you only use data streams and wish to use adapter native units, you don't have to set any coordinate transform information. Note that the coordinate system being used will then be entirely dependent on the adapter being used. Usage tips: If your coordinate system dpi changes, remember to update. If CoordinateTransformSetOriginOffset() is used to get window local coordinates, remember to update when your window moves (and when dpi scaling changes) Note If no coordinate transform is set, the default coordinate system for the current adapter is used (if available).
Result	CoordinateTransformAddOrUpdateDisplayArea (float widthUserUnits, float heightUserUnits, float widthVirtualUnits=0, float heightVirtualUnits=0, float xOriginVirtualUnits=0, float yOriginVirtualUnits=0, string virtualDisplayAreaId="")
	Adds a display area (usually a screen) to the coordinate transform setup. Typically call this method multiple times to add information on dpi scaling and location of all screens in the system (see sample/separate documentation for details). More...

Result	CoordinateTransformSetOriginOffset (float xOriginOffsetVirtualUnits, float yOriginOffsetVirtualUnits)
	Sets your origin position, as it is in the virtual coordinate system. Typically used to set the window position to use window local coordinates for streams and interactors, or one could set the display center to use a centered, left-handed coordinate system. More...

Result	CoordinateTransformSetDisplayDensity (float xUnitsPerMm, float yUnitsPerMm)
	An alternative to CoordinateTransformAddOrUpdateDisplayArea(), normally only used in special circumstances. More...

Interactors
Interactors are regions on screen that can be interacted with using gaze. Various interaction events are produced for declared interactors when the user looks around (see Interactor Events). Add or update multiple interactors and their properties by subsequent calls to AddOrUpdateInteractor(), AddOrUpdateInteractorBounds(), UpdateInteractorZ(), RemoveInteractor(), and ClearInteractors(). Batches of updates are performed between calls to BeginInteractorUpdates() and CommitInteractorUpdates(). Calling both of them, and in the correct order, is required. Using BeginInteractorUpdates() and CommitInteractorUpdates() is both a performance benefit and an insurance of transaction safety: All changes take effect at the time of a successful commit, not for each individual add/update/remove/clear call. Note however that the interactor functions are not thread local.
Result	BeginInteractorUpdates ()
	Begins an interactor update transaction, in which many add/update/remove/clear calls are batched. More...

Result	CommitInteractorUpdates ()
	Commits all batched interactor add/update/remove/clear calls done since BeginInteractorUpdates() was called. More...

Result	AddOrUpdateInteractor (ulong interactorId, Rectangle bounds, float z)
	Adds an interactor or updates an existing one, specifying its `bounds` and `z` value (the value increases towards the user). More...

Result	UpdateInteractorBounds (ulong interactorId, Rectangle bounds)
	Updates the `bounds` for an existing interactor. More...

Result	UpdateInteractorZ (ulong interactorId, float z)
	Updates the `z` value for an existing interactor (the value increases towards the user). More...

Result	RemoveInteractor (ulong interactorId)
	Removes an existing interactor and all its related data. More...

Result	ClearInteractors ()
	Removes all existing interactors. More...

Interactor Weight Distributions
Weight distributions can be used to describe the visual attention properties of an interactor. As an example, UI buttons tend to have their visual content in the center, so the benefit from being center weighted. Standard Weight Distributions Standard weight distribution types are built into Interaction Library and can be used to specify, for example, center weighted or flat distributions. Use UpdateInteractorStandardWeightDistributionTypes() to change these. Setting a flat weight distribution type removes any previous weight distribution settings. Custom Weight Distributions Custom weight distributions can be used for three purposes: To specify non-rectangular shapes for interactors - use as a stencil map (isStencilMap = true). To declare a custom weight distribution (isWeightDistribution = true). A combination of the above. For stencil maps, values are checked for 0 or >0, with 0 being transparent. For weight distributions, values are in the range 0 to 255, with 0 still obscuring elements behind but not adding weight to selection of focused interactors. A value of 1 denotes normal weight. A combination of both work like weight distributions but with 0 being transparent (like in stencil maps). Custom weight distribution bitmaps can be bound to (used for) multiple interactors. They are stretched to fit the bounds of the bound interactor. You can add a maximum of one stencil map and one weight distribution per interactor (or one combined). Note Custom weight distributions are not copied. They need to be kept alive by you (and at the same location)!
Result	UpdateInteractorStandardWeightDistributionTypes (ulong interactorId, WeightDistributionType weightDistributionTypes)
	Sets the built-in standard weight distribution of an interactor, e.g., center weighted or flat. More...

Result	AddOrUpdateCustomWeightDistributionBitmap (ulong weightDistributionId, bool isWeightDistribution, bool isStencilMap, int bitmapColumns, int bitmapRows, byte[] bitmap)
	Adds a new custom weight distribution bitmap or updates an existing one. More...

Result	RemoveCustomWeightDistributionBitmap (ulong weightDistributionId)
	Removes an existing custom weight distribution bitmap. More...

Result	AddOrUpdateBindingToCustomWeightDistribution (ulong interactorId, ulong weightDistributionId)
	Adds a new custom weight distribution bitmap and binds it to an existing interactor, or changes an existing binding. More...

Result	RemoveBindingToCustomWeightDistribution (ulong interactorId, ulong weightDistributionId)
	Removes an existing binding to a custom weight distribution bitmap for the specified interactor. More...

Interactor Events
Gaze focus events are generated when the user looks at an interactor, as well as when the user's gaze leaves the interactor. Leave events are also produced if the user physically leaves his position in front of the tracker or the tracking stops, etc. Additionally, various device data streams are exposed in the Interaction Library. They can be subscribed to and unsubscribed from, at will, as long as only event handler is registered per data stream. Event handlers are invoked on the thread calling Update() or UpdateStreamingDataOutput(). Note Coordinates are in the original adapter coordinate system.
GazeFocusCallback	GazeFocusEvent
	Gaze focus event handler. More...

GazePointDataCallback	GazePointDataEvent
	Gaze point data stream event handler. More...

GazeOriginDataCallback	GazeOriginDataEvent
	Gaze origin data stream event handler. More...

PresenceDataCallback	PresenceDataEvent
	Presence data stream event handler. More...

HeadPoseDataCallback	HeadPoseDataEvent
	Head pose data stream handler. More...

DataStreamCapabilitiesChangedCallback	DataStreamCapabilitiesChangedEvent
	This callback will be triggered on UpdateStreamingDataOutput()/Update()/WaitAndUpdate() if capabilities have changed. Querying capabilites with GetDataStreamCapability(...) on this event invocation is allowed. More...

Result	GetDataStreamCapability (StreamType streamType, out Capability capability)
	Get information on the current system capabilities for a data stream. More...

Control
Various ways of controlling the Interaction Library processing flow. Since the Interaction Library does not have any threads by itself, periodic update calls are needed to collect data from the device, perform all calculations, select the currently focused interactor, produce suitable interaction events and trigger any callbacks. The Update() method performs all update operations while the UpdateStreamingDataOutput() and UpdateInteraction() methods can be used instead of Update() if more fine-grained control is needed. WaitForDeviceDataAvailable() can be used to block until new device data is available. This is optional. Note If WaitForDeviceDataAvailable() is not used, remember to call Update() or UpdateStreamingDataOutput() at least 10 times per second to ensure device connections are maintained and proper events are triggered.
Result	WaitAndUpdate (ulong connectionIntervalMs=1000)
	Checks/waits for device connection, waits for data, and updates. More...

Result	WaitForDeviceConnection ()
	Waits for a device to be available and a connection to be established. More...

Result	Update ()
	Updates the system and receives event callbacks that are called on the calling thread. More...

Result	WaitForDeviceDataAvailable ()
	Waits for data from the current device. More...

Result	UpdateStreamingDataOutput ()
	Updates stream buffers and process filters only, and publishes results on the calling thread via the registered streaming data callbacks. More...

Result	UpdateInteraction ()
	Updates interaction buffers, performs interactor selection calculations, and publishes results on calling thread via the interaction event handlers. More...

Detailed Description

Interface to the features exposed by the Interaction Library SDK C# binding.

Note: Since this interface is disposable, remember to call its Dispose() method when an instance of it isn't used any longer. Alternatively, use the instance in a using scope, where it'll be automatically disposed when the scope is left.

Explicit disposal: ``` IInteractionLib intlib = Tobii.InteractionLib.InteractionLibFactory.CreateInteractionLib(Tobii.InteractionLib.FieldOfUse.Interactive); // ... do things intlib.Dispose(); ```

Implicit disposal: ``` using (IInteractionLib intlib = Tobii.InteractionLib.InteractionLibFactory.CreateInteractionLib(Tobii.InteractionLib.FieldOfUse.Interactive)) { // ... do things } ```

Member Function Documentation

◆ SetAdapter()

Result SetAdapter ( IntPtr adapterFunctions )

Sets a custom adapter for this InteractionLib instance, or removes the current adapter.

Parameters

adapterFunctions Pointer to an instance of the native IL_AdapterFunctions structure that defines the custom adapter. IntPtr.Zero is a valid parameter value which means the current adapter will be removed. Without a valid adapter the following functions will do nothing and return Result.Warning_NoAdapterSet.

WaitAndUpdate() , WaitForDeviceConnection() , Update() , UpdateStreamingDataOutput() , UpdateInteraction() ,

However, it is still possible to add interactors and subscribe to gaze focus events and data streams.

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ CoordinateTransformAddOrUpdateDisplayArea()

Result CoordinateTransformAddOrUpdateDisplayArea	(	float	widthUserUnits,
		float	heightUserUnits,
		float	widthVirtualUnits = `0`,
		float	heightVirtualUnits = `0`,
		float	xOriginVirtualUnits = `0`,
		float	yOriginVirtualUnits = `0`,
		string	virtualDisplayAreaId = `""`
	)

Adds a display area (usually a screen) to the coordinate transform setup. Typically call this method multiple times to add information on dpi scaling and location of all screens in the system (see sample/separate documentation for details).

If you are in a single screen environment, or a defacto single screen environment (see above), or use other (external) mechanisms to handle multiple displays areas, you may call this only once and then omit all parameters except the first two.

If you are unable to determine this information in your environment, please use CoordinateTransformSetDisplayDensity() instead (see below).

Note: If you are using a UI binding, it will usually take care of setting up all display areas.

Parameters

widthUserUnits	The width in your preferred units (eg. with dpi scaling in your environment, or other preferred units)
heightUserUnits	The height in your preferred units (eg. with dpi scaling in your environment, or other preferred units)
widthVirtualUnits	The width in system virtual screen units (or custom units that you use for system display setup)
heightVirtualUnits	The height in system virtual screen units (or custom units that you use for system display setup)
xOriginVirtualUnits	The display origin x coordinate in the system virtual screen coordinate system (or your custom space for system display setup)
yOriginVirtualUnits	The display origin y coordinate in the system virtual screen coordinate system (or your custom space for system display setup)
virtualDisplayAreaId	The virtual display id as a string (eg. on Windows this is a number)

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ CoordinateTransformSetOriginOffset()

Result CoordinateTransformSetOriginOffset	(	float	xOriginOffsetVirtualUnits,
		float	yOriginOffsetVirtualUnits
	)

Sets your origin position, as it is in the virtual coordinate system. Typically used to set the window position to use window local coordinates for streams and interactors, or one could set the display center to use a centered, left-handed coordinate system.

Note: This command is optional. Not setting this will assume system virtual screen coordinates are being used for all on-display coordinates (or the custom coordinate system units that you used for system display setup).

Parameters

xOriginOffsetVirtualUnits	The x offset in the system virtual screen coordinate system (or your custom space)
yOriginOffsetVirtualUnits	The y offset in the system virtual screen coordinate system (or your custom space)

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ CoordinateTransformSetDisplayDensity()

Result CoordinateTransformSetDisplayDensity	(	float	xUnitsPerMm,
		float	yUnitsPerMm
	)

An alternative to CoordinateTransformAddOrUpdateDisplayArea(), normally only used in special circumstances.

This method exists as an alternative or addition to CoordinateTransformAddOrUpdateDisplayArea(). It is mainly intended to be used in edge cases where you are in a sandboxed environment and cannot access information about displays, or if a specialized adapter is used that you cannot access or modify for some reason and CoordinateTransformAddOrUpdateDisplayArea() is insufficient to solve the dpi scaling problem. You can see if you need to use CoordinateTransformSetDisplayDensity() by checking the return value from CoordinateTransformAddOrUpdateDisplayArea(). In almost all situations, using only CoordinateTransformAddOrUpdateDisplayArea() is sufficient.

Note: Only to be used in special circumstances!

Parameters

xUnitsPerMm	The number of horizontal units per mm.
yUnitsPerMm	The number of vertical units per mm.

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ BeginInteractorUpdates()

Result BeginInteractorUpdates ( )

Begins an interactor update transaction, in which many add/update/remove/clear calls are batched.

Note: Must be called before any add/update/remove/clear calls.

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ CommitInteractorUpdates()

Result CommitInteractorUpdates ( )

Commits all batched interactor add/update/remove/clear calls done since BeginInteractorUpdates() was called.

Note: Must be called for any interactor or interactor weights modifications to have effect.

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ AddOrUpdateInteractor()

Result AddOrUpdateInteractor	(	ulong	interactorId,
		Rectangle	bounds,
		float	z
	)

Adds an interactor or updates an existing one, specifying its bounds and z value (the value increases towards the user).

Parameters

interactorId
bounds
z

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ UpdateInteractorBounds()

Result UpdateInteractorBounds	(	ulong	interactorId,
		Rectangle	bounds
	)

Updates the bounds for an existing interactor.

Parameters

interactorId
bounds

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ UpdateInteractorZ()

Result UpdateInteractorZ	(	ulong	interactorId,
		float	z
	)

Updates the z value for an existing interactor (the value increases towards the user).

Parameters

interactorId
z

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ RemoveInteractor()

Result RemoveInteractor ( ulong interactorId )

Removes an existing interactor and all its related data.

Note: Custom weight distribution bitmaps are not removed, since they may be shared between interactors. However, the binding between the interactor and the custom weight distribution bitmaps are removed.

Parameters

interactorId

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ ClearInteractors()

Result ClearInteractors ( )

Removes all existing interactors.

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ UpdateInteractorStandardWeightDistributionTypes()

Result UpdateInteractorStandardWeightDistributionTypes	(	ulong	interactorId,
		WeightDistributionType	weightDistributionTypes
	)

Sets the built-in standard weight distribution of an interactor, e.g., center weighted or flat.

Parameters

interactorId
weightDistributionTypes

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ AddOrUpdateCustomWeightDistributionBitmap()

Result AddOrUpdateCustomWeightDistributionBitmap	(	ulong	weightDistributionId,
		bool	isWeightDistribution,
		bool	isStencilMap,
		int	bitmapColumns,
		int	bitmapRows,
		byte []	bitmap
	)

Adds a new custom weight distribution bitmap or updates an existing one.

Parameters

weightDistributionId
isWeightDistribution
isStencilMap
bitmapColumns
bitmapRows
bitmap

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ RemoveCustomWeightDistributionBitmap()

Result RemoveCustomWeightDistributionBitmap ( ulong weightDistributionId )

Removes an existing custom weight distribution bitmap.

Parameters

weightDistributionId

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ AddOrUpdateBindingToCustomWeightDistribution()

Result AddOrUpdateBindingToCustomWeightDistribution	(	ulong	interactorId,
		ulong	weightDistributionId
	)

Adds a new custom weight distribution bitmap and binds it to an existing interactor, or changes an existing binding.

Parameters

interactorId
weightDistributionId

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ RemoveBindingToCustomWeightDistribution()

Result RemoveBindingToCustomWeightDistribution	(	ulong	interactorId,
		ulong	weightDistributionId
	)

Removes an existing binding to a custom weight distribution bitmap for the specified interactor.

Parameters

interactorId
weightDistributionId

Returns: Result.Ok if the operation succeeded; otherwise a Result warning or error code.

◆ GetDataStreamCapability()

Result GetDataStreamCapability	(	StreamType	streamType,
		out Capability	capability
	)

Get information on the current system capabilities for a data stream.

Data stream availability is dependent on if a device is present, what type of device it is and current system state of the device being used. Data streams are typically not enabled unless the they are subscribed to, either internally by the Interaction Library or from this api.

Parameters

	streamType	The stream type to get capability information on.
[out]	capability	Will be set to the system capability for the stream type.

◆ WaitAndUpdate()

Result WaitAndUpdate ( ulong connectionIntervalMs = 1000 )

Checks/waits for device connection, waits for data, and updates.

This is a convenience method that aggregates all necessary control methods into one, and sleeps the calling thread for the appropriate amount of time between connection attempts when no device is connected. The default connection attempt interval is one second, passing 0 means no sleep.

If you need granular control over updates and/or non-blocking calls use a suitable combination of the various other control methods.

Returns: Result.Ok if all goes well. See the other control methods for information about other possible return codes.

◆ WaitForDeviceConnection()

Result WaitForDeviceConnection ( )

Waits for a device to be available and a connection to be established.

Returns: Result.WarningNoDeviceAvailable if a device can't be connected to (wait time is short but varies with adapter).; Result.Ok if a device is connected to. When a device connection has already been made previously and is still available, it returns Result.Ok immediately.

◆ Update()

Result Update ( )

Updates the system and receives event callbacks that are called on the calling thread.

Returns: Result.WarningNoAdapterSet if no adapter is set (see InteractionLibFactory.CreateInteractionLib()); otherwise another Result code.

◆ WaitForDeviceDataAvailable()

Result WaitForDeviceDataAvailable ( )

Waits for data from the current device.

May timeout or hang indefinitely depending on adapter implementation. Waiting is optional but if you do not wait, remember to call Update() or UpdateStreamingDataOutput() at least 10 times per second. Do call Update() (or some combination of the other update methods) after waiting regardless of return code to make sure all proper events are generated.

Returns: Result.WarningNoAdapterSet if no adapter is set (see InteractionLibFactory.CreateInteractionLib()); otherwise another Result code.

◆ UpdateStreamingDataOutput()

Result UpdateStreamingDataOutput ( )

Updates stream buffers and process filters only, and publishes results on the calling thread via the registered streaming data callbacks.

Use instead of Update() if you need more granular control or use multiple threads.

Returns: Result.ErrorNoAdapterSet if no adapter is set (see InteractionLibFactory.CreateInteractionLib()); otherwise another Result code.

◆ UpdateInteraction()

Result UpdateInteraction ( )

Updates interaction buffers, performs interactor selection calculations, and publishes results on calling thread via the interaction event handlers.

Use instead of Update() if you need more granular control or use multiple threads.

Note: UpdateStreamingDataOutput() needs to be called before this call.

Returns: Result.ErrorNoAdapterSet if no adapter is set (see InteractionLibFactory.CreateInteractionLib()); otherwise another Result code.

Event Documentation

◆ GazeFocusEvent

GazeFocusCallback GazeFocusEvent

Gaze focus event handler.

◆ GazePointDataEvent

GazePointDataCallback GazePointDataEvent

Gaze point data stream event handler.

◆ GazeOriginDataEvent

GazeOriginDataCallback GazeOriginDataEvent

Gaze origin data stream event handler.

◆ PresenceDataEvent

PresenceDataCallback PresenceDataEvent

Presence data stream event handler.

◆ HeadPoseDataEvent

HeadPoseDataCallback HeadPoseDataEvent

Head pose data stream handler.

◆ DataStreamCapabilitiesChangedEvent

DataStreamCapabilitiesChangedCallback DataStreamCapabilitiesChangedEvent

This callback will be triggered on UpdateStreamingDataOutput()/Update()/WaitAndUpdate() if capabilities have changed. Querying capabilites with GetDataStreamCapability(...) on this event invocation is allowed.

The documentation for this interface was generated from the following file:

InteractionLib.cs

Adapters

Display Properties and Coordinate Transforms

Interactors

Interactor Weight Distributions

Interactor Events

Control

Detailed Description

Member Function Documentation

◆ SetAdapter()

◆ CoordinateTransformAddOrUpdateDisplayArea()

◆ CoordinateTransformSetOriginOffset()

◆ CoordinateTransformSetDisplayDensity()

◆ BeginInteractorUpdates()

◆ CommitInteractorUpdates()

◆ AddOrUpdateInteractor()

◆ UpdateInteractorBounds()

◆ UpdateInteractorZ()

◆ RemoveInteractor()

◆ ClearInteractors()

◆ UpdateInteractorStandardWeightDistributionTypes()

◆ AddOrUpdateCustomWeightDistributionBitmap()

◆ RemoveCustomWeightDistributionBitmap()

◆ AddOrUpdateBindingToCustomWeightDistribution()

◆ RemoveBindingToCustomWeightDistribution()

◆ GetDataStreamCapability()

◆ WaitAndUpdate()

◆ WaitForDeviceConnection()

◆ Update()

◆ WaitForDeviceDataAvailable()

◆ UpdateStreamingDataOutput()

◆ UpdateInteraction()

Event Documentation

◆ GazeFocusEvent

◆ GazePointDataEvent

◆ GazeOriginDataEvent

◆ PresenceDataEvent

◆ HeadPoseDataEvent

◆ DataStreamCapabilitiesChangedEvent