Define event order of input sources (#629)

toji · web-flow · commit af393335b2b7 · 2019-05-13T22:14:08.000-07:00
Makes the order of `select`, `selectstart`, and `selectend` events generated by the API explicit, as well as their timing relative to certain non-XR input events in the case of transient input types (mouse, touch, etc.)
diff --git a/index.bs b/index.bs
@@ -479,7 +479,7 @@ The user agent MUST monitor any [=XR input source=]s associated with the [=/XR D
 
 <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:
+When <dfn for="XRSession" lt="add input source">new [=XR input source=]s become available</dfn> 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=]:
@@ -493,7 +493,7 @@ When new [=XR input source=]s become available for {{XRSession}} |session|, the
 
 <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:
+When any previously added <dfn for="XRSession" lt="remove input source">[=XR input source=]s are no longer available</dfn> 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:
@@ -1176,8 +1176,6 @@ interface XRInputSource {
 };
 </pre>
 
-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 [=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.
@@ -1186,9 +1184,7 @@ The <dfn attribute for="XRInputSource">targetRayMode</dfn> attribute describes t
   - <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 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">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}}.s
 
 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.
 
@@ -1200,9 +1196,79 @@ The <dfn attribute for="XRInputSource">gamepad</dfn> attribute is a {{Gamepad}}
  - A button which reports analog values
  - An axis
 
-NOTE: {{XRInputSource}}s with a <code>null</code> {{gamepad}} can still fire {{select}}, {{selectstart}}, and {{selectend}} events to report binary inputs.
+Each [=XR input source=] SHOULD define a <dfn>primary action</dfn>. The [=primary action=] is a platform-specific action that, when engaged, produces {{XRSession/selectstart}}, {{XRSession/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.
+
+<div class="algorithm" data-algorithm="on-input-start">
+
+When an [=XR input source=] for {{XRSession}} |session| begins its [=primary action=] the UA MUST run the following steps:
+
+  1. [=Queue a task=] that fires a {{XRInputSourceEvent}} named {{selectstart!!event}} on |session|.
+
+</div>
+
+<div class="algorithm" data-algorithm="on-input-end">
+
+When an [=XR input source=] for {{XRSession}} |session| ends its [=primary action=] the UA MUST run the following steps:
+
+  1. [=Queue a task=] to perform the following steps:
+    1. Fire an {{XRInputSourceEvent}} named {{select!!event}} on |session|.
+    1. Fire an {{XRInputSourceEvent}} named {{selectend!!event}} on |session|.
+
+</div>
+
+Sometimes platform-specific behavior can result in a [=primary action=] being interrupted or cancelled. For example, a [=/XR input source=] may be removed from the [=/XR device=] after the [=primary action=] is started but before it ends.
+
+<div class="algorithm" data-algorithm="on-input-cancelled">
+
+When an [=XR input source=] for {{XRSession}} |session| has its [=primary action=] cancelled the UA MUST run the following steps:
+
+  1. [=Queue a task=] that fires a {{XRInputSourceEvent}} named {{selectend!!event}} on |session|.
+
+</div>
 </section>
 
+Transient input {#transient-input}
+---------------
+
+Some [=/XR Device=]s may support <dfn>transient input sources</dfn>, where the [=XR input source=] is only meaningful while performing it's [=primary action=]. An example would be mouse, touch, or stylus input against an {{XRSessionMode/inline}} {{XRSession}}, which MUST produce a transient {{XRInputSource}} with a {{targetRayMode}} set to {{screen}}. [=Transient input sources=] are only present in the session's [=list of active XR input sources=] for the duration of the the {{selectstart}}, {{select}}, and {{selectend}} event sequence.
+
+[=Transient input sources=] follow a slightly different sequence when firing [=primary action=] events:
+
+<div class="algorithm" data-algorithm="on-transient-input-start">
+
+When a [=transient input source=] for {{XRSession}} |session| begins its [=primary action=] the UA MUST run the following steps:
+
+  1. [=Queue a task=] to perform the following steps:
+    1. Fire any <code>"pointerdown"</code> events produced by the [=XR input source=]'s action, if necessary.
+    1. [=add input source|Add the XR input source=] to the [=list of active XR input sources=].
+    1. Fire an {{XRInputSourceEvent}} named {{selectstart!!event}} on |session|.
+
+</div>
+
+<div class="algorithm" data-algorithm="on-transient-input-end">
+
+When a [=transient input source=] for {{XRSession}} |session| ends its [=primary action=] the UA MUST run the following steps:
+
+  1. [=Queue a task=] to perform the following steps:
+    1. Fires an {{XRInputSourceEvent}} named {{select!!event}} on |session|.
+    1. Fire any <code>"click"</code> events produced by the [=XR input source=]'s action, if necessary.
+    1. Fires an {{XRInputSourceEvent}} named {{selectend!!event}} on |session|.
+    1. [=remove input source|Remove the XR input source=] from the [=list of active XR input sources=].
+    1. Fire any <code>"pointerup"</code> events produced by the [=XR input source=]'s action, if necessary.
+
+</div>
+
+<div class="algorithm" data-algorithm="on-transient-input-cancelled">
+
+When a [=transient input source=] for {{XRSession}} |session| has its [=primary action=] cancelled the UA MUST run the following steps:
+
+  1. [=Queue a task=] to perform the following steps:  
+    1. Fire an {{XRInputSourceEvent}} named {{selectend!!event}} on |session|.
+    1. [=remove input source|Remove the XR input source=] from the [=list of active XR input sources=].
+    1. Fire any <code>"pointerup"</code> events produced by the [=XR input source=]'s action, if necessary.
+
+</div>
+
 <section class="unstable">
 XRInputSourceArray {#xrinputsourcearray-interface}
 ------------------
