Spec text for required and optional features (#749)

toji · web-flow · commit a09b874cbf81 · 2019-07-03T13:51:21.000-07:00
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.
diff --git a/explainer.md b/explainer.md
@@ -456,9 +456,11 @@ function onSessionStarted(session) {
 ```
 
 Some features recognized by the UA but not explicitly listed in these arrays will be enabled by default for a session. This is only done if the feature does not require a signal of [user intent](privacy-security-explainer.md#user-intent) nor impact performance or the behavior of other features when enabled. At this time, only the following features will be enabled by default:
+
 | Feature | Circumstances |
 | ------ | ------- |
-| `local` | Successfully created session of mode `immersive-ar` or `immersive-vr` |
+| `viewer` | Requested `XRSessionMode` is `inline`, `immersive-vr`, or `immersive-ar` |
+| `local` | Requested `XRSessionMode` is `immersive-vr` or `immersive-ar` |
 
 ### Controlling rendering quality
 
diff --git a/index.bs b/index.bs
@@ -227,7 +227,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;
@@ -311,7 +311,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.
@@ -337,6 +337,11 @@ When the <dfn method for="XR">requestSession(|mode|)</dfn> method is invoked, th
             1. Abort these steps.
         1. Let |session| be a new {{XRSession}} object.
         1. [=Initialize the session=] with |session|, |mode|, and |device|.
+        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. Potentially set the [=active immersive session=] based on the following:
             <dl class="switch">
               <dt> If |immersive| is <code>true</code>
@@ -384,6 +389,83 @@ 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.
 
+Feature Dependencies {#feature-dependencies}
+--------------------
+
+Some features of an {{XRSession}} may not be universally available for a number of reasons, among which is the fact not all XR devices can support the full set of features. Another consideration is that some features expose [=sensitive information=] which may require a clear signal of [=user intent=] before functioning.
+
+Since it is a poor user experience to to initialize the underlying XR platform and create an {{XRSession}} only to immediately notify the user that the applications cannot function correctly, developers can indicate <dfn>required features</dfn> by passing an {{XRSessionInit}} dictionary to {{XR/requestSession()}}. This will block the creation of the {{XRSession}} if any of the [=required features=] are unavailable due to device limitations or in the absense of a clear signal of [=user intent=] to expose [=sensitive information=] related to the feature.
+
+Additionally, developers are encouraged to design experiences which progressively enhance their functionality when run one more capable devices. <dfn>Optional features</dfn> which the experience does not require but will take advantage of when available must also be indicated in an {{XRSessionInit}} dictionary to ensure that [=user intent=] can be determined before enabling the feature if necessary.
+
+<pre class="idl">
+dictionary XRSessionInit {
+  sequence&lt;DOMString&gt; requiredFeatures;
+  sequence&lt;DOMString&gt; optionalFeatures;
+};
+</pre>
+
+The <dfn dict-member for="XRSessionInit">requiredFeatures</dfn> array contains any [=Required features=] for the experience. If any value in the list is not a recognized [=feature name=] the {{XRSession}} will not be created. If any feature listed in the {{XRSessionInit/requiredFeatures}} array is not supported by the [=XRSession/XR Device=] or, if necessary, has not received a clear signal of [=user intent=] the {{XRSession}} will not be created.
+
+The <dfn dict-member for="XRSessionInit">optionalFeatures</dfn> array contains any [=Optional features=] for the experience. 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, given a clear signal of [=user intent=], 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 enable certain [=feature names=] as [=optional features=] by default. This is only done if the feature does not require a signal of [=user intent=] nor impact performance or the behavior of other features when enabled. The following table describes 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/"viewer"}}</td>
+      <td>{{XRSessionMode/"inline"}}, {{XRSessionMode/"immersive-vr"}}, {{XRSessionMode/"immersive-ar"}}</td>
+    </tr>
+    <tr>
+      <td>{{XRReferenceSpaceType/"local"}}</td>
+      <td>{{XRSessionMode/"immersive-vr"}}, {{XRSessionMode/"immersive-ar"}}</td>
+    </tr>
+  </tbody>
+</table>
+
+ISSUE(immersive-web/webxr#757): Define <dfn>sensitive information</dfn>, what qualifies as a signal of <dfn>user intent</dfn>, when <dfn>explicit consent</dfn> is necessary and how user agents can request it.
+
+<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 valid [=feature name=], return <code>false</code>.
+    1. If the functionality described by |feature| is not supported by |session|'s [=XRSession/XR Device=] or the user agent has otherwise determined to reject the feature, return <code>false</code>.
+    1. If the functionality described by |feature| requires [=explicit 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 valid [=feature name=], continue to the next entry.
+    1. If the functionality described by |feature| is not supported by |session|'s [=XRSession/XR Device=] or the user agent has otherwise determined to reject the feature, continue to the next entry.
+    1. If the functionality described by |feature| requires [=explicit 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=] or the user agent has otherwise determined to reject the feature, continue to the next entry.
+    1. Else append |feature| to |session|'s [=list of enabled features=].
+  1. If |consentRequired| or |consentOptional| are not empty, request [=explicit consent=] to use the functionality described by those features.
+  1. For each |feature| in |consentRequired| perform the following steps:
+    1. If a clear signal of [=user intent=] to enable |feature| has not been given, return <code>false</code>.
+    1. Else append |feature| to |session|'s [=list of enabled features=].
+  1. For each |feature| in |consentOptional| perform the following steps:
+    1. If a clear signal of [=user intent=] to enable |feature| has not been given, continue to the next entry.
+    1. Else append |feature| to |session|'s [=list of enabled features=].
+  1. Return <code>true</code>
+
+</div>
 
 Session {#session}
 =======
@@ -478,6 +560,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=].
@@ -968,6 +1052,7 @@ When an {{XRReferenceSpace}} is requested, the user agent MUST <dfn>create a ref
 <div class="algorithm" data-algorithm="reference-space-supported">
 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 not [=list/contain|contained=] in |session|'s [=list of enabled features=] return <code>false</code>.
   1. If |type| is {{viewer}}, return <code>true</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>.
diff --git a/spatial-tracking-explainer.md b/spatial-tracking-explainer.md
@@ -324,9 +324,9 @@ function onSessionStarted(session) {
   xrSession.requestReferenceSpace('bounded-floor').then((referenceSpace) => {
     xrReferenceSpace = referenceSpace;
   }).catch(() => {
-    // If a bounded-floor reference space isn't available, request a local-floor 
+    // If a bounded-floor reference space isn't available, request a local
     // reference space as a fallback and adjust the experience as necessary.
-    return xrSession.requestReferenceSpace('local-floor').then((referenceSpace) => {
+    return xrSession.requestReferenceSpace('local').then((referenceSpace) => {
       xrReferenceSpace = referenceSpace;
     });
   })
