WebXR Gamepads Module - Level 1

W3C First Public Working Draft,

This version:
http://www.biaxls.live/TR/2019/WD-webxr-gamepads-module-1-20191010/
Latest published version:
http://www.biaxls.live/TR/webxr-gamepads-module-1/
Editor's Draft:
https://immersive-web.github.io/webxr-gamepads-module/
Issue Tracking:
GitHub
Editors:
(Google)
(Amazon [Microsoft until 2018])
Participate:
File an issue (open issues)
Mailing list archive
W3C’s #immersive-web IRC

Abstract

This specification module describes support for accessing button, trigger, thumbstick, and touchpad data associated with virtual reality (VR) and augmented reality (AR) devices on the Web.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.biaxls.live/TR/.

The Immersive Web Working Group maintains a list of all bug reports that the group has not yet addressed. This draft highlights some of the pending issues that are still to be discussed in the working group. No decision has been taken on the outcome of these issues including whether they are valid. Pull requests with proposed specification text for outstanding issues are strongly encouraged.

This document was published by the Immersive Web Working Group as a Working Draft. This document is intended to become a W3C Recommendation.

This document is a First Public Working Draft.

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 March 2019 W3C Process Document.

This WebXR Gamepads Module is designed as a module to be implemented in addition to WebXR Device API, and was originally included in WebXR Device API which was divided into core and modules.

1. Introduction

Hardware that enables Virtual Reality (VR) and Augmented Reality (AR) applications are now broadly available to consumers, offering an immersive computing platform with both new opportunities and challenges. The ability to interact directly with immersive hardware is critical to ensuring that the web is well equipped to operate as a first-class citizen in this environment. The WebXR Gamepads module adds interfaces and behaviors to the WebXR Device API and the Gamepads API to allow for querying the state of buttons, triggers, thumbsticks, and touchpads available as input sources on many WebXR compatible devices.

This module is an addition to the WebXR Device API.

1.1. Terminology

This document uses the acronym XR throughout to refer to the spectrum of hardware, applications, and techniques used for Virtual Reality, Augmented Reality, and other related technologies. Examples include, but are not limited to:

The important commonality between them being that they offer some degree of spatial tracking with which to simulate a view of virtual content.

Terms like "XR Device", "XR Application", etc. are generally understood to apply to any of the above. Portions of this document that only apply to a subset of these devices will indicate so as appropriate.

XR Devices often have additional controller hardware that allows users to interact with immersive experiences with button, trigger, thumbstick, or touchpad inputs. Frequently these devices are spatially tracked as well, and referred to as "motion controllers", "handheld controllers", or "tracked controllers".

2. WebXR Device API Integration

As defined in the WebXR Device API API, an XRInputSource represents an XR input source, which is any input mechanism which allows the user to perform targeted actions in the same virtual space as the viewer. Example XR input sources include, but are not limited to, handheld controllers, optically tracked hands, and gaze-based input methods that operate on the viewer's pose.

This document outlines the behavior of an XRInputSource when it has button, trigger, thumbstick, or touchpad data to report. This is commonly a motion controller, but may also be headset with buttons, triggers, thumbsticks, or touchpads on the XR device. As stated in the WebXR device API, input mechanisms which are not explicitly associated with the XR Device, such as traditional gamepads, MUST NOT be considered XR input sources.

2.1. XRInputSource

Button, trigger, thumbstick, and touchpad data is reported though a Gamepad object exposed on the XRInputSource it is associated with.

partial interface XRInputSource {
  [SameObject] readonly attribute Gamepad? gamepad;
};

The gamepad attribute is a Gamepad that describes the state of any buttons and axes on the XR input source. If the XR input source does not have at least one of the following properties, the gamepad attribute MUST be null:

Note: XRInputSources in an XRSession's inputSources array are "live". As such values within them, such as the gamepad button and axis state, are updated in-place. This means that it doesn’t work to save a reference to an XRInputSource's gamepad on one frame and compare it to the same XRInputSource's gamepad from a subsequent frame to test for state changes, because they will be the same object. Therefore developers that wish to compare input state from frame to frame should copy the state in question.

2.2. XRSession

