C#¶

The C# API provides comprehensive eye tracking functionality through an intuitive object-oriented design, following C# conventions and best practices.

Note

All C# types and classes described in this documentation are enclosed within the Eyeware.BeamEyeTracker namespace.

Core Classes¶

API¶

class Eyeware.BeamEyeTracker.API : IDisposable ¶

Main entry point for the Beam Eye Tracker SDK.

Note

See The API singleton for a high-level explanation of the API object.

Public Functions

API (string friendlyName, ViewportGeometry initialViewportGeometry)¶

Initializes a new instance of the Beam Eye Tracker API.

Param friendlyName:: Application identifier displayed in the Beam Eye Tracker UI (UTF-8, max 200 bytes)
Param initialViewportGeometry:: The initial viewport geometry configuration.
Throws ArgumentNullException:: Thrown when friendlyName is null or empty.
Throws ArgumentException:: Thrown when friendlyName exceeds 200 bytes.
Throws Exception:: Thrown when API creation fails.

Version GetVersion ()¶

Gets the version information of the Beam Eye Tracker SDK.

Throws ObjectDisposedException:: Thrown when the API instance has been disposed.
Return:: A Version structure containing major, minor, and patch version numbers.

void UpdateViewportGeometry (ViewportGeometry newViewportGeometry)¶

Updates the viewport geometry used for coordinate mapping.

Note

See Viewport for more information about viewport geometry.

Param newViewportGeometry:: The new viewport geometry configuration.
Throws ObjectDisposedException:: Thrown when the API instance has been disposed.

void AttemptStartingTheBeamEyeTracker ()¶

Attempts to automatically start the Beam Eye Tracker application if it’s not already running.

Note

See Launching the Beam Eye Tracker from your game or application for more information.

Throws ObjectDisposedException:: Thrown when the API instance has been disposed.

bool WaitForNewTrackingData (ref double lastReceivedTimestamp, uint timeoutMs = DefaultTrackingDataTimeoutMs)¶

Waits for new tracking data to become available.

Note

See Synchronous data access and Polling data access for more information.

Param lastReceivedTimestamp:: The timestamp of the last received data. Will be updated with the new timestamp if new data is available.
Param timeoutMs:: Maximum time to wait in milliseconds. Defaults to DefaultTrackingDataTimeoutMs.
Throws ObjectDisposedException:: Thrown when the API instance has been disposed.
Return:: True if new data is available, false if the timeout was reached.

TrackingDataReceptionStatus GetTrackingDataReceptionStatus ()¶

Gets the current status of tracking data reception.

Note

See The TrackingDataReceptionStatus object for more information.

Throws ObjectDisposedException:: Thrown when the API instance has been disposed.
Return:: The current TrackingDataReceptionStatus.

TrackingStateSet GetLatestTrackingStateSet ()¶

Gets the most recent tracking state set containing user state, camera state, and HUD state.

Note

See The TrackingStateSet object for more information.

Throws ObjectDisposedException:: Thrown when the API instance has been disposed.
Throws Exception:: Thrown when retrieving the tracking state set fails.
Return:: A TrackingStateSet containing the latest tracking data.

void StartReceivingTrackingDataOnListener (TrackingListener listener)¶

Registers a listener to receive tracking data updates.

Note

For a detailed explanation, see Asynchronous data access.

Param listener:: The TrackingListener to register.
Throws ArgumentNullException:: Thrown when listener is null.
Throws InvalidOperationException:: Thrown when the listener is already registered.
Throws Exception:: Thrown when registering the callbacks fails.
Throws ObjectDisposedException:: Thrown when the API instance has been disposed.

void StopReceivingTrackingDataOnListener (TrackingListener listener)¶

Unregisters a previously registered tracking data listener.

Param listener:: The TrackingListener to unregister.
Throws ArgumentNullException:: Thrown when listener is null.
Throws ArgumentException:: Thrown when the listener is not currently registered.
Throws ObjectDisposedException:: Thrown when the API instance has been disposed.

bool StartRecenterSimGameCamera ()¶

