#1734 actions based vr input (#1735)

richardTingle · web-flow · commit 4af7aabf304d · 2022-01-09T15:00:35.000-08:00
* #1734 Bring the LWJGL OpenVR implementation up to the modern actions based input/vr/AnalogActionState.java All the other apis are vender specific or are alternative of versions OpenVR, so are deprecated - Deprecate everything but lwjgl openVr - Add support for restricting analog, digital and haptics to a particular hand - improve vr javadocs - Add haptics to the new openVR api - Add analogue inputs - Add action based digital controls into jme-vr * #1734 Improve VR javadoc to make it clear that the action based API is only for OpenVr
diff --git a/jme3-vr/src/main/java/com/jme3/app/VRConstants.java b/jme3-vr/src/main/java/com/jme3/app/VRConstants.java
@@ -123,22 +123,31 @@ public class VRConstants {
 
     /**
      * The identifier of the OpenVR system.
+     *
+     * Deprecated as only the lwjgl OpenVr version has been upgraded to modern action based inputs
+     *
      * @see #SETTING_VRAPI_OSVR_VALUE
      * @see #SETTING_VRAPI_OPENVR_LWJGL_VALUE
      * @see #SETTING_VRAPI_OCULUSVR_VALUE
      */
+    @Deprecated
     public static final int SETTING_VRAPI_OPENVR_VALUE       = 1;
 
     /**
      * The identifier of the OSVR system.
+     *
+     * Deprecated as an OpenVr system should be used instead for a non vender specific api
+     *
      * @see #SETTING_VRAPI_OPENVR_VALUE
      * @see #SETTING_VRAPI_OPENVR_LWJGL_VALUE
      * @see #SETTING_VRAPI_OCULUSVR_VALUE
      */
+    @Deprecated
     public static final int SETTING_VRAPI_OSVR_VALUE         = 2;
 
     /**
      * The identifier of the OpenVR from LWJGL system.
+     *
      * @see #SETTING_VRAPI_OPENVR_VALUE
      * @see #SETTING_VRAPI_OSVR_VALUE
      * @see #SETTING_VRAPI_OCULUSVR_VALUE
@@ -147,10 +156,14 @@ public class VRConstants {
 
     /**
      * The identifier of the Oculus Rift system.
+     *
+     * Deprecated as an OpenVr system should be used instead (and the rift itself is discontinued)
+     *
      * @see #SETTING_VRAPI_OPENVR_VALUE
      * @see #SETTING_VRAPI_OSVR_VALUE
      * @see #SETTING_VRAPI_OPENVR_LWJGL_VALUE
      */
+    @Deprecated
     public static final int SETTING_VRAPI_OCULUSVR_VALUE    = 4;
 
     /**
diff --git a/jme3-vr/src/main/java/com/jme3/app/VREnvironment.java b/jme3-vr/src/main/java/com/jme3/app/VREnvironment.java
@@ -513,6 +513,8 @@ private void processSettings(){
 
             if (settings.get(VRConstants.SETTING_VRAPI) != null){
                 vrBinding = settings.getInteger(VRConstants.SETTING_VRAPI);
+            }else{
+                vrBinding = VRConstants.SETTING_VRAPI_OPENVR_LWJGL_VALUE; //this is the binding that is best supported so makes sense to be the default
             }
 
             if (settings.get(VRConstants.SETTING_SEATED_EXPERIENCE) != null){
diff --git a/jme3-vr/src/main/java/com/jme3/input/vr/AnalogActionState.java b/jme3-vr/src/main/java/com/jme3/input/vr/AnalogActionState.java
@@ -0,0 +1,48 @@
+package com.jme3.input.vr;
+
+public class AnalogActionState{
+
+    /**
+     * The X coordinate of the analog data (typically between -1 and 1 for joystick coordinates or 0 and 1 for
+     * trigger pulls)
+     */
+    public final float x;
+
+    /**
+     * The Y coordinate of the analog data (typically between -1 and 1)
+     *
+     * Will be zero if the analog action doesn't have at least 2 dimensions
+     */
+    public final float y;
+
+    /**
+     * The Z coordinate of the analog data (typically between -1 and 1)
+     *
+     * Will be zero if the analog action doesn't have at least 3 dimensions
+     */
+    public final float z;
+
+    /**
+     * The change in the X coordinate since the last frame
+     */
+    public final float deltaX;
+
+    /**
+     * The change in the Y coordinate since the last frame
+     */
+    public final float deltaY;
+
+    /**
+     * The change in the Z coordinate since the last frame
+     */
+    public final float deltaZ;
+
+    public AnalogActionState(float x, float y, float z, float deltaX, float deltaY, float deltaZ){
+        this.x = x;
+        this.y = y;
+        this.z = z;
+        this.deltaX = deltaX;
+        this.deltaY = deltaY;
+        this.deltaZ = deltaZ;
+    }
+}
diff --git a/jme3-vr/src/main/java/com/jme3/input/vr/DigitalActionState.java b/jme3-vr/src/main/java/com/jme3/input/vr/DigitalActionState.java
@@ -0,0 +1,19 @@
+package com.jme3.input.vr;
+
+public class DigitalActionState{
+
+    /**
+     * The current value of this action
+     */
+    public final boolean state;
+
+    /**
+     * If since the last loop the value of this action has changed
+     */
+    public final boolean changed;
+
+    public DigitalActionState(boolean state, boolean changed){
+        this.state = state;
+        this.changed = changed;
+    }
+}
diff --git a/jme3-vr/src/main/java/com/jme3/input/vr/VRInputAPI.java b/jme3-vr/src/main/java/com/jme3/input/vr/VRInputAPI.java
@@ -4,40 +4,182 @@
 import com.jme3.math.Vector2f;
 import com.jme3.math.Vector3f;
 
