Update to VITURE SDK v2.3.1, add Beast support

include/sdks/viture_camera_provider.h

@@ -0,0 +1,176 @@
+/**
+ * @file
+ * @brief Public C API for Viture Camera device provider lifecycle and management.
+ * @copyright 2026 VITURE Inc. All rights reserved.
+ *
+ * This header defines the core public C API for XR camera provider instances:
+ * - Lifecycle management: create, start, stop, destroy
+ * - Callback registration: camera frame callbacks
+ * - Device validation: camera product ID validation for different device models
+ *
+ * Camera Device Support:
+ * - Luma Pro, Luma Cyber, Luma Ultra: VID=0x0C45, PID=0x636B
+ * - Beast: VID=0x0C45, PID=0x6368
+ * - Luma: No camera support
+ * - One, Lite, Pro: No camera support
+ */
+
+#ifndef VITURE_CAMERA_PROVIDER_H
+#define VITURE_CAMERA_PROVIDER_H
+
+#include "viture_macros_public.h"
+#include <stdint.h>
+
+/**
+ * @brief Handle type for XRCameraProvider instances. This is an opaque pointer
+ * returned by `xr_camera_provider_create` and consumed by other API calls.
+ */
+typedef void* XRCameraProviderHandle;
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Camera frame format
+ */
+typedef enum {
+    XR_CAMERA_FORMAT_MJPEG = 0  // MJPEG compressed (raw from camera)
+} XRCameraFormat;
+
+/**
+ * @brief Camera frame data structure
+ */
+typedef struct {
+    uint8_t* data;           // Frame data pointer
+    uint32_t size;           // Frame data size in bytes
+    uint32_t width;          // Frame width in pixels
+    uint32_t height;         // Frame height in pixels
+    XRCameraFormat format;   // Frame format
+    uint64_t timestamp;      // Frame timestamp in nanoseconds
+    uint32_t sequence;       // Frame sequence number
+} XRCameraFrame;
+
+/**
+ * @brief Callback for receiving camera frames
+ *
+ * @param frame Pointer to the camera frame data (valid only during callback)
+ * @param user_data Application context pointer passed to xr_camera_provider_start
+ *                  Can be used to pass application-specific state/context
+ */
+typedef void (*XRCameraFrameCallback)(const XRCameraFrame* frame, void* user_data);
+
+/**
+ * @brief Get camera vendor ID for the given glasses product ID
+ *
+ * @param glasses_product_id Product ID of the glasses (from xr_device_provider)
+ * @return Camera vendor ID if supported, 0 if camera not available for this device
+ */
+VITURE_API int xr_camera_provider_get_camera_vid(int glasses_product_id);
+
+/**
+ * @brief Get camera product ID for the given glasses product ID
+ *
+ * @param glasses_product_id Product ID of the glasses (from xr_device_provider)
+ * @return Camera product ID if supported, 0 if camera not available for this device
+ *
+ * Supported devices and their camera PIDs:
+ * - Luma Pro, Luma Cyber: Camera PID 0x636B
+ * - Luma Ultra: Camera PID 0x636B
+ * - Beast: Camera PID 0x6368
+ * - Luma, One, Lite, Pro: No camera (returns 0)
+ */
+VITURE_API int xr_camera_provider_get_camera_pid(int glasses_product_id);
+
+/**
+ * @brief Check if the given USB device is a valid Viture camera
+ *
+ * @param vendor_id USB Vendor ID
+ * @param product_id USB Product ID
+ * @return 1 if valid Viture camera, 0 otherwise
+ */
+VITURE_API int xr_camera_provider_is_valid_camera(int vendor_id, int product_id);
+
+#ifdef __ANDROID__
+/**
+ * @brief Android variant: Create an XRCameraProvider instance
+ *
+ * Due to Android restrictions, USB file descriptor is needed for creation
+ *
+ * @param camera_vid Camera Vendor ID (use xr_camera_provider_get_camera_vid)
+ * @param camera_pid Camera Product ID (use xr_camera_provider_get_camera_pid)
+ * @param file_descriptor File descriptor of the opened USB camera device
+ * @return Handle to the created instance, or NULL on failure
+ */
+VITURE_API XRCameraProviderHandle xr_camera_provider_create(int camera_vid,
+                                                             int camera_pid,
+                                                             int file_descriptor);
+#else
+/**
+ * @brief Non-Android variant: Create an XRCameraProvider instance
+ *
+ * @param camera_vid Camera Vendor ID (use xr_camera_provider_get_camera_vid)
+ * @param camera_pid Camera Product ID (use xr_camera_provider_get_camera_pid)
+ * @return Handle to the created instance, or NULL on failure
+ */
+VITURE_API XRCameraProviderHandle xr_camera_provider_create(int camera_vid,
+                                                             int camera_pid);
+#endif
+
+/**
+ * @brief Start the camera stream with callback
+ *
+ * When started, camera frames will be delivered through the registered callback.
+ * The callback is invoked on a dedicated camera thread.
+ * Camera uses fixed configuration: 1920x1080@30fps, MJPEG format
+ *
+ * @param handle Handle to the XRCameraProvider instance
+ * @param callback Callback function for receiving camera frames
+ * @param user_data Application context passed to callback. Can be used to access
+ *                  application state/objects from the callback thread (can be NULL)
+ * @return VITURE_GLASSES_SUCCESS on success, or:
+ *         - VITURE_GLASSES_ERROR_INVALID_PARAM   invalid handle
+ *         - VITURE_GLASSES_ERROR_USB_UNAVAILABLE camera device not found or failed to open
+ *         - VITURE_GLASSES_ERROR_NOT_SUPPORTED   failed to negotiate stream format
+ *         - VITURE_GLASSES_ERROR_USB_EXEC        failed to start streaming
+ *         - VITURE_GLASSES_ERROR_INVALID_STATE   already streaming
+ */
+VITURE_API int xr_camera_provider_start(XRCameraProviderHandle handle,
+                                         XRCameraFrameCallback callback,
+                                         void* user_data);
+
+/**
+ * @brief Stop the camera stream
+ *
+ * After this call, no more frames will be delivered through the callback.
+ *
+ * @param handle Handle to the XRCameraProvider instance
+ * @return VITURE_GLASSES_SUCCESS on success, or:
+ *         - VITURE_GLASSES_ERROR_INVALID_PARAM  invalid handle
+ *         - VITURE_GLASSES_ERROR_INVALID_STATE  not currently streaming
+ */
+VITURE_API int xr_camera_provider_stop(XRCameraProviderHandle handle);
+
+/**
+ * @brief Destroy the XRCameraProvider instance and release all resources
+ *
+ * This will stop streaming if active and release all associated resources.
+ *
+ * @param handle Handle to the XRCameraProvider instance
+ */
+VITURE_API void xr_camera_provider_destroy(XRCameraProviderHandle handle);
+
+/**
+ * @brief Check if camera is currently streaming
+ *
+ * @param handle Handle to the XRCameraProvider instance
+ * @return 1 if streaming, 0 if not streaming or invalid handle
+ */
+VITURE_API int xr_camera_provider_is_streaming(XRCameraProviderHandle handle);
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // VITURE_CAMERA_PROVIDER_H