Starts the process of recentering the game camera.

Note

See Implement the camera recentering for more information.

Throws ObjectDisposedException:: Thrown when the API instance has been disposed.
Return:: True if recentering was successfully started, false otherwise.

void StopRecenterSimGameCamera ()¶

Stops the process of recentering the game camera.

Note

See Implement the camera recentering for more information.

Throws ObjectDisposedException:: Thrown when the API instance has been disposed.

void Dispose ()¶: Releases all resources used by this API instance.

Properties

bool IsDisposed { get; set; }¶: Gets whether this API instance has been disposed.

Public Static Functions

SimCameraTransform3D ComputeSimGameCameraTransformParameters (SimGameCameraState cameraState, float eyeTrackingWeight = 1.0f, float headTrackingWeight = 1.0f)¶

Computes the final camera transform parameters by combining eye and head tracking components.

Note

See In-game camera control for more information.

Param cameraState:: The current camera state containing eye and head tracking components.
Param eyeTrackingWeight:: Weight factor for the eye tracking component (default: 1.0).
Param headTrackingWeight:: Weight factor for the head tracking component (default: 1.0).
Return:: The computed camera transform parameters.

Public Static Attributes

const uint DefaultTrackingDataTimeoutMs = 1000¶: Default timeout in milliseconds for waiting for new tracking data.

TrackingStateSet¶

class Eyeware.BeamEyeTracker.TrackingStateSet¶

Contains the complete set of tracking data for a single frame, including user state, game camera state, and immersive HUD state.

This class provides access to all tracking data components through properties. The data is read immediately upon construction and remains immutable thereafter.

Properties

UserState UserState { get; set; }¶: Gets the current user state, including head pose and gaze information.

SimGameCameraState SimGameCameraState { get; set; }¶: Gets the current game camera state, including eye and head tracking components.

GameImmersiveHUDState GameImmersiveHUDState { get; set; }¶: Gets the current immersive HUD state, including viewport region indicators.

FoveatedRenderingState FoveatedRenderingState { get; set; }¶: Gets the current foveated rendering state, including foveation center and radii.

TrackingListener¶

class Eyeware.BeamEyeTracker.TrackingListener : IDisposable ¶

Base class for receiving tracking data updates from the Beam Eye Tracker. Implement this class to receive callbacks when tracking data or status changes occur.

This class implements IDisposable to ensure proper cleanup of native resources. Users should either call Dispose explicitly or use a using statement.

Public Functions

void OnTrackingDataReceptionStatusChanged (TrackingDataReceptionStatus status)¶

Called when the tracking data reception status changes. Override this method to handle status changes.

Param status:: The new tracking data reception status.

void OnTrackingStateSetUpdate (TrackingStateSet trackingStateSet, double timestamp)¶

Called when new tracking data is available. Override this method to handle tracking data updates.

Param trackingStateSet:: The new tracking state set.
Param timestamp:: The timestamp of the tracking data.

void Dispose ()¶: Releases all resources used by this listener instance.

Properties

bool IsDisposed { get; set; }¶: Gets whether this listener has been disposed.

Enums¶

TrackingDataReceptionStatus¶

enum Eyeware.BeamEyeTracker.TrackingDataReceptionStatus¶

Represents the status of the tracking data reception. This state indicates whether the client is receiving frame-by-frame tracking data or not, regardless of whether the user is being tracked or not.

Note

See The TrackingDataReceptionStatus object for more information.

Values:

NotReceivingTrackingData¶

The client is not currently receiving data from the Beam Eye Tracker. There could be multiple reasons why this is the case but in general it means that the user should manually start the Beam Eye Tracker application (if not yet launched), sign in, and/or successfully activate “Gaming Extensions” (as of Beam Eye Tracker v2.0).

.. note:: In general, this is when manual user intervention is needed to configure the tracker. Alternatively, see :ref:about_auto_start_tracking.

ReceivingTrackingData¶: It is actively connected to the Beam Eye Tracker and regularly receiving tracking data. Please note this does not imply that the user is being successfully tracked. It merely indicates that the Beam Eye Tracker is active and sending updates, even if the user is not being tracked.

