Skip to content

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

  See also

  API::wait_for_new_tracking_state_set()

constexpr Timestamp eyeware::beam_eye_tracker::NULL_DATA_TIMESTAMP = (EW_BET_Timestamp)(-1.0)

  See EW_BET_NULL_DATA_TIMESTAMP.

API Reference
C