Skip to content

Commit

Permalink
Merge pull request #168 from bradleyneedham/gh-pages
Browse files Browse the repository at this point in the history 
Enhance Gamepad interface description for Touch
  • Loading branch information
@nondebug
nondebug authored Oct 5, 2023
2 parents bb37e81 + ce87f1a commit 7a89897
Showing 1 changed file with 256 additions and 13 deletions.
269 changes: 256 additions & 13 deletions extensions.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -95,8 +95,7 @@
// document unless you know what you're doing. If in doubt ask your friendly neighbourhood
// Team Contact.
wgPatentURI: "https://www.w3.org/2004/01/pp-impl/83482/status",

xref: ["DOM", "HTML", "INFRA", "gamepad"],
xref: ["HTML", "DOM", "PERMISSIONS-POLICY", "HR-TIME", "INFRA", "gamepad"],
};
</script>
<style>
Expand Down Expand Up @@ -608,6 +607,12 @@ <h3>
{{GamepadEffectParameters/weakMagnitude}}, none of which are
required.
</p>
<p>
{{GamepadEffectParameters/startDelay}} and
{{GamepadEffectParameters/duration}} set the duration of the
initial delay before after initiating the effect before the
effect will be started
</p>
<p>
{{GamepadEffectParameters/startDelay}} sets the duration of the
delay after {{GamepadHapticActuator/playEffect()}} is called
Expand Down Expand Up @@ -831,9 +836,14 @@ <h2>
<dfn>touchId</dfn> attribute
</dt>
<dd>
Unique id of the touch event. Range is [0, 4294967295]. The user
agent is responsible for incrementing the touchId for each subsequent
touch event based on information provided by the device API.
Unique id of the touch event. Range is [0, 4294967295].
<p>The user agent is responsible for:</p>
<ul>
<li>Incrementing the id for each subsequent touch event based
on information provided by the device API.</li>
<li>Maintaining the uniqueness of the id per origin to
prevent fingerprinting.</li>
</ul>
{{GamepadTouch/touchId}} SHOULD be set to a default value of 0 when a
new {{Gamepad}} object is created.
</dd>
Expand Down Expand Up @@ -879,37 +889,109 @@ <h2>
[SameObject] readonly attribute GamepadHapticActuator? vibrationActuator;
};
</pre>
<p>
Instances of {{Gamepad}} are created with the internal slots described
in the following table:
</p>
<table class="simple">
<tr>
<th>
Internal slot
</th>
<th>
Initial value
</th>
<th>
Description (non-normative)
</th>
</tr>
<tr>
<td>
<dfn data-dfn-for="Gamepad">[[\hand]]</dfn>
</td>
<td>
`undefined`
</td>
<td>
Indicates the hand the controller is held in.
</td>
</tr>
<tr>
<td>
<dfn data-dfn-for="Gamepad">[[\hapticActuators]]</dfn>
</td>
<td>
`undefined`
</td>
<td>
List of all the haptic actuators in the gamepad.
</td>
</tr>
<tr>
<td>
<dfn data-dfn-for="Gamepad">[[\pose]]</dfn>
</td>
<td>
`null`
</td>
<td>
The current pose of the gamepad.
</td>
</tr>
<tr>
<td>
<dfn data-dfn-for="Gamepad">[[\touchEvents]]</dfn>
</td>
<td>
`null`
</td>
<td>
List of generated touch events.
</td>
</tr>
</table>
<dl data-dfn-for="Gamepad">
<dt>
<dfn>hand</dfn>
</dt>
<dd>
Describes the hand the controller is held in or is most likely to be
held in.
An enumeration, {{GamepadHand}}, that indicates which hand the controller
is being held in or is most likely to be held in.
</dd>
<dt>
<dfn>hapticActuators</dfn>
</dt>
<dd>
A list of all the haptic actuators in the gamepad. The same object
A list of all the {{GamepadHapticActuator}}s in the gamepad. The same object
MUST be returned until the user agent needs to return different
values (or values in a different order).
</dd>
<dt>
<dfn>pose</dfn>
</dt>
<dd>
The current pose of the gamepad, if supported by the hardware.
The current {{GamepadPose}} of the gamepad, if supported by the hardware.
Includes position, orientation, velocity, and acceleration. If the
hardware cannot supply any pose values, MUST be set to
<code>null</code>.
hardware cannot supply any pose values, MUST be set to `null`.
</dd>
<dt>
<dfn>touchEvents</dfn>
</dt>
<dd>
A list of touch events generated from all touch surfaces.
<code>null</code> if the device does not support touch events.
<p>
A list of {{GamepadTouch}} events generated from all touch surfaces. If the
device does not support touch events, MUST be set to `null`.
</p>
<p>
The {{Gamepad/touchEvents}} getter steps are:
</p>
<ol>
<li>If [=this=].{{Gamepad/[[touchEvents]]}} not `null` and not
empty, return [=this=].{{Gamepad/[[touchEvents]]}}.
</li>
<li>Otherwise return `null`.
</li>
</ol>
</dd>
<dt>
<dfn>vibrationActuator</dfn>
Expand All @@ -919,6 +1001,167 @@ <h2>
that vibrates the entire gamepad.
</dd>
</dl>
<section>
<h3>
Receiving inputs
</h3>
<p>
This section supplements the <a href=
"https://w3c.github.io/gamepad/#receiving-inputs">Receiving
inputs</a> section of the main <a href=
"https://w3c.github.io/gamepad/">Gamepad specification</a>.
</p>
<p>
In addtion to the steps defined in the main <a href=
"https://w3c.github.io/gamepad/">Gamepad specification</a>. When the
user agent modifies the list of |active touch points| for a touch
surface by adding touch points, removing touch points, or updating
the values of existing touch points, <dfn data-lt=
"updating touchEvents">update touchEvents</dfn> by running the
following steps:
</p>
<ol class="algorithm">
<li>Let |surfaceId:unsigned long| be 0.
</li>
<li>Remove any existing events from
{{Gamepad}}.{{Gamepad/[[touchEvents]]}}.
</li>
<li>Repeat the following steps for each [=touch surface=] on
|gamepad| in [=touch surface enumeration order=]:
<ol>
<li>Let |surfaceDimensions| be an `null`.
</li>
<li>If the touch surface exposes maximum surface dimensions in
device units:
<ol>
<li>Set |touchEvent|.{{GamepadTouch/surfaceDimensions}}[0] to
the maximum X dimension on the [=touch surface=] in device
units.
</li>
<li>Set |touchEvent|.{{GamepadTouch/surfaceDimensions}}[1] to
the maximum Y dimension on the [=touch surface=] in device
units.
</li>
</ol>
</li>
<li>Repeat the following steps for each [=active touch point=]
reported by the |gamepad| for the current [=touch surface=].
<ol>
<li>Let |nextTouchId:unsigned long| be the next available
touchId for the |gamepad|.
</li>
<li>Let |touchEvent:GamepadTouch| be a {{GamepadTouch}}.
</li>
<li>Set |touchEvent|.{{GamepadTouch/surfaceId}} to be
|surfaceId|.
</li>
<li>If the touch data is part of an existing [=active touch
point=] tracked by the user agent:
<ol>
<li>Set |touchEvent|.{{GamepadTouch/touchId}} to the
touchId of the [=active touch point=].
</li>
<li>Otherwise, set touchId to nextTouchId and increment
nextTouchId.
<p class="note" title=
"Touch ids are relative to the Gamepad">
If the Gamepad has multiple touch surfaces the touch
id will be unique across surfaces.
</p>
</li>
</ol>
</li>
<li>Let |position| be a [=new=] {{Float32Array}} with length
2.
</li>
<li>
<p>
|position|[0] should be set to the 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.
</p>
<p class="note" title=
"Possible implementation (if surfaceDimensions are available)">
`position[0] = (2.0 * touchData.x / surfaceDimensions[0])
- 1`
</p>
</li>
<li>
<p>
|position|[1] should be set to the device Y coordinate
relative to the device [=touch surface=] and normalized
to [-1.0,1.0] where -1.0 is the topmost coordinate and
1.0 is the bottommost coordinate.
</p>
<p class="note" title=
"Possible implementation (if surfaceDimensions are available)">
`position[1] = (2.0 * touchData.y / surfaceDimensions[1])
- 1`
</p>
</li>
</ol>
</li>
<li>Set |touchEvent|.{{GamepadTouch/position}} to be
|position:Float32Array|.
</li>
<li>Add |touchEvent| to {{Gamepad}}.{{Gamepad/[[touchEvents]]}}.
</li>
</ol>
</li>
<li>Increment |surfaceId|
</li>
<li>Increment |surfaceId|
</li>
</ol>
</section>
<section>
<h3>
Constructing a `Gamepad`
</h3>
<p>
This section supplements the <a href=
"https://w3c.github.io/gamepad/#constructing-a-gamepad">Constructing
a `Gamepad`</a> section of the main <a href=
"https://w3c.github.io/gamepad/">Gamepad specification</a>.
</p>
<p>
In addtion to the steps defined in the main <a href=
"https://w3c.github.io/gamepad/">Gamepad specification</a>. When
constructing <dfn>a new `Gamepad`</dfn> representing a connected
gamepad device perform the following steps:
</p>
<ol>
<li>Let |gamepad:Gamepad| be a newly created {{Gamepad}} instance:
<ol>
<li>If the |gamepad| has touch surfaces, initialize |gamepad|'s
{{Gamepad/touchEvents}} to an empty [=list=].
</li>
<li>Otherwise, initialize |gamepad|'s {{Gamepad/touchEvents}}
<code>null</code>.
</li>
</ol>
</li>
</ol>
</section>
</section>
<section>
<h3>
Glossary
</h3>
<p>
<dfn>touch surface</dfn> is a surface that can detect contact from a
users fingers and report where on the surface the contact is made.
</p>
<p>
<dfn>touch surface enumeration order</dfn> is an ordered listing of all
the surfaces in a |gamepad|.
</p>
<p>
<dfn>active touch point</dfn> is defined in the <a href=
"https://w3c.github.io/touch-events/#dfn-active-touch-point">Touch
Events - Level 2</a> specification.
</p>
</section>
</body>
</html>

0 comments on commit 7a89897

Please sign in to comment.