Please rewrite these steps with a branch where surfaceDimensions is set to null. We can leave "why is it null?" up to the browser implementer, but if we don't have steps where it can be set to null then it should never be null.

It should be something like:

• If the touch surface exposes maximum surface dimensions in device units:
  • Set touchEvent.surfaceDimensions[0] to ...
  • Set touchEvent.surfaceDimensions[1] to ...
• Otherwise:
  • Set touchEvent.surfaceDimensions to null

Updated.

This may need more discussion. Perhaps there is not a case where surfaceDimensions can be null. For the DS4 touch coordinates are normalized using the device touch point and the surface dimensions. Should the algorithm include receiving input from a device that sends already normalized touch points and does not report surface dimensions?

We're adding to the touchEvents internal slot but never remove from it. This algorithm should start by emptying touchEvents since we plan to replace the whole list each time we update.

Added step to empty out any existing events from touchEvents.

It's unclear where the device surfaceId comes from. I think it would be simpler to specify it as an index into whatever the surface ordering happens to be:

• Let surfaceId be 0
• For each touch surface:
  • For each touch input on that surface:
    • Create and add the touch event (with surfaceId)
  • Increment surfaceId

Added outer loop to iterate surfaces.

We need to specify more of how the touch event's touchID is initialized since it's important for how applications will interact with the API. Let's try to leverage the Touch Events specification which already defines "active touch point":

https://w3c.github.io/touch-events/#dfn-active-touch-point

• If the touch data is part of an existing [=active touch point=] tracked by the user agent:
  • Set touchID to the touchID of the active touch point
  • Otherwise, set touchID to nextTouchID and increment nextTouchID

nextTouchID should be a Gamepad internal slot so it's always unique even when there are multiple touch surfaces on the same gamepad.

@nondebug I manually added the link, it appears that the dfn is not exported (or possibly, probably, I am not using xref correctly). I am also a little concerned that we are making the spec too restrictive to implementers, e.g. I am working on the DS4 GamepadTouch implementation in chromium and find that normalizing the touchId is much easier at the ds4_controller than the device/gamepad (this may be a bad assumption on my part that when you refer to an "internal slot" it would translate to that object). Requiring the nextTouchId in device/gamepad might cause difficulty in implementing other touch controllers. The specification just needs to be clear that implementers support 32 bit value starting at 0 and incrementing with each new touch event not associated with an existing active touch point. How this is accomplished should be open.
I will try and add some "Usage Examples" to better explain how applications will interact with the API.

it appears that the dfn is not exported

I'm not sure why the xref dfn doesn't work. It doesn't show up in https://respec.org/xref/ either. https://respec.org/docs/#xref suggests it needs a change to the touch-events spec to export it. I'm okay with leaving it as-is for now, we can clean this up later when the extension is merged into the main specification.

normalizing the touchId is much easier at the ds4_controller than the device/gamepad (this may be a bad assumption on my part that when you refer to an "internal slot" it would translate to that object)

Normalizing touchId in Dualshock4Controller won't work because a device::Gamepad isn't 1-to-1 with a blink::Gamepad. Most of the time, "internal slot" should be read as "1-to-1 with blink::Gamepad". The only time we can attach internal slots to device::Gamepad is if all tabs should see the same value. This isn't true for touchId and nextTouchId since they may differ between tabs even for the same gamepad.

Suppose there's a tab accessing a DS4 through Gamepad API and it receives a touch point with ID 0. Then a second tab is opened and begins accessing DS4 through Gamepad API. When the next touch occurs, the first tab should get a touch point with ID 1 and the second tab should get touch ID 0. If we deliver touch ID 1 to both tabs then the second tab can deduce that another tab was accessing Gamepad API.

We can store raw touchIds in the device::Gamepad buffer and normalize them in blink::Gamepad::UpdateFromDeviceState. To normalize the ID, blink::Gamepad will need to maintain nextTouchId along with a mapping from raw->normalized touchIds for all active touch points. The rest of the touch data (surfaceId, position, surfaceDimensions) won't change between tabs so we can store it in the device::Gamepad buffer.

