Remove XRSessionCreationOptions

toji · toji · commit 8f38f0439bc2 · 2019-04-16T13:43:13.000-07:00
As described in #542, this switches `requestSession` to a "primary type + options bag" pattern. However, since the dictionary only had a single key after outputContext was moved this change ends up removing the XRSessionCreationOptions dictionary entirely in favor of just passing in the type enum directly. In the future if additional options *are* needed for `requestSession`, the expected pattern would be: ``` navigator.xr.requestSession('immersive-vr', { option: value }); ```
diff --git a/explainer.md b/explainer.md
@@ -72,7 +72,7 @@ The basic steps most WebXR applications will go through are:
 
 The UA will identify an available physical unit of XR hardware that can present imagery to the user, referred to here as an "XR device". On desktop clients this will usually be a headset peripheral; on mobile clients it may represent the mobile device itself in conjunction with a viewer harness (e.g., Google Cardboard/Daydream or Samsung Gear VR). It may also represent devices without stereo-presentation capabilities but with more advanced tracking, such as ARCore/ARKit-compatible devices. Any queries for XR capabilities or functionality are implicitly made against this device.
 
-> **Non-normative Note:** If there are multiple XR devices available, the UA will need to pick which one to expose. The UA is allowed to use any criteria it wishes to select which device is used, including settings UI that allow users to manage device priority. Calling `navigator.xr.supportsSessionMode` or `navigator.xr.requestSession` with `{ mode: 'inline' }` should **not** trigger device-selection UI, however, as this would cause many sites to display XR-specific dialogs early in the document lifecycle without user activation.
+> **Non-normative Note:** If there are multiple XR devices available, the UA will need to pick which one to expose. The UA is allowed to use any criteria it wishes to select which device is used, including settings UI that allow users to manage device priority. Calling `navigator.xr.supportsSessionMode` or `navigator.xr.requestSession` with `'inline'` should **not** trigger device-selection UI, however, as this would cause many sites to display XR-specific dialogs early in the document lifecycle without user activation.
 
 It's possible that even if no XR device is available initially, one may become available while the application is running, or that a previously available device becomes unavailable. This will be most common with PC peripherals that can be connected or disconnected at any time. Pages can listen to the `devicechange` event emitted on `navigator.xr` to respond to changes in device availability after the page loads. (XR devices already available when the page loads will not cause a `devicechange` event to be fired.) `devicechange` fires an event of type `Event`.
 
