diff --git a/index.html b/index.html index c75088a..c6e4c6d 100644 --- a/index.html +++ b/index.html @@ -86,7 +86,7 @@
- Some [=user agent=]s have connected gamepad devices. These devices are + Some [=user agents=] have connected gamepad devices. These devices are desirable and suited to input for gaming applications, and for "10 foot" user interfaces (presentations, media viewers).
@@ -120,7 +120,7 @@While the primary goal is support for gamepad devices, supporting these @@ -386,10 +386,10 @@
- This interface defines an individual gamepad device. + This interface represents a [=gamepad=].
[Exposed=Window]
@@ -430,10 +430,10 @@
[[\connected]]
- `false`
+ `true`
- A flag indicating that the device is connected to the system
+ A flag indicating that the [=gamepad=] is [=available=]
@@ -456,7 +456,7 @@
A [=sequence=] of {{double}} values representing the current state
- of axes exposed by this device
+ of each [=axis=]
@@ -468,7 +468,7 @@
A [=sequence=] of {{GamepadButton}} objects representing the
- current state of buttons exposed by this device
+ current state of each [=button=]
@@ -491,30 +491,8 @@
An empty [=ordered map=]
- Mapping from unmapped axis index to an index in the
- {{Gamepad/axes}} array
-
-
-
-
- [[\axisMinimums]]
-
-
- An empty [=list=]
-
-
- A [=list=] containing the minimum logical value for each axis
-
-
-
-
- [[\axisMaximums]]
-
-
- An empty [=list=]
-
-
- A [=list=] containing the maximum logical value for each axis
+ Mapping from indices in the [=axis list=] to indices in
+ {{Gamepad}}.{{Gamepad/axes}}
@@ -525,30 +503,8 @@
An empty [=ordered map=]
- Mapping from unmapped button index to an index in the
- {{Gamepad/buttons}} array
-
-
-
-
- [[\buttonMinimums]]
-
-
- An empty [=list=]
-
-
- A [=list=] containing the minimum logical value for each button.
-
-
-
-
- [[\buttonMaximums]]
-
-
- An empty [=list=]
-
-
- A [=list=] containing the maximum logical value for each button
+ Mapping from indices in the [=button list=] to indices in
+ {{Gamepad}}.{{Gamepad/buttons}}
@@ -556,11 +512,12 @@
[[\touches]]
- Initialize to an [=list/is empty=] [=list=]
+ An empty [=list=]
- Holds the list of user-generated touches, if any. If the gamepad
- does not support touch surfaces, then the list will remain empty.
+ Holds the [=list=] of {{GamepadTouch}} objects representing all
+ active [=touch points=] for the [=gamepad=]. If the [=gamepad=] has
+ no [=touch surfaces=], then the list will remain empty.
@@ -568,10 +525,11 @@
[[\nextTouchId]]
- Initialize to 0
+ 0
- Touch id to use for the next incoming touch.
+ {{GamepadTouch/touchId}} value to use for the next [=touch point=]
+ that is not [=part of an existing active touch point=]
@@ -582,8 +540,7 @@
undefined
- A {{GamepadHapticActuator}} object capable of generating a haptic
- effect that vibrates the entire gamepad
+ The [=gamepad=]'s [=vibration actuator=]
@@ -593,8 +550,7 @@
- An identification string for the gamepad. This string identifies
- the brand or style of connected gamepad device.
+ The [=gamepad=]'s [=gamepad identifier string=].
The exact format of the {{Gamepad/id}} string is left unspecified.
@@ -610,24 +566,15 @@
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.
+ The index of the {{Gamepad}} object in
+ {{Navigator}}.{{Navigator/[[gamepads]]}}.
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 {{Gamepad/connected}} attribute MUST be set to
- `false`.
+ Indicates whether the [=gamepad=] is [=available=].
The {{Gamepad/connected}} getter steps are:
@@ -642,17 +589,11 @@
- The {{Gamepad/timestamp}} allows the author to determine the last
- time the {{Gamepad/axes}} or {{Gamepad/buttons}} attribute for this
- gamepad was updated. The value MUST be set to the [=current high
- resolution time=] each time the system [=receives new button or
- axis input values=] from the device. If no data has been received
- from the hardware, {{Gamepad/timestamp}} MUST be the [=current high
- resolution time=] at the time when the {{Gamepad}} was first made
- available to script.
+ The {{Gamepad/timestamp}} allows the author to determine when the
+ [=input values=] for this {{Gamepad}} updated.
- [=User agent=]s SHOULD set a minimum resolution of |gamepad|'s
+ [=User agents=] SHOULD set a minimum resolution of the
{{Gamepad/timestamp}} attribute to 5 microseconds, following
[[HR-TIME]]'s clock resolution recommendation.
@@ -669,18 +610,20 @@
- The mapping in use for this device. If the user agent has knowledge
- of the layout of the device, then it SHOULD indicate that a mapping
- is in use by setting {{Gamepad/mapping}} to the corresponding
- {{GamepadMappingType}} value.
+ Indicates whether inputs in the [=axis list=] and [=button list=]
+ are reordered when setting {{Gamepad}}.{{Gamepad/axes}} and
+ {{Gamepad}}.{{Gamepad/buttons}}. If the [=user agent=] has
+ knowledge of the [=input control layout=], then it SHOULD indicate
+ that a mapping is in use by setting {{Gamepad/mapping}} to the
+ corresponding {{GamepadMappingType}} value.
To select a mapping for a
- gamepad device, run the following steps:
+ [=gamepad=], run the following steps:
- - If the button and axis layout of the gamepad device corresponds
- with the [=Standard Gamepad=] layout, then return
+
- If the [=input control layout=] [=corresponds with=] the
+ [=Standard Gamepad=] layout, then return
{{GamepadMappingType/"standard"}}.
- Return {{GamepadMappingType/""}}.
@@ -692,17 +635,18 @@
-
- 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, -1.0 SHOULD correspond to "forward" or "left",
- and 1.0 SHOULD correspond to "backward" or "right". Axes that are
- drawn from a 2D 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 return different
- values (or values in a different order).
+ Array of values for all [=axis=] inputs of the [=gamepad=]
+ normalized to the range [-1 .. 1]. If the [=gamepad=] is
+ perpendicular to the ground with the thumbsticks pointing up, -1
+ SHOULD correspond to "forward" or "left", and 1 SHOULD correspond
+ to "backward" or "right". [=Axis=] inputs with [=input values=]
+ from a thumbstick, joystick, or another input control that reports
+ X and Y values SHOULD appear next to each other in the
+ {{Gamepad/axes}} array, X then Y. It is RECOMMENDED that [=axis=]
+ inputs appear in decreasing order of importance, such that element
+ 0 and 1 typically represent the X and Y axes of a thumbstick or
+ joystick. The same object MUST be returned until the [=user agent=]
+ needs to return different values (or values in a different order).
The {{Gamepad/axes}} getter steps are:
@@ -717,12 +661,13 @@
-
- Array of button states for 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).
+ Array of [=button=] states for 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
+ {{Gamepad/buttons}} array. The same object MUST be returned until
+ the [=user agent=] needs to return different values (or values in a
+ different order).
The {{Gamepad/buttons}} getter steps are:
@@ -737,8 +682,8 @@
-
- A [=list=] of {{GamepadTouch}} objects generated from all touch
- surfaces.
+ A [=list=] of {{GamepadTouch}} objects representing the current
+ contact points across all [=touch surfaces=].
The {{Gamepad/touches}} getter steps are:
@@ -753,8 +698,8 @@
-
- A {{GamepadHapticActuator}} object that represents the device's
- primary vibration actuator.
+ A {{GamepadHapticActuator}} object that represents the
+ [=gamepad=]'s [=vibration actuator=].
The {{Gamepad/vibrationActuator}} getter steps are:
@@ -770,15 +715,27 @@
Receiving inputs
- When the system receives new button or axis input values,
- run the following steps:
+ When an [=available=] [=gamepad=] has updated [=input values=], run
+ the following steps [=set/for each=] [=top-level traversable=]
+ |traversable| of the [=user agent=]'s [=user agent/top-level
+ traversable set=]:
- - Let |gamepad:Gamepad| be the {{Gamepad}} object representing the
- device that received new button or axis input values.
-
- - [=Queue a task=] on the [=gamepad task source=] to [=update
- gamepad state=] for |gamepad|.
+
- [=list/For each=] [=navigable=] of |traversable|'s
+ [=navigable/active document=]'s [=Document/inclusive descendant
+ navigables=]:
+
+ - Let |window:Window| be |navigable|'s [=navigable/active
+ window=].
+
+ - Let |gamepad:Gamepad| be the {{Gamepad}} in
+ |window|.{{Window/navigator}}.{{Navigator/[[gamepads]]}}
+ representing the [=gamepad=] that has updated [=input values=].
+
+ - [=Queue a global task=] on the [=gamepad task source=] given
+ |window| to [=update gamepad state=] for |gamepad|.
+
+
@@ -786,8 +743,13 @@
following steps:
+ - If |gamepad|'s [=relevant global object=] is not a {{Window}},
+ abort these steps.
+
+ - Let |window| be |gamepad|'s [=relevant global object=].
+
- Let |now:DOMHighResTimeStamp| be the [=current high resolution
- time=].
+ time=] given |window|.
- Set |gamepad|.{{Gamepad/[[timestamp]]}} to |now|.
@@ -797,17 +759,16 @@
- Run the steps to [=record touches=] for |gamepad|.
- - Let |navigator:Navigator| be |gamepad|'s [=relevant global
- object=]'s {{Navigator}} object.
-
- - If |navigator|.{{Navigator/[[hasGamepadGesture]]}} is `false` and
- |gamepad| [=contains a gamepad user gesture=]:
+
- If
+ |window|.{{Window/navigator}}.{{Navigator/[[hasGamepadGesture]]}} is
+ `false` and |gamepad| [=contains a gamepad user gesture=]:
- - Set |navigator|.{{Navigator/[[hasGamepadGesture]]}} to
- `true`.
+
- Set
+ |window|.{{Window/navigator}}.{{Navigator/[[hasGamepadGesture]]}}
+ to `true`.
- [=list/For each=] |connectedGamepad:Gamepad?| of
- |navigator|.{{Navigator/[[gamepads]]}}:
+ |window|.{{Window/navigator}}.{{Navigator/[[gamepads]]}}:
- If |connectedGamepad| is not equal to `null`:
@@ -817,16 +778,15 @@
- Set |connectedGamepad|.{{Gamepad/[[timestamp]]}} to
|now|.
- - Let |document:Document?| be |gamepad|'s [=relevant
- global object=]'s [=associated `Document`=]; otherwise
- `null`.
+
- Let |document:Document| be |window|'s [=associated
+ `Document`=].
- - If |document| is not `null` and is [=Document/fully
- active=], then [=queue a task=] on the [=gamepad task
- source=] to [=fire an event=] named {{gamepadconnected}}
- at |gamepad|'s [=relevant global object=] using
- {{GamepadEvent}} with its {{GamepadEvent/gamepad}}
- attribute initialized to |connectedGamepad|.
+
- If |document| is [=Document/fully active=], then
+ [=queue a global task=] on the [=gamepad task source=]
+ given |window| to [=fire an event=] named
+ {{gamepadconnected}} at |window| using {{GamepadEvent}}
+ with its {{GamepadEvent/gamepad}} attribute initialized
+ to |connectedGamepad|.
@@ -840,91 +800,101 @@
following steps:
- - Let |axisValues:list| be a [=list=] of {{unsigned long}} values
- representing the most recent logical axis input values for each axis
- input of the device represented by |gamepad|.
-
- - Let |maxRawAxisIndex:long| be the [=list/size=] of |axisValues| −
- 1.
+
- Let |rawGamepad| be the [=gamepad=] represented by |gamepad|.
- - [=list/For each=] |rawAxisIndex:long| of [=the range=] from 0 to
- |maxRawAxisIndex|:
+
- [=list/For each=] |rawAxisIndex:long| of the [=list/indices=] of
+ the [=axis list=] of |rawGamepad|:
+ - Let |rawAxis| be the [=axis=] at index |rawAxisIndex| of the
+ [=axis list=].
+
- Let |mappedIndex:long| be
|gamepad|.{{Gamepad/[[axisMapping]]}}[|rawAxisIndex|].
- - Let |logicalValue:unsigned long| be
- |axisValues|[|rawAxisIndex|].
+
- Set |gamepad|.{{Gamepad/[[axes]]}}[|mappedIndex|] to the
+ current [=normalized axis value=] for |rawAxis|.
- - Let |logicalMinimum:unsigned long| be
- |gamepad|.{{Gamepad/[[axisMinimums]]}}[|rawAxisIndex|].
-
- - Let |logicalMaximum:unsigned long| be
- |gamepad|.{{Gamepad/[[axisMaximums]]}}[|rawAxisIndex|].
+
+
+
+
+ To compute the normalized axis value for an [=axis=]
+ |rawAxis|:
+
+
+ - Let |logicalValue:unsigned long| be the current [=logical
+ value=] for |rawAxis|.
+
+ - Let |logicalMinimum:unsigned long| be the [=logical minimum=]
+ for |rawAxis|.
+
+ - Let |logicalMaximum:unsigned long| be the [=logical maximum=]
+ for |rawAxis|.
+
+ - If |logicalValue| is less than |logicalMinimum|, set
+ |logicalValue| to |logicalMinimum|.
+
+ - If |logicalValue| is greater than |logicalMaximum|, set
+ |logicalValue| to |logicalMaximum|.
+
+ -
+
+ If |rawAxis| has a [=center position value=]:
+
+
+ - Let |center:unsigned long| be the [=center position value=]
+ for |rawAxis|.
- - Let |normalizedValue:double| be 2 (|logicalValue| −
- |logicalMinimum|) / (|logicalMaximum| − |logicalMinimum|) − 1.
+
- If |logicalValue| is greater than |center|, return
+ (|logicalValue| − |center|) / (|logicalMaximum| − |center|).
- - Set |gamepad|.{{Gamepad/[[axes]]}}[|axisIndex|] to be
- |normalizedValue|.
+
- Return (|logicalValue| − |center|) / (|center| −
+ |logicalMinimum|).
+ - Return 2 (|logicalValue| − |logicalMinimum|) / (|logicalMaximum|
+ − |logicalMinimum|) − 1.
+
To map and normalize buttons for |gamepad:Gamepad|, run
the following steps:
- - Let |buttonValues:list| be a [=list=] of {{unsigned long}} values
- representing the most recent logical button input values for each
- button input of the device represented by |gamepad|.
+
- Let |rawGamepad| be the [=gamepad=] represented by |gamepad|.
- - Let |maxRawButtonIndex:long| be the [=list/size=] of
- |buttonValues| − 1.
-
- - [=list/For each=] |rawButtonIndex:long| of [=the range=] from 0
- to |maxRawButtonIndex|:
+
- [=list/For each=] |rawButtonIndex:long| of the [=list/indices=]
+ of the |rawGamepad|'s [=button list=]:
+ - Let |rawButton| be the [=button=] at index |rawButtonIndex|
+ of |rawGamepad|'s [=button list=].
+
- Let |mappedIndex:long| be
|gamepad|.{{Gamepad/[[buttonMapping]]}}[|rawButtonIndex|].
- - Let |logicalValue:unsigned long| be
- |buttonValues|[|rawButtonIndex|].
-
- - Let |logicalMinimum:unsigned long| be
- |gamepad|.{{Gamepad/[[buttonMinimums]]}}[|rawButtonIndex|].
-
- - Let |logicalMaximum:unsigned long| be
- |gamepad|.{{Gamepad/[[buttonMaximums]]}}[|rawButtonIndex|].
-
- - Let |normalizedValue:double| be (|logicalValue| −
- |logicalMinimum|) / (|logicalMaximum| − |logicalMinimum|).
-
- - Let |button:GamepadButton| be
- |gamepad|.{{Gamepad/[[buttons]]}}[|mappedIndex|].
-
- - Set |button|.{{GamepadButton/[[value]]}} to
- |normalizedValue|.
+
- Set
+ |gamepad|.{{Gamepad/[[buttons]]}}[|mappedIndex|].{{GamepadButton/[[value]]}}
+ to the current [=normalized button value=] for |rawButton|.
-
- If the button has a digital switch to indicate a pure pressed
- or released state, set |button|.{{GamepadButton/[[pressed]]}}
- to `true` if the button is pressed or `false` if it is not
- pressed.
+ If |rawButton| has a [=digital button value=], set
+ |button|.{{GamepadButton/[[pressed]]}} to the [=digital
+ button value=].
Otherwise, set |button|.{{GamepadButton/[[pressed]]}} to
- `true` if the value is above the [=button press threshold=]
- or `false` if it is not above the threshold.
+ `true` if the current [=normalized button value=] for
+ |rawButton| is above the [=button press threshold=] or
+ `false` if it is not above the threshold.
-
- If the button is capable of detecting touch, set
- |button|.{{GamepadButton/[[touched]]}} to `true` if the
- button is currently being touched.
+ If |rawButton| has a [=button touch value=], set
+ |button|.{{GamepadButton/[[touched]]}} to |rawButton|'s
+ [=button touch value=].
Otherwise, set |button|.{{GamepadButton/[[touched]]}} to
@@ -934,67 +904,100 @@
+
+ To compute the normalized button value for a [=button=]
+ |rawButton|:
+
+
+ - If |rawButton| has an [=analog button value=]:
+
+ - Let |logicalMinimum:unsigned long| be the [=logical minimum=]
+ for |rawButton|.
+
+ - Let |logicalMaximum:unsigned long| be the [=logical maximum=]
+ for |rawButton|.
+
+ - Let |logicalValue:unsigned long| be the current [=analog
+ button value=] for |rawButton|.
+
+ - If |logicalValue| is less than |logicalMinimum|, set
+ |logicalValue| to |logicalMinimum|.
+
+ - If |logicalValue| is greater than |logicalMaximum|, set
+ |logicalValue| to |logicalMaximum|.
+
+ - Return (|logicalValue| − |logicalMinimum|) /
+ (|logicalMaximum| − |logicalMinimum|).
+
+
+
+ - If |rawButton| has a [=digital button value=] and its [=digital
+ button value=] is `true`, return 1.
+
+ - Return 0.
+
+
To record touches for |gamepad:Gamepad|, run the following
steps:
- - Assert: {{Gamepad}}.{{Gamepad/[[touches]]}} is [=list/empty=].
+
- [=list/Empty=] |gamepad|.{{Gamepad/[[touches]]}}.
- - Repeat the following steps for each touch surface on |gamepad| in
- touch surface enumeration order:
+
- [=list/For each=] |surfaceId:unsigned long| of the
+ [=list/indices=] of the [=touch surface list=] of the [=gamepad=]
+ represented by |gamepad|:
- - Let |surfaceId:unsigned long| be the current surface
- enumeration index.
+
- Let |surface| be the [=touch surface=] at index |surfaceId|
+ in the [=touch surface list=].
- - If the touch surface exposes maximum surface dimensions in
- device units, then set |touch|.{{GamepadTouch/surfaceDimensions}}
- to a {{DOMRectReadOnly}} with {{DOMRectReadOnly/width}} and
- {{DOMRectReadOnly/height}} initialized to the maximum X and Y
- dimensions on the touch surface in device units.
+
- If |surface| has surface dimensions, then set
+ |touch|.{{GamepadTouch/surfaceDimensions}} to a
+ {{DOMRectReadOnly}} with {{DOMRectReadOnly/width}} initialized to
+ the [=surface width=] and {{DOMRectReadOnly/height}} initialized
+ to the [=surface height=].
- - Repeat the following steps for each active touch point
- reported by the |gamepad| for the current touch surface.
+
- [=list/For each=] |point| in |surface|'s [=active touch point
+ list=]:
- Let |touch:GamepadTouch| be a newly created
{{GamepadTouch}} object.
- Set |touch|.{{GamepadTouch/surfaceId}} to be |surfaceId|.
- - If the touch data is part of an existing active touch
- point tracked by the user agent:
-
- - Set |touch|.{{GamepadTouch/touchId}} to the touchId
- of the active touch point.
-
- - Otherwise, set touchId to nextTouchId and increment
- nextTouchId.
-
- If the Gamepad has multiple touch surfaces the touch
- id will be unique across surfaces.
-
-
-
+ -
+
+ If |point| is [=part of an existing active touch point=],
+ set |touch|.{{GamepadTouch/touchId}} to the [=active
+ touch point id=].
+
+
+ Otherwise, set |touch|.{{GamepadTouch/touchId}} to
+ |gamepad|.{{Gamepad/[[nextTouchId]]}} and increment
+ |gamepad|.{{Gamepad/[[nextTouchId]]}}.
+
+
+ If the {{Gamepad}} has multiple [=touch surfaces=] the
+ {{GamepadTouch/touchId}} will be unique across surfaces.
+
- Set |touch|.{{GamepadTouch/position}} to a [=new=]
{{DOMPointReadOnly}} with {{DOMPointReadOnly/x}} initialized
- to device X coordinate relative to the device touch surface
- and normalized to [-1.0,1.0] where -1.0 is the leftmost
- coordinate and 1.0 is the rightmost coordinate and
- {{DOMPointReadOnly/y}} initialized to the device touch
- surface and normalized to [-1.0,1.0] where -1.0 is the
- leftmost coordinate and 1.0 is the rightmost coordinate.
-
- `x = (2.0 * touchData.x / surfaceDimensions.width) - 1`
-
+ to the [=touch x coordinate=] normalized to [-1 .. 1] where
+ -1 is the leftmost coordinate and 1 is the rightmost
+ coordinate and {{DOMPointReadOnly/y}} initialized to the
+ [=touch y coordinate=] normalized to [-1 .. 1] where -1 is
+ the topmost coordinate and 1 is the bottommost coordinate.
+ `x = (2.0 * touchData.x / surfaceDimensions.width) -
+ 1`
`y = (2.0 * touchData.y / surfaceDimensions.height) - 1`
- - Add |touch| to {{Gamepad}}.{{Gamepad/[[touches]]}}.
+
- [=list/Append=] |touch| to
+ |gamepad|.{{Gamepad/[[touches]]}}.
@@ -1007,64 +1010,60 @@
Constructing a `Gamepad`
- A new `Gamepad` representing a connected gamepad device is
- constructed by performing the following steps:
+ A new `Gamepad` representing an [=available=] [=gamepad=]
+ for a |window:Window| is constructed by performing the following
+ steps:
- Let |gamepad:Gamepad| be a newly created {{Gamepad}} instance:
- - Initialize |gamepad|'s {{Gamepad/id}} attribute to an
- identification string for the gamepad.
+
- Initialize |gamepad|'s {{Gamepad/id}} attribute to the
+ [=gamepad identifier string=] for the [=gamepad=].
- Initialize |gamepad|'s {{Gamepad/index}} attribute to the
- result of [=selecting an unused gamepad index=] for |gamepad|.
+ result of [=selecting an unused gamepad index=] given |window|.
- Initialize |gamepad|'s {{Gamepad/mapping}} attribute to the
- result of [=selecting a mapping=] for the gamepad device.
-
- - Initialize |gamepad|.{{Gamepad/[[connected]]}} to `true`.
-
- - Initialize |gamepad|.{{Gamepad/[[timestamp]]}} to the
- [=current high resolution time=].
-
- - Initialize |gamepad|.{{Gamepad/[[axes]]}} to the result of
- [=initializing axes=] for |gamepad|.
-
- - Initialize |gamepad|.{{Gamepad/[[buttons]]}} to the result of
- [=initializing buttons=] for |gamepad|.
-
- - Initialize |gamepad|.{{Gamepad/[[vibrationActuator]]}}
- following the steps of [=constructing a GamepadHapticActuator=]
- for |gamepad|.
+ result of [=selecting a mapping=] for the [=gamepad=].
+ - Set |gamepad|.{{Gamepad/[[timestamp]]}} to the [=current high
+ resolution time=] given |window|.
+
+ - Set |gamepad|.{{Gamepad/[[axes]]}} to the result of
+ [=initializing axes=] for |gamepad|.
+
+ - Set |gamepad|.{{Gamepad/[[buttons]]}} to the result of
+ [=initializing buttons=] for |gamepad|.
+
+ - If the [=gamepad=] has a [=vibration actuator=], set
+ |gamepad|.{{Gamepad/[[vibrationActuator]]}} to the result of
+ [=constructing a GamepadHapticActuator=] for the [=gamepad=]'s
+ [=vibration actuator=].
+
- Return |gamepad|.
To select an unused
- gamepad index for |gamepad:Gamepad|, run the following steps:
+ gamepad index given |window:Window|, run the following steps:
- - Let |navigator:Navigator| be |gamepad|'s [=relevant global
- object=]'s {{Navigator}} object.
-
- - Let |maxGamepadIndex:long| be the [=list/size=] of
- |navigator|.{{Navigator/[[gamepads]]}} − 1.
-
- - [=list/For each=] |gamepadIndex:long| of [=the range=] from 0 to
- |maxGamepadIndex|:
+
- [=list/For each=] |gamepadIndex:long| of the [=list/indices=] of
+ |window|.{{Window/navigator}}.{{Navigator/[[gamepads]]}}:
- - If |navigator|.{{Navigator/[[gamepads]]}}[|gamepadIndex|] is
- `null`, then return |gamepadIndex|.
+
- If
+ |window|.{{Window/navigator}}.{{Navigator/[[gamepads]]}}[|gamepadIndex|]
+ is `null`, then return |gamepadIndex|.
- - [=list/Append=] `null` to |navigator|.{{Navigator/[[gamepads]]}}.
+
- [=list/Append=] `null` to
+ |window|.{{Window/navigator}}.{{Navigator/[[gamepads]]}}.
- Return the [=list/size=] of
- |navigator|.{{Navigator/[[gamepads]]}} − 1.
+ |window|.{{Window/navigator}}.{{Navigator/[[gamepads]]}} − 1.
@@ -1072,33 +1071,18 @@
|gamepad:Gamepad|, run the following steps:
- - Let |inputCount:long| be the number of axis inputs exposed by the
- device represented by |gamepad|.
-
- - Set |gamepad|.{{Gamepad/[[axisMinimums]]}} to a [=list=] of
- {{unsigned long}} values with [=list/size=] equal to |inputCount|
- containing minimum logical values for each of the axis inputs.
-
- - Set |gamepad|.{{Gamepad/[[axisMaximums]]}} to a [=list=] of
- {{unsigned long}} values with [=list/size=] equal to |inputCount|
- containing maximum logical values for each of the axis inputs.
-
- - Initialize |unmappedInputList| to be an empty [=list=].
-
- - Initialize |mappedIndexList| to be an empty [=list=].
-
- - Initialize |axesSize:long| to be 0.
-
- - [=list/For each=] |rawInputIndex:long| of [=the range=] from 0 to
- |inputCount| − 1:
+
- [=list/For each=] |rawInputIndex:long| of the [=list/indices=] of
+ the [=axis list=] of the [=gamepad=] represented by |gamepad|:
- - If the the gamepad axis at index |rawInputIndex| [=represents
- a Standard Gamepad axis=]:
+
- Let |rawAxis| be the [=axis=] at index |rawInputIndex| of the
+ [=axis list=].
+
+ - If |rawAxis| [=represents a Standard Gamepad axis=]:
- Let |canonicalIndex:long| be the [=canonical index=] for
- the axis.
+ |rawAxis|.
- - If |mappedIndexList| [=list/contain=]s |canonicalIndex|,
+
- If |mappedIndexList| [=list/contains=] |canonicalIndex|,
then append |rawInputIndex| to |unmappedInputList|.
Otherwise:
@@ -1124,11 +1108,11 @@
- - Initialize |axisIndex:long| to be 0.
+
- Let |axisIndex:long| be 0.
- [=list/For each=] |rawInputIndex:long| of |unmappedInputList|:
- - While |mappedIndexList| [=list/contain=]s |axisIndex|:
+
- While |mappedIndexList| [=list/contains=] |axisIndex|:
- Increment |axisIndex|.
@@ -1144,7 +1128,7 @@
- - Initialize |axes| to be an empty [=list=].
+
- Let |axes| be an empty [=list=].
- [=list/For each=] |axisIndex:long| of [=the range=] from 0 to
|axesSize| − 1, [=list/append=] 0 to |axes|.
@@ -1153,35 +1137,20 @@
- To initialize buttons for a
- gamepad, run the following steps:
+ To initialize buttons for
+ |gamepad:Gamepad|, run the following steps:
- - Let |inputCount:long| be the number of button inputs exposed by
- the device represented by |gamepad|.
-
- - Set |gamepad|.{{Gamepad/[[buttonMinimums]]}} to be a [=list=] of
- {{unsigned long}} values with [=list/size=] equal to |inputCount|
- containing minimum logical values for each of the button inputs.
-
- - Set |gamepad|.{{Gamepad/[[buttonMaximums]]}} to be a [=list=] of
- {{unsigned long}} values with [=list/size=] equal to |inputCount|
- containing maximum logical values for each of the button inputs.
-
- - Initialize |unmappedInputList| to be an empty [=list=].
-
- - Initialize |mappedIndexList| to be an empty [=list=].
-
- - Initialize |buttonsSize:long| to be 0.
-
- - [=list/For each=] |rawInputIndex:long| of [=the range=] from 0 to
- |inputCount| − 1:
+
- [=list/For each=] |rawInputIndex:long| of the [=list/indices=] of
+ the [=button list=] of the [=gamepad=] represented by |gamepad|:
- - If the the gamepad button at index |rawInputIndex|
- [=represents a Standard Gamepad button=]:
+
- Let |rawButton| be the [=button=] at index |rawInputIndex| in
+ the [=button list=].
+
+ - If |rawButton| [=represents a Standard Gamepad button=]:
- Let |canonicalIndex:long| be the [=canonical index=] for
- the button.
+ |rawButton|.
- If |mappedIndexList| [=list/contain=]s |canonicalIndex|,
then append |rawInputIndex| to |unmappedInputList|.
@@ -1212,11 +1181,11 @@
- - Initialize |buttonIndex:long| to be 0.
+
- Let |buttonIndex:long| be 0.
- [=list/For each=] |rawInputIndex:long| of |unmappedInputList|:
- - While |mappedIndexList| [=list/contain=]s |buttonIndex|:
+
- While |mappedIndexList| [=list/contains=] |buttonIndex|:
- Increment |buttonIndex|.
@@ -1232,7 +1201,7 @@
- - Initialize |buttons| to be an empty [=list=].
+
- Let |buttons| be an empty [=list=].
- [=list/For each=] |buttonIndex:long| of [=the range=] from 0 to
|buttonsSize| − 1, [=list/append=] a [=new=] {{GamepadButton}} to
@@ -1248,8 +1217,8 @@
GamepadButton Interface
- This interface defines the state of an individual button on a gamepad
- device.
+ This interface defines the state of an individual [=button=] on a
+ [=gamepad=] at a single point in time.
[Exposed=Window]
@@ -1283,7 +1252,7 @@
`false`
- A flag indicating that the button is pressed
+ A flag indicating that the [=button=] is pressed
@@ -1294,7 +1263,7 @@
`false`
- A flag indicating that the button is touched
+ A flag indicating that the [=button=] is touched
@@ -1302,11 +1271,11 @@
[[\value]]
- 0.0
+ 0
- A {{double}} representing the button value scaled to the range [0.0
- .. 1.0]
+ A {{double}} in the range [0 .. 1] representing the degree to which
+ the [=button=] is activated
@@ -1316,14 +1285,15 @@
-
- The pressed state of the button. This property MUST be `true` if
- the button is currently pressed, and `false` if it is not pressed.
- For buttons which do not have a digital switch to indicate a pure
- pressed or released state, the [=user agent=] MUST choose a
+ Indicates whether the [=button=] is pressed. This property MUST be
+ `true` if the button is currently pressed, and `false` if it is not
+ pressed. For buttons which do not have a digital switch to indicate
+ a pure pressed or released state, the [=user agent=] MUST choose a
button press threshold to indicate the button as pressed
when its value is above a certain amount. If the platform API gives
- a recommended value, the user agent SHOULD use that. In other
- cases, the user agent SHOULD choose some other reasonable value.
+ a recommended value, the [=user agent=] SHOULD use that. In other
+ cases, the [=user agent=] SHOULD choose some other reasonable
+ value.
The {{GamepadButton/pressed}} getter steps are:
@@ -1338,14 +1308,16 @@
-
- The touched state of the button. If the button is capable of
- detecting touch, this property MUST be `true` if the button is
- currently being touched, and `false` otherwise. If the button is
- not capable of detecting touch and is capable of reporting an
- analog value, this property MUST be `true` if the value property is
- greater than 0, and `false` if the value is 0. If the button is not
- capable of detecting touch and can only report a digital value,
- this property MUST mirror the {{GamepadButton/pressed}} attribute.
+ Indicates whether the [=button=] is detecting any interaction,
+ including interactions that do not cause the button to activate. If
+ the [=button=] has a [=button touch value=],
+ {{GamepadButton/touched}} is the [=button touch value=]. If the
+ [=button=] does not have a [=button touch value=] but has an
+ [=analog button value=], {{GamepadButton/touched}} is `true` if the
+ current [=analog button value=] is greater than the [=logical
+ minimum=], otherwise `false`. If the [=button=] does not have
+ a [=button touch value=] or an [=analog button value=],
+ {{GamepadButton/touched}} mirrors {{GamepadButton/pressed}}.
The {{GamepadButton/touched}} getter steps are:
@@ -1360,12 +1332,15 @@
-
- For buttons that have an analog sensor, this property MUST
- represent the amount which the button has been pressed. All button
- values MUST be linearly normalized to the range [0.0 .. 1.0]. 0.0
- MUST mean fully unpressed, and 1.0 MUST mean fully pressed. For
- buttons without an analog sensor, only the values 0.0 and 1.0 for
- fully unpressed and fully pressed respectively, MUST be provided.
+ A value in the range [0 .. 1] representing the degree to which the
+ [=button=] is activated. For [=buttons=] that have an [=analog
+ button value=], this property MUST be the [=analog button value=]
+ clamped to the [=logical minimum=] and [=logical maximum=]
+ and then linearly normalized to the range [0 .. 1]. 0 MUST
+ mean fully unpressed, and 1 MUST mean fully pressed. For
+ [=buttons=] without an [=analog button value=], only the values 0
+ and 1 for fully unpressed and fully pressed respectively, MUST be
+ provided.
The {{GamepadButton/value}} getter steps are:
@@ -1382,12 +1357,11 @@
GamepadTouch Interface
- This interface defines a touch on a gamepad's touch surface that
- supports such input. The object consists of a touch
- {{GamepadTouch/touchId}} that uniquely identifies the touch point from
- the time the input medium (e.g. finger, stylus, etc) makes contact with
- the touch device, up to the time the input medium is no longer making
- contact with the touch device.
+ This interface represents a [=touch point=] on a [=touch surface=]. The
+ object consists of a {{GamepadTouch/touchId}} that uniquely identifies
+ the [=touch point=] from the time the input medium (e.g. finger,
+ stylus, etc) makes contact with the [=touch surface=], up to the time
+ the input medium is no longer making contact with the surface.
dictionary GamepadTouch {
@@ -1402,42 +1376,47 @@
touchId attribute
-
- Unique id of the touch. Range is [0, 4294967295].
+ Identifier shared by [=touch points=] that are [=part of an existing
+ active touch point=]. Range is [0 .. 4294967295].
-
- surfaceId
+ surfaceId attribute
-
- Unique id of the surface that generated the touch.
+ Identifier of the [=touch surface=] that generated the [=touch
+ point=].
-
- position
+ position attribute
-
- A {{DOMPointReadOnly}} which holds the {{DOMPointReadOnly/x}},
- {{DOMPointReadOnly/y}} coordinates of the touch. The z and w value
- are currently unused. The range of each coordinate is normalized to
- [-1.0, 1.0]. Along the x-axis, -1.0 references the leftmost
- coordinate and 1.0 references the rightmost coordinate. Along the
- y-axis, -1.0 references the topmost coordinate and 1.0 references the
- bottommost coordinate.
+ A {{DOMPointReadOnly}} which holds the normalized [=touch x
+ coordinate=] and [=touch y coordinate=] of the [=touch point=] as
+ {{DOMPointReadOnly/x}} and {{DOMPointReadOnly/y}}. The
+ {{DOMPointReadOnly/z}} and {{DOMPointReadOnly/w}} values are
+ currently unused. The range of each coordinate is normalized to [-1
+ .. 1]. Along the x-axis, -1 references the leftmost coordinate and 1
+ references the rightmost coordinate. Along the y-axis, -1 references
+ the topmost coordinate and 1 references the bottommost coordinate.
-
- surfaceDimensions
+ surfaceDimensions attribute
-
- A {{DOMRectReadOnly}} initialized with the {{DOMRectReadOnly/width}}
- and {{DOMRectReadOnly/height}} of the touch surface in integer units.
- If not available then
null.
+ A {{DOMRectReadOnly}} initialized with the [=surface width=] and
+ [=surface height=] of the [=touch surface=] as
+ {{DOMRectReadOnly/width}} and {{DOMRectReadOnly/height}}, if the
+ [=touch surface=] has surface dimensions. Otherwise, `null`.
- This enum defines the set of known mappings for a Gamepad. + This enum defines the mapping types for mapping from a [=gamepad=] to a + {{Gamepad}}.
enum GamepadMappingType {
@@ -1451,23 +1430,27 @@
""
- The empty string indicates that no mapping is in use for this
- gamepad.
+ The empty string indicates that the [=gamepad=] does not have an
+ [=input control layout=], or the [=user agent=] does not know the
+ [=gamepad=]'s [=input control layout=], or the layout [=corresponds
+ with=] none of the standard layouts. The {{Gamepad/axes}} and
+ {{Gamepad/buttons}} arrays are not reordered.
"standard"
- The Gamepad's controls have been mapped to the [=Standard Gamepad=]
- layout.
+ The [=gamepad=]'s [=input control layout=] [=corresponds with=] the
+ [=Standard Gamepad=] layout. The {{Gamepad/axes}} and
+ {{Gamepad/buttons}} arrays are reordered.
"xr-standard"
- The Gamepad's controls have been mapped to the [="xr-standard"
+ The [=gamepad=]'s controls have been mapped to the [="xr-standard"
gamepad mapping=]. This mapping is reserved for use by the
- [[[webxr-gamepads-module-1]]]. Gamepads returned by
+ [[[webxr-gamepads-module-1]]]. {{Gamepad}} objects returned by
{{Navigator/getGamepads()}} MUST NOT report a {{Gamepad/mapping}} of
{{GamepadMappingType/"xr-standard"}}.
@@ -1479,9 +1462,9 @@
GamepadHapticActuator Interface
- A {{GamepadHapticActuator}} corresponds to a configuration of motors or
- other actuators that can apply a force for the purposes of haptic
- feedback.
+ This interface represents a [=haptic actuator=] capable of playing
+ [=haptic effects=] that move the [=gamepad=] in a way that can be felt
+ by the user.
[Exposed=Window]
@@ -1542,10 +1525,11 @@
Array of {{Gamepad/GamepadHapticEffectType}} values representing
- all the types of haptic effects that the actuator supports. This
- property lists the {{Gamepad/GamepadHapticEffectType}} values that
- the actuator supports, unless the [=user agent=] does not support
- playing effects of that type.
+ all the types of [=haptic effects=] that the
+ {{GamepadHapticActuator}} supports. This property lists the
+ {{Gamepad/GamepadHapticEffectType}} values that the actuator
+ supports, unless the [=user agent=] does not support playing
+ effects of that type.
The {{GamepadHapticActuator/effects}} getter steps are:
@@ -1562,20 +1546,25 @@
The {{GamepadHapticActuator/playEffect()}} method steps, called
with {{GamepadHapticEffectType}} |type:GamepadHapticEffectType| and
- {{GamepadEffectParameters}} |params:GamepadEffectParameters |, are:
+ {{GamepadEffectParameters}} |params:GamepadEffectParameters|, are:
- If |params:GamepadEffectParameters| does not describe a [=valid
effect=] of type |type:GamepadHapticEffectType|, return [=a promise
rejected with=] a {{TypeError}}.
- - Let |document:Document?| be the [=current settings object=]'s
- [=relevant global object=]'s [=associated `Document`=].
+
- If the [=current global object=] is not a {{Window}}, return
+ [=a promise rejected with=] an "{{InvalidStateError}}"
+ {{DOMException}}.
+
+ - Let |window:Window| be the [=current global object=].
- - If |document| is `null` or |document| is not [=Document/fully
- active=] or |document|'s [=Document/visibility state=] is
- `"hidden"`, return [=a promise rejected with=] an
- "{{InvalidStateError}}" {{DOMException}}.
+
- Let |document:Document| be the |window|'s [=associated
+ `Document`=].
+
+ - If |document| is not [=Document/fully active=] or |document|'s
+ [=Document/visibility state=] is `"hidden"`, return [=a promise
+ rejected with=] an "{{InvalidStateError}}" {{DOMException}}.
- If [=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}}
is not `null`:
@@ -1587,33 +1576,32 @@
[=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}} to
`null`.
- - [=Queue a global task=] on the [=relevant global object=]
- of [=this=] using the [=gamepad task source=] to [=resolve=]
- |effectPromise| with {{GamepadHapticsResult/"preempted"}}.
+
- [=Queue a global task=] on the [=gamepad task source=] with
+ |window| to [=resolve=] |effectPromise| with
+ {{GamepadHapticsResult/"preempted"}}.
- If |this|'s gamepad's actuator cannot [=play effects with
- type=] |type|, return [=a promise rejected with=] reason
+ If [=this=] {{GamepadHapticActuator}} cannot [=play effects
+ with type=] |type|, return [=a promise rejected with=] reason
{{NotSupportedError}}.
Let {{GamepadHapticActuator/[[playingEffectPromise]]}} be [=a
new promise=].
- Let |playEffectTimestamp:DOMHighResTimestamp| be the [=current
- high resolution time=] given the |document|'s [=relevant global
- object=].
+ Let |playEffectTimestamp:DOMHighResTimeStamp| be the [=current
+ high resolution time=] given |window|.
Do the following steps [=in parallel=]:
- - [=Issue a haptic effect=] to the actuator with |type|,
- |params|, and the |playEffectTimestamp|.
+
- [=Play a haptic effect=] on the [=haptic actuator=]
+ represented by [=this=] with |type|, |params|, and the
+ |playEffectTimestamp|.
- When the effect completes, if
[=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}} is
- not `null`, [=queue a global task=] on the [=relevant global
- object=] of [=this=] using the [=gamepad task source=] to run
- the following steps:
+ not `null`, [=queue a global task=] on the [=gamepad task
+ source=] with |window| to run the following steps:
- If
[=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}}
@@ -1643,13 +1631,18 @@
The {{GamepadHapticActuator/reset()}} method steps are:
- - Let |document:Document?| be the [=current settings object=]'s
- [=relevant global object=]'s [=associated `Document`=].
+
- If the [=current global object=] is not a {{Window}}, return
+ [=a promise rejected with=] an "{{InvalidStateError}}"
+ {{DOMException}}.
+
+ - Let |window:Window| be the [=current global object=].
- - If |document| is `null` or |document| is not [=Document/fully
- active=] or |document|'s [=Document/visibility state=] is
- `"hidden"`, return [=a promise rejected with=] an
- "{{InvalidStateError}}" {{DOMException}}.
+
- Let |document:Document| be |window|'s [=associated
+ `Document`=].
+
+ - If |document| is not [=Document/fully active=] or |document|'s
+ [=Document/visibility state=] is `"hidden"`, return [=a promise
+ rejected with=] an "{{InvalidStateError}}" {{DOMException}}.
- Let |resetResultPromise:Promise| be [=a new promise=].
@@ -1659,7 +1652,8 @@
- Let |effectPromise| be
[=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}}.
- - [=Stop haptic effects=] on [=this=]'s gamepad's actuator.
+
- [=Stop haptic effects=] on the [=haptic actuator=]
+ represented by [=this=] {{GamepadHapticActuator}}.
- If the effect has been successfully stopped, do:
@@ -1669,9 +1663,8 @@
[=this=].{{GamepadHapticActuator/[[playingEffectPromise]]}}
to `null`.
- - [=Queue a global task=] on the [=relevant global
- object=] of [=this=] using the [=gamepad task source=] to
- [=resolve=] |effectPromise| with
+
- [=Queue a global task=] on [=gamepad task source=] with
+ |window| to [=resolve=] |effectPromise| with
{{GamepadHapticsResult/"preempted"}}.
@@ -1721,56 +1714,70 @@
- To issue a haptic effect on an actuator, the [=user agent=]
- MUST send a command to the device to render an effect of
- |type:GamepadHapticEffectType| and try to make it use the provided
- |params:GamepadEffectParameters|. The [=user agent=] SHOULD use the
- provided |playEffectTimestamp:DOMHighResTimestamp| for more precise
- playback timing when |params|.{{GamepadEffectParameters/startDelay}} is
- not `0.0`. The [=user agent=] MAY modify the effect to increase
- compatibility. For example, an effect intended for a rumble motor may
- be transformed into a waveform-based effect for a device that supports
- waveform haptics but lacks rumble motors.
+ To play a haptic effect on a [=haptic actuator=], the [=user
+ agent=] MUST command the [=haptic actuator=] to render a [=haptic
+ effect=] of |type:GamepadHapticEffectType| and try to make it use the
+ provided |params:GamepadEffectParameters|. The [=user agent=] SHOULD
+ use the provided |playEffectTimestamp:DOMHighResTimeStamp| for more
+ precise playback timing when
+ |params|.{{GamepadEffectParameters/startDelay}} is not 0. The [=user
+ agent=] MAY modify the effect to increase compatibility. For example,
+ an effect intended for a rumble motor may be transformed into a
+ waveform-based effect for a device that supports waveform haptics but
+ lacks rumble motors.
- To stop haptic effects on an actuator, the [=user agent=]
- MUST send a command to the device to abort any effects currently being
- played. If a haptic effect was interrupted, the actuator SHOULD return
- to a motionless state as quickly as possible.
+ To stop haptic effects on a [=haptic actuator=], the [=user
+ agent=] MUST command the [=haptic actuator=] to abort any effects
+ currently being played on that actuator. If a [=haptic effect=] was
+ interrupted, the actuator SHOULD return to a motionless state as
+ quickly as possible.
Handling visibility change
- When the |document|'s [=Document/visibility state=] becomes
- `"hidden"`, run these steps for each {{GamepadHapticActuator}}
- |actuator:GamepadHapticActuator|:
+ When the |document:Document|'s [=Document/visibility state=] becomes
+ `"hidden"`, run these steps:
- - If |actuator|.{{GamepadHapticActuator/[[playingEffectPromise]]}}
- is `null`, abort these steps.
+
- Let |window:Window| be |document|'s [=relevant global object=].
- - [=Queue a global task=] on the [=relevant global object=] of
- |actuator| using the [=gamepad task source=] to run the following
- steps:
+
- [=list/For each=] |gamepad:Gamepad?| of
+ |window|.{{Window/navigator}}.{{Navigator/[[gamepads]]}}:
+ - If |gamepad| is `null`, continue.
+
+ - If |gamepad|.{{Gamepad/vibrationActuator}} is `null`,
+ continue.
+
- If
- |actuator|.{{GamepadHapticActuator/[[playingEffectPromise]]}} is
- `null`, abort these steps.
+ |gamepad|.{{Gamepad/vibrationActuator}}.{{GamepadHapticActuator/[[playingEffectPromise]]}}
+ is `null`, continue.
- - [=Resolve=]
- |actuator|.{{GamepadHapticActuator/[[playingEffectPromise]]}}
- with {{GamepadHapticsResult/"preempted"}}.
+
- [=Queue a global task=] on the [=gamepad task source=] with
+ |window| to run the following steps:
+
+ - If
+ |gamepad|.{{Gamepad/vibrationActuator}}.{{GamepadHapticActuator/[[playingEffectPromise]]}}
+ is `null`, abort these steps.
+
+ - [=Resolve=]
+ |gamepad|.{{Gamepad/vibrationActuator}}.{{GamepadHapticActuator/[[playingEffectPromise]]}}
+ with {{GamepadHapticsResult/"preempted"}}.
+
+ - Set
+ |gamepad|.{{Gamepad/vibrationActuator}}.{{GamepadHapticActuator/[[playingEffectPromise]]}}
+ to `null`.
+
+
- - Set
- |actuator|.{{GamepadHapticActuator/[[playingEffectPromise]]}} to
- `null`.
+
- [=Stop haptic effects=] on the [=haptic actuator=]
+ represented by |gamepad|.{{Gamepad/vibrationActuator}}.
- - [=Stop haptic effects=] on |actuator|.
-
@@ -1780,22 +1787,19 @@
A new
|gamepadHapticActuator:GamepadHapticActuator| representing a
- {{Gamepad}}'s primary vibration actuator is constructed by performing
- the following steps:
+ [=gamepad=]'s [=vibration actuator=] is constructed by performing the
+ following steps:
- Let |gamepadHapticActuator:GamepadHapticActuator| be a newly
created {{GamepadHapticActuator}} instance.
- - Let `supportedEffectsList` be an empty list.
+
- Set |gamepadHapticActuator|.{{GamepadHapticActuator/[[effects]]}}
+ to the [=supported effect types=] for the [=vibration actuator=].
- - For each enum value |type:GamepadHapticEffectType| of
- {{GamepadHapticEffectType}}, if the [=user agent=] can send a command
- to initiate effects of that type on that actuator, append |type| to
- `supportedEffectsList`.
+
- Return |gamepadHapticActuator|.
- - Set |gamepadHapticActuator|.{{GamepadHapticActuator/[[effects]]}}
- to `supportedEffectsList`.
+
- Return |gamepadHapticActuator|.
@@ -1816,7 +1820,7 @@
-
- The haptic effected completed playing.
+ The [=haptic effect=] completed playing.
-
@@ -1824,19 +1828,20 @@
-
- The current effect was stopped or replaced (i.e., "preempted") by
- another effect.
+ The current [=haptic effect=] was stopped or replaced (i.e.,
+ "preempted") by another effect.
- The effect type defines how the effect parameters are interpreted by - the actuator. + Each value represents a different style of [=haptic effect=]. The + effect type defines how to generate a [=haptic effect=] from the + {{GamepadEffectParameters}}.
enum GamepadHapticEffectType {
@@ -1852,10 +1857,10 @@
{{GamepadHapticEffectType/"dual-rumble"}} describes a haptic
configuration with an eccentric rotating mass (ERM) vibration motor
- in each handle of a standard gamepad. In this configuration, either
- motor is capable of vibrating the whole gamepad. The vibration
+ in each handle of a [=gamepad=]. In this configuration, either
+ motor is capable of vibrating the whole [=gamepad=]. The vibration
effects created by each motor are unequal so that the effects of
- each can be combined to create more complex haptic effects.
+ each can be combined to create more complex [=haptic effects=].
A {{GamepadHapticEffectType/"dual-rumble"}} effect is a
@@ -1871,7 +1876,7 @@
{{GamepadEffectParameters/strongMagnitude}} and
{{GamepadEffectParameters/weakMagnitude}} set the intensity levels
for the low-frequency and high-frequency vibrations, normalized to
- the range `[0,1]`, defaulting to 0.
+ the range [0 .. 1], defaulting to 0.
Given {{GamepadEffectParameters}} |params:GamepadEffectParameters|,
@@ -1879,8 +1884,8 @@
effect|valid=] {{GamepadEffectParameters/duration}}, a [=valid
effect|valid=] {{GamepadEffectParameters/startDelay}}, and both the
{{GamepadEffectParameters/strongMagnitude}} and the
- {{GamepadEffectParameters/weakMagnitude}} must be in the range
- `[0,1]`.
+ {{GamepadEffectParameters/weakMagnitude}} must be in the range [0
+ .. 1].
@@ -1918,7 +1923,7 @@
{{GamepadEffectParameters/leftTrigger}} and
{{GamepadEffectParameters/rightTrigger}}, respectively, set the
intensity levels for the left and right bottom front buttons
- vibrations, normalized to the range `[0,1]`, defaulting to 0.
+ vibrations, normalized to the range [0 .. 1], defaulting to 0.
Given {{GamepadEffectParameters}} |params:GamepadEffectParameters|,
@@ -1928,8 +1933,8 @@
{{GamepadEffectParameters/strongMagnitude}},
{{GamepadEffectParameters/weakMagnitude}},
{{GamepadEffectParameters/leftTrigger}}, and
- {{GamepadEffectParameters/rightTrigger}} must be in the range
- `[0,1]`.
+ {{GamepadEffectParameters/rightTrigger}} must be in the range [0 ..
+ 1].
@@ -1939,9 +1944,9 @@
GamepadEffectParameters Dictionary
- A GamepadEffectParameters dictionary contains keys for
- parameters used by haptic effects. The meaning of each key is defined
- by the haptic effect, and some keys may be unused.
+ A `GamepadEffectParameters` dictionary contains keys for parameters
+ used by [=haptic effects=]. The meaning of each key is defined by the
+ haptic effect type, and some keys may be unused.
To mitigate unwanted long-running effects, the [=user agent=] MAY limit
@@ -2076,9 +2081,11 @@
Each device manufacturer creates many different products and each has - unique styles and layouts of buttons and axes. It is intended that the + unique styles and [=input control layouts=]. It is intended that the [=user agent=] support as many of these as possible.
@@ -2220,35 +2230,36 @@
- The [=Standard Gamepad=] buttons are laid out in a left cluster of four - buttons, a right cluster of four buttons, a center cluster of three - buttons, and a pair of front facing buttons on the left and right side - of the gamepad. The four axes of the "Standard Gamepad" are associated - with a pair of analog sticks, one on the left and one on the right. The - following table describes the buttons/axes and their physical - locations. + The [=Standard Gamepad=] [=buttons=] are laid out in a left cluster of + four [=buttons=], a right cluster of four [=buttons=], a center cluster + of three [=buttons=], and a pair of front facing [=buttons=] on the + left and right side of the [=gamepad=]. The four [=axis=] inputs of the + "Standard Gamepad" are associated with a pair of analog sticks, one on + the left and one on the right. The following table describes the input + controls and their physical locations.
- An axis input represents a Standard Gamepad axis if it - reports the input value for a thumbstick axis, the thumbstick is + An [=axis=] input represents a Standard Gamepad axis if it + reports the [=input values=] for a thumbstick axis, the thumbstick is located in approximately the same location as the corresponding - [=Standard Gamepad=] thumbstick, and the orientation of the axis + [=Standard Gamepad=] thumbstick, and the orientation of the [=axis=] (up-down or left-right) matches the orientation of the [=Standard - Gamepad=] axis. If there are multiple axes that represent the same - [=Standard Gamepad=] axis, then the [=user agent=] SHOULD select one to - be the [=Standard Gamepad=] axis and assign a different index to the - other axis. + Gamepad=] [=axis=]. If there are multiple [=axis=] inputs that + represent the same [=Standard Gamepad=] [=axis=], then the [=user + agent=] SHOULD select one to be the [=Standard Gamepad=] [=axis=] and + assign a different index to the other [=axis=].
- A button input represents a Standard Gamepad button if it - reports the input value for a button or trigger, and the button or - trigger is located in approximately the same location as the - corresponding [=Standard Gamepad=] button. + A [=button=] input represents a Standard Gamepad button if + it reports the [=input values=] for a button or trigger, and the button + or trigger is located in approximately the same location as the + corresponding [=Standard Gamepad=] button or trigger.
- If an axis or button input represents a [=Standard Gamepad=] axis or - button, then its canonical index - is the index of the corresponding [=Standard Gamepad=] axis or button. + If an [=axis=] or [=button=] input represents a [=Standard Gamepad=] + [=axis=] or [=button=], then its canonical index is the index of the + corresponding [=Standard Gamepad=] [=axis=] or [=button=].