From 35b70e1c3514a8129e04956651504ff67dbe187f Mon Sep 17 00:00:00 2001 From: Brandon Jones Date: Thu, 2 Feb 2017 10:55:22 -0800 Subject: [PATCH] Move WebVR functionality under navigator.vr This updates the VR interfaces to remove dependencies on the `window` object and enable use of the API in contexts other than the main page thread, such as workers. (Note that the WorkerNavigator interface and worker exposure meta tags will be added in a follow-up PR) --- index.bs | 156 ++++++++----- index.html | 640 +++++++++++++++++++++++++++++++++-------------------- 2 files changed, 510 insertions(+), 286 deletions(-) diff --git a/index.bs b/index.bs index ee3739a5..8de23d7a 100644 --- a/index.bs +++ b/index.bs @@ -169,6 +169,12 @@ interface VRDisplay : EventTarget { * created without preserveDrawingBuffer set to true will be cleared. */ void submitFrame(); + + attribute EventHandler onactivate; + attribute EventHandler ondeactivate; + attribute EventHandler onblur; + attribute EventHandler onfocus; + attribute EventHandler onpresentchange; }; @@ -215,6 +221,39 @@ Returns an array with the {{VRLayer}} currently being presented. MUST return an submitFrame() Captures the current state of the {{VRLayer}} currently being presented and displays it on the {{VRDisplay}}. It is assumed that the frame was rendered using the {{VRPose}} and matrices provided by the last call to {{getFrameData()}}. If {{getFrameData()}} was not called prior to calling {{submitFrame()}} the user agent MAY warn the user of potentially malformed visuals or prevent the frame from being shown at all. +onactivate +An Event handler IDL attribute for the {{activate}} event type. + +ondeactivate +An Event handler IDL attribute for the {{deactivate}} event type. + +onblur +An Event handler IDL attribute for the {{VRDisplay/blur}} event type. + +onfocus +An Event handler IDL attribute for the {{VRDisplay/focus}} event type. + +onpresentchange +An Event handler IDL attribute for the {{presentchange}} event type. + +### Events ### {#vrdisplay-events} + +The UA MUST provide the following new events. The corresponding events must be of type {{VRDisplayEvent}} and must fire on a {{VRDisplay}} object. Registration for and firing of the events must follow the usual behavior of DOM4 Events. + +activate +A UA MAY dispatch this event type to indicate that something has occurred which suggests the {{VRDisplay}} should be presented to. For example, if the {{VRDisplay}} is capable of detecting when the user has put it on, this event SHOULD fire when they do so with the {{VRDisplayEvent/reason}} "mounted". + +deactivate +A UA MAY dispatch this event type to indicate that something has occurred which suggests the {{VRDisplay}} should exit presentation. For example, if the {{VRDisplay}} is capable of detecting when the user has taken it off, this event SHOULD fire when they do so with the {{VRDisplayEvent/reason}} "unmounted". + +blur +A UA MAY dispatch this event type to indicate that presentation to the {{VRDisplay}} by the page is paused by the user agent, OS, or VR hardware. While a {{VRDisplay}} is blurred it does not lose it's presenting status ({{isPresenting}} continues to report true) but {{getFrameData()}} returns false without updating the provided {{VRFrameData}} and {{getPose()}} returns null. This is to prevent tracking while the user interacts with potentially sensitive UI. For example: A user agent SHOULD blur the presenting application when the user is typing a URL into the browser with a virtual keyboard, otherwise the presenting page may be able to guess the URL the user is entering by tracking their head motions. The event {{VRDisplayEvent/reason}} MUST be set to "blur". + +focus +A UA MAY dispatch this event type to indicate that presentation to the {{VRDisplay}} by the page has resumed after being blurred. The event {{VRDisplayEvent/reason}} MUST be set to "focus". + +presentchange +A UA MUST dispatch this event type to indicate that the {{VRDisplay}} has begun or ended VR presentation. This event should not fire on subsequent calls to {{requestPresent()}} after the {{VRDisplay}} has already begun VR presentation. If presentation has begun the event {{VRDisplayEvent/reason}} MUST be set to "presentstart". If presentation has ended the event {{VRDisplayEvent/reason}} MUST be set to "presentend".
The following code demonstrates presenting a simple rendering loop to a {{VRDisplay}}. @@ -559,23 +598,61 @@ Width of the play-area bounds in meters. The bounds are defined as an axis-align sizeZ Depth of the play-area bounds in meters. The bounds are defined as an axis-aligned rectangle on the floor. The center of the rectangle is at (0,0,0) in standing-space coordinates. These bounds are defined for safety purposes. Content should not require the user to move beyond these bounds; however, it is possible for the user to ignore the bounds resulting in position values outside of this rectangle. - -## Navigator Interface extension ## {#interface-navigator} +## VR Interface ## {#interface-vr} 
-partial interface Navigator {
-  Promise<sequence<VRDisplay>> getVRDisplays();
-  readonly attribute FrozenArray<VRDisplay> activeVRDisplays;
+interface VR : EventTarget {
+  Promise<boolean> getAvailability();
+  Promise<sequence<VRDisplay>> getDisplays();
+
+  attribute EventHandler ondisplayconnect;
+  attribute EventHandler ondisplaydisconnect;
+  attribute EventHandler onnavigate;
 };
-### Attributes ### {#navigator-attributes} +### Attributes ### {#vr-attributes} + +getAvailability() +Return a Promise and run the following steps in parallel: -getVRDisplays() +0. If the user has configured the UA to return a particular answer from this function for the current origin, queue a task to resolve the promise with the configured answer, and abort these steps. +1. If the UA has the ability to use WebVR, queue a task to resolve the promise with true. +2. Otherwise, queue a task to resolve the promise with false. + +getDisplays() Return a Promise which resolves to a list of available {{VRDisplay}}s. -activeVRDisplays -{{activeVRDisplays}} includes every {{VRDisplay}} that is currently presenting. +ondisplayconnect +An Event handler IDL attribute for the {{displayconnect}} event type. + +ondisplaydisconnect +An Event handler IDL attribute for the {{displaydisconnect}} event type. + +onnavigate +An Event handler IDL attribute for the {{navigate}} event type. + +### Events ### {#vr-events} + +The UA MUST provide the following new events. The corresponding events must be of type {{VRDisplayEvent}} and must fire on the {{VR}} object. Registration for and firing of the events must follow the usual behavior of DOM4 Events. + +displayconnect +A UA MAY dispatch this event type to indicate that a {{VRDisplay}} has been connected. + +displaydisconnect +A UA MAY dispatch this event type to indicate that a {{VRDisplay}} has been disconnected. + +navigate +A UA MAY dispatch this event type to indicate that the current page has been navigated to from a browsing context that was actively presenting VR content. The current page can call {{requestPresent()}} in response to this event in order to stay in VR presentation mode. + + +## Navigator Interface extension ## {#interface-navigator} + +
+partial interface Navigator {
+  readonly attribute VR vr;
+};
+
The following code finds the first available {{VRDisplay}}. @@ -583,7 +660,7 @@ The following code finds the first available {{VRDisplay}}. 
 var vrDisplay;
 
-navigator.getVRDisplays().then(function (displays) {
+navigator.vr.getDisplays().then(function (displays) {
   // Use the first display in the array if one is available. If multiple
   // displays are present, you may want to present the user with a way to
   // select which display to use.
@@ -601,7 +678,11 @@ enum VRDisplayEventReason {
   "mounted",
   "navigation",
   "requested",
-  "unmounted"
+  "unmounted",
+  "blur",
+  "focus",
+  "presentstart",
+  "presentend",
 };
@@ -619,6 +700,19 @@ The user agent MAY request start VR presentation mode. This allows user agents t unmounted The {{VRDisplay}} has detected that the user has taken it off. +blur +The {{VRDisplay}} has lost focus. + +focus +The {{VRDisplay}} has regained focus. + +presentstart +The {{VRDisplay}} has entered presentation mode. + +presentend +The {{VRDisplay}} has exited presentation mode. + + ## VRDisplayEvent ## {#interface-vrdisplayevent} 
@@ -642,44 +736,6 @@ The {{VRDisplay}} associated with this event.
 reason
 {{VRDisplayEventReason}} describing why this event has has been fired.
 
-
-## Window Interface extension ## {#interface-window}
-
-
-partial interface Window {
-  attribute EventHandler onvrdisplayconnect;
-  attribute EventHandler onvrdisplaydisconnect;
-  attribute EventHandler onvrdisplayactivate;
-  attribute EventHandler onvrdisplaydeactivate;
-  attribute EventHandler onvrdisplayblur;
-  attribute EventHandler onvrdisplayfocus;
-  attribute EventHandler onvrdisplaypresentchange;
-};
-

-
-User agents implementing this specification MUST provide the following new DOM events. The corresponding events must be of type {{VRDisplayEvent}} and must fire on the window object. Registration for and firing of the events must follow the usual behavior of DOM4 Events.
-
-onvrdisplayconnect
-A user agent MAY dispatch this event type to indicate that a {{VRDisplay}} has been connected.
-
-onvrdisplaydisconnect
-A user agent MAY dispatch this event type to indicate that a {{VRDisplay}} has been disconnected.
-
-onvrdisplayactivate
-A user agent MAY dispatch this event type to indicate that something has occured which suggests the {{VRDisplay}} should be presented to. For example, if the {{VRDisplay}} is capable of detecting when the user has put it on, this event SHOULD fire when they do so with the reason "mounted".
-
-onvrdisplaydeactivate
-A user agent MAY dispatch this event type to indicate that something has occured which suggests the {{VRDisplay}} should exit presentation. For example, if the {{VRDisplay}} is capable of detecting when the user has taken it off, this event SHOULD fire when they do so with the reason "unmounted".
-
-onvrdisplayblur
-A user agent MAY dispatch this event type to indicate that presentation to the display by the page is paused by the user agent, OS, or VR hardware. While a {{VRDisplay}} is blurred it does not lose it's presenting status ({{isPresenting}} continues to report true) but {{getFrameData()}} returns false without updating the provided {{VRFrameData}} and {{getPose()}} returns null. This is to prevent tracking while the user interacts with potentially sensitive UI. For example: A user agent SHOULD blur the presenting application when the user is typing a URL into the browser with a virtual keyboard, otherwise the presenting page may be able to guess the URL the user is entering by tracking their head motions.
-
-onvrdisplayfocus
-A user agent MAY dispatch this event type to indicate that presentation to the display by the page has resumed after being blurred.
-
-onvrdisplaypresentchange
-A user agent MUST dispatch this event type to indicate that a {{VRDisplay}} has begun or ended VR presentation. This event should not fire on subsequent calls to {{requestPresent()}} after the {{VRDisplay}} has already begun VR presentation.
-
 ## Gamepad Interface extension ## {#interface-gamepad}
 
 
@@ -704,6 +760,6 @@ While not directly affecting the API interface and Web IDL, WebVR implementation
 * The {{VRDisplay}} pose and other VR inputs are only updated for the focused page.
 * The Gamepad API will be updated such that the gamepad inputs are only updated for the focused page.
 * Non-focused tabs are allowed to enumerate {{Gamepad}}s and {{VRDisplay}}s but will see last received state or default values.
-* To prevent CORS-related vulnerabilities, each page will see a new instance of objects returned by the WebVR API, such as {{VRDisplay}}. Attributes such as the {{VRLayer}}.{{VRLayer/source}} set by one page must not be able to be read by another.
+* To prevent CORS-related vulnerabilities, each page will see a new instance of objects returned by the WebVR API, such as {{VRDisplay}}. Attributes such as the {{VRLayer/source}} set by one page must not be able to be read by another.
 
 # Acknowledgements # {#ack}
diff --git a/index.html b/index.html
index f4eb47ec..234239c2 100644
--- a/index.html
+++ b/index.html
@@ -1176,7 +1176,7 @@
 		}
 	}
 
-  
+