AttemptingTrackingAutoStart¶

It is trying to launch the Beam Eye Tracker and/or start its tracking after an explicit request to auto-start tracking. While in this state, there are multiple things that could be happening behind the scenes:

Checking if the Beam Eye Tracker is installed.
Checking if the Beam Eye Tracker is running.
Launching the Beam Eye Tracker.
Requesting the Beam Eye Tracker to activate Gaming Extensions (or other API enabling mode) Thus, depending on the state of the Beam Eye Tracker, this could fail, succeed quickly (~100ms) or succeed taking a while (~10 seconds).

TrackingConfidence¶

enum Eyeware.BeamEyeTracker.TrackingConfidence¶

Realibility measure for obtained tracking results.

Note

See Tracking Confidence for a detailed explanation.

Values:

LostTracking¶: The signal/data in question is unavailable and should be discarded.

Low¶: Tracking is present but highly uncertain.

Medium¶: Tracking reliability is fair.

High¶: Tracking is as reliable as it gets.

Data Types¶

Coordinates¶

struct Eyeware.BeamEyeTracker.Point¶

2D integer point coordinates. Used primarily for screen coordinates in the unified coordinate system.

Public Functions

Point (Int32 x, Int32 y)¶

Initializes a new instance of the Point structure.

Param x:: X coordinate
Param y:: Y coordinate

Public Members

Int32 X¶: X coordinate.

Int32 Y¶: Y coordinate.

struct Eyeware.BeamEyeTracker.PointF¶

2D floating point coordinates. Used for normalized viewport coordinates and precise positioning.

Public Functions

PointF (float x, float y)¶

Initializes a new instance of the PointF structure.

Param x:: X coordinate
Param y:: Y coordinate

Public Members

float X¶: X coordinate.

float Y¶: Y coordinate.

struct Eyeware.BeamEyeTracker.Vector3D¶

Representation of a 3D vector or 3D point.

Public Members

float X¶: X coordinate.

float Y¶: Y coordinate.

float Z¶: Z coordinate.

UInt32 _Padding¶: Internal padding for alignment.

Viewport management¶

struct Eyeware.BeamEyeTracker.ViewportGeometry¶

Viewport geometry definition. It is used to map from unified screen coordinates to the viewport normalized coordinates, ranging [0.0, 1.0] for a point inside the viewport rectangle.

Note

See Viewport for more information.

Public Functions

ViewportGeometry (Point point00, Point point11)¶

Initializes a new instance of the ViewportGeometry structure.

Param point00:: Point in unified screen coordinates where the (0.0, 0.0) point of the viewport is
Param point11:: Point in unified screen coordinates where the (1.0, 1.0) point of the viewport is

Public Members

Point Point00¶: Point, in unified screen coordinates, where the (0.0, 0.0) point of the viewport is. The point is inclusive, i.e., considered part of the border of the viewport rectangle.

Point Point11¶: Point, in unified screen coordinates, where the (1.0, 1.0) point of the viewport is. The point is inclusive, i.e., considered part of the border of the viewport rectangle.

Real-time tracking¶

struct Eyeware.BeamEyeTracker.UserState¶

Complete user tracking state.

Note

See Real-time tracking for a detailed explanation.

Public Members

UInt64 StructVersion¶: Structure version for compatibility.

double TimestampInSeconds¶: Data timestamp.

HeadPose HeadPose¶: 3D head position and orientation

UnifiedScreenGaze UnifiedScreenGaze¶: Gaze in screen coordinates.

ViewportGaze ViewportGaze¶: Normalized viewport gaze.

byte[] Reserved¶: Reserved for future use.

Public Static Functions

UserState Create ()¶

Creates a new instance of UserState with default values.

Return:: A new UserState instance with default values.

struct Eyeware.BeamEyeTracker.UnifiedScreenGaze¶

Represents gaze information in screen coordinates.

Public Members

TrackingConfidence Confidence¶: The confidence of the tracking result.