+import java.util.Collection;
+
 /**
  * An interface that represents a VR input (typically a VR device such as a controller).
  * @author reden - phr00t - https://github.com/phr00t
  * @author Julien Seinturier - COMEX SA - <a href="http://www.seinturier.fr">http://www.seinturier.fr</a>
  */
 public interface VRInputAPI {
+
+    /**
+     * Registers an action manifest. An actions manifest is a file that defines "actions" a player can make.
+     * (An action is an abstract version of a button press). The action manifest may then also include references to
+     * further files that define default mappings between those actions and physical buttons on the VR controllers.
+     *
+     * Note that registering an actions manifest will deactivate legacy inputs (i.e. methods such as {@link #isButtonDown}
+     * will no longer work
+     *
+     * See https://github.com/ValveSoftware/openvr/wiki/Action-manifest for documentation on how to create an
+     * action manifest
+     *
+     * This option is only relevant to OpenVR
+     *
+     * @param actionManifestAbsolutePath
+     *          the absolute file path to an actions manifest
+     * @param startingActiveActionSet
+     *          the actions in the manifest are divided into action sets (groups) by their prefix (e.g. "/actions/main").
+     *          These action sets can be turned off and on per frame. This argument sets the action set that will be
+     *          active now. The active action sets can be later be changed by calling {@link #setActiveActionSet}.
+     *          Note that at present only a single set at a time is supported
+     *
+     */
+    default void registerActionManifest( String actionManifestAbsolutePath, String startingActiveActionSet ){
+        throw new UnsupportedOperationException("Action manifests are not supported for the currently used VR API");
+    }
+
+    /**
+     * Updates the active action set (the action group that will have their states available to be polled).
+     *
+     * Note that this update will not take effect until the next loop
+     * Note that at present only a single set at a time is supported
+     *
+     * @param activeActionSet
+     *          the actions in the manifest are divided into action sets (groups) by their prefix (e.g. "/actions/main").
+     *          These action sets can be turned off and on per frame. This argument sets the action set that will be
+     *          active now.
+     */
+    default void setActiveActionSet( String activeActionSet ){
+        throw new UnsupportedOperationException("Action manifests are not supported for the currently used VR API");
+    }
+
+    /**
+     * Gets the current state of the action (abstract version of a button press).
+     *
+     * This is called for digital style actions (a button is pressed, or not)
+     *
+     * This method is commonly called when it's not important which hand the action is bound to (e.g. if a button press
+     * is opening your inventory that could be bound to either left or right hand and that would not matter).
+     *
+     * If the handedness matters use {@link #getDigitalActionState(String, String)}
+     *
+     * {@link #registerActionManifest} must have been called before using this method.
+     *
+     * @param actionName The name of the action. Will be something like /actions/main/in/openInventory
+     * @return the DigitalActionState that has details on if the state has changed, what the state is etc.
+     */
+    default DigitalActionState getDigitalActionState( String actionName ){
+        return getDigitalActionState(actionName, null);
+    }
+
+    /**
+     * Gets the current state of the action (abstract version of a button press).
+     *
+     * This is called for digital style actions (a button is pressed, or not)
+     *
+     * This method is commonly called when it is important which hand the action is found on. For example while
+     * holding a weapon a button may be bound to "eject magazine" to allow you to load a new one, but that would only
+     * want to take effect on the hand that is holding the weapon
+     *
+     * Note that restrictToInput only restricts, it must still be bound to the input you want to receive the input from in
+     * the action manifest default bindings.
+     *
+     * {@link #registerActionManifest} must have been called before using this method.
+     *
+     * @param actionName The name of the action. E.g. /actions/main/in/openInventory
+     * @param restrictToInput the input to restrict the action to. E.g. /user/hand/right. Or null, which means "any input"
+     * @return the DigitalActionState that has details on if the state has changed, what the state is etc.
+     */
+    default DigitalActionState getDigitalActionState( String actionName, String restrictToInput ){
+        throw new UnsupportedOperationException("Action manifests are not supported for the currently used VR API");
+    }
+
+    /**
+     * Gets the current state of the action (abstract version of a button press).
+     *
+     * This is called for analog style actions (most commonly joysticks, but button pressure can also be mapped in analog).
+     *
+     * This method is commonly called when it's not important which hand the action is bound to (e.g. if the thumb stick
+     * is controlling a third-person character in-game that could be bound to either left or right hand and that would
+     * not matter).
+     *
+     * If the handedness matters use {@link #getAnalogActionState(String, String)}
+     *
+     * {@link #registerActionManifest} must have been called before using this method.
+     *
+     * @param actionName The name of the action. E.g. /actions/main/in/openInventory
+     * @return the DigitalActionState that has details on if the state has changed, what the state is etc.
+     */
+    default AnalogActionState getAnalogActionState( String actionName ){
+        return getAnalogActionState(actionName, null);
+    }
+
+    /**
+     * Gets the current state of the action (abstract version of a button press).
+     *
+     * This is called for analog style actions (most commonly joysticks, but button pressure can also be mapped in analog).
+     *
+     * This method is commonly called when it is important which hand the action is found on. For example an "in universe"
+     * joystick that has a hat control might (while you are holding it) bind to the on-controller hat, but only on the hand
+     * holding it
+     *
+     * Note that restrictToInput only restricts, it must still be bound to the input you want to receive the input from in
+     * the action manifest default bindings.
+     *
+     * {@link #registerActionManifest} must have been called before using this method.
+     *
+     * @param actionName The name of the action. E.g. /actions/main/in/openInventory
+     * @param restrictToInput the input to restrict the action to. E.g. /user/hand/right. Or null, which means "any input"
+     * @return the DigitalActionState that has details on if the state has changed, what the state is etc.
+     */
+    default AnalogActionState getAnalogActionState( String actionName, String restrictToInput ){
+        throw new UnsupportedOperationException("Action manifests are not supported for the currently used VR API");
+    }
+
     /**
      * Check if the given button is down (more generally if the given input type is activated).
+     *
+     * Deprecated as should use an actions manifest approach. See {@link #registerActionManifest}. Note; action based will only work with the OpenVR api
+     *
      * @param controllerIndex the index of the controller to check.
      * @param checkButton the button / input to check.
      * @return <code>true</code> if the button / input is down / activated and <code>false</code> otherwise.
      */
+    @Deprecated
     public boolean isButtonDown(int controllerIndex, VRInputType checkButton);
 
     /**
      * Check if the given button / input from the given controller has been just pressed / activated.
+     *
+     * Deprecated as should use an actions manifest approach. See {@link #registerActionManifest}.  Note; action based will only work with the OpenVR api
+     *
      * @param controllerIndex the index of the controller.
      * @param checkButton the button / input to check.
      * @return <code>true</code> if the given button / input from the given controller has been just pressed / activated and <code>false</code> otherwise.
      */
+    @Deprecated
     public boolean wasButtonPressedSinceLastCall(int controllerIndex, VRInputType checkButton);
 
     /**
      * Reset the current activation of the inputs. After a call to this method, all input activation is considered as new activation.
      * @see #wasButtonPressedSinceLastCall(int, VRInputType)
+     *
+     * Deprecated as should use an actions manifest approach. See {@link #registerActionManifest}.  Note; action based will only work with the OpenVR api
      */
+    @Deprecated
     public void resetInputSinceLastCall();
 
     /**
      * Get the controller axis delta from the last value.
+     *
+     * Deprecated as should use an actions manifest approach. See {@link #registerActionManifest}.  Note; action based will only work with the OpenVR api
+     *
      * @param controllerIndex the index of the controller.
      * @param forAxis the axis.
      * @return the controller axis delta from the last call.
      */
+    @Deprecated
     public Vector2f getAxisDeltaSinceLastCall(int controllerIndex, VRInputType forAxis);
 
     /**
@@ -59,21 +201,29 @@ public interface VRInputAPI {
     /**
      * Get the axis value for the given input on the given controller.
      * This value is the {@link #getAxisRaw(int, VRInputType) raw value} multiplied by the  {@link #getAxisMultiplier() axis multiplier}.
+     *
+     * Deprecated as should use an actions manifest approach. See {@link #registerActionManifest}. Note; action based will only work with the OpenVR api
+     *
      * @param controllerIndex the index of the controller.
      * @param forAxis the axis.
      * @return the axis value for the given input on the given controller.
      * @see #getAxisRaw(int, VRInputType)
      * @see #getAxisMultiplier()
      */
+    @Deprecated
     public Vector2f getAxis(int controllerIndex, VRInputType forAxis);
 
     /**
      * Get the axis value for the given input on the given controller.
+     *
+     * Deprecated as should use an actions manifest approach. See {@link #registerActionManifest}  Note; action based will only work with the OpenVR api
+     *
      * @param controllerIndex the index of the controller.
      * @param forAxis the axis.
      * @return the axis value for the given input on the given controller.
      * @see #getAxis(int, VRInputType)
      */
+    @Deprecated
     public Vector2f getAxisRaw(int controllerIndex, VRInputType forAxis);
 
     /**
@@ -184,8 +334,46 @@ public interface VRInputAPI {
 
     /**
      * Trigger a haptic pulse on the selected controller for the duration given in parameters (in seconds).
+     *
+     * Deprecated, use triggerHapticAction instead (as it has more options and doesn't use deprecated methods)
+     *
      * @param controllerIndex the index of the controller.
      * @param seconds the duration of the pulse in seconds.
      */
+    @Deprecated
     public void triggerHapticPulse(int controllerIndex, float seconds);
+
+    /**
+     * Triggers a haptic action (aka a vibration).
+     *
+     * Note if you want a haptic action in only one hand that is done either by only binding the action to one hand in
+     * the action manifest's standard bindings or by binding to both and using {@link #triggerHapticAction(String, float, float, float, String)}
+     * to control which input it gets set to at run time
+     *
+     * @param actionName The name of the action. Will be something like /actions/main/out/vibrate
+     * @param duration how long in seconds the
+     * @param frequency in cycles per second
+     * @param amplitude between 0 and 1
+     */
+   default void triggerHapticAction( String actionName, float duration, float frequency, float amplitude){
+       triggerHapticAction( actionName, duration, frequency, amplitude, null );
+   }
+
+    /**
+     * Triggers a haptic action (aka a vibration) restricted to just one input (e.g. left or right hand).
+     *
+     * Note that restrictToInput only restricts, it must still be bound to the input you want to send the haptic to in
+     * the action manifest default bindings.
+     *
+     * This method is typically used to bind the haptic to both hands then decide at run time which hand to sent to     *
+     *
+     * @param actionName The name of the action. Will be something like /actions/main/out/vibrate
+     * @param duration how long in seconds the
+     * @param frequency in cycles per second
+     * @param amplitude between 0 and 1
+     * @param restrictToInput the input to restrict the action to. E.g. /user/hand/right, /user/hand/left. Or null, which means "any input"
+     */
+    default void triggerHapticAction( String actionName, float duration, float frequency, float amplitude, String restrictToInput){
+        throw new UnsupportedOperationException("Action manifests are not supported for the currently used VR API");
+    }
 }
