Skip to content

# C

The C API provides a complete interface for eye tracking integration, designed for maximum compatibility and ease of use.

## Core Objects

### API

typedef void *EW_BET_API_HANDLE

  Opaque handle to the API instance.

  This handle represents a connection to the Beam Eye Tracker. All API functions require a valid handle obtained through EW_BET_API_Create().

  See also

  EW_BET_API_Create

  See also

  EW_BET_NULL_HANDLE

int32_t EW_BET_API_Create(const char *friendly_name, EW_BET_ViewportGeometry initial_viewport_geometry, EW_BET_API_HANDLE *api_handle)

  Initialize the Beam Eye Tracker API.

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

  Parameters:

    - friendly_name – Application identifier (UTF-8, max 200 bytes) displayed in the Beam Eye Tracker UI

    - initial_viewport_geometry – Initial viewport configuration for coordinate mapping

    - api_handle – [out] Pointer to store the created API handle

  Returns:

    0 on success, error code otherwise

void EW_BET_API_Destroy(EW_BET_API_HANDLE api_handle)

  Clean up and release API resources.

  Must be called when the application is shutting down or no longer needs eye tracking functionality. After this call, the handle becomes invalid and should be set to EW_BET_NULL_HANDLE.

  Parameters:

    api_handle – Handle to destroy (becomes invalid after call)

void EW_BET_API_GetVersion(EW_BET_API_HANDLE api_handle, EW_BET_Version *version)

  Get SDK version information.

  Example:

      EW_BET_Version version;
      EW_BET_API_GetVersion(api, &version);
      printf("Beam Eye Tracker SDK v%d.%d.%d (build %d)\n",
             version.major, version.minor,
             version.patch, version.build);

  Parameters:

    - api_handle – Valid API handle

    - version – [out] Structure to receive version info (already allocated)

void EW_BET_API_UpdateViewportGeometry(EW_BET_API_HANDLE api_handle, EW_BET_ViewportGeometry new_viewport_geometry)

  Update the viewport geometry for coordinate mapping.

  Note

  For a detailed explanation, see Viewport.

  Parameters:

    - api_handle – Valid API handle.

    - new_viewport_geometry – The new viewport geometry to set.

void EW_BET_API_AttemptStartingTheBeamEyeTracker(EW_BET_API_HANDLE api_handle)

  Attempts to start the Beam Eye Tracker application and tracking output.

  Note

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

int32_t EW_BET_API_RegisterTrackingCallbacks(EW_BET_API_HANDLE api_handle, EW_BET_TrackingDataReceptionStatusCallback on_tracking_data_reception_status_changed, EW_BET_TrackingDataCallback on_tracking_state_set_update, void *user_data, EW_BET_CALLBACKS_HANDLE *callbacks_handle)

  Register callbacks for asynchronous tracking data reception

  Note

  For a detailed explanation, see Asynchronous data access.

  Warning

  The callbacks must remain valid until unregistered

  Parameters:

    - api_handle – Handle to the API instance

    - on_tracking_data_reception_status_changed – Callback for tracking data reception status

    - on_tracking_state_set_update – Callback for new tracking data

    - user_data – User data pointer passed to callbacks

    - callbacks_handle – [out] Handle to the callbacks to unregister

  Returns:

    0 on success, non-zero error code otherwise

void EW_BET_API_UnregisterTrackingCallbacks(EW_BET_API_HANDLE api_handle, EW_BET_CALLBACKS_HANDLE *callbacks_handle)

  Deregisters the callbacks from receiving data from the Beam Eye Tracker application.

  Parameters:

    - api_handle – Handle to the API instance

    - callbacks_handle – [inout] Handle to the callbacks to unregister, which will also be set to nullptr on success.

bool EW_BET_API_WaitForNewTrackingStateSet(EW_BET_API_HANDLE api_handle, EW_BET_Timestamp *last_update_timestamp, uint32_t timeout_ms)

  Waits until new tracking data becomes available. This is a blocking call lasting until timeout_ms milliseconds.

  Note

  See Synchronous data access and Polling data access.

  Parameters:

    - api_handle – Valid API handle

    - last_update_timestamp – [inout] On input: the timestamp of the last received frame, used to determine if new data is available. On output: if new data is available, this will be updated to the timestamp of the newly received frame. Prior to the first iteration, you can initialize to EW_BET_NULL_DATA_TIMESTAMP.

    - timeout_ms – The maximum time to wait for new tracking data. Set to 0 to return immediately.

  Returns:

    true if new tracking data is available, false if the timeout was reached without new data.

