XR_MNDX_force_feedback_curl

specification/registry/xr.xml

@@ -477,6 +477,8 @@ maintained in the default branch of the Khronos OpenXR GitHub project.
         <type name="XrFoveationDynamicFlagBitsHTC" category="enum"/>
         <type name="XrFoveationLevelHTC" category="enum"/>
 
+        <!-- XR_MNDX_force_feedback_curl -->
+        <type name="XrForceFeedbackCurlLocationMNDX" category="enum"/>
 
         <!-- Struct types -->
         <type category="struct" name="XrVector2f">
@@ -2551,6 +2553,26 @@ maintained in the default branch of the Khronos OpenXR GitHub project.
             <member><type>XrActionSet</type> <name>actionSet</name></member>
             <member><type>uint32_t</type>    <name>priorityOverride</name></member>
         </type>
+
+        <!-- XR_MNDX_force_feedback_curl -->
+        <type category="struct" name="XrSystemForceFeedbackCurlPropertiesMNDX" structextends="XrSystemProperties" returnedonly="true">
+            <member values="XR_TYPE_SYSTEM_FORCE_FEEDBACK_CURL_PROPERTIES_MNDX"><type>XrStructureType</type> <name>type</name></member>
+            <member><type>void</type>*    <name>next</name></member>
+            <member><type>XrBool32</type> <name>supportsForceFeedbackCurl</name></member>
+        </type>
+
+        <type category="struct" name="XrForceFeedbackCurlApplyLocationsMNDX">
+            <member values="XR_TYPE_FORCE_FEEDBACK_CURL_APPLY_LOCATIONS_MNDX"><type>XrStructureType</type> <name>type</name></member>
+            <member>const <type>void</type>*                                               <name>next</name></member>
+            <member><type>uint32_t</type>                                                  <name>locationCount</name></member>
+            <member len="locationCount"><type>XrForceFeedbackCurlApplyLocationMNDX</type>* <name>locations</name></member>
+        </type>
+
+        <type category="struct" name="XrForceFeedbackCurlApplyLocationMNDX">
+            <member><type>XrForceFeedbackCurlLocationMNDX</type> <name>location</name></member>
+            <member><type>float</type>                           <name>value</name></member>
+        </type>
+
     </types>
 
     <!-- SECTION: OpenXR enumerant (token) definitions. -->
@@ -3271,6 +3293,15 @@ maintained in the default branch of the Khronos OpenXR GitHub project.
     </enums>
 
 
+    <!-- enums for XR_MNDX_force_feedback_curl -->
+    <enums name="XrForceFeedbackCurlLocationMNDX" type="enum">
+        <enum value="0"   name="XR_FORCE_FEEDBACK_CURL_LOCATION_THUMB_CURL_MNDX"  comment="force feedback for thumb curl"/>
+        <enum value="1"   name="XR_FORCE_FEEDBACK_CURL_LOCATION_INDEX_CURL_MNDX"  comment="force feedback for index finger curl"/>
+        <enum value="2"   name="XR_FORCE_FEEDBACK_CURL_LOCATION_MIDDLE_CURL_MNDX" comment="force feedback for middle finger curl"/>
+        <enum value="3"   name="XR_FORCE_FEEDBACK_CURL_LOCATION_RING_CURL_MNDX"   comment="force feedback for ring finger curl"/>
+        <enum value="4"   name="XR_FORCE_FEEDBACK_CURL_LOCATION_LITTLE_CURL_MNDX" comment="force feedback for little finger curl"/>
+    </enums>
+
     <!-- SECTION: OpenXR command definitions -->
     <commands>
         <command successcodes="XR_SUCCESS" errorcodes="XR_ERROR_FUNCTION_UNSUPPORTED,XR_ERROR_VALIDATION_FAILURE,XR_ERROR_RUNTIME_FAILURE,XR_ERROR_HANDLE_INVALID,XR_ERROR_INSTANCE_LOST,XR_ERROR_OUT_OF_MEMORY">
@@ -4521,6 +4552,13 @@ maintained in the default branch of the Khronos OpenXR GitHub project.
             <param>const <type>XrFoveationApplyInfoHTC</type>* <name>applyInfo</name></param>
         </command>
 
+
+        <!-- commands for XR_MNDX_force_feedback_curl -->
+        <command successcodes="XR_SUCCESS,XR_SESSION_LOSS_PENDING,XR_SESSION_NOT_FOCUSED" errorcodes="XR_ERROR_FUNCTION_UNSUPPORTED,XR_ERROR_VALIDATION_FAILURE,XR_ERROR_RUNTIME_FAILURE,XR_ERROR_HANDLE_INVALID,XR_ERROR_INSTANCE_LOST,XR_ERROR_SESSION_LOST">
+            <proto><type>XrResult</type> <name>xrApplyForceFeedbackCurlMNDX</name></proto>
+            <param><type>XrHandTrackerEXT</type> <name>handTracker</name></param>
+            <param>const <type>XrForceFeedbackCurlApplyLocationsMNDX</type>* <name>locations</name></param>
+        </command>
     </commands>
 
     <!-- SECTION: OpenXR API interface definitions -->
