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