UInt32 _Padding¶

Point PointOfRegard¶: Point where the user is looking at, kept within bounds of the screen(s) resolution(s).

Point UnboundedPointOfRegard¶

Point where the user is looking at, which may be outside the physical screen space. This alternative to PointOfRegard is important because:

having a continuous signal crossing the screen boundaries is useful for smoother animations, or controlling elements that are not confined to the screen
it allows you to implement heuristics to account for eye tracker inaccuracies nearby the screen bounds.

struct Eyeware.BeamEyeTracker.ViewportGaze¶

Represents gaze information in viewport coordinates.

Public Members

TrackingConfidence Confidence¶: The confidence of the tracking result.

UInt32 _Padding¶

PointF NormalizedPointOfRegard¶: Point where the user is looking at, normalized such that, if the gaze is inside the viewport, then the values are in the range [0, 1]. However, it can be negative or exceed 1, if the gaze is outside the viewport.

struct Eyeware.BeamEyeTracker.HeadPose¶

Represents information of the head pose for the given time instant.

Note

See Head Pose for a detailed explanation.

Public Members

TrackingConfidence Confidence¶: The confidence of the tracking result.

float[] RotationFromHcsToWcs¶: Rotation matrix, with respect to the World Coordinate System (WCS).

Vector3D TranslationFromHcsToWcs¶: Translation vector, with respect to the World Coordinate System (WCS).

ulong TrackSessionUid¶: Indicates the ID of the session of uninterrupted consecutive tracking. When a user is being tracked over consecutive frames, the track_session_uid is kept unchanged. However, if the user goes out of frame or turns around such that they can no longer be tracked, then this number is incremented once the user is detected again.

In-game camera control¶

struct Eyeware.BeamEyeTracker.SimGameCameraState¶

Holds the required data to achieve real-time immersive controls of the in-game camera. To consume the parameters, we do not recommend accessing the EyeTrackingPoseComponent and HeadTrackingPoseComponent directly, but instead, use the provided method that applies a weighted combination of the two components.

Note

See In-game camera control for a detailed explanation.

Public Members

UInt64 StructVersion¶: Structure version for compatibility.

double TimestampInSeconds¶: The timestamp of this update, in seconds. If it is equal to NullDataTimestamp, then the rest of the data is invalid and should be ignored. This is effectively a counter since the tracking started. Note that given that the user can turn off/on the tracking at will, this counter can’t be assumed to be strictly monotonic.

SimCameraTransform3D EyeTrackingPoseComponent¶: The camera transform if based solely on the eye tracking data. See SimCameraTransform3D for interpretation of the parameters. We do not recommend using this signal directly and instead use the ComputeSimGameCameraTransformParameters method to get the final camera transform.

SimCameraTransform3D HeadTrackingPoseComponent¶: The camera transform if based solely on the head tracking data. See SimCameraTransform3D for interpretation of the parameters. We do not recommend using this signal directly and instead use the ComputeSimGameCameraTransformParameters method to get the final camera transform.

ulong[] Reserved¶: Reserved for future use.

Public Static Functions

SimGameCameraState Create ()¶

Creates a new instance of SimGameCameraState with default values.

Return:: A new SimGameCameraState instance with default values.

struct Eyeware.BeamEyeTracker.SimCameraTransform3D¶

Represents the 3D transform parameters to be applied to the in-game camera.

Warning

Please see Mapping to the game engine coordinate system for explanation on how to interpret the parameters.

Public Members

float RollInRadians¶: Roll angle in radians.

float PitchInRadians¶: Pitch angle in radians.

float YawInRadians¶: Yaw angle in radians.

float XInMeters¶: X translation in meters.

float YInMeters¶: Y translation in meters.

float ZInMeters¶: Z translation in meters.

Immersive HUD¶

struct Eyeware.BeamEyeTracker.GameImmersiveHUDState¶