EW_BET_TrackingDataReceptionStatus EW_BET_API_GetTrackingDataReceptionStatus(EW_BET_API_HANDLE api_handle)

  Returns the current status of the tracking data reception.

  Note

  See The TrackingDataReceptionStatus object for more information.

  Parameters:

    api_handle – Valid API handle

  Returns:

    The current status of the tracking data reception.

int32_t EW_BET_API_CreateAndFillLatestTrackingStateSet(EW_BET_API_HANDLE api_handle, EW_BET_TRACKING_STATE_SET_HANDLE *tracking_state_set)

  Get the latest tracking state.

  Creates and fills a new `TrackingStateSet` with the most recent data. The caller is responsible for destroying the handle when done.

  Example:

      EW_BET_TRACKING_STATE_SET_HANDLE tss_handle;
      if(EW_BET_API_CreateAndFillLatestTrackingStateSet(api, &tss_handle) == 0) {
        const EW_BET_UserState* user = EW_BET_API_GetUserState(tss_handle);
        // Do something with the user state
        EW_BET_API_DestroyTrackingStateSet(tss_handle);
      }

  Warning

  Must call EW_BET_API_DestroyTrackingStateSet when done

  Note

  See The TrackingStateSet object for more information.

  Parameters:

    - api_handle – Valid API handle

    - tracking_state_set – [out] Handle to receive the new state

  Returns:

    0 on success, error code otherwise

void EW_BET_API_DestroyTrackingStateSet(EW_BET_TRACKING_STATE_SET_HANDLE tracking_state_set_handle)

  Release tracking state resources.

  Must be called to free memory associated with a tracking state handle. After this call, the handle becomes invalid and should not be used.

  Parameters:

    tracking_state_set_handle – Handle to destroy (becomes invalid)

bool EW_BET_API_RecenterSimGameCameraStart(EW_BET_API_HANDLE api_handle)

  Start recentering the sim game camera, adjusting it to current user state.

  Note

  See Implement the camera recentering for more information.

  Parameters:

    api_handle – Handle to the API instance

  Returns:

    true if the start recentering process could be queued, false otherwise.

void EW_BET_API_RecenterSimGameCameraEnd(EW_BET_API_HANDLE api_handle)

  End recentering the sim game camera.

  Note

  See Implement the camera recentering for more information.

  Parameters:

    api_handle – Handle to the API instance

### TrackingStateSet

typedef void *EW_BET_TRACKING_STATE_SET_HANDLE

  Opaque handle to tracking state data.

  Represents a snapshot of tracking data including gaze, head pose, and other states. Must be properly managed with Create/Destroy functions to avoid memory leaks except when received through callbacks.

const EW_BET_UserState *EW_BET_API_GetUserState(EW_BET_TRACKING_STATE_SET_HANDLE tracking_state_set_handle)

  Returns the user state including the user’s gaze on screen and head pose.

  Note

  See Real-time tracking for more information.

  Parameters:

    tracking_state_set_handle – Handle to the tracking state set.

  Returns:

    The user state.

const EW_BET_SimGameCameraState *EW_BET_API_GetSimGameCameraState(EW_BET_TRACKING_STATE_SET_HANDLE tracking_state_set_handle)

  Access the latest game camera state to implement the immersive in-game camera controls.

  Note

  See In-game camera control for more information.

  Parameters:

    tracking_state_set_handle – Handle to the tracking state set

  Returns:

    The latest camera controls.

const EW_BET_GameImmersiveHUDState *EW_BET_API_GetGameImmersiveHUDState(EW_BET_TRACKING_STATE_SET_HANDLE tracking_state_set_handle)

  Returns the parameters to implement an immersive HUD in your game.

  Note

  See Dynamic HUDs for more information.

  Parameters:

    tracking_state_set_handle – Handle to the tracking state set

  Returns:

    The latest game immersive HUD state.

### Asynchronous Data Reception

typedef void *EW_BET_CALLBACKS_HANDLE

  Opaque handle to callback registration.

  Used to manage asynchronous callback registrations. Each registration creates a unique handle that must be used to unregister the callbacks later.

  See also

  EW_BET_API_RegisterTrackingCallbacks

  See also

  EW_BET_API_UnregisterTrackingCallbacks

typedef void (*EW_BET_TrackingDataReceptionStatusCallback)(EW_BET_TrackingDataReceptionStatus status, void *user_data)

  Callback function type for tracking data reception status changes.

typedef void (*EW_BET_TrackingDataCallback)(const EW_BET_TRACKING_STATE_SET_HANDLE tracking_state_set_handle, EW_BET_Timestamp timestamp, void *user_data)

  Callback function to receive the latest tracking data as soon as it arrives.

