From fea4209b6164695a2303ff5fed578c0a03b47f60 Mon Sep 17 00:00:00 2001 From: Matt Reynolds Date: Thu, 24 Oct 2019 13:49:05 -0700 Subject: [PATCH 01/12] Spec liveness of Gamepad and GamepadButton objects (#8) https://github.com/w3c/gamepad/issues/8 --- index.html | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/index.html b/index.html index bba99f2..f11f025 100644 --- a/index.html +++ b/index.html @@ -209,7 +209,11 @@

Gamepad interface

- This interface defines an individual gamepad device. + 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. 

         [Exposed=Window]
@@ -230,7 +234,8 @@ 

         

           An identification string for the gamepad. This string identifies the
           brand or style of connected gamepad device. Typically, this will
-          include the USB vendor and a product ID.
+          include the USB vendor and a product ID. The ID string MUST NOT change
+          once the Gamepad object has been returned to script.
         

         

           index attribute
@@ -296,19 +301,19 @@ 

           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 return different values (or values in
-          a different order).
+          the user agent needs to modify the length of the array or
+          return different axis values.
         
         

           buttons attribute
         

         

-          Array of button states for all buttons of the gamepad. It is
+          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 return
-          different values (or values in a different order).
+          MUST be returned until the user agent needs to modify the
+          length of the array or the button ordering.
         

       
     
@@ -318,7 +323,13 @@ 

       

       

         This interface defines the state of an individual button on a gamepad
-        device.
+        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.
       

       
         [Exposed=Window]
@@ -416,7 +427,7 @@ 

           getGamepads
         

         

-          Retrieve a snapshot of the data for the the currently connected and
+          Retrieve an array of Gamepad objects representing currently connected and
           interacted-with gamepads. Gamepads MUST only appear in the list if
           they are currently connected to the user agent, and at least
           one device has been interacted with by the user. If no devices have

From 16a6521f082f590ad8d0c0e84f5f7a18600a9bab Mon Sep 17 00:00:00 2001
From: Matt Reynolds 
Date: Thu, 7 Nov 2019 12:31:47 -0800
Subject: [PATCH 02/12] Update index.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Marcos Cáceres 
---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index f11f025..19fc102 100644
--- a/index.html
+++ b/index.html
@@ -213,7 +213,7 @@ 

         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.
+        event loop to update the state of the {{Gamepad}} object.
       

       
         [Exposed=Window]

From 4cd26da99b10f2b08118a2088c54c12e55643772 Mon Sep 17 00:00:00 2001
From: Matt Reynolds 
Date: Thu, 7 Nov 2019 12:32:01 -0800
Subject: [PATCH 03/12] Update index.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Marcos Cáceres 
---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 19fc102..6e63ecc 100644
--- a/index.html
+++ b/index.html
@@ -308,7 +308,7 @@ 

           buttons attribute
         
         

-          Array of GamepadButton objects representing all buttons of the gamepad. It is
+          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

From 1a553cb80bc755485fec33ed84b0db7f8e4763f8 Mon Sep 17 00:00:00 2001
From: Matt Reynolds 
Date: Thu, 7 Nov 2019 12:33:07 -0800
Subject: [PATCH 04/12] Update index.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Marcos Cáceres 
---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 6e63ecc..35ea591 100644
--- a/index.html
+++ b/index.html
@@ -323,7 +323,7 @@ 

       

       

         This interface defines the state of an individual button on a gamepad
-        device. A GamepadButton is a live object; that is, user interaction with
+        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

From 9f2ee3a46d2a19a061d9aaf5391fa42a783671cd Mon Sep 17 00:00:00 2001
From: Matt Reynolds 
Date: Thu, 7 Nov 2019 12:33:17 -0800
Subject: [PATCH 05/12] Update index.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Marcos Cáceres 
---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 35ea591..69489dd 100644
--- a/index.html
+++ b/index.html
@@ -427,7 +427,7 @@ 

           getGamepads
         
         

-          Retrieve an array of Gamepad objects representing currently connected and
+          Retrieve a sequence of {{Gamepad}} objects representing currently connected and
           interacted-with gamepads. Gamepads MUST only appear in the list if
           they are currently connected to the user agent, and at least
           one device has been interacted with by the user. If no devices have

From de433b4e3e4d99391bea3d52c5e0c3b47c18cf5d Mon Sep 17 00:00:00 2001
From: Matt Reynolds 
Date: Thu, 24 Oct 2019 13:49:05 -0700
Subject: [PATCH 06/12] 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.
       

     

     


From 4d0d02db2af5985fa296dafe501f54baf150bb4a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marcos=20C=C3=A1ceres?= 
Date: Tue, 12 Nov 2019 16:31:25 +1100
Subject: [PATCH 07/12] Add [NewObject] to getGamepads

---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index c0bf04b..daf4832 100644
--- a/index.html
+++ b/index.html
@@ -479,7 +479,7 @@ 

       
         [Exposed=Window]
         partial interface Navigator {
-          sequence<Gamepad?> getGamepads();
+          [NewObject] sequence<Gamepad?> getGamepads();
         };
       

       


From f846365102a4159cdb48a5bd462e9d0985d4b96f Mon Sep 17 00:00:00 2001
From: Matt Reynolds 
Date: Wed, 20 Nov 2019 15:54:04 -0800
Subject: [PATCH 08/12] Update index.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Marcos Cáceres 
---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index daf4832..02de81d 100644
--- a/index.html
+++ b/index.html
@@ -210,7 +210,7 @@ 

       

       

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

From 260b9e7a1e1d584a317c8d860bc26fa2c5f22f7f Mon Sep 17 00:00:00 2001
From: Matt Reynolds 
Date: Wed, 20 Nov 2019 17:13:08 -0800
Subject: [PATCH 09/12] Update index.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Marcos Cáceres 
---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 02de81d..d334737 100644
--- a/index.html
+++ b/index.html
@@ -291,7 +291,7 @@ 

           

           

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


From b79f0ae9fcf78d09776adcae23c2b67164151642 Mon Sep 17 00:00:00 2001
From: Matt Reynolds 
Date: Wed, 20 Nov 2019 17:13:17 -0800
Subject: [PATCH 10/12] Update index.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Marcos Cáceres 
---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index d334737..0b00626 100644
--- a/index.html
+++ b/index.html
@@ -343,7 +343,7 @@ 

           

           

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

         


From 2bf948bf578a6e778a3658de79abe616df46865e Mon Sep 17 00:00:00 2001
From: Matt Reynolds 
Date: Wed, 20 Nov 2019 17:13:26 -0800
Subject: [PATCH 11/12] Update index.html
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Marcos Cáceres 
---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 0b00626..ed396c7 100644
--- a/index.html
+++ b/index.html
@@ -366,7 +366,7 @@ 

           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
+          button as a button from the previous array, the same {{GamepadButton}}
           object MUST be reused.
           

         


From f71842d80ad58a257c002af1b6140096052a556d Mon Sep 17 00:00:00 2001
From: Matt Reynolds 
Date: Thu, 24 Oct 2019 13:49:05 -0700
Subject: [PATCH 12/12] Changes from https://github.com/w3c/gamepad/pull/123

---
 index.html | 33 ++++++++++++++++++++++++++-------
 1 file changed, 26 insertions(+), 7 deletions(-)

diff --git a/index.html b/index.html
index ed396c7..81a70ee 100644
--- a/index.html
+++ b/index.html
@@ -234,8 +234,7 @@ 

         

           An identification string for the gamepad. This string identifies the
           brand or style of connected gamepad device. Typically, this will
-          include the USB vendor and a product ID. The ID string MUST NOT change
-          once the Gamepad object has been returned to script.
+          include the USB vendor and a product ID.
         

         

           index attribute
@@ -258,6 +257,30 @@ 

           lowest previously used index MUST be assigned to the newly connected
           gamepad.
           

+
+          
+            // Consider three gamepads padA, padB, and padC.
+            // Initially, padA and padB are connected with indices 0 and 1.
+            // padC is not connected.
+            var gamepads = navigator.getGamepads();
+            // The following statements should all evaluate to true.
+            gamepads.length == 2;
+            gamepads[0].index == 0;  // padA
+            gamepads[1].index == 1;  // padB
+            // padA is disconnected.
+            gamepads.length == 2;
+            gamepads[0] == null;
+            gamepads[1].index == 1;  // padB
+            // padC is connected and takes the lowest unassigned index (0).
+            gamepads.length == 2;
+            gamepads[0].index == 0;  // padC
+            gamepads[1].index == 1;  // padB
+            // padA is reconnected and takes the lowest unassigned index (2).
+            gamepads.length == 3;
+            gamepads[0].index == 0;  // padC
+            gamepads[1].index == 1;  // padB
+            gamepads[2].index == 2;  // padA
+          

         

         

           connected attribute
@@ -379,7 +402,7 @@ 

       

         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
+        the button represented by the object is periodically reflected in the object's
         properties. When the system receives new data from a connected gamepad,
         a microtask MUST be queued with the user interaction task source to
         update the state of the GamepadButton objects representing the buttons
@@ -500,10 +523,6 @@ 

           {{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
           disconnection or connection until after the gamepaddisconnected