Describe how the input source list is maintained (#628)

toji · web-flow · commit 8050a019f31c · 2019-05-13T22:01:40.000-07:00
Defines what should happen as input sources for a session are added,
removed, and changed. Also clarifies the definitions for some of the
related concepts.
diff --git a/index.bs b/index.bs
@@ -471,7 +471,57 @@ When the <dfn method for="XRSession">requestReferenceSpace(|options|)</dfn> meth
 
 </div>
 
-The <dfn attribute for="XRSession">inputSources</dfn> attribute returns the {{XRSession}}'s [=list of active input sources=].
+Each {{XRSession}} has a <dfn>list of active XR input sources</dfn> (a [=/list=] of {{XRInputSource}}) which MUST be initially an empty [=/list=].
+
+The <dfn attribute for="XRSession">inputSources</dfn> attribute returns the {{XRSession}}'s [=list of active XR input sources=].
+
+The user agent MUST monitor any [=XR input source=]s associated with the [=/XR Device=], including detecting when [=XR input source=]s are added, removed, or changed.
+
+<div class="algorithm" data-algorithm="on-input-source-added">
+
+When new [=XR input source=]s become available for {{XRSession}} |session|, the user agent MUST run the following steps:
+
+  1. Let |added| be a new [=/list=].
+  1. For each new [=XR input source=]:
+    1. Let |inputSource| be a new {{XRInputSource}}.
+    1. Add |inputSource| to |added|.
+  1. [=Queue a task=] to perform the following steps:
+    1. [=list/Extend=] |session|'s [=list of active XR input sources=] with |added|.
+    1. Fire an {{XRInputSourcesChangeEvent}} named {{inputsourceschange!!event}} on |session| with {{XRInputSourcesChangeEvent/added}} set to |added|.
+
+</div>
+
+<div class="algorithm" data-algorithm="on-input-source-removed">
+
+When any previously added [=XR input source=]s are no longer available for {{XRSession}} |session|, the user agent MUST run the following steps:
+
+  1. Let |removed| be a new [=/list=].
+  1. For each [=XR input source=] that is no longer available:
+    1. Let |inputSource| be the {{XRInputSource}} in |session|'s [=list of active XR input sources=] associated with the [=XR input source=].
+    1. Add |inputSource| to |removed|.
+  1. [=Queue a task=] to perform the following steps:
+    1. [=list/Remove=] each {{XRInputSource}} in |removed| from |session|'s [=list of active XR input sources=].
+    1. Fire an {{XRInputSourcesChangeEvent}} named {{inputsourceschange!!event}} on |session| with {{XRInputSourcesChangeEvent/removed}} set to |removed|.
+
+</div>
+
+<div class="algorithm" data-algorithm="on-input-source-change">
+
+When the {{XRInputSource/handedness}}, {{XRInputSource/targetRayMode}}, or presence of a {{XRInputSource/gripSpace}} or {{XRInputSource/gamepad}} for any [=XR input source=]s change for {{XRSession}} |session|, the user agent MUST run the following steps:
+
+  1. Let |added| be a new [=/list=].
+  1. Let |removed| be a new [=/list=].
+  1. For each changed [=XR input source=]:
+    1. Let |oldInputSource| be the {{XRInputSource}} in |session|'s [=list of active XR input sources=] previously associated with the [=XR input source=].
+    1. Let |newInputSource| be a new {{XRInputSource}}.
+    1. Add |oldInputSource| to |removed|.
+    1. Add |newInputSource| to |added|.
+  1. [=Queue a task=] to perform the following steps:
+    1. [=list/Remove=] each {{XRInputSource}} in |removed| from |session|'s [=list of active XR input sources=].
+    1. [=list/Extend=] |session|'s [=list of active XR input sources=] with |added|.
+    1. Fire an {{XRInputSourcesChangeEvent}} named {{inputsourceschange!!event}} on |session| with{{XRInputSourcesChangeEvent/added}} set to |added| and {{XRInputSourcesChangeEvent/removed}} set to |removed|.
+
+</div>
 
 Each {{XRSession}} has a <dfn>environment blending mode</dfn> value, which is a enum which MUST be set to whichever of the following values best matches the behavior of imagery rendered by the session in relation to the user's surrounding environment.
 
@@ -511,8 +561,6 @@ We still need to document what happens when we <dfn lt="blur all sessions">blur
 
 We still need to document what happens when we <dfn>poll the device pose</dfn> (This is <a href="https://github.com/immersive-web/webxr/issues/480">filed</a>.)
 
-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>.)
-
 XRRenderState {#xrrenderstate-interface}
 -------------
 
@@ -1047,7 +1095,7 @@ The <dfn constructor for="XRRay">XRRay(|transform|)</dfn> constructor MUST perfo
   1. Multiply |ray|'s {{XRRay/direction}} by the |transform|'s {{XRRigidTransform/matrix}} and set |ray| to the result.
   1. [=Normalize=] the {{DOMPointReadOnly/x}}, {{DOMPointReadOnly/y}}, and {{DOMPointReadOnly/z}} components of |ray|'s {{XRRay/direction}}
   1. Return |ray|.
-  
+
 </div>
 
 The <dfn attribute for="XRRay">origin</dfn> attribute defines the 3-dimensional point in space that the ray originates from, given in meters. The {{XRRay/origin}}'s {{DOMPointReadOnly/w}} attribute MUST be <code>1.0</code>.
@@ -1103,7 +1151,7 @@ Input {#input}
 XRInputSource {#xrinputsource-interface}
 -------------
 
-An {{XRInputSource}} represents any input mechanism which allows the user to perform targeted actions in the same virtual space as the [=viewer=].
+An {{XRInputSource}} represents an <dfn>XR input source</dfn>, which is any input mechanism which allows the user to perform targeted actions in the same virtual space as the [=viewer=]. Example [=XR input source=]s include, but are not limited to, handheld controllers, optically tracked hands, and gaze-based input methods that operate on the [=viewer=]'s pose. Input mechanisms which are not explicitly associated with the [=/XR Device=], such as traditional gamepads, mice, or keyboards SHOULD NOT be considered [=XR input source=]s.
 
 <pre class="idl">
 enum XRHandedness {
@@ -1130,23 +1178,23 @@ interface XRInputSource {
 
 Each {{XRInputSource}} SHOULD define a <dfn>primary action</dfn>. The [=primary action=] is a platform-specific action that, when engaged, produces {{selectstart}}, {{selectend}}, and {{XRSession/select}} events. Examples of possible [=primary action=]s are pressing a trigger, touchpad, or button, speaking a command, or making a hand gesture. If the platform guidelines define a recommended primary input then it should be used as the [=primary action=], otherwise the user agent is free to select one.
 
-The <dfn attribute for="XRInputSource">handedness</dfn> attribute describes which hand the input source is associated with, if any. Input sources with no natural handedness (such as headset-mounted controls or standard gamepads) or for which the handedness is not currently known MUST set this attribute {{XRHandedness/none}}.
+The <dfn attribute for="XRInputSource">handedness</dfn> attribute describes which hand the [=XR input source=] is associated with, if any. Input sources with no natural handedness (such as headset-mounted controls or standard gamepads) or for which the handedness is not currently known MUST set this attribute {{XRHandedness/none}}.
 
 The <dfn attribute for="XRInputSource">targetRayMode</dfn> attribute describes the method used to produce the target ray, and indicates how the application should present the target ray to the user if desired.
 
   - <dfn enum-value for="XRTargetRayMode">gaze</dfn> indicates the target ray will originate at the user's head and follow the direction they are looking (this is commonly referred to as a "gaze input" device).
   - <dfn enum-value for="XRTargetRayMode">tracked-pointer</dfn> indicates that the target ray originates from either a handheld device or other hand-tracking mechanism and represents that the user is using their hands or the held device for pointing. The orientation of the target ray relative to the tracked object MUST follow platform-specific ergonomics guidelines when available. In the absence of platform-specific guidance, the target ray SHOULD point in the same direction as the user's index finger if it was outstretched.
   - <dfn enum-value for="XRTargetRayMode">screen</dfn> indicates that the input source was an interaction with the canvas element associated with a inline session's output context, such as a mouse click or touch event.
 
-Note: Some input sources, like an {{XRInputSource}} with {{targetRayMode}} set to {{screen}}, will only be added to the session's [=list of active input sources=] immediately before the {{selectstart}} event, and removed from the session's [=list of active input sources=] immediately after the {{selectend}} event.
+Note: Some input sources, like an {{XRInputSource}} with {{targetRayMode}} set to {{screen}}, will only be added to the session's [=list of active XR input sources=] immediately before the {{selectstart}} event, and removed from the session's [=list of active XR input sources=] immediately after the {{selectend}} event.
 
 The <dfn attribute for="XRInputSource">targetRaySpace</dfn> attribute is an {{XRSpace}} that has a [=native origin=] tracking the position and orientation of the preferred pointing ray of the {{XRInputSource}}, as defined by the {{targetRayMode}}.
 
 The <dfn attribute for="XRInputSource">gripSpace</dfn> attribute is an {{XRSpace}} that has a [=native origin=] tracking to the pose that should be used to render virtual objects such that they appear to be held in the user's hand. If the user were to hold a straight rod, this {{XRSpace}} places the [=native origin=] at the centroid of their curled fingers and where the <code>-Z</code> axis points along the length of the rod towards their thumb. The <code>X</code> axis is perpendicular to the back of the hand being described, with back of the users right hand pointing towards <code>+X</code> and the back of the user's left hand pointing towards <code>-X</code>. The <code>Y</code> axis is implied by the relationship between the <code>X</code> and <code>Z</code> axis, with <code>+Y</code> roughly pointing in the direction of the user's arm.
 
 The {{gripSpace}} MUST be <code>null</code> if the input source isn't inherently trackable such as for input sources with a {{targetRayMode}} of {{XRTargetRayMode/gaze}} or {{XRTargetRayMode/screen}}.
 
-The <dfn attribute for="XRInputSource">gamepad</dfn> attribute is a {{Gamepad}} that describes the state of any buttons and axes on the input device. If the device does not have at least one of the following properties, the {{gamepad}} attribute MUST be <code>null</code>:
+The <dfn attribute for="XRInputSource">gamepad</dfn> attribute is a {{Gamepad}} that describes the state of any buttons and axes on the [=XR input source=]. If the  [=XR input source=] does not have at least one of the following properties, the {{gamepad}} attribute MUST be <code>null</code>:
 
  - Multiple buttons
  - A button which reports analog values
@@ -1184,7 +1232,7 @@ Gamepad API Integration {#gamepad-api-integration}
 
   - {{XRInputSource/gamepad}} MUST NOT be included in the array returned by {{navigator.getGamepads()}}.
   - {{XRInputSource/gamepad}}'s {{Gamepad/index}} attribute MUST be <code>0</code>.
-  - {{XRInputSource/gamepad}}'s {{Gamepad/connected}} attribute MUST be <code>true</code> until the {{XRInputSource}} is removed from the [=list of active input sources=] or the {{XRSession}} is ended.
+  - {{XRInputSource/gamepad}}'s {{Gamepad/connected}} attribute MUST be <code>true</code> until the {{XRInputSource}} is removed from the [=list of active XR input sources=] or the {{XRSession}} is ended.
 
 The {{XRInputSource/gamepad}}'s {{Gamepad/id}} also enforces additional behavioral restrictions, and MUST conform to the following rules:
 
@@ -1621,6 +1669,36 @@ When the user agent fires an {{XRInputSourceEvent}} |event| it MUST run the foll
 </div>
 </section>
 
+<section class="unstable">
+XRInputSourcesChangeEvent {#xrinputsourceschangeevent-interface}
+--------------
+
+{{XRInputSourcesChangeEvent}}s are fired to indicate changes to the {{XRInputSource}}s that are available to an {{XRSession}}.
+
+<pre class="idl">
+[SecureContext, Exposed=Window, Constructor(DOMString type, XRInputSourcesChangeEventInit eventInitDict)]
+interface XRInputSourcesChangeEvent : Event {
+  [SameObject] readonly attribute XRSession session;
+  [SameObject] readonly attribute FrozenArray&lt;XRInputSource&gt; added;
+  [SameObject] readonly attribute FrozenArray&lt;XRInputSource&gt; removed;
+};
+
+dictionary XRInputSourcesChangeEventInit : EventInit {
+  required XRSession session;
+  required FrozenArray&lt;XRInputSource&gt; added;
+  required FrozenArray&lt;XRInputSource&gt; removed;
+  
+};
+</pre>
+
+The <dfn attribute for="XRInputSourcesChangeEvent">session</dfn> attribute indicates the {{XRSession}} that generated the event.
+
+The <dfn attribute for="XRInputSourcesChangeEvent">added</dfn> attribute is a [=/list=] of {{XRInputSource}}s that were added to the {{XRSession}} at the time of the event.
+
+The <dfn attribute for="XRInputSourcesChangeEvent">removed</dfn> attribute is a [=/list=] of {{XRInputSource}}s that were removed from the {{XRSession}} at the time of the events.
+</section>
+
+
 XRReferenceSpaceEvent {#xrreferencespaceevent-interface}
 -----------------------
 
@@ -1659,7 +1737,7 @@ A user agent MAY dispatch a <dfn event for="XRSession">focus</dfn> event on an {
 A user agent MUST dispatch a <dfn event for="XRSession">end</dfn> event on an {{XRSession}} when the session ends, either by the application or the user agent. The event MUST be of type {{XRSessionEvent}}.
 
 <section class="unstable">
-A user agent MUST dispatch a <dfn event for="XRSession">inputsourceschange</dfn> event on an {{XRSession}} when the session's [=list of active input sources=] has changed. The event MUST be of type {{XRSessionEvent}}.
+A user agent MUST dispatch a <dfn event for="XRSession">inputsourceschange</dfn> event on an {{XRSession}} when the session's [=list of active XR input sources=] has changed. The event MUST be of type {{XRInputSourcesChangeEvent}}.
 </section>
 
 A user agent MUST dispatch a <dfn event for="XRSession">selectstart</dfn> event on an {{XRSession}} when one of its {{XRInputSource}}s begins its [=primary action=]. The event MUST be of type {{XRInputSourceEvent}}.