## Enums

### EW_BET_TrackingDataReceptionStatus

typedef int32_t EW_BET_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.

  Alternatively, see The TrackingDataReceptionStatus object for more information.

EW_BET_NOT_RECEIVING_TRACKING_DATA

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

  In general, this is when manual user intervention is needed to configure the tracker. Alternatively, see Launching the Beam Eye Tracker from your game or application.

EW_BET_RECEIVING_TRACKING_DATA

  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.

EW_BET_ATTEMPTING_TRACKING_AUTO_START

  It is trying to to launch the Beam Eye Tracker and/or start its tracking after a explicit request to Launching the Beam Eye Tracker from your game or application.

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

### EW_BET_TrackingConfidence

typedef int32_t EW_BET_TrackingConfidence

  Realibility measure for obtained tracking results.

  Note

  See Tracking Confidence for a detailed explanation.

EW_BET_LOST_TRACKING

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

EW_BET_LOW

  Tracking is present but highly uncertain.

EW_BET_MEDIUM

  Tracking reliability is fair.

EW_BET_HIGH

  Tracking is as reliable as it gets.

## Data Types

### Coordinates

struct EW_BET_Point

  2D integer point coordinates

  Used primarily for screen coordinates in the unified coordinate system

  Public Members

  int32_t x

    X coordinate

  int32_t y

    Y coordinate

struct EW_BET_PointF

  2D floating point coordinates

  Used for normalized viewport coordinates and precise positioning

  Public Members

  float x

    X coordinate

  float y

    Y coordinate

struct EW_BET_Vector3D

  Representation of a 3D vector or 3D point.

  Public Members

  float x

    x coordinate.

  float y

    y coordinate.

  float z

    z coordinate.

typedef float eyeware::beam_eye_tracker::EW_BET_Matrix3x3[3][3]

  Matrix of 3x3, implemented as an array of arrays (row-major).

      Matrix3x3 my_matrix; // Assume a Matrix3x3 instance is available
      int row = 1;
      int col = 2;
      float coefficient = my_matrix[row][col];

### Viewport management

struct EW_BET_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 Members

  EW_BET_Point point_00

    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.

  EW_BET_Point point_11

    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. Thus:

    width = point_11.x + 1 - point_00.x height = point_11.y + 1 - point_00.y

### Real-time tracking

struct EW_BET_UserState

  Complete user tracking state.

  Note

  See Real-time tracking for a detailed explanation.

  Public Members

  uint64_t struct_version

    Structure version for compatibility

  EW_BET_Timestamp timestamp_in_seconds

    Data timestamp

  EW_BET_HeadPose head_pose

    3D head position and orientation

  EW_BET_UnifiedScreenGaze unified_screen_gaze

    Gaze in screen coordinates

  EW_BET_ViewportGaze viewport_gaze

    Normalized viewport gaze

  uint8_t reserved[128]

    Reserved for future use

struct EW_BET_UnifiedScreenGaze

  Represents information on how the user attention relates to the plugged-in displays.

  Point coordinates are referred to the unified screen coordinate system. Accuracy is expected to be lower for the screens for which the eye tracking was not calibrated, and that lead to the users head to have large angles with respect to the camera, when looking at them.

  Public Members

  EW_BET_TrackingConfidence confidence

    The confidence of the tracking result.

  EW_BET_Point point_of_regard

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

  EW_BET_Point unbounded_point_of_regard

    Point where the user is looking at, which may be outside the physical screen space.

    This alternative to point_of_regard 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 (e.g. the eye tracking overlay implemented in the Beam Eye Tracker software);

    - it allows yo to implement heuristics to account for eye tracker inaccuracies nearby the screen bounds.

struct EW_BET_ViewportGaze

  Public Members

  EW_BET_TrackingConfidence confidence

    The confidence of the tracking result.

  EW_BET_PointF normalized_point_of_regard

    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 EW_BET_HeadPose

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

  Note

  See Head Pose for a detailed explanation.

  Public Members

  EW_BET_TrackingConfidence confidence

    The confidence of the tracking result.

  EW_BET_Matrix3x3 rotation_from_hcs_to_wcs

    Rotation matrix, with respect to the World Coordinate System (WCS).

  EW_BET_Vector3D translation_from_hcs_to_wcs

    Translation vector, with respect to the World Coordinate System (WCS).

  uint64_t track_session_uid

    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 tracker, then this number is incremented once the user is detected again.

### In-game camera control

