Spec text for required and optional features

This is the corresponding spec text for the functionality described in PR #739. There's some hand waving going on around user consent and such because those will be better defined in a follow-up PR. The primary goal of this PR is to establish the algorithims that drive how the feature requests are processed.
immersive-web · Jul 2, 2019 · f4da3f6 · f4da3f6
1 parent 1b6a4c2
commit f4da3f6
Showing 1 changed file with 81 additions and 2 deletions.
diff --git a/index.bs b/index.bs
@@ -231,7 +231,7 @@ XR {#xr-interface}
 [SecureContext, Exposed=Window] interface XR : EventTarget {
   // Methods
   Promise&lt;void&gt; supportsSession(XRSessionMode mode);
-  Promise&lt;XRSession&gt; requestSession(XRSessionMode mode);
+  Promise&lt;XRSession&gt; requestSession(XRSessionMode mode, optional XRSessionInit options);
 
   // Events
   attribute EventHandler ondevicechange;
@@ -315,7 +315,7 @@ The {{XR}} object has a <dfn>pending immersive session</dfn> boolean, which MUST
 
 <div class="algorithm" data-algorithm="request-session">
 
-When the <dfn method for="XR">requestSession(|mode|)</dfn> method is invoked, the user agent MUST run the following steps:
+When the <dfn method for="XR">requestSession(|mode|, |options|)</dfn> method is invoked, the user agent MUST run the following steps:
 
   1. Let |promise| be [=a new Promise=].
   1. Let |immersive| be <code>true</code> if |mode| is {{XRSessionMode/"immersive-vr"}} or {{XRSessionMode/"immersive-ar"}}, and <code>false</code> otherwise.
@@ -340,6 +340,11 @@ When the <dfn method for="XR">requestSession(|mode|)</dfn> method is invoked, th
             1. If |immersive| is <code>true</code>, set [=pending immersive session=] to <code>false</code>.
             1. Abort these steps.
         1. Let |session| be a new {{XRSession}} object.
+        1. [=Resolve the requested features=] given by |options|' {{XRSessionInit/requiredFeatures}} and |options|' {{XRSessionInit/optionalFeatures}} values for |session|, and let |resolved| be the returned value.
+        1. If |resolved| is <code>false</code>, run the following steps:
+            1. [=Reject=] |promise| with a "{{NotSupportedError}}" {{DOMException}}.
+            1. If |immersive| is <code>true</code>, set [=pending immersive session=] to <code>false</code>.
+            1. Abort these steps.
         1. [=Initialize the session=] with |session|, |mode|, and |device|.
         1. Potentially set the [=active immersive session=] based on the following:
             <dl class="switch">
@@ -388,6 +393,77 @@ NOTE: Examples of ways [=exclusive access=] may be presented include stereo cont
 
 NOTE: As an example of overlaid UI, the user-agent or operating system in an [=immersive session=] may show notifications over the rendered content. Similarly, in {{immersive-ar}} mode the user-agent or operating system may overlay mandatory "home" and navigational buttons over the user's wrist.
 
+Session Features {#session-features}
+----------------
+
+Some features of {{XRSession}} may require the user's consent to access, and will be inaccessable by default unless the features are explicitly requested when calling {{XR/requestSession()}}. These features are passed via {{XRSessionInit}} object.
+
+<pre class="idl">
+dictionary XRSessionInit {
+  sequence&lt;DOMString&gt; requiredFeatures;
+  sequence&lt;DOMString&gt; optionalFeatures;
+};
+</pre>
+
+Requested features are split into two groups:
+
+ - Required features are passed by via the <dfn dict-member for="XRSessionInit">requiredFeatures</dfn> array. If any value in the list is not a recognized [=feature name=] the {{XRSession}} will not be created. All features listed in the {{XRSessionInit/requiredFeatures}} array MUST be supported by the [=XRSession/XR Device=] and, if necessary, consented to by the user or the {{XRSession}} will not be created.
+ - Optional features are passed via the <dfn dict-member for="XRSessionInit">optionalFeatures</dfn> array. If any value in the list is not a recognized [=feature name=] it will be ignored. Features listed in the {{XRSessionInit/optionalFeatures}} array will be enabled if supported by the [=XRSession/XR Device=] and, if necessary, consented to by the user, but will not block creation of the {{XRSession}} if absent. 
+
+The feature lists accept any string. However, in order to be a considered a valid <dfn>feature name</dfn>, the string must be a value from the following enums:
+
+ - {{XRReferenceSpaceType}}
+
+Some {{XRSessionMode}}s request certain [=feature names=] as optional features by default. The following table described the <dfn>default features</dfn> associated with each {{XRSessionMode}}:
+
+<table class="tg">
+  <thead>
+    <tr>
+      <th>Feature</th>
+      <th>{{XRSessionMode}}</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>{{XRReferenceSpaceType/"local"}}</td>
+      <td>{{XRSessionMode/"immersive-vr"}}</td>
+    </tr>
+  </tbody>
+</table>
+
+ISSUE: Define what it means when a feature <dfn>requires consent</dfn>, how user agents can <dfn>request user consent</dfn>, and what it means when a user <dfn>denied consent</dfn>.
+
+<div class="algorithm" data-algorithm="resolve-features">
+
+To <dfn>resolve the requested features</dfn> given |requiredFeatures| and |optionalFeatures| for an {{XRSession}} |session|, the user agent MUST run the following steps:
+
+  1. Let |consentRequired| be an empty [=/list=] of {{DOMString}}.
+  1. Let |consentOptional| be an empty [=/list=] of {{DOMString}}.
+  1. For each |feature| in |requiredFeatures| perform the following steps:
+    1. If |feature| is not a value in the {{XRReferenceSpaceType}} enum, return <code>false</code>.
+    1. If the functionality described by |feature| is not supported by |session|'s [=XRSession/XR Device=], return <code>false</code>.
+    1. If the functionality described by |feature| [=requires consent=], append it to |consentRequired|.
+    1. Else append |feature| to |session|'s [=list of enabled features=].
+  1. For each |feature| in |optionalFeatures| perform the following steps:
+    1. If |feature| is not a value in the {{XRReferenceSpaceType}} enum, continue to the next entry.
+    1. If the functionality described by |feature| is not supported by |session|'s [=XRSession/XR Device=], continue to the next entry.
+    1. If the functionality described by |feature| [=requires consent=], append it to |consentOptional|.
+    1. Else append |feature| to |session|'s [=list of enabled features=].
+  1. For each |feature| in the [=default features=] table perform the following steps:
+    1. If |session|'s [=XRSession/mode=] is not one of the modes associated with |feature| in the [=default features=], continue to the next entry.
+    1. If the functionality described by |feature| is not supported by |session|'s [=XRSession/XR Device=], continue to the next entry.
+    1. If the functionality described by |feature| [=requires consent=], append it to |consentOptional|.
+    1. Else append |feature| to |session|'s [=list of enabled features=].
+  1. If |consentRequired| or |consentOptional| are not empty, [=request user consent=] to use the functionality described by those features.
+  1. For each |feature| in |requiredFeatures| perform the following steps:
+    1. If the user [=denied consent=] to use |feature|, return <code>false</code>.
+    1. Else append |feature| to |session|'s [=list of enabled features=].
+  1. For each |feature| in |requiredFeatures| perform the following steps:
+    1. If the user [=denied consent=] to use |feature|, continue to the next entry.
+    1. Else append |feature| to |session|'s [=list of enabled features=].
+  1. Return <code>true</code>
+
+</div>
 
 Session {#session}
 =======
@@ -482,6 +558,8 @@ The <dfn method for="XRSession">end()</dfn> method provides a way to manually sh
 
 </div>
 
+Each {{XRSession}} has a <dfn for="XRSession">list of enabled features</dfn>, which is a [=/list=] of [=feature names=] which MUST be initially an empty [=/list=]
+
 Each {{XRSession}} has an <dfn>active render state</dfn> which is a new {{XRRenderState}}, and a <dfn>pending render state</dfn>, which is an {{XRRenderState}} which is initially <code>null</code>.
 
 The <dfn attribute for="XRSession">renderState</dfn> attribute returns the {{XRSession}}'s [=active render state=].
@@ -973,6 +1051,7 @@ When an {{XRReferenceSpace}} is requested, the user agent MUST <dfn>create a ref
 To check if a <dfn>reference space is supported</dfn> for a given reference space type |type| and {{XRSession}} |session|, run the following steps:
 
   1. If |type| is {{viewer}}, return <code>true</code>.
+  1. If |type| is not [=list/contain|contained=] in |session|'s [=list of enabled features=] return <code>false</code>.
   1. If |type| is {{local}} or {{local-floor}}, and |session| is an [=immersive session=], return <code>true</code>.
   1. If |type| is {{local}} or {{local-floor}}, and the [=XRSession/XR device=] supports reporting orientation data, return <code>true</code>.
   1. If |type| is {{bounded-floor}} and |session| is an [=immersive session=], return if [=bounded reference spaces are supported=] by the [=XRSession/XR device=].