Refactor getDevices into requestDevice

explainer.md

@@ -42,43 +42,36 @@ VR provides an interesting canvas for artists looking to explore the possibiliti
 
 The basic steps any WebVR application will go through are:
 
- 1. Request a list of the available VR devices.
- 2. Checks to see if the desired device supports the presentation modes the application needs.
- 3. If so, application advertises VR functionality to the user.
- 4. User performs an action that indicates they want to enter VR mode.
- 5. Request a VR session to present VR content with.
- 6. Begin a render loop that produces graphical frames to be displayed on the VR device.
- 7. Continue producing frames until the user indicates that they wish to exit VR mode.
- 8. End the VR session.
+ 1. Request a VR device that supports the presentation modes the application needs.
+ 1. If a device is available, application advertises VR functionality to the user.
+ 1. User performs an action that indicates they want to enter VR mode.
+ 1. Request a VR session from the device to present VR content with.
+ 1. Begin a render loop that produces graphical frames to be displayed on the VR device.
+ 1. Continue producing frames until the user indicates that they wish to exit VR mode.
+ 1. End the VR session.
 
-### Device enumeration
+### Acquiring a Device
 
-The first thing that any VR-enabled page will want to do is enumerate the available VR hardware and, if present, advertise VR functionality to the user.
+The first thing that any VR-enabled page will want to do is request a `VRDevice` and, if present, advertise VR functionality to the user.
 
-`navigator.vr.getDevices` returns a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves to a list of available devices. Each `VRDevice` represents a physical unit of VR hardware that can present imagery to the user somehow, referred to here as a "VR hardware 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 or Samsung Gear VR). It may also represent devices without stereo presentation capabilities but more advanced tracking, such as Tango devices.
+`navigator.vr.requestDevice` returns a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves to a `VRDevice` if one is available. A `VRDevice` represents a physical unit of VR hardware that can present imagery to the user somehow, referred to here as a "VR hardware 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 or Samsung Gear VR). It may also represent devices without stereo presentation capabilities but more advanced tracking, such as ARCore/ARKit enabled devices.
 
 ```js
-let vrDevice = null;
-
-navigator.vr.getDevices().then(devices => {
-  if (devices.length > 0) {
-    // Use the first device in the array if one is available. If multiple
-    // devices are present, you may want to provide the user a way of choosing
-    // which device to use.
-    vrDevice = devices[0];
-    onVRAvailable();
-  } else {
-    // Could not find any VR hardware connected.
-  }
-}, err => {
-  // An error occurred querying VR hardware. May be the result of blocked
-  // permissions by a parent frame.
+navigator.vr.requestDevice().then(device => {
+  onVRAvailable(device);
+}, (err) => {
+  // Could not find any available VR hardware or an error occurred querying VR
+  // hardware.
 });
 ```
 
+If there are multiple VR hardware devices available the UA will need to pick which one to return. The UA is allowed to use any criteria it wishes to select which device is returned, including settings UI that allows users to manage device priority. Calling `requestDevice` should not trigger device selection UI, however, as this would cause many sites to display VR-specific dialogs early in the page lifetime when the user has not made any indication that they wish to use VR features.
+
+Future iterations of the API may add filter criteria to `requestDevice`.
+
 ### Sessions
 
-A `VRDevice` indicates the presence of a VR hardware device but provides very little information about it outside of a name that could be used to select it from a list. In order to do anything that involves the hardware's presentation or tracking capabilities the application will need to request a `VRSession` from the `VRDevice`.
+A `VRDevice` indicates the presence of a VR hardware device but provides very little information about it. In order to do anything that involves the hardware's presentation or tracking capabilities the application will need to request a `VRSession` from the `VRDevice`.
 
 Sessions can be created with one of two levels of access:
 
@@ -93,7 +86,11 @@ If a `VRDevice` is available and able to create an exclusive session, the applic
 In the following examples we will focus on using exclusive sessions, and cover non-exclusive session use in the [`Advanced Functionality`](#non-exclusive-sessions-magic-windows) section. With that in mind, we ask here if the `VRDevice` supports sessions with `exclusive` access (the default), since we want the ability to display imagery on the headset.
 
 ```js
-async function onVRAvailable() {
+let vrDevice = null;
+
+async function onVRAvailable(device) {
+  vrDevice = device;
+
   // Most (but not all) VRDevices are capable of granting exclusive access to
   // the device, which is necessary to show imagery in a headset. If the device
   // has that capability the page will want to add an "Enter VR" button (similar
@@ -623,18 +620,15 @@ partial interface Navigator {
 };
 
 [SecureContext, Exposed=Window] interface VR : EventTarget {
-  attribute EventHandler ondeviceconnect;
-  attribute EventHandler ondevicedisconnect;
-
-  Promise<sequence<VRDevice>> getDevices();
+  attribute EventHandler ondevicechanged;
+  Promise<VRDevice> requestDevice();
 };
 
 //
 // Device
 //
 
 [SecureContext, Exposed=Window] interface VRDevice : EventTarget {
-  readonly attribute DOMString deviceName;
   readonly attribute boolean isExternal;
 
   Promise<void> supportsSession(optional VRSessionCreationOptions parameters);