struct EW_BET_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 roll_in_radians

    Roll, in radians.

  float pitch_in_radians

    Pitch, in radians.

  float yaw_in_radians

    Yaw, in radians.

  float x_in_meters

    X translation, in meters.

  float y_in_meters

    Y translation, in meters.

  float z_in_meters

    Z translation, in meters.

struct EW_BET_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 eye_tracking_pose_component and head_tracking_pose_component 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

  EW_BET_Timestamp timestamp_in_seconds

    The timestamp of this update, in seconds. If it is equal to EW_BET_NULL_DATA_TIMESTAMP, 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.

  EW_BET_SimCameraTransform3D eye_tracking_pose_component

    The camera transform if based solely on the eye tracking data.

    See EW_BET_SimCameraTransform3D for interpretation of the parameters.

    We do not recommend using this signal and, instead, use the get method to get the final camera transform.

  EW_BET_SimCameraTransform3D head_tracking_pose_component

    The camera transform if based solely on the head tracking data.

    See EW_BET_SimCameraTransform3D for interpretation of the parameters.

    We do not recommend using this signal and, instead, use the get method to get the final camera transform.

### Immersive HUD

struct EW_BET_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

  EW_BET_Timestamp timestamp_in_seconds

    The timestamp of this update, in seconds. If it is equal to EW_BET_NULL_DATA_TIMESTAMP, 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 looking_at_viewport_top_left

    Signals of whether the user is looking at the top-left region of the screen.

  float looking_at_viewport_top_middle

    Signal of whether the user is looking at the top-middle region of the screen.

  float looking_at_viewport_top_right

    Signal of whether the user is looking at the top-right region of the screen.

  float looking_at_viewport_center_left

    Signal of whether the user is looking at the center-left region of the screen.

  float looking_at_viewport_center_right

    Signal of whether the user is looking at the center-right region of the screen.

  float looking_at_viewport_bottom_left

    Signal of whether the user is looking at the bottom-left region of the screen.

  float looking_at_viewport_bottom_middle

    Signal of whether the user is looking at the bottom-middle region of the screen.

  float looking_at_viewport_bottom_right

    Signal of whether the user is looking at the bottom-right region of the screen.

### Foveated rendering

struct EW_BET_FoveationRadii

  Representation of the radii of the foveated rendering regions.

  Public Members

  float radius_level_1

    Inner area should be rendered at highest definition.

  float radius_level_2

    Second level of definition.

  float radius_level_3

    Third level of definition.

  float radius_level_4

    Outer area should be rendered at lowest definition.

struct EW_BET_FoveatedRenderingState

  Holds the required data to achieve foveated rendering.

  Note

  See Foveated rendering for a detailed explanation.

  Public Members

  EW_BET_Timestamp timestamp_in_seconds

    The timestamp of this update, in seconds. If it is equal to EW_BET_NULL_DATA_TIMESTAMP, 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.

  EW_BET_PointF normalized_foveation_center

    Point where to place the foveated rendering regions, it is normalized by the viewport width and height like EW_BET_ViewportGaze::normalized_point_of_regard.

  EW_BET_FoveationRadii normalized_foveation_radii

    The radii of the foveated rendering regions normalized by the viewport width.

    See EW_BET_FoveationRadii for interpretation of the parameters.

### Other

struct EW_BET_Version

  SDK version information.

  Public Members

  uint32_t major

    Major version number

  uint32_t minor

    Minor version number

  uint32_t patch

    Patch level

  uint32_t build

    Build number

typedef double EW_BET_Timestamp

  Timestamp type for tracking data.

  Represents time in seconds since tracking started. The counter may reset when tracking is stopped and restarted.

  Warning

  Not guaranteed to be strictly monotonic due to potential tracking restarts

## Utils

EW_BET_SimCameraTransform3D EW_BET_API_ComputeSimGameCameraTransformParameters(EW_BET_SimGameCameraState *camera_state, float eye_tracking_weight, float head_tracking_weight)

  Compute the transform parameters to apply to the in-game camera.

  See further explanation in the `C++` API function `eyeware::beam_eye_tracker::API::compute_sim_game_camera_transform_parameters()`.

  Parameters:

    - camera_state – The current state of the in-game camera.

    - eye_tracking_weight – The weight of the eye tracking component.

    - head_tracking_weight – The weight of the head tracking component.

  Returns:

    The transform parameters to apply to the in-game camera.

EW_BET_NULL_DATA_TIMESTAMP

  Special value indicating an invalid timestamp.

  Note

  See Timestamps for more information.

## Constants

EW_BET_NULL_HANDLE

  Invalid handle value.

  Used to:

  - Initialize handle variables

  - Check for failed handle creation

  - Mark handles as invalid after destruction

C++
Python