Re: [w3c/gamepad] Spec gamepad input events (PR #234)

@nondebug requested changes on this pull request.



> @@ -839,6 +841,29 @@ <h3>
               </li>
             </ol>
           </li>
+          <li>Let |oldGamepad:Gamepad| be the state of the device represented

"Before the current input changes were applied" is ambigious, please add steps to copy the state from |gamepad| to |oldGamepad| before running the steps to map and normalize buttons and axes.

> @@ -787,6 +787,17 @@ <h3>
           following steps:
         </p>
         <ol>
+          <li>Let |navigator:Navigator| be |gamepad|'s [=relevant global
+          object=]'s {{Navigator}} object.
+          </li>
+          <li>Let |document:Document?| be |gamepad|'s [=relevant global
+          object=]'s [=associated `Document`=]; otherwise `null`.
+          </li>
+          <li>If |document| is `null`, abort these steps.
+          </li>
+          <li>If |document| is not [=allowed to use=] the [=policy-controlled
+          feature=] named "gamepad", then abort these steps.
+          </li>

Currently the steps to update gamepad state don't check if the document is fully active before firing an event. We should update the steps to abort on not-fully-active documents so that input and connection events only fire when the document is fully active.

> @@ -1006,6 +1031,109 @@ <h3>
             </ol>
           </li>
         </ol>
+        <p>
+          To <dfn>detect gamepad input changes</dfn> between |gamepad1:Gamepad|
+          and |gamepad2:Gamepad|, run the following steps:
+        </p>
+        <ol class="algorithm">
+          <li>Assert: |gamepad1| and |gamepad2| are not `null`.
+          </li>
+          <li>If [=list/size=] of |gamepad1|.{{Gamepad/[[axes]]}} is not equal

nit: prefer the possessive form:

If |gamepad1|.{{Gamepad/[[axes]]}}'s [=list/size=] is not equal to |gamepad2|.{{Gamepad/[[axes]]}}'s [=list/size=], return `true`.

> @@ -1006,6 +1031,109 @@ <h3>
             </ol>
           </li>
         </ol>
+        <p>
+          To <dfn>detect gamepad input changes</dfn> between |gamepad1:Gamepad|
+          and |gamepad2:Gamepad|, run the following steps:
+        </p>
+        <ol class="algorithm">
+          <li>Assert: |gamepad1| and |gamepad2| are not `null`.
+          </li>
+          <li>If [=list/size=] of |gamepad1|.{{Gamepad/[[axes]]}} is not equal
+          to the [=list/size=] of |gamepad2|.{{Gamepad/[[axes]]}}, return
+          `true`.
+          </li>
+          <li>[=list/For each=] |axisIndex:long| of

nit:

[=list/For each=] [=list/index=] |axisIndex| of |gamepad1|.{{Gamepad/[[axes]]}}:

> +          <li>[=list/For each=] |axisIndex:long| of
+          |gamepad1|.{{Gamepad/[[axes]]}}'s [=list/indices=]:
+            <ol>
+              <li>If |gamepad1|.{{Gamepad/[[axes]]}}[|axisIndex|] is not equal
+              to |gamepad2|.{{Gamepad/[[axes]]}}[|axisIndex|], return `true`.
+              </li>
+            </ol>
+          </li>
+          <li>If [=list/size=] of |gamepad1|.{{Gamepad/[[buttons]]}} is not
+          equal to the [=list/size=] of |gamepad2|.{{Gamepad/[[buttons]]}},
+          return `true`.
+          </li>
+          <li>[=list/For each=] |buttonIndex:long| of
+          |gamepad1|.{{Gamepad/[[buttons]]}}'s [=list/indices=]:
+            <ol>
+              <li>Let |button1:GamepadButton| be equal to

nit: Omit "equal to" in let statements

<li>Let |button1:GamepadButton| be |gamepad1|.{{Gamepad/[[buttons]]}}[|buttonIndex|].

> +                  <li>|touch1|.{{GamepadTouch/position}}.{{DOMPointReadOnly/x}}
+                  is not equal to
+                  |touch2|.{{GamepadTouch/position}}.{{DOMPointReadOnly/x}}
+                  </li>
+                  <li>|touch1|.{{GamepadTouch/position}}.{{DOMPointReadOnly/y}}
+                  is not equal to
+                  |touch2|.{{GamepadTouch/position}}.{{DOMPointReadOnly/y}}
+                  </li>
+                  <li>Exactly one of
+                  |touch1|.{{GamepadTouch/surfaceDimensions}} and
+                  |touch2|.{{GamepadTouch/surfaceDimensions}} is `null`.
+                  </li>
+                  <li>|touch1|.{{GamepadTouch/surfaceDimensions}} and
+                  |touch2|.{{GamepadTouch/surfaceDimensions}} are both not
+                  `null`, and any of the following are true:
+                    <ol>

Use an unordered list <ul> for "any of the following"

> @@ -2610,6 +2738,21 @@ <h2 id="event-gamepaddisconnected">
         dispatched to that same {{Window}}.
       </p>
     </section>
+    <section>
+      <h2 id="event-gamepadrawinputchanged">
+        The <dfn class="event">gamepadrawinputchanged</dfn> event
+      </h2>
+      <p>
+        This event should be fired whenever the system [=receives new button or

SHOULD should be capitalized since it's an RFC 2119 keyword in a normative statement.

Alternatively, we can remove "should be" and say "This event is fired" to avoid the keyword. I think there are enough cases where the event is not fired that we don't want to use "should" here.

> @@ -2610,6 +2738,21 @@ <h2 id="event-gamepaddisconnected">
         dispatched to that same {{Window}}.
       </p>
     </section>
+    <section>
+      <h2 id="event-gamepadrawinputchanged">
+        The <dfn class="event">gamepadrawinputchanged</dfn> event
+      </h2>
+      <p>
+        This event should be fired whenever the system [=receives new button or
+        axis input values=], and [=detect gamepad input changes|input changes
+        are detected=] for a gamepad device.
+      </p>
+      <p>
+        [=User agents=] implementing this specification must provide a new DOM

Capitalize MUST

-- 
Reply to this email directly or view it on GitHub:
https://github.com/w3c/gamepad/pull/234#pullrequestreview-5463438510
You are receiving this because you are subscribed to this thread.

Message ID: <w3c/gamepad/pull/234/review/5463438510@github.com>