From de433b4e3e4d99391bea3d52c5e0c3b47c18cf5d Mon Sep 17 00:00:00 2001 From: Matt Reynolds Date: Thu, 24 Oct 2019 13:49:05 -0700 Subject: [PATCH] Spec liveness of Gamepad and GamepadButton objects (#8) https://github.com/w3c/gamepad/issues/8 --- index.html | 135 ++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 102 insertions(+), 33 deletions(-) diff --git a/index.html b/index.html index 69489dd..c0bf04b 100644 --- a/index.html +++ b/index.html @@ -212,8 +212,8 @@

This interface represents an individual gamepad device. A Gamepad is a live object; that is, user interaction with the device will be reflected in the state of the object's properties. When the system receives new - data from a connected gamepad, a microtask is queued in the current - event loop to update the state of the {{Gamepad}} object. + data from a connected gamepad, a microtask MUST be queued with the user + interaction task source to update the state of the {{Gamepad}} object. 

         [Exposed=Window]
@@ -241,28 +241,46 @@ 

           index attribute
         
         

-          The index of the gamepad in the {{Navigator}}. When multiple gamepads
-          are connected to a user agent, indices MUST be assigned on a
-          first-come, first-serve basis, starting at zero. If a gamepad is
-          disconnected, previously assigned indices MUST NOT be reassigned to
-          gamepads that continue to be connected. However, if a gamepad is
-          disconnected, and subsequently the same or a different gamepad is
-          then connected, the lowest previously used index MUST be reused.
+          

+          Zero-based index of the gamepad in the {{Navigator}}. The index
+          MUST NOT change once the Gamepad object has been returned to script.
+          

+          

+          When the system is notified that a gamepad has been connected,
+          its index attribute MUST be assigned to the lowest index that is not
+          assigned to any currently connected gamepad, starting at zero.
+          

+          

+          When the system is notified that a previously connected gamepad has
+          become unavailable, the `index` attribute of other gamepads MUST NOT
+          be reassigned. However, if a gamepad is disconnected, and
+          subsequently the same or a different gamepad is connected, the
+          lowest previously used index MUST be assigned to the newly connected
+          gamepad.
+          

         

         

           connected attribute
         

         

+          

           Indicates whether the physical device represented by this object is
-          still connected to the system. When a gamepad becomes unavailable,
-          whether by being physically disconnected, powered off or otherwise
-          unusable, the `connected` attribute MUST be set to false.
+          still connected to the system.
+          

+          

+          When the system is notified that a previously-connected gamepad has
+          become unavailable, whether by being physically disconnected,
+          powered off, or otherwise unusable, a microtask MUST be queued with
+          the user interaction task source to set the `connected` attribute to
+          false.
+          

         

         

           timestamp attribute
         

         

-          Last time the data for this gamepad was updated. Timestamp is a
+          

+          Last time the data for this gamepad was updated. The `timestamp` is a
           monotonically increasing value that allows the author to determine if
           the axes and button data have been updated from the
           hardware. The value must be relative to the
@@ -270,10 +288,21 @@ 

           PerformanceTiming interface. Since values are monotonically
           increasing they can be compared to determine the ordering of updates,
           as newer values will always be greater than or equal to older values.
+          

+          

           If no data has been received from the hardware, the value of the
-          timestamp attribute should be the time relative to
+          timestamp attribute MUST be the time relative to
           navigationStart when the Gamepad object was first
           made available to script.
+          

+          

+          When the system receives new data from a connected gamepad, a
+          microtask MUST be queued with the user interaction task source to
+          update the gamepad state. If the updated data would cause an
+          observable change to the `buttons` or `axes` attributes, then the
+          timestamp MUST be set to the time that the data was received from
+          hardware, not the time when the microtask was executed.
+          

         

         

           mapping attribute
@@ -292,6 +321,7 @@ 

           axes attribute
         

         

+          

           Array of values for all axes of the gamepad. All axis values MUST be
           linearly normalized to the range [-1.0 .. 1.0]. If the controller is
           perpendicular to the ground with the directional stick pointing up,
@@ -300,20 +330,45 @@ 

           input device SHOULD appear next to each other in the axes array, X
           then Y. It is RECOMMENDED that axes appear in decreasing order of
           importance, such that element 0 and 1 typically represent the X and Y
-          axis of a directional stick. The same object MUST be returned until
-          the user agent needs to modify the length of the array or
-          return different axis values.
+          axis of a directional stick.
+          

+          

+          When the system receives new data from a connected gamepad, a
+          microtask MUST be queued with the user interaction task source to
+          update the gamepad state. If the gamepad has the same axes in the same
+          order as the previous update, and if no axis values have changed
+          since the previous update, then the axes attribute MUST return the
+          same array object. If the number of axes has changed, or if any axis
+          value has changed, then the axis attribute MUST return a new array.
+          

+          

+          Once the system is notified that a previously connected gamepad has
+          been disconnected, the axes attribute MUST continue to return the
+          last state received from the gamepad before disconnection.
+          

         

         

           buttons attribute
         

         

-          Array of {{GamepadButton}} objects representing all buttons of the gamepad. It is
-          RECOMMENDED that buttons appear in decreasing importance such that
-          the primary button, secondary button, tertiary button, and so on
-          appear as elements 0, 1, 2, ... in the buttons array. The same object
-          MUST be returned until the user agent needs to modify the
-          length of the array or the button ordering.
+          

+          Array of {{GamepadButton}} objects representing the current state of
+          all buttons of the gamepad. It is RECOMMENDED that buttons appear in
+          decreasing importance such that the primary button, secondary
+          button, tertiary button, and so on appear as elements 0, 1, 2, ...
+          in the buttons array.
+          

+          

+          When the system receives new data from a connected gamepad, a
+          microtask MUST be queued with the user interaction task source to
+          update the gamepad state. If the gamepad has the same buttons in the
+          same order as the previous update, the buttons attribute MUST return
+          the same array object. If the number of buttons or the ordering of
+          buttons has changed, the buttons attribute MUST return a new array
+          object. If a button in the new array represents the same physical
+          button as a button from the previous array, the same GamepadButton
+          object MUST be reused.
+          

         

       
     
@@ -322,14 +377,19 @@ 

         GamepadButton Interface
       

       

-        This interface defines the state of an individual button on a gamepad
+        This interface represents the current state of an individual button on a gamepad
         device. A {{GamepadButton}} is a live object; that is, user interaction with
         the button represented by the object will be reflected in the object's
         properties. When the system receives new data from a connected gamepad,
-        a microtask is queued in the current event loop to update the state of
-        the GamepadButton object. If a gamepad device is disconnected, the
-        GamepadButton objects representing its buttons MUST continue to return
-        the last state received from the device before disconnection.
+        a microtask MUST be queued with the user interaction task source to
+        update the state of the GamepadButton objects representing the buttons
+        on the gamepad.
+      

+      

+        Once the system is notified that a previously-connected gamepad has been
+        disconnected, the GamepadButton objects representing its buttons MUST
+        continue to return the last state received from the gamepad before
+        disconnection.
       

       
         [Exposed=Window]
@@ -439,6 +499,10 @@ 

           each Gamepad present at the index in the array specified by its
           {{Gamepad/index}} attribute. Array indices for which there is no
           connected Gamepad with the corresponding index should return null.
+
+          

+          A new array MUST be returned for each call to getGamepads().
+          

           
           

           The gamepad state returned from getGamepads() does not reflect
@@ -763,10 +827,14 @@ 

         DOM Events. [[DOM]]
       

       

+        When the system is notified that a gamepad has been connected, a
+        microtask MUST be queued with the user interaction task source to fire a
+        gamepadconnected event.
         A user agent MUST dispatch this event type to indicate the user
         has connected a gamepad. If a gamepad was already connected when the
         page was loaded, the gamepadconnected event SHOULD be dispatched
-        when the user presses a button or moves an axis.
+        when the user presses a button or moves an axis on any connected
+        gamepad.
       

     
     

@@ -782,10 +850,11 @@ 

         of DOM Events. [[DOM]]
       

       

-        When a gamepad is disconnected from the user agent, if the
-        user agent has previously dispatched a gamepadconnected
-        event for that gamepad to a window, a gamepaddisconnected event
-        MUST be dispatched to that same window.
+        If a gamepadconnected event was previously dispatched for a
+        particular gamepad and the system is notified that the gamepad has
+        become unavailable, a microtask MUST be queued with the user interaction
+        task source to dispatch a gamepaddisconnected event to the same
+        window.