Requiring the nextTouchId in device/gamepad might cause difficulty in implementing other touch controllers. The specification just needs to be clear that implementers support 32 bit value starting at 0 and incrementing with each new touch event not associated with an existing active touch point. How this is accomplished should be open.

Agreed, the spec should not care how active touch points are identified. We only need to be able to enumerate them and somehow associate current set of active touch points with the set of active touch points from the previous update.

touchEvents should define a getter algorithm that returns the data from the internal slot.

Added.

When the system receives new touch input values,

This seems ambiguous to me, it's unclear whether "new touch input values" includes updates where there are no touches, for example a DS4 input report that doesn't contain any active touch points. We want this method to run for every DS4 input report, even when there are no active touch points.

Perhaps something like:

"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, update touchEvents by running the following steps:"

Updated.

I think here we should initialize the touchEvents internal slot to an empty list if the gamepad has any touch surfaces, otherwise null. The [=updating touchEvents=] algorithm will be called automatically whenever the first touch inputs are received so we don't need to call it here.

The actual touchEvents attribute (not the internal slot) should define a getter algorithm that returns the data from the internal slot. That way the attribute is initialized when we initialize the internal slot. We use the internal slot because the attribute is readonly so technically it has no setter but we still need a way to update it.

Updated.

it appears that the dfn is not exported

I'm not sure why the xref dfn doesn't work. It doesn't show up in https://respec.org/xref/ either. https://respec.org/docs/#xref suggests it needs a change to the touch-events spec to export it. I'm okay with leaving it as-is for now, we can clean this up later when the extension is merged into the main specification.

normalizing the touchId is much easier at the ds4_controller than the device/gamepad (this may be a bad assumption on my part that when you refer to an "internal slot" it would translate to that object)

Normalizing touchId in Dualshock4Controller won't work because a device::Gamepad isn't 1-to-1 with a blink::Gamepad. Most of the time, "internal slot" should be read as "1-to-1 with blink::Gamepad". The only time we can attach internal slots to device::Gamepad is if all tabs should see the same value. This isn't true for touchId and nextTouchId since they may differ between tabs even for the same gamepad.

Suppose there's a tab accessing a DS4 through Gamepad API and it receives a touch point with ID 0. Then a second tab is opened and begins accessing DS4 through Gamepad API. When the next touch occurs, the first tab should get a touch point with ID 1 and the second tab should get touch ID 0. If we deliver touch ID 1 to both tabs then the second tab can deduce that another tab was accessing Gamepad API.

We can store raw touchIds in the device::Gamepad buffer and normalize them in blink::Gamepad::UpdateFromDeviceState. To normalize the ID, blink::Gamepad will need to maintain nextTouchId along with a mapping from raw->normalized touchIds for all active touch points. The rest of the touch data (surfaceId, position, surfaceDimensions) won't change between tabs so we can store it in the device::Gamepad buffer.

Requiring the nextTouchId in device/gamepad might cause difficulty in implementing other touch controllers. The specification just needs to be clear that implementers support 32 bit value starting at 0 and incrementing with each new touch event not associated with an existing active touch point. How this is accomplished should be open.

Agreed, the spec should not care how active touch points are identified. We only need to be able to enumerate them and somehow associate current set of active touch points with the set of active touch points from the previous update.

In this algorithm we describe touchSurfaces, touchInputs, touchData but there's no instructions on how to construct those objects.

We want to emphasize the assumptions we're making about the inputs but we also don't want to specify more than we have to. I think we can modify the algorithm to be more specific about the assumptions we're making while being less specific about how the data is presented. For example, if we specify that a gamepad's touch surfaces need to have some consistent ordering then we can iterate over them without creating lists:

