- A {{GamepadHapticActuator}} corresponds to a configuration of motors or - other actuators that can apply a force for the purposes of haptic - feedback. -
-
- [Exposed=Window]
- interface GamepadHapticActuator {
- readonly attribute GamepadHapticActuatorType type;
- boolean canPlayEffectType(GamepadHapticEffectType type);
- Promise<GamepadHapticsResult> playEffect(
- GamepadHapticEffectType type,
- optional GamepadEffectParameters params = {});
- Promise<boolean> pulse(double value, double duration);
- Promise<GamepadHapticsResult> reset();
- };
-
- - Instances of {{GamepadHapticActuator}} are created with the internal - slots described in the following table: -
-| - Internal slot - | -- Initial value - | -- Description (non-normative) - | -
|---|---|---|
| - [[\playingEffectPromise]] - | -- `undefined` - | -- The {{Promise}} for the playing effect, or `undefined` if no effect - is playing. - | -
- A {{GamepadHapticActuatorType}} value representing the actuator - type. -
-- The {{GamepadHapticActuator/canPlayEffectType()}} method steps are: -
-- The {{GamepadHapticActuator/playEffect()}} method steps are: -
-
- pulse() applies a value to the actuator for
- duration milliseconds. The value passed to
- pulse() is clamped to limits defined by the actuator
- type. The returned Promise will resolve true once the
- pulse has completed.
-
- Repeated calls to pulse() override the previous
- values.
-
- The {{GamepadHapticActuator/reset()}} method steps are: -
-- Add new steps to [=a new `Gamepad`=]: -
-- A new `GamepadHapticActuator` with - |type:GamepadHapticEffectType| is constructed by performing the - following steps: -
-- This specification defines an [=external now hidden algorithm=]. - When the |document|'s [=visibility state=] becomes `"hidden"`, run - these steps for each {{GamepadHapticActuator}} - |actuator:GamepadHapticActuator|: -
-- A {{GamepadHapticActuator}} can play effects with type - |type:GamepadHapticEffectType| if the [=user agent=] can send a command - to initiate effects of that type on that actuator. -
-- An effect with {{GamepadHapticEffectType}} - |type:GamepadHapticEffectType| and {{GamepadEffectParameters}} - |params:GamepadEffectParameters| describes a valid effect if - |params| contains all of the required parameters for |type| effects and - all of the parameters have valid values. Additional parameters MUST be - ignored. -
-- A [=user agent=] that implements this API MUST provide a method to - issue a haptic effect to an actuator with - |type:GamepadHapticEffectType| and |params:GamepadEffectParameters|. - 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. -
-- A [=user agent=] that implements this API MUST provide a method to - stop haptic effects on an actuator. When called, if there is - a playing haptic effect, the [=user agent=] MUST send a command to the - device to stop the effect. If a haptic effect was interrupted, the - actuator SHOULD return to a motionless state as quickly as possible. -
-- An enum representing the result of a call to - {{GamepadHapticActuator}}.{{GamepadHapticActuator/playEffect()}} or - {{GamepadHapticActuator}}.{{GamepadHapticActuator/reset()}}. -
-
- enum GamepadHapticsResult {
- "complete",
- "preempted"
- };
-
- - The value the {{Promise}} returned by - {{GamepadHapticActuator}}.{{GamepadHapticActuator/playEffect()}} - or {{GamepadHapticActuator}}.{{GamepadHapticActuator/reset()}} - will resolve to when the effect completes normally. -
-- The value the {{Promise}} returned by - {{GamepadHapticActuator}}.{{GamepadHapticActuator/playEffect()}} - or {{GamepadHapticActuator}}.{{GamepadHapticActuator/reset()}} - will resolve to when the operation does not complete because the - {{Document}} is [=Document/hidden=] or another effect was started - on the same actuator. -
-- An enum value identifying the actuator type. Deprecated in order to - allow the [=user agent=] to define compatibility between actuators - and effects. Applications are expected to use - {{GamepadHapticActuator}}.{{GamepadHapticActuator/canPlayEffectType()}} - for capability detection. -
-
- enum GamepadHapticActuatorType {
- "vibration",
- "dual-rumble"
- };
-
- - The value of - {{GamepadHapticActuator}}.{{GamepadHapticActuator/type}} for an - actuator that is exposed as an element of - {{Gamepad}}.{{Gamepad/hapticActuators}}. -
-- The value of - {{GamepadHapticActuator}}.{{GamepadHapticActuator/type}} for an - actuator that is exposed as - {{Gamepad}}.{{Gamepad/vibrationActuator}}. -
-- The effect type defines how the effect parameters are interpreted by - the actuator. -
-- The [=user agent=] MAY modify the behavior of - {{GamepadHapticActuator}}.{{GamepadHapticActuator/playEffect}} to - extend support for new {{GamepadHapticEffectType}} values and - {{GamepadEffectParameter}} attributes. Implementations MUST NOT - modify the definition of a [=valid effect=] for effect types defined - in this specification. -
-
- enum GamepadHapticEffectType {
- "dual-rumble"
- };
-
- - {{GamepadHapticEffectType/"dual-rumble"}} describes a haptics - 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 effects created by each motor are unequal - so that the effects of each can be combined to create more - complex haptic effects. -
-- A {{GamepadHapticEffectType/"dual-rumble"}} effect is a - fixed-length, constant-intensity vibration effect intended for an - actuator of this type. {{GamepadHapticEffectType/"dual-rumble"}} - effects are defined by {{GamepadEffectParameters/startDelay}}, - {{GamepadEffectParameters/duration}}, - {{GamepadEffectParameters/strongMagnitude}}, and - {{GamepadEffectParameters/weakMagnitude}}, none of which are - required. -
-- {{GamepadEffectParameters/startDelay}} and - {{GamepadEffectParameters/duration}} set the duration of the - initial delay before after initiating the effect before the - effect will be started -
-- {{GamepadEffectParameters/startDelay}} sets the duration of the - delay after {{GamepadHapticActuator/playEffect()}} is called - until vibration is started, in milliseconds. During the delay - interval, the actuator must not vibrate. An effect with negative - {{GamepadEffectParameters/startDelay}} is not a [=valid effect=]. - If the {{GamepadEffectParameters/startDelay}} is not specified, - the default delay is 0 milliseconds. -
-- {{GamepadEffectParameters/duration}} sets the duration in - milliseconds that the actuator will vibrate. If - {{GamepadEffectParameters/duration}} is not specified, the - default duration is 0 milliseconds. -
-- {{GamepadEffectParameters/strongMagnitude}} and - {{GamepadEffectParameters/weakMagnitude}} set the vibration - intensity levels for the low-frequency and high-frequency rumble - motors, normalized to the range `[0,1]`, default 0. An effect - with magnitude values outside of this range is not a [=valid - effect=]. -
-
- 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.
-
- To mitigate unwanted long-running effects, the [=user agent=] MAY - limit the total effect duration for a [=valid effect=] to some - maximum duration. It is RECOMMENDED that the [=user agent=] use a - maximum of 5 seconds. -
-
- dictionary GamepadEffectParameters {
- double duration = 0.0;
- double startDelay = 0.0;
- double strongMagnitude = 0.0;
- double weakMagnitude = 0.0;
- };
-
- @@ -993,13 +472,6 @@
+ This partial interface supplements the {{GamepadHapticActuator}} + interface described in the main + Gamepad spec. +
+
+ [Exposed=Window]
+ partial interface GamepadHapticActuator {
+ Promise<boolean> pulse(double value, double duration);
+ };
+
+
+ {{GamepadHapticActuator/pulse()}} applies a |value:double| to the
+ actuator for duration milliseconds. The value
+ passed to pulse() is clamped to limits defined by the
+ actuator type. The returned Promise will resolve true
+ once the pulse has completed.
+
+ Repeated calls to pulse() override the previous
+ values.
+
@@ -301,6 +302,18 @@
+ A {{GamepadHapticActuator}} object that represents the device's + primary vibration actuator. +
++ The {{Gamepad/vibrationActuator}} getter steps are: +
++ A {{GamepadHapticActuator}} corresponds to a configuration of motors or + other actuators that can apply a force for the purposes of haptic + feedback. +
+
+ [Exposed=Window]
+ interface GamepadHapticActuator {
+ [SameObject] readonly attribute FrozenArray<GamepadHapticEffectType> effects;
+ Promise<GamepadHapticsResult> playEffect(
+ GamepadHapticEffectType type,
+ optional GamepadEffectParameters params = {}
+ );
+ Promise<GamepadHapticsResult> reset();
+ };
+
+ + Instances of {{GamepadHapticActuator}} are created with the internal + slots described in the following table: +
+| + Internal slot + | ++ Initial value + | ++ Description + | +
|---|---|---|
| + [[\effects]] + | ++ An empty [=list=] of {{Gamepad/GamepadHapticEffectType}}. + | ++ Represents the effects supported by the actuator. + | +
| + [[\playingEffectPromise]] + | ++ `null` + | ++ The {{Promise}} to play some effect, or `null` if no effect is + playing. + | +
+ 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. +
++ The {{GamepadHapticActuator/effects}} getter steps are: +
++ The {{GamepadHapticActuator/playEffect()}} method steps, called with + {{GamepadHapticEffectType}} |type:GamepadHapticEffectType| and + {{GamepadEffectParameters}} |params:GamepadEffectParameters |, are: +
++ The {{GamepadHapticActuator/reset()}} method steps are: +
++ A {{GamepadHapticActuator}} can play effects with type + |type:GamepadHapticEffectType| if |type:GamepadHapticEffectType| can be + found in the {{GamepadHapticActuator/[[effects]]}} [=list=]. +
++ To check if an effect with {{GamepadHapticEffectType}} + |type:GamepadHapticEffectType| and {{GamepadEffectParameters}} + |params:GamepadEffectParameters| describes a valid effect, + run the following steps: +
++ 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|.{{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 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. +
++ When the |document|'s [=Document/visibility state=] becomes `"hidden"`, run + these steps for each {{GamepadHapticActuator}} + |actuator:GamepadHapticActuator|: +
++ A new + |gamepadHapticActuator:GamepadHapticActuator| representing a + {{Gamepad}}'s primary vibration actuator is constructed by + performing the following steps: +
+
+ enum GamepadHapticsResult {
+ "complete",
+ "preempted"
+ };
+
+ + The haptic effected completed playing. +
++ The current effect was stopped or replaced (i.e., "preempted") by + another effect. +
++ The effect type defines how the effect parameters are interpreted by + the actuator. +
+
+ enum GamepadHapticEffectType {
+ "dual-rumble"
+ };
+
+ + {{GamepadHapticEffectType/"dual-rumble"}} describes a haptics + 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 effects created by each motor are unequal + so that the effects of each can be combined to create more + complex haptic effects. +
++ A {{GamepadHapticEffectType/"dual-rumble"}} effect is a + fixed-duration, constant-intensity vibration effect intended for an + actuator of this type. {{GamepadHapticEffectType/"dual-rumble"}} + effects are defined by {{GamepadEffectParameters/startDelay}}, + {{GamepadEffectParameters/duration}}, + {{GamepadEffectParameters/strongMagnitude}}, and + {{GamepadEffectParameters/weakMagnitude}}, none of which are + required because they default to 0. +
++ {{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. +
++ Given {{GamepadEffectParameters}} |params:GamepadEffectParameters|, + a valid dual-rumble effect must have a valid + duration, a valid startDelay, and both the + {{GamepadEffectParameters/strongMagnitude}} and the + {{GamepadEffectParameters/weakMagnitude}} must be in the range + `[0,1]`. +
+
+ 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.
+
+ To mitigate unwanted long-running effects, the [=user agent=] MAY + limit the total effect duration for a [=valid effect=] to some + maximum duration. It is RECOMMENDED that the [=user agent=] use a + maximum of 5 seconds. +
+
+ dictionary GamepadEffectParameters {
+ unsigned long long duration = 0;
+ unsigned long long startDelay = 0;
+ double strongMagnitude = 0.0;
+ double weakMagnitude = 0.0;
+ };
+
+