@@ -8083,10 +8121,20 @@ maintained in the default branch of the Khronos OpenXR GitHub project.
         </require>
     </extension>
 
-    <extension name="XR_MNDX_extension_376" number="376" type="instance" supported="disabled">
+    <extension name="XR_MNDX_force_feedback_curl" number="376" type="instance" supported="openxr" requires="XR_EXT_hand_tracking" provisional="true">
         <require>
-            <enum value="1"                                 name="XR_MNDX_extension_376_SPEC_VERSION"/>
-            <enum value="&quot;XR_MNDX_extension_376&quot;" name="XR_MNDX_extension_376_EXTENSION_NAME"/>
+            <enum value="1"                                       name="XR_MNDX_force_feedback_curl_SPEC_VERSION"/>
+            <enum value="&quot;XR_MNDX_force_feedback_curl&quot;" name="XR_MNDX_FORCE_FEEDBACK_CURL_EXTENSION_NAME"/>
+
+            <command name="xrApplyForceFeedbackCurlMNDX"/>
+
+            <type name="XrSystemForceFeedbackCurlPropertiesMNDX"/>
+            <type name="XrForceFeedbackCurlLocationMNDX"/>
+            <type name="XrForceFeedbackCurlApplyLocationsMNDX"/>
+            <type name="XrForceFeedbackCurlApplyLocationMNDX"/>
+
+            <enum offset="0" extends="XrStructureType" name="XR_TYPE_SYSTEM_FORCE_FEEDBACK_CURL_PROPERTIES_MNDX"/>
+            <enum offset="1" extends="XrStructureType" name="XR_TYPE_FORCE_FEEDBACK_CURL_APPLY_LOCATIONS_MNDX"/>
         </require>
     </extension>
 

specification/sources/chapters/extensions/mndx/mndx_force_feedback_curl.adoc