@@ -127,7 +127,7 @@ After confirming that the desired mode is available with `navigator.xr.supportsS
 function beginXRSession() {
   // requestSession must be called within a user gesture event
   // like click or touch when requesting an immersive session.
-  navigator.xr.requestSession({mode: 'immersive-vr'})
+  navigator.xr.requestSession('immersive-vr')
       .then(onSessionStarted)
       .catch(err => {
         // May fail for a variety of reasons. Probably just want to
@@ -339,13 +339,13 @@ If the UA needs to halt use of a session temporarily, the session should be susp
 
 ## AR sessions
 
-If an XR-enabled page wants to display Augmented Reality content instead of Virtual Reality, it can create an AR session by passing `{mode: 'immersive-ar'}` into `requestSession`. 
+If an XR-enabled page wants to display Augmented Reality content instead of Virtual Reality, it can create an AR session by passing `'immersive-ar'` into `requestSession`. 
 
 ```js
 function beginXRSession() {
   // requestSession must be called within a user gesture event
   // like click or touch when requesting an immersive session.
-  navigator.xr.requestSession({mode: 'immersive-ar'})
+  navigator.xr.requestSession('immersive-ar')
       .then(onSessionStarted);
 }
 ```
@@ -387,7 +387,7 @@ function beginXRSession() {
   let mirrorCtx = mirrorCanvas.getContext('xrpresent');
   document.body.appendChild(mirrorCanvas);
 
-  navigator.xr.requestSession({ mode: 'immersive-vr' })
+  navigator.xr.requestSession('immersive-vr')
       .then((session) => {
         // A mirror context isn't required to render, so it's not necessary to
         // wait for the updateRenderState promise to resolve before continuing.
@@ -428,7 +428,7 @@ document.body.appendChild(inlineCanvas);
 
 function beginInlineXRSession() {
   // Request an inline session in order to render to the page.
-  navigator.xr.requestSession()
+  navigator.xr.requestSession('inline')
       .then((session) => {
         // Inline sessions must have an output context prior to rendering, so
         // it's a good idea to wait until the outputContext is confirmed to have
@@ -619,7 +619,7 @@ partial interface Navigator {
 [SecureContext, Exposed=Window] interface XR : EventTarget {
   attribute EventHandler ondevicechange;
   Promise<void> supportsSessionMode(XRSessionMode mode);
-  Promise<XRSession> requestSession(optional XRSessionCreationOptions parameters);
+  Promise<XRSession> requestSession(XRSessionMode mode);
 };
 
 //
@@ -632,10 +632,6 @@ enum XRSessionMode {
   "immersive-ar"
 }
 
-dictionary XRSessionCreationOptions {
-  XRSessionMode mode = "inline";
-};
-
 [SecureContext, Exposed=Window] interface XRSession : EventTarget {
   readonly attribute XRSessionMode mode;
   readonly attribute XREnvironmentBlendMode environmentBlendMode;
diff --git a/index.bs b/index.bs
@@ -212,7 +212,7 @@ XR {#xr-interface}
 [SecureContext, Exposed=Window] interface XR : EventTarget {
   // Methods
   Promise&lt;void&gt; supportsSessionMode(XRSessionMode mode);
-  Promise&lt;XRSession&gt; requestSession(optional XRSessionCreationOptions parameters);
+  Promise&lt;XRSession&gt; requestSession(XRSessionMode mode);
 
   // Events
   attribute EventHandler ondevicechange;
@@ -287,9 +287,8 @@ 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(|options|)</dfn> method is invoked, the user agent MUST return [=a new Promise=] |promise| and run the following steps [=in parallel=]:
+When the <dfn method for="XR">requestSession(|mode|)</dfn> method is invoked, the user agent MUST return [=a new Promise=] |promise| and run the following steps [=in parallel=]:
 
-  1. Let |mode| be the {{XRSessionCreationOptions/mode}} attribute of the |options| argument.
   1. Let |immersive| be a boolean set to <code>true</code> if |mode| is {{immersive-vr}} or {{immersive-ar}} and <code>false</code> otherwise.
   1. If |immersive| is <code>true</code>: 
     1. If [=pending immersive session=] is <code>true</code> or [=active immersive session=] is not <code>null</code>, [=reject=] |promise| with an {{InvalidStateError}} and abort these steps.
@@ -314,12 +313,34 @@ The following code attempts to retrieve an {{immersive-vr}} {{XRSession}}.
 <pre highlight="js">
 let xrSession;
 
-navigator.xr.requestSession({ mode: "immersive-vr" }).then((session) => {
+navigator.xr.requestSession("immersive-vr").then((session) => {
   xrSession = session;
 });
 </pre>
 </div>
 
+<section class="unstable">
+XRSessionMode {#xrsessionmode-enum}
+-------------------------
+
+The {{XRSessionMode}} enum defines the modes that an {{XRSession}} can operate in.
+
+<pre class="idl">
+enum XRSessionMode {
+  "inline",
+  "immersive-vr",
+  "immersive-ar"
+};
+</pre>
+
+  - A session mode of <dfn enum-value for="XRSessionMode">inline</dfn> indicates that the session's output will be shown as an element in the HTML document. {{inline}} session content MAY be displayed in mono or stereo and MAY allow for [=viewer=] tracking. User agents MUST allow {{inline}} sessions to be created for any [=/XR device=].
+  - A session mode of <dfn enum-value for="XRSessionMode">immersive-vr</dfn> indicates that the session's output will be given [=exclusive access=] to the [=/XR device=] display and that content <b>is not</b> intended to be integrated with the user's environment. The {{environmentBlendMode}} for {{immersive-vr}} sessions is expected to be {{opaque}} when possible, but MAY be {{additive}} if the hardware requires it.
+  - A session mode of <dfn enum-value for="XRSessionMode">immersive-ar</dfn> indicates that the session's output will be given [=exclusive access=] to the [=/XR device=] display and that content <b>is</b> intended to be integrated with the user's environment. The {{environmentBlendMode}} MUST NOT be {{opaque}} for {{immersive-ar}} sessions.
+
+An <dfn>immersive session</dfn> refers to either an {{immersive-vr}} or an {{immersive-ar}} session. [=Immersive sessions=] MUST provide some level of [=viewer=] tracking, and content MUST be shown at the proper scale relative to the user and/or the surrounding environment. Additionally, [=Immersive sessions=] MUST be given <dfn>exclusive access</dfn> to the [=/XR device=], meaning that while the [=immersive session=] is not [=blurred=] the HTML document is not shown on the [=/XR device=]'s display, nor is content from other applications shown on the [=/XR device=]'s display.
+
+NOTE: Examples of ways [=exclusive access=] may be presented include stereo content displayed on a virtual reality or augmented reality headset, or augmented reality content displayed fullscreen on a mobile device.
+</section>
 
 Session {#session}
 =======
@@ -504,42 +525,6 @@ We still need to document what happens when we <dfn>poll the device pose</dfn> (
 
 We still need to document how the<dfn>list of active input sources</dfn> is maintained. (This is <a href="https://github.com/immersive-web/webxr/issues/465">filed</a>.)
 
-<section class="unstable">
-XRSessionMode {#xrsessionmode-enum}
--------------------------
-
-The {{XRSessionMode}} enum defines the modes that an {{XRSession}} can operate in.
-
-<pre class="idl">
-enum XRSessionMode {
-  "inline",
-  "immersive-vr",
-  "immersive-ar"
-};
-</pre>
-
-  - A session mode of <dfn enum-value for="XRSessionMode">inline</dfn> indicates that the session's output will be shown as an element in the HTML document. {{inline}} session content MAY be displayed in mono or stereo and MAY allow for [=viewer=] tracking. User agents MUST allow {{inline}} sessions to be created for any [=/XR device=].
-  - A session mode of <dfn enum-value for="XRSessionMode">immersive-vr</dfn> indicates that the session's output will be given [=exclusive access=] to the [=/XR device=] display and that content <b>is not</b> intended to be integrated with the user's environment. The {{environmentBlendMode}} for {{immersive-vr}} sessions is expected to be {{opaque}} when possible, but MAY be {{additive}} if the hardware requires it.
-  - A session mode of <dfn enum-value for="XRSessionMode">immersive-ar</dfn> indicates that the session's output will be given [=exclusive access=] to the [=/XR device=] display and that content <b>is</b> intended to be integrated with the user's environment. The {{environmentBlendMode}} MUST NOT be {{opaque}} for {{immersive-ar}} sessions.
-
-An <dfn>immersive session</dfn> refers to either an {{immersive-vr}} or an {{immersive-ar}} session. [=Immersive sessions=] MUST provide some level of [=viewer=] tracking, and content MUST be shown at the proper scale relative to the user and/or the surrounding environment. Additionally, [=Immersive sessions=] MUST be given <dfn>exclusive access</dfn> to the [=/XR device=], meaning that while the [=immersive session=] is not [=blurred=] the HTML document is not shown on the [=/XR device=]'s display, nor is content from other applications shown on the [=/XR device=]'s display.
-
-NOTE: Examples of ways [=exclusive access=] may be presented include stereo content displayed on a virtual reality or augmented reality headset, or augmented reality content displayed fullscreen on a mobile device.
-</section>
-
-<section class="unstable">
-XRSessionCreationOptions {#xrsessioncreationoptions-interface}
--------------------------
-
-The {{XRSessionCreationOptions}} dictionary provides a <dfn>session description</dfn>, indicating the desired properties of a session to be returned from {{requestSession()}}.
-
-<pre class="idl">
-dictionary XRSessionCreationOptions {
-  XRSessionMode mode = "inline";
-};
-</pre>
-</section>
-
 XRRenderState {#xrrenderstate-interface}
 -------------
 
@@ -864,7 +849,7 @@ An {{XRUnboundedReferenceSpace}} represents a tracking space where the user is e
 <pre class="idl">
 [SecureContext, Exposed=Window] 
 interface XRUnboundedReferenceSpace : XRReferenceSpace {
-};  
+};
 </pre>
 
 Views {#views}
diff --git a/spatial-tracking-explainer.md b/spatial-tracking-explainer.md
@@ -318,18 +318,6 @@ function onSessionStarted(session) {
 }
 ```
 
-While many sites will be able to provide this fallback, for some sites this will not be possible.  Under these circumstances, it is instead preferable for session creation to reject rather than spin up immersive display/tracking systems only to immediately exit the session.
-
-```js
-function beginImmersiveSession() {
-  xrDevice.requestSession({ immersive: true,  requiredReferenceSpaceType:'unbounded' })
-      .then(onSessionStarted)
-      .catch(err => {
-        // Error will indicate required reference space type unavailable
-      });
-}
-```
-
 ### Floor Alignment
 Some XR hardware with inside-out tracking has users establish "known spaces" that can be used to easily provide `XRBoundedReferenceSpace` and the `floor-level` subtype of `XRStationaryReferenceSpace`.  On inside-out XR hardware which does not intrinsically provide these known spaces, the User Agent must still provide `XRStationaryReferenceSpace` of subtype `floor-level`.  It may do so by estimating a floor level, but may not present any UI at the time the reference space is requested.  
 
