Skip to content

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

Python
Versioning & Legal