From b43f875b3b1f2d29f677ab66b7fa705835891a37 Mon Sep 17 00:00:00 2001 From: awtterpip Date: Wed, 27 Dec 2023 20:03:41 -0600 Subject: [PATCH] add doc comments --- xr_api/src/api.rs | 130 +++++++++++++++--------------------- xr_api/src/api_traits.rs | 10 ++- xr_api/src/backend/webxr.rs | 2 +- xr_api/src/types.rs | 10 +-- 4 files changed, 65 insertions(+), 87 deletions(-) diff --git a/xr_api/src/api.rs b/xr_api/src/api.rs index e83ca54..d5046e7 100644 --- a/xr_api/src/api.rs +++ b/xr_api/src/api.rs @@ -3,6 +3,9 @@ use std::rc::Rc; use crate::prelude::*; +/// Entry point to the API +/// +/// To see methods available for this struct, refer to [EntryTrait] #[derive(Clone)] pub struct Entry(Rc); @@ -16,100 +19,71 @@ impl Entry { } } +/// Represents an intent to start a session with requested extensions. +/// +/// To see methods available for this struct, refer to [InstanceTrait] #[derive(Clone)] pub struct Instance(Rc); +/// Represents a running XR application. +/// +/// To see methods available for this struct, refer to [SessionTrait] #[derive(Clone)] pub struct Session(Rc); +/// A view of one eye. Used to retrieve render data such as texture views and projection matrices. +/// +/// To see methods available for this struct, refer to [ViewTrait] #[derive(Clone)] pub struct View(Rc); +/// Represents all XR input sources. +/// +/// To see methods available for this struct, refer to [InputTrait] #[derive(Clone)] pub struct Input(Rc); +/// Represents an XR Action. Can be used to retrieve input values or trigger output devices such as haptics. +/// +/// The methods available to this struct are dependent upon the action type. For input values, use `.get()` to retrieve the values. +/// For haptics, please refer to [HapticTrait] #[derive(Clone)] -pub struct Action(A::Inner); +pub struct Action(Rc); -impl Deref for Entry { - type Target = dyn EntryTrait; +macro_rules! impl_api { + ($($t:ty, $trait:ident; )*) => { + $( + impl std::ops::Deref for $t { + type Target = dyn $trait; + + fn deref(&self) -> &Self::Target { + &*self.0 + } + } + + impl From for $t { + fn from(value: T) -> Self { + Self(Rc::new(value)) + } + } + )* + + }; +} + +impl_api! { + Entry, EntryTrait; + Instance, InstanceTrait; + Session, SessionTrait; + View, ViewTrait; + Input, InputTrait; +} + +impl Deref for Action { + type Target = A::Inner; fn deref(&self) -> &Self::Target { - &*self.0 - } -} - -impl Deref for Instance { - type Target = dyn InstanceTrait; - - fn deref(&self) -> &Self::Target { - &*self.0 - } -} - -impl Deref for Session { - type Target = dyn SessionTrait; - - fn deref(&self) -> &Self::Target { - &*self.0 - } -} - -impl Deref for View { - type Target = dyn ViewTrait; - - fn deref(&self) -> &Self::Target { - &*self.0 - } -} - -impl Deref for Input { - type Target = dyn InputTrait; - - fn deref(&self) -> &Self::Target { - &*self.0 - } -} - -impl Deref for Action -where - A: ActionType, - A::Inner: Deref, -{ - type Target = O; - - fn deref(&self) -> &Self::Target { - &*self.0 - } -} - -impl From for Entry { - fn from(value: T) -> Self { - Self(Rc::new(value)) - } -} - -impl From for Instance { - fn from(value: T) -> Self { - Self(Rc::new(value)) - } -} - -impl From for Session { - fn from(value: T) -> Self { - Self(Rc::new(value)) - } -} - -impl From for View { - fn from(value: T) -> Self { - Self(Rc::new(value)) - } -} - -impl From for Input { - fn from(value: T) -> Self { - Self(Rc::new(value)) + &self.0 } } diff --git a/xr_api/src/api_traits.rs b/xr_api/src/api_traits.rs index 1c6ba47..95ac71b 100644 --- a/xr_api/src/api_traits.rs +++ b/xr_api/src/api_traits.rs @@ -26,8 +26,8 @@ pub trait SessionTrait { -> Option<(Device, Queue, AdapterInfo, Adapter, wgpu::Instance)>; /// Request input modules with the specified bindings. fn create_input(&self, bindings: Bindings) -> Result; - /// Blocks until a rendering frame is available, then returns the texture views for the left and right eyes. - fn begin_frame(&self) -> Result<(TextureView, TextureView)>; + /// Blocks until a rendering frame is available, then returns the views for the left and right eyes. + fn begin_frame(&self) -> Result<(View, View)>; /// Submits rendering work for this frame. fn end_frame(&self) -> Result<()>; } @@ -64,8 +64,12 @@ pub trait ActionTrait { fn id(&self) -> ActionId; } -pub trait ActionInputTrait {} +/// Represents input actions, such as bools, floats, and poses +pub trait ActionInputTrait { + fn get(&self) -> A; +} +/// Represents haptic actions. pub trait HapticTrait {} impl EntryTrait for T { diff --git a/xr_api/src/backend/webxr.rs b/xr_api/src/backend/webxr.rs index 2ca069f..16dd19b 100644 --- a/xr_api/src/backend/webxr.rs +++ b/xr_api/src/backend/webxr.rs @@ -90,7 +90,7 @@ impl SessionTrait for WebXrSession { .into()) } - fn begin_frame(&self) -> Result<(wgpu::TextureView, wgpu::TextureView)> { + fn begin_frame(&self) -> Result<(View, View)> { let mut end_frame_sender = self.end_frame_sender.lock().unwrap(); if end_frame_sender.is_some() { Err(XrError::Placeholder)? diff --git a/xr_api/src/types.rs b/xr_api/src/types.rs index 988f32f..ed8be23 100644 --- a/xr_api/src/types.rs +++ b/xr_api/src/types.rs @@ -33,13 +33,13 @@ pub struct Haptic; pub struct Pose; pub trait ActionType: Sized { - type Inner; + type Inner: ?Sized; fn get(input: &dyn InputTrait, path: ActionId) -> Result>; } impl ActionType for Haptic { - type Inner = Rc; + type Inner = dyn HapticTrait; fn get(input: &dyn InputTrait, path: ActionId) -> Result> { input.get_haptics(path) @@ -47,7 +47,7 @@ impl ActionType for Haptic { } impl ActionType for Pose { - type Inner = Rc>; + type Inner = dyn ActionInputTrait; fn get(input: &dyn InputTrait, path: ActionId) -> Result> { input.get_pose(path) @@ -55,7 +55,7 @@ impl ActionType for Pose { } impl ActionType for f32 { - type Inner = Rc>; + type Inner = dyn ActionInputTrait; fn get(input: &dyn InputTrait, path: ActionId) -> Result> { input.get_float(path) @@ -63,7 +63,7 @@ impl ActionType for f32 { } impl ActionType for bool { - type Inner = Rc>; + type Inner = dyn ActionInputTrait; fn get(input: &dyn InputTrait, path: ActionId) -> Result> { input.get_bool(path)