Add XRInteractionSpace

Author: Manishearth

ar-module-explainer.md

@@ -68,6 +68,39 @@ function drawScene() {
 }
 ```
 
+### Drawing UI elements
+
+The AR module supports a variety of device form factors, including "handheld" phone AR as well as "headworn" glasses-style AR. If the application wishes to show UI elements to the user, it needs to be done differently based on the form factor. This information is exposed through `XRSession`'s `interactionSpace` attribute.
+
+For handheld devices, the UI elements probably should be drawn directly to the screen in screen-space coordinates, without applying any projections. In such a case, `interactionSpace` will report `"screen-space"`.
+ 
+For headworn devices, the UI elements probably should be drawn in the world space, perhaps at some distance from the user's head so that they may easily interact with it. In such a case, `interactionSpace` will report `"world-space"`.
+
+The <a href="https://immersive-web.github.io/dom-overlays/">WebXR DOM Overlays module</a>, if implemented for the device, is able to automatically place UI for both handheld and headworn sessions. However, it is only useful if you wish to do your UI as DOM elements as opposed to 
+
+```js
+function drawScene() {
+  // draw the rest of the scene
+
+  if (xrSession.interactionSpace == "world-space") {
+    // Add UI elements to actual scene
+  } else {
+    // Draw UI elements directly to screen
+  }
+}
+
+xrSession.onselect = function(e) {
+  if (xrSession.interactionSpace == "world-space") {
+    // intersect the target ray with the UI elements in world space
+    // to determine which UI element, if any, was selected
+  } else {
+    // determine the screen-space coordinates of the select event and
+    // see which UI element, if any, was selected
+  }
+}
+
+```
+
 ## Appendix B: Proposed IDL
 
 ```webidl
@@ -87,7 +120,13 @@ enum XREnvironmentBlendMode {
   "alpha-blend",
 };
 
+enum XRInteractionSpace {
+    "screen-space",
+    "world-space",
+};
+
 partial interface XRSession {
   readonly attribute XREnvironmentBlendMode environmentBlendMode;
+  readonly attribute XRInteractionSpace interactionSpace;
 }
 ```

index.bs

@@ -165,6 +165,7 @@ navigator.xr.requestSession("immersive-ar").then((session) => {
 </pre>
 </div>
 
+
 XREnvironmentBlendMode {#xrenvironmentblendmode-enum}
 ----------------------
 When drawing XR content, it is often useful to understand how the rendered pixels will be blended by the [=XR Compositor=] with the [=real-world environment=].
@@ -190,6 +191,33 @@ The <dfn attribute for="XRSession">environmentBlendMode</dfn> attribute MUST rep
 
 - A blend mode of <dfn enum-value for="XREnvironmentBlendMode">additive</dfn> MUST be reported if the [=XR Compositor=] is using [=additive environment blending=].
 
+
+
+XRInteractionSpace {#xrinteractionspace-enum}
+----------------------
+
+Sometimes the application will wish to draw UI that the user may interact with. WebXR allows for a variety of form factors, including both handheld phone AR and head-worn AR. For different form factors, the UIs will belong in different spaces to facilitate smooth interaction, for example the UI for handheld phone AR will likely be drawn directly on the screen without projection, but the UI for headworn AR will likely be drawn a small distance from the head so that users may use their controllers to interact with it.
+
+<pre class="idl">
+enum XRInteractionSpace {
+    "screen-space",
+    "world-space",
+};
+
+partial interface XRSession {
+  // Attributes
+  readonly attribute XRInteractionSpace interactionSpace;
+};
+</pre>
+
+The <dfn attribute for="XRSession">interactionSpace</dfn> attribute describes the best space (according to the user agent) for the application to draw interactive UI for the current session.
+
+ - An {{XRSession/interactionSpace}} value of {{XRInteractionSpace/"screen-space"}} indicates that the UI should be drawn directly to the screen without projection. Typically in this scenario, {{select!!event}} events are triggered with {{XRInputSourceEvent/inputSource}}s having an {{XRInputSource/targetRayMode}} of {{XRTargetRayMode/"screen"}}.
+
+ - An {{XRSession/interactionSpace}} value of {{XRInteractionSpace/"world-space"}} indicates that the UI should be drawn in the world, some distance from the user, so that they may interact with it using controllers. Typically in this scenario, {{select!!event}} events are triggered with {{XRInputSourceEvent/inputSource}}s having an {{XRInputSource/targetRayMode}} of {{XRTargetRayMode/"tracked-pointer"}} or {{XRTargetRayMode/"gaze"}}.
+
+Note: The <a href="https://immersive-web.github.io/dom-overlays/">WebXR DOM Overlays module</a>, if supported, can be used in some of these cases instead.
+
 XR Compositor Behaviors {#xr-compositor-behaviors}
 ---------------------