implement XR_META_environment_depth

openxr/src/environment_depth.rs

@@ -0,0 +1,353 @@
+//! The [Environment Depth feature](https://developer.oculus.com/documentation/native/android/mobile-depth/)
+//! allows you to access depth maps based on the user environment.
+//! This is primarily used to occlude virtual objects by real-world objects and surfaces.
+//!
+//! This feature is exclusive to the Oculus Quest 3 as of September 2024.
+//!
+//! More details about the environment depth feature can be found in the [OpenXR specification](https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XR_META_environment_depth).
+use crate::{
+    cvt, raw, sys, Graphics, Instance, Result, Session, SessionInner, Space, SystemId, Time, View,
+};
+use std::marker::PhantomData;
+use std::ptr;
+use std::sync::Arc;
+
+#[derive(Debug, Copy, Clone)]
+pub struct SystemEnvironmentDepthProperties {
+    pub supports_environment_depth: bool,
+    pub supports_hand_removal: bool,
+}
+
+impl Instance {
+    #[inline]
+    pub fn environment_depth_properties(
+        &self,
+        system: SystemId,
+    ) -> Result<SystemEnvironmentDepthProperties> {
+        unsafe {
+            if self.exts().meta_environment_depth.is_none() {
+                return Err(sys::Result::ERROR_EXTENSION_NOT_PRESENT);
+            }
+            let mut env_depth = sys::SystemEnvironmentDepthPropertiesMETA::out(ptr::null_mut());
+            let mut p = sys::SystemProperties::out(&mut env_depth as *mut _ as _);
+            cvt((self.fp().get_system_properties)(
+                self.as_raw(),
+                system,
+                p.as_mut_ptr(),
+            ))?;
+            Ok(env_depth.assume_init().into())
+        }
+    }
+}
+
+impl From<sys::SystemEnvironmentDepthPropertiesMETA> for SystemEnvironmentDepthProperties {
+    fn from(value: sys::SystemEnvironmentDepthPropertiesMETA) -> Self {
+        SystemEnvironmentDepthProperties {
+            supports_environment_depth: value.supports_environment_depth.into(),
+            supports_hand_removal: value.supports_hand_removal.into(),
+        }
+    }
+}
+
+impl<G: Graphics> Session<G> {
+    #[inline]
+    /// Create an [`EnvironmentDepthProvider`].
+    ///
+    /// Requires [`XR_META_environment_depth`].
+    ///
+    /// [`XR_META_environment_depth`]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XR_META_environment_depth
+    /// [`EnvironmentDepthProvider`]: environment_depth/struct.EnvironmentDepthProvider.html
+    pub fn create_depth_environment_provider(&self) -> Result<EnvironmentDepthProvider> {
+        EnvironmentDepthProvider::create(self)
+    }
+
+    #[inline]
+    /// Create an [`EnvironmentDepthSwapchain`].
+    ///
+    /// Requires [`XR_META_environment_depth`].
+    ///
+    /// [`XR_META_environment_depth`]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XR_META_environment_depth
+    /// [`EnvironmentDepthSwapchain`]: environment_depth/struct.EnvironmentDepthSwapchain.html
+    pub fn create_depth_environment_swapchain(
+        &self,
+        provider: &EnvironmentDepthProvider,
+    ) -> Result<EnvironmentDepthSwapchain<G>> {
+        EnvironmentDepthSwapchain::create(self, provider)
+    }
+}
+
+/// An [Environment Depth Provider].
+///
+/// Requires [`XR_META_environment_depth`] to be enabled.
+///
+/// See the [`EnvironmentDepthProviderMETA struct`].
+///
+/// [`XR_META_environment_depth`]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XR_META_environment_depth
+/// [`EnvironmentDepthProviderMETA struct`]: https://docs.rs/openxr-sys/latest/openxr_sys/struct.EnvironmentDepthProviderMETA.html
+/// [Environment Depth Provider]: https://developer.oculus.com/documentation/native/android/mobile-depth/#creating-a-depth-provider
+pub struct EnvironmentDepthProvider {
+    pub(crate) session: Arc<SessionInner>,
+    handle: sys::EnvironmentDepthProviderMETA,
+}
+
+impl EnvironmentDepthProvider {
+    /// [Create] an environment depth provider.
+    ///
+    /// [Create]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrCreateEnvironmentDepthProviderMETA
+    pub(crate) fn create<G>(session: &Session<G>) -> Result<Self> {
+        let info = sys::EnvironmentDepthProviderCreateInfoMETA {
+            ty: sys::EnvironmentDepthProviderCreateInfoMETA::TYPE,
+            next: ptr::null(),
+            create_flags: sys::EnvironmentDepthProviderCreateFlagsMETA::EMPTY,
+        };
+        let fp = fp(&session.inner);
+        let mut handle = sys::EnvironmentDepthProviderMETA::NULL;
+        unsafe {
+            cvt((fp.create_environment_depth_provider)(
+                session.as_raw(),
+                &info,
+                &mut handle,
+            ))?;
+        }
+        Ok(EnvironmentDepthProvider {
+            session: session.inner.clone(),
+            handle,
+        })
+    }
+
+    /// [Start] an environment depth provider.
+    ///
+    /// [Start]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrStartEnvironmentDepthProviderMETA
+    pub fn start(&self) -> Result<()> {
+        let fp = fp(&self.session);
+        unsafe {
+            cvt((fp.start_environment_depth_provider)(self.handle))?;
+        }
+        Ok(())
+    }
+
+    /// [Stop] an environment depth provider.
+    ///
+    /// [Stop]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrStopEnvironmentDepthProviderMETA
+    pub fn stop(&self) -> Result<()> {
+        let fp = fp(&self.session);
+        unsafe {
+            cvt((fp.stop_environment_depth_provider)(self.handle))?;
+        }
+        Ok(())
+    }
+
+    /// Set the [hand removal option].
+    ///
+    /// [hand removal option]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrSetEnvironmentDepthHandRemovalMETA
+    pub fn set_hand_removal(&self, enabled: bool) -> Result<()> {
+        let info = sys::EnvironmentDepthHandRemovalSetInfoMETA {
+            ty: sys::EnvironmentDepthHandRemovalSetInfoMETA::TYPE,
+            next: ptr::null(),
+            enabled: enabled.into(),
+        };
+        let fp = fp(&self.session);
+        unsafe {
+            cvt((fp.set_environment_depth_hand_removal)(self.handle, &info))?;
+        }
+        Ok(())
+    }
+
+    /// [Acquire] the latest available swapchain image that has been generated.
+    ///
+    /// [Acquire]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrAcquireEnvironmentDepthImageMETA
+    pub fn acquire_image(
+        &self,
+        space: &Space,
+        display_time: Time,
+    ) -> Result<EnvironmentDepthImage> {
+        let info = sys::EnvironmentDepthImageAcquireInfoMETA {
+            ty: sys::EnvironmentDepthImageAcquireInfoMETA::TYPE,
+            next: ptr::null(),
+            space: space.as_raw(),
+            display_time,
+        };
+        let fp = fp(&self.session);
+        let default_img_view = sys::EnvironmentDepthImageViewMETA {
+            ty: sys::EnvironmentDepthImageViewMETA::TYPE,
+            next: ptr::null(),
+            pose: sys::Posef::default(),
+            fov: sys::Fovf::default(),
+        };
+        let mut img = sys::EnvironmentDepthImageMETA {
+            ty: sys::EnvironmentDepthImageMETA::TYPE,
+            next: ptr::null(),
+            near_z: 0.0,
+            far_z: 0.0,
+            swapchain_index: 0,
+            views: [default_img_view, default_img_view],
+        };
+        unsafe {
+            cvt((fp.acquire_environment_depth_image)(
+                self.handle,
+                &info,
+                &mut img,
+            ))?;
+            Ok(img.into())
+        }
+    }
+}
+
+impl Drop for EnvironmentDepthProvider {
+    fn drop(&mut self) {
+        unsafe {
+            ((fp(&self.session).destroy_environment_depth_provider)(self.handle));
+        }
+    }
+}
+
+/// An [Environment Depth Swapchain].
+///
+/// Requires [`XR_META_environment_depth`] to be enabled.
+///
+/// See the [`EnvironmentDepthSwapchainMETA struct`].
+///
+/// [`XR_META_environment_depth`]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XR_META_environment_depth
+/// [`EnvironmentDepthSwapchainMETA struct`]: https://docs.rs/openxr-sys/latest/openxr_sys/struct.EnvironmentDepthSwapchainMETA.html
+/// [Environment Depth Swapchain]: https://developer.oculus.com/documentation/native/android/mobile-depth/#creating-and-enumerating-a-depth-swapchain
+pub struct EnvironmentDepthSwapchain<G> {
+    pub(crate) session: Arc<SessionInner>,
+    pub(crate) handle: sys::EnvironmentDepthSwapchainMETA,
+    _marker: PhantomData<G>,
+}
+
+impl<G: Graphics> EnvironmentDepthSwapchain<G> {
+    /// [Create] an environment depth swapchain.
+    ///
+    /// [Create]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrCreateEnvironmentDepthSwapchainMETA
+    pub(crate) fn create(
+        session: &Session<G>,
+        provider: &EnvironmentDepthProvider,
+    ) -> Result<Self> {
+        let info = sys::EnvironmentDepthSwapchainCreateInfoMETA {
+            ty: sys::EnvironmentDepthSwapchainCreateInfoMETA::TYPE,
+            next: ptr::null(),
+            create_flags: sys::EnvironmentDepthSwapchainCreateFlagsMETA::EMPTY,
+        };
+        let fp = fp(&session.inner);
+        let mut handle = sys::EnvironmentDepthSwapchainMETA::NULL;
+        unsafe {
+            cvt((fp.create_environment_depth_swapchain)(
+                provider.handle,
+                &info,
+                &mut handle,
+            ))?;
+        }
+        Ok(EnvironmentDepthSwapchain {
+            session: session.inner.clone(),
+            handle,
+            _marker: PhantomData,
+        })
+    }
+
+    /// Retrieve the [environment depth swapchain state].
+    ///
+    /// [environment depth swapchain state]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrGetEnvironmentDepthSwapchainStateMETA
+    pub fn get_state(&self) -> Result<EnvironmentDepthSwapchainState> {
+        let fp = fp(&self.session);
+        let mut state = sys::EnvironmentDepthSwapchainStateMETA {
+            ty: sys::EnvironmentDepthSwapchainStateMETA::TYPE,
+            next: ptr::null_mut(),
+            width: 0,
+            height: 0,
+        };
+        unsafe {
+            cvt((fp.get_environment_depth_swapchain_state)(
+                self.handle,
+                &mut state,
+            ))?;
+            Ok(state.into())
+        }
+    }
+
+    #[inline]
+    /// [Enumerate] the environment depth swapchain images.
+    ///
+    /// [`Enumerate`]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#xrEnumerateEnvironmentDepthSwapchainImagesMETA
+    pub fn enumerate_images(&self) -> Result<Vec<G::SwapchainImage>> {
+        G::enumerate_depth_environment_swapchain_images(self)
+    }
+
+    #[inline]
+    pub(crate) fn fp(&self) -> &raw::EnvironmentDepthMETA {
+        fp(&self.session)
+    }
+}
+
+impl<G> Drop for EnvironmentDepthSwapchain<G> {
+    fn drop(&mut self) {
+        unsafe {
+            ((fp(&self.session).destroy_environment_depth_swapchain)(self.handle));
+        }
+    }
+}
+
+/// An [Environment Depth Swapchain State].
+///
+/// Requires [`XR_META_environment_depth`] to be enabled.
+///
+/// See the [`EnvironmentDepthSwapchainStateMETA struct`].
+///
+/// [`XR_META_environment_depth`]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XR_META_environment_depth
+/// [`EnvironmentDepthSwapchainStateMETA struct`]: https://docs.rs/openxr-sys/latest/openxr_sys/struct.EnvironmentDepthSwapchainStateMETA.html
+/// [Environment Depth Swapchain State]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrEnvironmentDepthSwapchainStateMETA
+#[derive(Debug, Copy, Clone)]
+pub struct EnvironmentDepthSwapchainState {
+    pub width: u32,
+    pub height: u32,
+}
+
+impl From<sys::EnvironmentDepthSwapchainStateMETA> for EnvironmentDepthSwapchainState {
+    fn from(value: sys::EnvironmentDepthSwapchainStateMETA) -> Self {
+        EnvironmentDepthSwapchainState {
+            width: value.width,
+            height: value.height,
+        }
+    }
+}
+
+/// An [Environment Depth Image].
+///
+/// Requires [`XR_META_environment_depth`] to be enabled.
+///
+/// See the [`EnvironmentDepthImageMETA struct`].
+///
+/// [`XR_META_environment_depth`]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XR_META_environment_depth
+/// [`EnvironmentDepthImageMETA struct`]: https://docs.rs/openxr-sys/latest/openxr_sys/struct.EnvironmentDepthImageMETA.html
+/// [Environment Depth Image]: https://registry.khronos.org/OpenXR/specs/1.1/html/xrspec.html#XrEnvironmentDepthImageMETA
+#[derive(Copy, Clone)]
+pub struct EnvironmentDepthImage {
+    pub swapchain_index: u32,
+    pub near_z: f32,
+    pub far_z: f32,
+    pub views: [View; 2],
+}
+
+impl From<sys::EnvironmentDepthImageMETA> for EnvironmentDepthImage {
+    fn from(value: sys::EnvironmentDepthImageMETA) -> Self {
+        EnvironmentDepthImage {
+            swapchain_index: value.swapchain_index,
+            near_z: value.near_z,
+            far_z: value.far_z,
+            views: value.views.map(|v| View {
+                pose: v.pose,
+                fov: v.fov,
+            }),
+        }
+    }
+}
+
+#[inline]
+fn fp(session: &SessionInner) -> &raw::EnvironmentDepthMETA {
+    session
+        .instance
+        .exts()
+        .meta_environment_depth
+        .as_ref()
+        .expect("`XR_META_environment_depth` not loaded")
+}