XRInputSources are reported in the inputSources array as they are connected and disconnected. When the presence of a gamepad changes for any entry in the inputSources array, the user agent MUST invoke the WebXR Device API’s algorithm for responding to input source attribute changes.

3. Gamepad API Integration

Gamepad instances returned by an XRInputSource's gamepad attribute behave as described by the Gamepad API, with several additional behavioral restrictions.

The Gamepad API states a snapshot of Gamepad data can be retrieved by calling the navigator.getGamepads() function. However, Gamepad instances returned by an XRInputSource's gamepad attribute MUST NOT be included in the array returned by navigator.getGamepads().

3.2. Gamepad

The following Gamepad attributes MUST exhibit the following behavioral restrictions when the Gamepad has been returned by an XRInputSource's gamepad attribute.

3.3. "xr-standard" Gamepad Mapping

This module extends the GamepadMappingType to describe the mapping of common XR controller devices.

enum GamepadMappingType {
  "",            // Defined in the Gamepad API
  "standard",    // Defined in the Gamepad API
  "xr-standard",
};

The xr-standard mapping indicates that the layout of the buttons and axes of the gamepad corresponds as closely as possible to the tables below.

In order to report a mapping of "xr-standard" the device MUST report a targetRayMode of "tracked-pointer" and MUST have a non-null gripSpace. It MUST have at least one primary button, often a trigger, separate from any touchpads or thumbsticks. If a device does not meet the requirements for the "xr-standard" mapping it may still expose a gamepad with a mapping of "" (empty string). The "xr-standard" mapping MUST only be used by Gamepad instances reported by an XRInputSource.

Buttons xr-standard Mapping Required
buttons[0] Primary button/trigger Yes
buttons[1] Primary squeeze No
buttons[2] Primary touchpad No
buttons[3] Primary thumbstick No

Axes xr-standard Mapping Required
axes[0] Primary touchpad X No
axes[1] Primary touchpad Y No
axes[2] Primary thumbstick X No
axes[3] Primary thumbstick Y No

Devices that lack one of the optional inputs listed in the tables above MUST preserve their place in the buttons or axes array, reporting a placeholder button or placeholder axis, respectively. A placeholder button MUST report 0 for value, false for pressed, and false for touched. A placeholder axis MUST report 0. Placeholder buttons and axes MUST be omitted if they are the last element in the array or all following elements are also placeholder buttons or axes.

Additional buttons or axes may be exposed after these reserved indices, and SHOULD appear in order of decreasing importance. Related axes (such as both axes of a thumbstick) MUST be grouped and, if applicable, MUST appear in X, Y, Z order. Buttons reserved by the UA or platform MUST NOT be exposed.

This diagram demonstrates how two example controllers would be exposed with the "xr-standard" mapping. Images are not intended to represent any particular device and are used for reference purposes only. Simple 'xr-standard' controller and Advanced 'xr-standard' controller

4. Security and Privacy

The WebXR Device API provides powerful new features which bring with them several unique privacy, security, and comfort risks that user agents must take steps to mitigate. This topic is covered in detail as part of the WebXR Device API. This module adds additional considerations, but does not change the fundamental WebXR security and privacy principles.

4.1. Fingerprinting

Given that the API describes hardware available to the user and its capabilities it will inevitably provide additional surface area for fingerprinting. While it’s impossible to completely avoid this, user agents should take steps to mitigate the issue. As defined in the WebXR Device API, XRInputSources are only reported after an XRSession has been created, which requires additional protections when sensitive information will be exposed. In addition, this module requires XRInputSource's gamepad.id to not report a string identifiers.

5. Acknowledgements

The following individuals have contributed to the design of the WebXR Device API specification:

And a special thanks to Vladimir Vukicevic (Unity) for kick-starting this whole adventure!

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[GAMEPAD]
James Hollyer; et al. Gamepad. 3 October 2019. WD. URL: http://www.biaxls.live/TR/gamepad/
[WebIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

IDL Index

partial interface XRInputSource {
  [SameObject] readonly attribute Gamepad? gamepad;
};

enum GamepadMappingType {
  "",            // Defined in the Gamepad API
  "standard",    // Defined in the Gamepad API
  "xr-standard",
};

排列三浙江风采网走势图