From e85af307da8c1f23634ebb70f23e27b24b0b93ee Mon Sep 17 00:00:00 2001
From: Danny Wolf <wolfd@users.noreply.github.com>
Date: Mon, 23 Feb 2026 18:05:34 +0000
Subject: [PATCH] Add more timestamp functions

Allow getting the three different timestamp values from a frame, as well
as enabling the global timestamp feature.

Topic: timestamp-functions
---
 src/device.rs     | 14 ++++++++++++++
 src/frame.rs      | 19 +++++++++++++++++++
 src/sys/device.rs | 21 +++++++++++++++++++++
 src/sys/frame.rs  | 36 ++++++++++++++++++++++++++++++++++++
 4 files changed, 90 insertions(+)

diff --git a/src/device.rs b/src/device.rs
index f45cbab..3b3a346 100644
--- a/src/device.rs
+++ b/src/device.rs
@@ -251,6 +251,20 @@ impl Device {
         }
         Ok(())
     }
+
+    /// Check if the device supports global timestamp
+    pub fn is_global_timestamp_supported(&self) -> Result<bool, OrbbecError> {
+        self.inner
+            .is_global_timestamp_supported()
+            .map_err(OrbbecError::from)
+    }
+
+    /// Enable or disable global timestamp
+    pub fn enable_global_timestamp(&self, enabled: bool) -> Result<(), OrbbecError> {
+        self.inner
+            .enable_global_timestamp(enabled)
+            .map_err(OrbbecError::from)
+    }
 }
 
 /// A list of Orbbec devices available
diff --git a/src/frame.rs b/src/frame.rs
index bbe3cac..f18d877 100644
--- a/src/frame.rs
+++ b/src/frame.rs
@@ -8,6 +8,25 @@ pub trait Frame: From<OBFrame> + AsRef<OBFrame> {}
 macro_rules! impl_video_frame {
     ($t:ident) => {
         impl $t {
+            /// Get the device timestamp of the video frame
+            pub fn timestamp_us(&self) -> u64 {
+                self.inner.get_timestamp_us().unwrap()
+            }
+
+            /// Get the system timestamp of the video frame
+            pub fn system_timestamp_us(&self) -> Result<u64, OrbbecError> {
+                self.inner
+                    .get_system_timestamp_us()
+                    .map_err(OrbbecError::from)
+            }
+
+            /// Get the global timestamp of the video frame
+            pub fn global_timestamp_us(&self) -> Result<u64, OrbbecError> {
+                self.inner
+                    .get_global_timestamp_us()
+                    .map_err(OrbbecError::from)
+            }
+
             /// Get the raw data of the video frame
             pub fn raw_data(&self) -> &[u8] {
                 // Unwrap is safe here because internal pointer is guaranteed to be valid
diff --git a/src/sys/device.rs b/src/sys/device.rs
index 57ece06..3ae4974 100644
--- a/src/sys/device.rs
+++ b/src/sys/device.rs
@@ -261,6 +261,27 @@ impl OBDevice {
         Ok(value)
     }
 
+    pub fn is_global_timestamp_supported(&self) -> Result<bool, OBError> {
+        let mut err_ptr = std::ptr::null_mut();
+
+        let supported =
+            unsafe { orb::ob_device_is_global_timestamp_supported(self.inner, &mut err_ptr) };
+
+        OBError::consume(err_ptr)?;
+
+        Ok(supported)
+    }
+
+    pub fn enable_global_timestamp(&self, enabled: bool) -> Result<(), OBError> {
+        let mut err_ptr = std::ptr::null_mut();
+
+        unsafe { orb::ob_device_enable_global_timestamp(self.inner, enabled, &mut err_ptr) };
+
+        OBError::consume(err_ptr)?;
+
+        Ok(())
+    }
+
     /// Load the device preset
     /// After loading the preset, the settings in the preset will set to the device immediately. Therefore, it is recommended to re-read the device settings to update the user program temporarily.
     pub fn load_preset(&self, preset_name: &CStr) -> Result<(), OBError> {
diff --git a/src/sys/frame.rs b/src/sys/frame.rs
index 14ddde3..24da138 100644
--- a/src/sys/frame.rs
+++ b/src/sys/frame.rs
@@ -18,6 +18,42 @@ impl OBFrame {
         self.inner
     }
 
+    /// Get the frame timestamp (also known as device timestamp, hardware timestamp) of the frame in microseconds.
+    /// The hardware timestamp is the time point when the frame was captured by the device (Typically in the mid-exposure, unless otherwise stated), on device clock domain.
+    pub fn get_timestamp_us(&self) -> Result<u64, OBError> {
+        let mut err_ptr = std::ptr::null_mut();
+
+        let timestamp = unsafe { orb::ob_frame_get_timestamp_us(self.inner, &mut err_ptr) };
+
+        OBError::consume(err_ptr)?;
+
+        Ok(timestamp)
+    }
+
+    /// Get the system timestamp of the frame in microseconds.
+    /// The system timestamp is the time point when the frame was received by the host, on host clock domain.
+    pub fn get_system_timestamp_us(&self) -> Result<u64, OBError> {
+        let mut err_ptr = std::ptr::null_mut();
+
+        let timestamp = unsafe { orb::ob_frame_get_system_timestamp_us(self.inner, &mut err_ptr) };
+
+        OBError::consume(err_ptr)?;
+
+        Ok(timestamp)
+    }
+
+    /// Get the global timestamp of the frame in microseconds.
+    /// The global timestamp is the time point when the frame was captured by the device, and has been converted to the host clock domain. The conversion process base on the frame timestamp and can eliminate the timer drift of the device
+    pub fn get_global_timestamp_us(&self) -> Result<u64, OBError> {
+        let mut err_ptr = std::ptr::null_mut();
+
+        let timestamp = unsafe { orb::ob_frame_get_global_timestamp_us(self.inner, &mut err_ptr) };
+
+        OBError::consume(err_ptr)?;
+
+        Ok(timestamp)
+    }
+
     /// Get the data buffer of a frame
     pub fn get_data(&self) -> Result<&[u8], OBError> {
         let mut err_ptr = std::ptr::null_mut();