C++¶

The C++ API is the primary interface of the Beam SDK. It provides comprehensive eye tracking functionality through an intuitive object-oriented design.

Note

All C++ types and classes described in this documentation are enclosed within the eyeware::beam_eye_tracker namespace.

Core Classes¶

API¶

class API¶

Main entry point for the Beam Eye Tracker SDK.

See also

TrackingListener For asynchronous data reception

Note

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

Public Functions

API(const char *friendly_name, const ViewportGeometry &initial_viewport_geometry)¶

Create a new API instance to communicate with the Beam Eye Tracker application.

Parameters:

friendly_name – Application identifier displayed in the Beam Eye Tracker UI (UTF-8, max 200 bytes)
initial_viewport_geometry – Initial screen viewport configuration for coordinate mapping

Throws:

std::invalid_argument – If friendly_name is invalid or exceeds size limit
std::runtime_error – If API initialization fails

API(const API&) = delete¶

API &operator=(const API&) = delete¶

API(API&&)¶

API &operator=(API&&)¶

~API()¶

Version get_version() const¶

Get the current SDK version information.

Example:

Version ver = api.get_version();
printf("SDK Version: %d.%d.%d.%d\n",
       ver.major, ver.minor, ver.patch, ver.build);

Returns:: Version structure containing major, minor, patch and build numbers

void update_viewport_geometry(const ViewportGeometry &new_viewport_geometry)¶

Update the viewport geometry for coordinate mapping.

Note

For a detailed explanation, see Viewport.

Parameters:: new_viewport_geometry – The new viewport geometry to set.

void attempt_starting_the_beam_eye_tracker()¶: 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.

TRACKING_LISTENER_HANDLE start_receiving_tracking_data_on_listener(TrackingListener *listener)¶

Register a listener for asynchronous tracking data updates.

Note

For a detailed explanation, see Asynchronous data access.

Warning

The listener must remain valid until unregistered

Parameters:: listener – Pointer to listener implementation
Returns:: Handle for the registered listener

void stop_receiving_tracking_data_on_listener(TRACKING_LISTENER_HANDLE listener_handle)¶

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

Parameters:: listener_handle – The handle to the listener to stop receiving tracking data.

