From d6d3b40fc3ad8c372363cfbc7d02fd7bd82551a5 Mon Sep 17 00:00:00 2001
From: Benjamin Saunders <ben.e.saunders@gmail.com>
Date: Mon, 17 Jul 2017 21:36:04 -0700
Subject: [PATCH] Additional compositor methods and docs

---
 src/compositor/mod.rs | 15 +++++++++++++++
 src/render_models.rs  | 13 +++++++------
 2 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/src/compositor/mod.rs b/src/compositor/mod.rs
index 1812c5c..5967974 100644
--- a/src/compositor/mod.rs
+++ b/src/compositor/mod.rs
@@ -92,6 +92,14 @@ impl<'a> Compositor<'a> {
         }
     }
 
+    /// Call immediately after presenting your app's window (i.e. companion window) to unblock the compositor.
+    ///
+    /// This is an optional call, which only needs to be used if you can't instead call `wait_get_poses` immediately
+    /// after submitting frames.  For example, if your engine's render and game loop are not on separate threads, or
+    /// blocking the render thread until 3ms before the next vsync would introduce a deadlock of some sort.  This
+    /// function tells the compositor that you have finished all rendering after having Submitted buffers for both eyes,
+    /// and it is free to start its rendering work.  This should only be called from the same thread you are rendering
+    /// on.
     pub fn post_present_handoff(&self) {
         unsafe { (self.0.PostPresentHandoff.unwrap())() };
     }
@@ -100,6 +108,13 @@ impl<'a> Compositor<'a> {
     pub fn is_fullscreen(&self) -> bool {
         unsafe { (self.0.IsFullscreen.unwrap())() }
     }
+
+    /// Clears the frame that was sent with the last call to `submit.
+    ///
+    /// This will cause the compositor to show the grid until `submit` is called again.
+    pub fn clear_last_submitted_frame(&self) {
+        unsafe { self.0.ClearLastSubmittedFrame.unwrap()() }
+    }
 }
 
 #[derive(Debug, Copy, Clone)]
diff --git a/src/render_models.rs b/src/render_models.rs
index e7642cb..8c077ad 100644
--- a/src/render_models.rs
+++ b/src/render_models.rs
@@ -38,8 +38,7 @@ impl<'a> RenderModels<'a> {
     /// Get the names of available components.
     ///
     /// `component` does not correlate to a tracked device index, but is only used for iterating over all available
-    /// components.  If it's out of range, this function will return None.  Otherwise, it will return the size of the
-    /// buffer required for the name.
+    /// components.  If it's out of range, this function will return None.
     pub fn component_name(&self, model: &CStr, component: u32) -> Option<CString> {
         unsafe { get_string(|ptr, n| self.0.GetComponentName.unwrap()(model.as_ptr() as *mut _, component, ptr, n)) }
     }
@@ -50,7 +49,7 @@ impl<'a> RenderModels<'a> {
         (0..n).map(|i| self.component_name(model, i).expect("inconsistent component presence reported by OpenVR")).collect::<Vec<_>>().into_iter()
     }
 
-    /// Use this to get the render model name for the specified rendermode/component combination, to be passed to
+    /// Use this to get the render model name for the specified rendermodel/component combination, to be passed to
     /// `load_render_model`.
     ///
     /// If the component name is out of range, this function will return None.
@@ -64,10 +63,12 @@ impl<'a> RenderModels<'a> {
 
     /// Use this to query information about the component, as a function of the controller state.
     ///
-    /// Returns None if the component is invalid or should not be rendered in the current state.
+    /// Returns None if the component is invalid.
     ///
-    /// For dynamic controller components (ex: trigger) values will reflect component motions
-    /// For static components this will return a consistent value independent of the VRControllerState_t
+    /// Check `ComponentState::is_visible()` to determine whether the returned component should be rendered.
+    ///
+    /// For dynamic controller components (ex: trigger) values will reflect component motions.
+    /// For static components this will return a consistent value independent of the `ControllerState`.
     pub fn component_state(&self, model: &CStr, component: &CStr, state: &ControllerState, mode: &ControllerMode) -> Option<ComponentState> {
         unsafe {
             let mut out = mem::uninitialized();