• Let |surfaceId| be 0.
• Repeat these steps for each [=touch surface=] on |gamepad| in [=touch surface enumeration order=]:
  • Let |surfaceDimensions| be null.
  • If the [=touch surface=] exposes maximum dimensions in device units:
    • Set |surfaceDimensions| to a [=new=] {{Array}} with length 2.
    • Set |surfaceDimensions|[0] to the maximum X dimension of the current [=touch surface=] in device units.
    • Set |surfaceDimensions|[1] to the maximum Y dimension of the current [=touch surface=] in device units.
  • Repeat these steps for each [=active touch point=] on the current [=touch surface=]:
    • Let |x:float| be the X coordinate for the current [=active touch point=] in device units.
    • Let |y:float| be the Y coordinate for the current [=active touch point=] in device units.
    • Let |position| be a [=new=] {{Array}} with length 2.
    • If |surfaceDimensions| is null:
      • Set |position|[0] to ???.
      • Set |position|[1] to ???.
    • Otherwise:
      • Set |position|[0] to a value calculated from |x| and |surfaceDimensions|[0] and normalized to [-1,1].
      • Set |position|[1] to a value calculated from |y| and |surfaceDimensions|[1] and normalized to [-1,1].
    • Let |touchEvent| be a [=new=] {{GamepadTouch}}:
      • Initialize |touchEvent|.{{GamepadTouch/surfaceId}} to |surfaceId|.
      • Initialize |touchEvent|.{{GamepadTouch/position}} to |position|.
      • Initialize |touchEvent|.{{GamepadTouch/surfaceDimensions}} to |surfaceDimensions|.
      • [=list/Append=] |touchEvent| to |gamepad|.{{Gamepad/[[touchEvents]]}}.
  • Increment |surfaceId|.

Normalizing touchId in Dualshock4Controller won't work because a device::Gamepad isn't 1-to-1 with a blink::Gamepad. Most of the time, "internal slot" should be read as "1-to-1 with blink::Gamepad". The only time we can attach internal slots to device::Gamepad is if all tabs should see the same value. This isn't true for touchId and nextTouchId since they may differ between tabs even for the same gamepad.

I went back and double checked and what I have observed is that the lifetime of a blink::Gamepad is very short maybe each render, so will not work for touchId and nextTouchId. This is probably not the forum for this discussion (I need to figure out how to start it over on the chromium site).
This does create an issue with implementing the specification since the lifetime of the device::Gamepad is not correct either as you point out.

We want to emphasize the assumptions we're making about the inputs but we also don't want to specify more than we have to. I think we can modify the algorithm to be more specific about the assumptions we're making while being less specific about how the data is presented. For example, if we specify that a gamepad's touch surfaces need to have some consistent ordering then we can iterate over them without creating lists:

Agreed, I will work on addressing this.

Ah right, blink::Gamepad is short-lived. The specification says it should behave like a live object but the Chromium implementation hasn't been updated to match that behavior yet. (Relevant spec issue: #8)

We've worked around this by attaching the internal state to blink::NavigatorGamepad instead of blink::Gamepad and creating a Gamepad::Client interface to provide access to this internal state so it's persisted even when the blink::Gamepad is destroyed and recreated.

This is probably not the forum for this discussion (I need to figure out how to start it over on the chromium site).

Let's use this crbug to discuss the Chromium implementation: 1143942: Gamepad Multitouch

@nondebug I have restructured the Receiving inputs section and added a Glossary for terms. Several updates to your other comments we made a bit back, should I just resolve those comments?
There is a suggestion at the top "Still in progress? Convert to draft", does that make since?

Please remove this xref in favor of the xref below with a list of specification short names.

Done

Updated.

I wonder if this should initially just be an empty list? Then we don't need to deal with list and null as types

I think because not all Gamepads support touch pads, it is better this way to distinguish between a Gamepad that will never have touchIds (null) and a Gamepad that just has no new input (empty list).

Would "both" be better than ""?

The enumeration is better described above in the document. I changed this to refer to the above definition. I think "" can mean "both", "either", or "NA", and perhaps it only matters to the developer if it is "left" or "right".
Perhaps @nondebug has more insight.

This should solve the ReSpec/xref issue

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.