Represents the information you need to implement an immersive HUD in your game. In many games, the HUD is implemented by UI elements on the 4 corners of the screen, but this struct provides values for all non-center 8 regions of the screen (corners and mid-edges). The values are in the range [0, 1], where 0 means the user is not looking at the element, and 1 means the user is looking at the element. In most cases, you can simply map to a boolean value using 0.5 as threshold.

Note

See Ready to use “looking at HUD” signals for more information.

Public Members

UInt64 StructVersion¶: Structure version for compatibility.

double TimestampInSeconds¶: The timestamp of this update, in seconds. If it is equal to NullDataTimestamp, then the rest of the data is invalid and should be ignored. This is effectively a counter since the tracking started. Note that given that the user can turn off/on the tracking at will, this counter can’t be assumed to be strictly monotonic.

float LookingAtViewportTopLeft¶: Signal of whether the user is looking at the top-left region of the screen.

float LookingAtViewportTopMiddle¶: Signal of whether the user is looking at the top-middle region of the screen.

float LookingAtViewportTopRight¶: Signal of whether the user is looking at the top-right region of the screen.

float LookingAtViewportCenterLeft¶: Signal of whether the user is looking at the center-left region of the screen.

float LookingAtViewportCenterRight¶: Signal of whether the user is looking at the center-right region of the screen.

float LookingAtViewportBottomLeft¶: Signal of whether the user is looking at the bottom-left region of the screen.

float LookingAtViewportBottomMiddle¶: Signal of whether the user is looking at the bottom-middle region of the screen.

float LookingAtViewportBottomRight¶: Signal of whether the user is looking at the bottom-right region of the screen.

byte[] Reserved¶: Reserved for future use.

Public Static Functions

GameImmersiveHUDState Create ()¶

Creates a new instance of GameImmersiveHUDState with default values.

Return:: A new GameImmersiveHUDState instance with default values.

Foveated rendering¶

struct Eyeware.BeamEyeTracker.FoveationRadii¶

Public Functions

FoveationRadii (float radiusLevel1, float radiusLevel2, float radiusLevel3, float radiusLevel4)¶

Initializes a new instance of the FoveationRadii structure.

Param radiusLevel1:: Inner area should be rendered at highest definition.
Param radiusLevel2:: Second level of definition.
Param radiusLevel3:: Third level of definition.
Param radiusLevel4:: Outer area should be rendered at lowest definition.

Public Members

float RadiusLevel1¶: Inner area should be rendered at highest definition.

float RadiusLevel2¶: Second level of definition.

float RadiusLevel3¶: Third level of definition.

float RadiusLevel4¶: Outer area should be rendered at lowest definition.

struct Eyeware.BeamEyeTracker.FoveatedRenderingState¶

Represents the information needed to implement foveated rendering.

Note

See Foveated rendering for more information.

Public Members

UInt64 StructVersion¶: Structure version for compatibility.

double TimestampInSeconds¶: The timestamp of this update, in seconds. If it is equal to NullDataTimestamp, then the rest of the data is invalid and should be ignored. This is effectively a counter since the tracking started. Note that given that the user can turn off/on the tracking at will, this counter can’t be assumed to be strictly monotonic.

PointF NormalizedFoveationCenter¶: The center of the foveated rendering region normalized by the viewport width and height.

FoveationRadii NormalizedFoveationRadii¶: The radii of the foveated rendering regions normalized by the viewport width.

byte[] Reserved¶: Reserved for future use.

Public Static Functions

FoveatedRenderingState Create ()¶

Creates a new instance of FoveatedRenderingState with default values.

Return:: A new FoveatedRenderingState instance with default values.

Other¶

struct Eyeware.BeamEyeTracker.Version¶

SDK version information.

Public Members

UInt32 Major¶: Major version number.

UInt32 Minor¶: Minor version number.

UInt32 Patch¶: Patch level.

UInt32 Padding¶: Internal padding for alignment.

Constants¶

class Eyeware.BeamEyeTracker.Constants¶

Global constants for the Beam Eye Tracker SDK.

Public Static Attributes

const double NullDataTimestamp = -1.0¶: Special value indicating an invalid timestamp.

Note

See Timestamps for more information.