Skip to content

Commit

Permalink
Change supportsSession promise to return void (#259)
Browse files Browse the repository at this point in the history
This lets us focus on the simple behavior of resolve/reject being the
signal for support and allows us to extend the promise to return more
information in the future if needed.
  • Loading branch information
toji authored Jul 21, 2017
1 parent 814f429 commit 0cea0c1
Showing 1 changed file with 7 additions and 6 deletions.
13 changes: 7 additions & 6 deletions explainer.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ Sessions can be created with one of two levels of access:

### Detecting and advertising VR mode

If a `VRDevice` is available and able to create an exclusive session, the application will usually want to add some UI to trigger activation of "VR Presentation Mode", where the application can begin sending imagery to the device. Testing to see if the device supports the capabilities the application needs is done via the `supportsSession` call, which takes a dictionary of the desired functionality and returns whether or not the device can create a session supporting them. Querying for support this way is necessary because it allows the application to detect what VR features are available without actually engaging the sensors or beginning presentation, which can incur significant power or performance overhead on some systems and may have side effects such as launching a VR status tray or storefront.
If a `VRDevice` is available and able to create an exclusive session, the application will usually want to add some UI to trigger activation of "VR Presentation Mode", where the application can begin sending imagery to the device. Testing to see if the device supports the capabilities the application needs is done via the `supportsSession` call, which takes a dictionary of the desired functionality and returns a promise which resolves if the device can create a session which supporting those properties and rejects otherwise. Querying for support this way is necessary because it allows the application to detect what VR features are available without actually engaging the sensors or beginning presentation, which can incur significant power or performance overhead on some systems and may have side effects such as launching a VR status tray or storefront.

In the following example we ask if the `VRDevice` supports sessions with `exclusive` access, since we want the ability to display imagery on the headset.

Expand All @@ -99,19 +99,20 @@ async function OnVRAvailable() {
// has that capability the page will want to add an "Enter VR" button (similar
// to "Enter Fullscreen") that triggers the page to begin showing imagery on
// the headset.
let exclusiveMode = await vrDevice.supportsSession({ exclusive: true });
if (exclusiveMode) {
vrDevice.supportsSession({ exclusive: true }).then(() => {
var enterVrBtn = document.createElement("button");
enterVrBtn.innerHTML = "Enter VR";
enterVrBtn.addEventListener("click", BeginVRSession);
document.body.appendChild(enterVrBtn);
}
}).catch((reason) => {
console.log("Session not supported: " + reason);
});
}
```

### Beginning a VR session

Clicking the "Enter VR" button in the previous sample will attempt to acquire a `VRSession` by callling `VRDisplay.requestSession`. This returns a promise that resolves to a `VRSession` upon success. When requesting a session, the capabilities that the returned session must have are passed in via a dictionary, exactly like the `supportsSession` call. If `supportsSession` returned true for a given dictionary, then calling `requestSession` with the same dictionary values should be reasonably expected to succeed, barring external factors (such as `requestSession` not being called in a user gesture for an exclusive session.) The UA is ultimately responsible for determining if it can honor the request.
Clicking the "Enter VR" button in the previous sample will attempt to acquire a `VRSession` by callling `VRDisplay.requestSession`. This returns a promise that resolves to a `VRSession` upon success. When requesting a session, the capabilities that the returned session must have are passed in via a dictionary, exactly like the `supportsSession` call. If `supportsSession` resolved for a given dictionary, then calling `requestSession` with the same dictionary values should be reasonably expected to succeed, barring external factors (such as `requestSession` not being called in a user gesture for an exclusive session.) The UA is ultimately responsible for determining if it can honor the request.

```js
function BeginVRSession(isExclusive) {
Expand Down Expand Up @@ -593,7 +594,7 @@ interface VRDevice : EventTarget {
attribute EventHandler onactivate;
attribute EventHandler ondeactivate;

Promise<boolean> supportsSession(optional VRSessionCreateParametersInit parameters);
Promise<void> supportsSession(optional VRSessionCreateParametersInit parameters);
Promise<VRSession> requestSession(optional VRSessionCreateParametersInit parameters);
};

Expand Down

0 comments on commit 0cea0c1

Please sign in to comment.