bool wait_for_new_tracking_state_set(Timestamp &last_update_timestamp, unsigned int timeout_ms = DEFAULT_TRACKING_DATA_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:

last_update_timestamp – [in,out] 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 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.

TrackingStateSet get_latest_tracking_state_set() const¶

Returns the latest tracking state set. See TrackingStateSet for more information.

Note

See The TrackingStateSet object for more information.

Returns:: The latest tracking state set.

TrackingDataReceptionStatus get_tracking_data_reception_status() const¶

Returns the current status of the tracking data reception.

Note

See The TrackingDataReceptionStatus object for more information.

Returns:: The current status of the tracking data reception.

bool recenter_sim_game_camera_start()¶

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

Note

See Implement the camera recentering for more information.

Returns:: true if the start recentering process could be queued.

void recenter_sim_game_camera_end()¶: End recentering the sim game camera.

Note

See Implement the camera recentering for more information.

Public Static Functions

static SimCameraTransform3D compute_sim_game_camera_transform_parameters(const SimGameCameraState &state, float eye_tracking_weight = 1.0f, float head_tracking_weight = 1.0f)¶

Computes the transform you should apply to the in-game camera.

Use the weight parameters to control the contributions of the eye and head tracking data. A weight of 1.0 (for both) is the default, which would apply the camera movement as configured by the user within the Beam Eye Tracker (which may have already applied curve mappings, amplification/suppression or choosing only head or eye tracking).

The weight values values affect how much the eye/head tracking influences camera movement. A weight of 2.0 will make the camera move twice as much for the same head/eye movement, while 0.5 will make it move half as much.

Note

See Sensitivity/Range Sliders for more information.

Parameters:

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.

TrackingStateSet¶

class TrackingStateSet¶

The TrackingStateSet is the key object holding tracking data for a time instanct.

Note

See The TrackingStateSet object for more information.

Public Functions

TrackingStateSet(TrackingStateSet&&)¶: The TrackingStateSet is intended as an inmmutable data holder, which is only generated by the API class and thus it is only movable by client code.

TrackingStateSet &operator=(TrackingStateSet&&)¶

~TrackingStateSet()¶

const UserState &user_state() const¶

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

Note

See Real-time tracking for more information.

Returns:: The user state.

const SimGameCameraState &sim_game_camera_state() const¶

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

Note

See In-game camera control for more information.

Returns:: The latest camera controls.

const GameImmersiveHUDState &game_immersive_hud_state() const¶

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

Note

See Dynamic HUDs for more information.

Returns:: The latest game immersive HUD state.

const FoveatedRenderingState &foveated_rendering_state() const¶

Returns the parameters to implement foveated rendering.

Returns:: The latest foveated rendering state.

TrackingListener¶

class TrackingListener¶

Interface class which you need to inherit and override with your own callback logic.

Note

See Asynchronous data access for more information.

Public Functions

virtual ~TrackingListener() = default¶

virtual void on_tracking_data_reception_status_changed(TrackingDataReceptionStatus status) = 0¶

Reimplement this method to receive the status of the tracking data reception.

Parameters:: status – The new status for the tracking data reception.

virtual void on_tracking_state_set_update(const TrackingStateSet &tracking_state_set, const Timestamp timestamp) = 0¶

Reimplement this method to access the latest tracking data as soon as it arrives.

Parameters:: state_set – The latest tracking data.

Enums¶

TrackingDataReceptionStatus¶

enum class eyeware::beam_eye_tracker::TrackingDataReceptionStatus : EW_BET_TrackingDataReceptionStatus ¶

Values:

enumerator NOT_RECEIVING_TRACKING_DATA¶: Same meaning as EW_BET_NOT_RECEIVING_TRACKING_DATA.

enumerator RECEIVING_TRACKING_DATA¶: Same meaning as EW_BET_RECEIVING_TRACKING_DATA.

enumerator ATTEMPTING_TRACKING_AUTO_START¶: Same meaning as EW_BET_ATTEMPTING_TRACKING_AUTO_START.

TrackingConfidence¶

enum class eyeware::beam_eye_tracker::TrackingConfidence : EW_BET_TrackingConfidence ¶

See EW_BET_TrackingConfidence.

Values:

enumerator LOST_TRACKING¶: Same meaning as EW_BET_LOST_TRACKING

enumerator LOW¶: Same meaning as EW_BET_LOW

enumerator MEDIUM¶: Same meaning as EW_BET_MEDIUM

enumerator HIGH¶: Same meaning as EW_BET_HIGH

Data Types¶

The C++ types are aliases for the types defined in the C API, but following C++ naming and namespace conventions.

Coordinates¶

using eyeware::beam_eye_tracker::Point = EW_BET_Point ¶

using eyeware::beam_eye_tracker::PointF = EW_BET_PointF ¶

using eyeware::beam_eye_tracker::Vector3D = EW_BET_Vector3D ¶

using eyeware::beam_eye_tracker::Matrix3x3 = EW_BET_Matrix3x3 ¶

Viewport management¶

using eyeware::beam_eye_tracker::ViewportGeometry = EW_BET_ViewportGeometry ¶

Real-time tracking¶

using eyeware::beam_eye_tracker::UserState = EW_BET_UserState ¶

using eyeware::beam_eye_tracker::UnifiedScreenGaze = EW_BET_UnifiedScreenGaze ¶

using eyeware::beam_eye_tracker::ViewportGaze = EW_BET_ViewportGaze ¶

using eyeware::beam_eye_tracker::HeadPose = EW_BET_HeadPose ¶

In-game camera control¶

using eyeware::beam_eye_tracker::SimGameCameraState = EW_BET_SimGameCameraState ¶

using eyeware::beam_eye_tracker::SimCameraTransform3D = EW_BET_SimCameraTransform3D ¶

Immersive HUD¶

using eyeware::beam_eye_tracker::GameImmersiveHUDState = EW_BET_GameImmersiveHUDState ¶

Foveated rendering¶

using eyeware::beam_eye_tracker::FoveationRadii = EW_BET_FoveationRadii ¶

using eyeware::beam_eye_tracker::FoveatedRenderingState = EW_BET_FoveatedRenderingState ¶

Other¶

using eyeware::beam_eye_tracker::Version = EW_BET_Version ¶

using eyeware::beam_eye_tracker::Timestamp = EW_BET_Timestamp ¶

Constants¶

constexpr unsigned int eyeware::beam_eye_tracker::DEFAULT_TRACKING_DATA_TIMEOUT_MS = 1000¶

Default timeout in milliseconds for tracking data retrieval operations.