@@ -0,0 +1,188 @@
+// Copyright (c) 2022, Daniel Willmott
+//
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/XR_MNDX_force_feedback_curl.adoc[]
+
+*Last Modified Date*::
+    2022-11-18
+
+*IP Status*::
+    No known IP claims.
+
+*Contributors*::
+    Daniel Willmott +
+    Moses Turner (Collabora, Ltd.) +
+    Christoph Haagch (Collabora, Ltd.) +
+    Jakob Bornecrantz (Collabora, Ltd.) +
+
+
+*Overview*
+
+This extension provides APIs for force feedback devices capable of
+restricting physical movement in a single direction along a single
+dimension.
+
+The intended use for this extension is to provide simple force feedback
+capabilities to restrict finger movement for VR Gloves.
+
+The application must: also enable the `<<XR_EXT_hand_tracking>>` extension
+in order to use this extension.
+
+[open,refpage='XrForceFeedbackCurlLocationMNDX',type='enums',desc='Describes which location to apply force feedback',xrefs='']
+--
+The elink:XrForceFeedbackCurlLocationMNDX describes which location to apply
+force feedback.
+
+include::{generated}/api/enums/XrForceFeedbackCurlLocationMNDX.txt[]
+
+include::{generated}/api/enums/XrForceFeedbackCurlLocationMNDX.comments-box.txt[]
+--
+
+*New Object Types*
+
+*New Flag Types*
+
+*New Enum Constants*
+
+elink:XrStructureType enumeration is extended with:
+
+* ename:XR_TYPE_SYSTEM_FORCE_FEEDBACK_CURL_PROPERTIES_MNDX
+* ename:XR_TYPE_FORCE_FEEDBACK_CURL_APPLY_LOCATIONS_MNDX
+
+*New Enums*
+
+* elink:XrForceFeedbackCurlLocationMNDX
+
+*New Structures*
+
+[open,refpage='XrSystemForceFeedbackCurlPropertiesMNDX',type='structs',desc='System property for force feedback curl',xrefs='XrSystemProperties xrGetSystemProperties']
+--
+
+The slink:XrSystemForceFeedbackCurlPropertiesMNDX structure is defined as:
+
+include::{generated}/api/structs/XrSystemForceFeedbackCurlPropertiesMNDX.txt[]
+
+.Member Descriptions
+****
+* pname:type is the elink:XrStructureType of this structure.
+* pname:next is code:NULL or a pointer to the next structure in a structure
+  chain.
+* pname:supportsForceFeedbackCurl is an basetype:XrBool32, indicating if the
+  current system is capable of performing force feedback.
+****
+
+An application may: inspect whether the system is capable of force feedback
+by chaining an slink:XrSystemForceFeedbackCurlPropertiesMNDX structure to
+the slink:XrSystemProperties structure when calling
+flink:xrGetSystemProperties.
+
+The runtime should: return ename:XR_TRUE for pname:supportsForceFeedback
+when force feedback is available in the system, otherwise ename:XR_FALSE.
+Force feedback calls must: return ename:XR_ERROR_FEATURE_UNSUPPORTED if
+force feedback is not available in the system.
+
+include::{generated}/validity/structs/XrSystemForceFeedbackCurlPropertiesMNDX.txt[]
+--
+
+[open,refpage='XrForceFeedbackCurlApplyLocationsMNDX',type='structs',desc='Structure representing an array of locations to apply force feedback to',xrefs='xrApplyForceFeedbackCurlMNDX']
+--
+The slink:XrForceFeedbackCurlApplyLocationsMNDX structure is defined as:
+
+include::{generated}/api/structs/XrForceFeedbackCurlApplyLocationsMNDX.txt[]
+
+.Member Descriptions
+****
+* pname:type is the elink:XrStructureType of this structure.
+* pname:next is code:NULL or a pointer to the next structure in a structure
+  chain.
+  No such structures are defined in core OpenXR or this extension.
+* pname:locationCount is the number of elements in the pname:locations
+  array.
+* pname:locations is a pointer to an array of locations to apply force
+  feedback.
+****
+
+Contains an array of slink:XrForceFeedbackCurlApplyLocationMNDX that
+contains information on locations to apply force feedback to.
+
+include::{generated}/validity/structs/XrForceFeedbackCurlApplyLocationsMNDX.txt[]
+--
+
+[open,refpage='XrForceFeedbackCurlApplyLocationMNDX',type='structs',desc='Structure representing and containing information on how to apply force feedback to a single location.',xrefs='xrApplyForceFeedbackCurlMNDX']
+--
+The slink:XrForceFeedbackCurlApplyLocationMNDX structure is defined as:
+
+include::{generated}/api/structs/XrForceFeedbackCurlApplyLocationMNDX.txt[]
+
+.Member Descriptions
+****
+* pname:location represents the location to apply force feedback to.
+* pname:value is a value from 0-1 representing the amount of force feedback
+  to apply.
+  The range of the value should represent the entire range the location is
+  capable of moving through, with 1 representing making the location
+  incapable of movement, and 0 being fully flexible.
+  For example, in the case of a finger curl, setting pname:value to 1 would
+  prevent the finger from curling at all (fully extended), and 0 would allow
+  the finger to have free range of movement, being able to curl fully.
+****
+
+pname:value is specified as a limit in a single direction.
+For example, if the value specified is 0.5, a location must: have free
+movement from the point where it would be incapable of movement if
+pname:value was 1, to 0.5 of the range the location is capable of moving.
+
+include::{generated}/validity/structs/XrForceFeedbackCurlApplyLocationMNDX.txt[]
+--
+
+*New Functions*
+
+[open,refpage='xrApplyForceFeedbackCurlMNDX',desc='Applies force feedback to a set of locations',type='protos',xrefs='']
+--
+The flink:xrApplyForceFeedbackCurlMNDX function is defined as:
+
+include::{generated}/api/protos/xrApplyForceFeedbackCurlMNDX.txt[]
+
+.Parameter Descriptions
+****
+* pname:handTracker is an slink:XrHandTrackerEXT handle previously created
+  with flink:xrCreateHandTrackerEXT.
+* pname:locations is an slink:XrForceFeedbackCurlApplyLocationsMNDX
+  containing a set of locations to apply force feedback to.
+****
+
+The flink:xrApplyForceFeedbackCurlMNDX function applies force feedback to
+the set locations listed in slink:XrForceFeedbackCurlApplyLocationsMNDX.
+
+flink:xrApplyForceFeedbackCurlMNDX should: be called every time an
+application wishes to update a set of force feedback locations.
+
+Submits a request for force feedback for a set of locations.
+The runtime should: deliver this request to the pname:handTracker device.
+If the pname:handTracker device is not available, the runtime may: ignore
+this request for force feedback.
+
+If the session associated with pname:handTracker is not focused, the runtime
+must: return ename:XR_SESSION_NOT_FOCUSED, and not apply force feedback.
+
+When an application submits force feedback for a set of locations, the
+runtime must: update the set of locations to that specified by the
+application.
+A runtime must: set any locations not specified by the application when
+submitting force feedback to 0.
+
+The runtime may: discontinue force feedback if the application that set it
+loses focus.
+An application should: call the function again after regaining focus if
+force feedback is still desired.
+
+include::{generated}/validity/protos/xrApplyForceFeedbackCurlMNDX.txt[]
+--
+
+*Issues*
+
+*Version History*
+
+* Revision 1, 2022-09-07 (Daniel Willmott)
+** Initial version