include/sdks/viture_device.h

@@ -19,7 +19,7 @@
  * @param timestamp Timestamp in device timebase for IMU sample.
  * @param vsync     VSync timestamp associated with the sample.
  *
- * Should be set before calling open_imu with Imu::Mode::MODE_RAW
+ * Should be set before calling xr_device_provider_open_imu with VITURE_IMU_MODE_RAW
  * Data format:
  * 1. Viture One / Pro / Lite: [gyroscope_raw_x, gyroscope_raw_y, gyroscope_raw_z,
  *                              accelerometer_raw_x, accelerometer_raw_y, accelerometer_raw_z,
@@ -38,8 +38,9 @@ typedef void (*VitureImuRawCallback)(float* data, uint64_t timestamp, uint64_t v
  * @param data      Pointer to pose data buffer
  * @param timestamp Timestamp in device timebase for IMU sample.
  *
- * Should be set before calling open_imu with Imu::Mode::MODE_POSE
- * Data format: [roll, pitch, yaw, quaternion_0, quaternion_1, quaternion_2, quaternion_3]
+ * Should be set before calling xr_device_provider_open_imu with VITURE_IMU_MODE_POSE
+ * Coordinate system: North-West-Up (NWU), X->North, Y->West, Z->Up.
+ * Data format: [roll, pitch, yaw, quaternion_w, quaternion_x, quaternion_y, quaternion_z]
  */
 typedef void (*VitureImuPoseCallback)(float* data, uint64_t timestamp);
 
@@ -56,9 +57,10 @@ extern "C" {
  *
  * @param handle           Handle to the `XRDeviceProvider` instance.
  * @param imu_raw_callback Callback function pointer.
- * @return 0 on success, -1 on failure.
+ * @return VITURE_GLASSES_SUCCESS on success, VITURE_GLASSES_ERROR_INVALID_PARAM on failure.
  */
-VITURE_API int register_raw_callback(XRDeviceProviderHandle handle, VitureImuRawCallback imu_raw_callback);
+VITURE_API int xr_device_provider_register_imu_raw_callback(XRDeviceProviderHandle handle,
+                                                            VitureImuRawCallback imu_raw_callback);
 
 /**
  * @brief Register a combined IMU + VSync callback for a Viture device.
@@ -69,28 +71,35 @@ VITURE_API int register_raw_callback(XRDeviceProviderHandle handle, VitureImuRaw
  *
  * @param handle            Handle to the `XRDeviceProvider` instance.
  * @param imu_pose_callback Callback function pointer.
- * @return 0 on success, -1 on failure.
+ * @return VITURE_GLASSES_SUCCESS on success, VITURE_GLASSES_ERROR_INVALID_PARAM on failure.
  */
-VITURE_API int register_pose_callback(XRDeviceProviderHandle handle, VitureImuPoseCallback imu_pose_callback);
+VITURE_API int xr_device_provider_register_imu_pose_callback(XRDeviceProviderHandle handle,
+                                                             VitureImuPoseCallback imu_pose_callback);
 
 /**
  * @brief Open imu (no effect for carina device)
  * @param handle Handle to the XRDeviceProvider instance
  * @param imu_mode viture::protocol::imu::Mode
  * @param imu_report_frequency viture::protocol::imu::Frequency
- * @return 0: Success, -1: Param error, -2: USB execution error
- * @return -3: Device type not supported, -4: Other error
+ * @return VITURE_GLASSES_SUCCESS on success, or:
+ *         - VITURE_GLASSES_ERROR_INVALID_PARAM null handle
+ *         - VITURE_GLASSES_ERROR_USB_EXEC      USB execution error
+ *         - VITURE_GLASSES_ERROR_NOT_SUPPORTED device type not supported
+ *         - VITURE_GLASSES_ERROR_UNKNOWN       other error
  */
-VITURE_API int open_imu(XRDeviceProviderHandle handle, uint8_t imu_mode, uint8_t imu_report_frequency);
+VITURE_API int xr_device_provider_open_imu(XRDeviceProviderHandle handle, uint8_t imu_mode, uint8_t imu_report_frequency);
 
 /**
  * @brief Close IMU (no effect for Carina device)
  * @param handle Handle to the XRDeviceProvider instance
  * @param imu_mode viture::protocol::imu::Mode
- * @return 0: Success, -1: Param error, -2: USB execution error
- * @return -3: Device type not supported, -4: Other error
+ * @return VITURE_GLASSES_SUCCESS on success, or:
+ *         - VITURE_GLASSES_ERROR_INVALID_PARAM null handle
+ *         - VITURE_GLASSES_ERROR_USB_EXEC      USB execution error
+ *         - VITURE_GLASSES_ERROR_NOT_SUPPORTED device type not supported
+ *         - VITURE_GLASSES_ERROR_UNKNOWN       other error
  */
-VITURE_API int close_imu(XRDeviceProviderHandle handle, uint8_t imu_mode);
+VITURE_API int xr_device_provider_close_imu(XRDeviceProviderHandle handle, uint8_t imu_mode);
 
 #ifdef __cplusplus
 }

include/sdks/viture_device_carina.h

@@ -14,9 +14,11 @@
 #include "viture_glasses_provider.h"
 
 /**
- * @brief Callback invoked when a new pose sample is available.
+ * @brief Callback invoked when a new pose sample is available, This function
+ * returns pose data at the Camera's frequency (25 Hz). In most cases, this
+ * interface can be ignored.
  *
- * @param pose      Array of 7 floats: position (x,y,z) and quaternion (w,x,y,z).
+ * @param pose      Array of 7 floats: [px, py, pz, qw, qx, qy, qz].
  * @param timestamp Monotonic timestamp in seconds.
  */
 typedef void (*XRPoseCallback)(float* pose, double timestamp);
@@ -31,7 +33,7 @@ typedef void (*XRVSyncCallback)(double timestamp);
 /**
  * @brief IMU data callback for Carina device.
  *
- * @param imu       Pointer to IMU buffer (device-defined layout).
+ * @param imu       IMU data: [ax, ay, az, gx, gy, gz].
  * @param timestamp Timestamp in seconds for the IMU sample.
  */
 typedef void (*XRImuCallback)(float* imu, double timestamp);
@@ -70,37 +72,75 @@ extern "C" {
  * @param vsync_callback Callback for VSync events.
  * @param imu_callback   Callback for IMU samples.
  * @param camera_callback Callback for stereo camera frames.
- * @return 0 on success, -1 on failure.
+ * @return VITURE_GLASSES_SUCCESS on success, VITURE_GLASSES_ERROR_INVALID_PARAM on failure.
  */
-VITURE_API int register_callbacks_carina(XRDeviceProviderHandle handle,
-                                         XRPoseCallback pose_callback,
-                                         XRVSyncCallback vsync_callback,
-                                         XRImuCallback imu_callback,
-                                         XRCameraCallback camera_callback);
+VITURE_API int xr_device_provider_register_callbacks_carina(XRDeviceProviderHandle handle,
+                                                            XRPoseCallback pose_callback,
+                                                            XRVSyncCallback vsync_callback,
+                                                            XRImuCallback imu_callback,
+                                                            XRCameraCallback camera_callback);
 
 /**
- * @brief Reset position
+ * @brief Set DOF type for Carina device. Must be called after xr_device_provider_create
+ *        and before xr_device_provider_initialize. Default is 6DOF.
  * @param handle Handle to the XRDeviceProvider instance
- * @return 0 on success, -1 on failure
+ * @param is_6dof 1 for 6DOF, 0 for 3DOF
+ * @return VITURE_GLASSES_SUCCESS on success, error code on failure
  */
-VITURE_API int reset_pose_carina(XRDeviceProviderHandle handle);
+VITURE_API int xr_device_provider_set_dof_type_carina(XRDeviceProviderHandle handle, int is_6dof);
 
 /**
- * @brief Get IMU pose data with prediction time (Twb matrix in OpenGL coordinate system: x -> right, y -> up, z -> backward)
+ * @brief Trigger a full VIO re-initialisation.
+ *
+ * Resets the Carina tracking state, including position and yaw.  Pitch and roll remain
+ * gravity-anchored and are not affected.
+ *
+ * This is a heavyweight operation that briefly interrupts tracking.  Prefer
+ * xr_device_provider_reset_origin_carina() for lightweight heading/position recentering.
+ *
  * @param handle Handle to the XRDeviceProvider instance
- * @param pose Array to store pose data (7 floats for position and quaternion)
- * @param predict_time Prediction time in nanoseconds, 0 for current pose data
- * @return 0 on success, -1 on failure
+ * @return VITURE_GLASSES_SUCCESS on success, VITURE_GLASSES_ERROR_INVALID_PARAM on failure
  */
-VITURE_API int get_gl_pose_carina(XRDeviceProviderHandle handle, float* pose, double predict_time);
+VITURE_API int xr_device_provider_reset_pose_carina(XRDeviceProviderHandle handle);
 
 /**
- * Toggle glasses status report
+ * @brief Set a new tracking origin in OpenGL coordinate system (x -> right, y -> up, z -> backward).
+ *
+ * After this call, subsequent xr_device_provider_get_gl_pose_carina() returns poses expressed
+ * relative to the specified origin.
+ *
+ * Typical uses:
+ *   - Pass the pose returned by xr_device_provider_get_gl_pose_carina() to reset position and
+ *     yaw to the user's current physical state.
+ *   - Pass a manually constructed pose to relocate the tracking origin to any desired position
+ *     and heading (e.g. teleporting the camera to a fixed point in the scene).
+ *
+ * Axis reset behaviour:
+ *   - Position is reset to the translation encoded in `pose`.
+ *   - Yaw is reset to the yaw component of the quaternion in `pose`.
+ *   - Pitch and roll are gravity-anchored by the Carina VIO system and are NOT affected by this
+ *     call regardless of the quaternion passed.  They always reflect the device's absolute
+ *     orientation relative to gravity.
+ *
+ * @param handle Handle to the XRDeviceProvider instance
+ * @param pose   Target origin pose: [px, py, pz, qw, qx, qy, qz].
+ *               Pass the result of xr_device_provider_get_gl_pose_carina() to anchor the origin
+ *               at the current physical pose, or supply a custom pose to teleport to a specific
+ *               location and heading.
+ * @return VITURE_GLASSES_SUCCESS on success, error code on failure
+ */
+VITURE_API int xr_device_provider_reset_origin_carina(XRDeviceProviderHandle handle, float *pose);
+
+/**
+ * @brief Get IMU pose data with prediction time (Twb matrix in OpenGL coordinate system: x -> right, y -> up, z -> backward)
  * @param handle Handle to the XRDeviceProvider instance
- * @param toggle Enable / disable
- * @return 0 on success
+ * @param pose Array to store pose data (7 floats for position and quaternion)
+ * @param predict_time Prediction time in nanoseconds, 0 for current pose data
+ * @param pose_status Output pose status: 0 = stable, 1 = unstable (may occur briefly after device start). Can be null.
+ * @return VITURE_GLASSES_SUCCESS on success, VITURE_GLASSES_ERROR_INVALID_PARAM on failure
  */
-VITURE_API int toggle_status_report_carina(XRDeviceProviderHandle handle, bool toggle);
+VITURE_API int xr_device_provider_get_gl_pose_carina(XRDeviceProviderHandle handle,
+                                                     float *pose, double predict_time, int *pose_status);
 
 #ifdef __cplusplus
 }