diff --git a/jme3-vr/src/main/java/com/jme3/input/vr/VRInputType.java b/jme3-vr/src/main/java/com/jme3/input/vr/VRInputType.java
@@ -5,7 +5,10 @@
  * @author reden - phr00t - https://github.com/phr00t
  * @author Julien Seinturier - COMEX SA - <a href="http://www.seinturier.fr">http://www.seinturier.fr</a>
  *
+ * Deprecated, use the LWJGL openVR bindings and use actions instead
+ *
  */
+@Deprecated
 public enum VRInputType {
     /**
      * an HTC vive trigger axis (about <a href="https://www.vive.com/us/support/category_howto/720435.html">Vive controller</a>).
diff --git a/jme3-vr/src/main/java/com/jme3/input/vr/lwjgl_openvr/LWJGLOpenVRAnalogActionData.java b/jme3-vr/src/main/java/com/jme3/input/vr/lwjgl_openvr/LWJGLOpenVRAnalogActionData.java
diff --git a/jme3-vr/src/main/java/com/jme3/input/vr/lwjgl_openvr/LWJGLOpenVRDigitalActionData.java b/jme3-vr/src/main/java/com/jme3/input/vr/lwjgl_openvr/LWJGLOpenVRDigitalActionData.java
diff --git a/jme3-vr/src/main/java/com/jme3/input/vr/lwjgl_openvr/LWJGLOpenVRInput.java b/jme3-vr/src/main/java/com/jme3/input/vr/lwjgl_openvr/LWJGLOpenVRInput.java

Original file line number	Diff line number	Diff line change
`@@ -513,6 +513,8 @@ private void processSettings(){`
`513`	`513`
`514`	`514`	`if (settings.get(VRConstants.SETTING_VRAPI) != null){`
`515`	`515`	`vrBinding = settings.getInteger(VRConstants.SETTING_VRAPI);`
	`516`	`+ }else{`
	`517`	`+ vrBinding = VRConstants.SETTING_VRAPI_OPENVR_LWJGL_VALUE; //this is the binding that is best supported so makes sense to be the default`
`516`	`518`	`}`
`517`	`519`
`518`	`520`	`if (settings.get(VRConstants.SETTING_SEATED_EXPERIENCE) != null){`