Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Enhance Gamepad interface description for Touch #168

Merged
merged 18 commits into from
Oct 5, 2023
Merged

Enhance Gamepad interface description for Touch #168

Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
115afbd
Enhance Gamepad interface description for Touch
bradleyneedham Jul 15, 2022
41f86b3
Add branch where surfaceDimensions is set to null.
bradleyneedham Jul 25, 2022
ceb63de
Add step to remove events from gamepad.touchEvents
bradleyneedham Jul 25, 2022
9a8dc18
Add outer loop for multiple surfaces
bradleyneedham Jul 25, 2022
c9d3302
Reword when "update touchEvents" should occur.
bradleyneedham Jul 25, 2022
8fe5ed0
Add getter algorithm
bradleyneedham Jul 25, 2022
218799f
Update initialization of touchEvents.
bradleyneedham Aug 1, 2022
69a415e
Included [active touch point] to set touchId
bradleyneedham Aug 8, 2022
3a9b4de
Restructure of Receiving inputs section.
bradleyneedham Aug 12, 2022
f451bfb
Create multitouch_explainer.md
bradleyneedham Dec 12, 2022
96aec0a
Update multitouch_explainer.md
bradleyneedham Dec 12, 2022
5188615
Delete multitouch_explainer.md
bradleyneedham Dec 12, 2022
464c237
Apply tidy to clean up HTML format
bradleyneedham Dec 12, 2022
8c2e295
Remove "xref: true"
bradleyneedham Dec 12, 2022
3947b1e
Specify touchId requires unique ids per origin
bradleyneedham Feb 21, 2023
427ff97
Update extensions.html
nondebug Sep 12, 2023
75761be
Update extensions.html
nondebug Sep 13, 2023
ce87f1a
Update extensions.html
nondebug Sep 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
269 changes: 256 additions & 13 deletions extensions.html
View file
Open in desktop
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"],
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
xref: ["HTML", "DOM", "PERMISSIONS-POLICY", "HR-TIME", "INFRA", "gamepad"],
xref: ["HTML", "DOM", "PERMISSIONS-POLICY", "HR-TIME", "INFRA", "gamepad","webxr-gamepads-module"],

This should solve the ReSpec/xref issue

Copy link
Collaborator

@nondebug nondebug Sep 12, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that's not sufficient to solve the issue. The failure is in index.html in a part of the document not modified by the PR, so I suspect it was a change in respec that caused this failure.

@marcoscaceres said it looks like a respec bug. The xref sees " instead of double-quote characters so it fails to match against the webxr-gamepads-module reference.

};
</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>