• 山西拨付2.7亿元资金支持全省七大河流生态修复治理 2020-01-04
  • 国务院关税税则委员会发布公告决定对原产于美国的500亿美元进口商品加征关税 2019-12-22
  • 视频:世界杯路边“摄”之印象最深刻的瞬间 2019-12-21
  • 国务院关税税则委员会关于对原产于美国500亿美元进口商品加征关税的公告 2019-12-21
  • 【北京宝泽行车型报价】北京宝泽行4S店车型价格 2019-12-17
  • “改革开放40年山东教育成就展”启动 2019-12-17
  • 阶级理论已经过时了,现在所有的国家都是发展生产力。发展是硬道理,科学技术是第一生产力,都是解决社会需求不平衡,不充分的矛盾的, 2019-12-10
  • 回复@老老保老张工:那咋分配呢? 2019-11-17
  • 工信部:鼓励婴幼儿配方乳企质量安全追溯体系建设 2019-11-17
  • 第527期:过年该送健康礼,几点秘籍教给你 2019-11-11
  • 竹编:缝隙里的乡愁文章中国国家地理网 2019-11-11
  • 感触名家笔下的端午文化 吃香粽原来可以这样"文艺" 2019-11-06
  • 人民日报召开习近平新闻思想理论研讨会 2019-10-31
  • 鹏城展翅再高飞(壮阔东方潮 奋进新时代——庆祝改革开放40年) 2019-10-31
  • 财经 —频道 春城壹网 七彩云南 一网天下 2019-10-16
  • 香港麻将游戏单机:Gamepad

    W3C Working Draft

    This version:
    http://www.vfdks.tw/TR/2020/WD-gamepad-20200121/
    Latest published version:
    http://www.vfdks.tw/TR/gamepad/
    Latest editor's draft:
    https://w3c.github.io/gamepad/
    Test suite:
    https://w3c-test.org/gamepad/
    Implementation report:
    https://wpt.fyi/results/gamepad
    Previous version:
    http://www.vfdks.tw/TR/2019/WD-gamepad-20191114/
    Editors:
    Steve Agoston (Sony)
    James Hollyer (Google)
    Matt Reynolds (Google)
    Former editors:
    Brandon Jones (Google)
    Scott Graham (Google)
    Ted Mielczarek (Mozilla)
    Participate:
    GitHub w3c/gamepad
    File a bug
    Commit history
    Pull requests

    Abstract

    The Gamepad specification defines a low-level interface that represents gamepad devices.

    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.vfdks.tw/TR/.

    This is a work in progress.

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

    GitHub Issues are preferred for discussion of this specification.

    Please see the Working Group's implementation report.

    Publication as a 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.

    1. Introduction

    This section is non-normative.

    Some user agents have connected gamepad devices. These devices are desirable and suited to input for gaming applications, and for "10 foot" user interfaces (presentations, media viewers).

    Currently, the only way for a gamepad to be used as input would be to emulate mouse or keyboard events, however this would lose information and require additional software outside of the user agent to accomplish emulation.

    Meanwhile, native applications are capable of accessing these devices via system APIs.

    The Gamepad API provides a solution to this problem by specifying interfaces that allow web applications to directly act on gamepad data.

    2. Dependencies

    This specification references interfaces from a number of other specifications:

    3. Scope

    Interfacing with external devices designed to control games has the potential to become large and intractable if approached in full generality. In this specification we explicitly choose to narrow scope to provide a useful subset of functionality that can be widely implemented and broadly useful.

    Specifically, we choose to only support the functionality required to support gamepads. Support for gamepads requires two input types: buttons and axes. Both buttons and axes are reported as analog values, buttons ranging from [0..1], and axes ranging from [-1..1].

    While the primary goal is support for gamepad devices, supporting these two types of analog inputs allows support for other similar devices common to current gaming systems including joysticks, driving wheels, pedals, and accelerometers. As such, the name "gamepad" is exemplary rather than trying to be a generic name for the entire set of devices addressed by this specification.

    We specifically exclude support for more complex devices that may also be used in some gaming contexts, including those that that do motion sensing, depth sensing, video analysis, gesture recognition, and so on.

    4. Gamepad interface

    This interface defines an individual gamepad device.

    WebIDL[Exposed=Window]
    interface Gamepad {
      readonly attribute DOMString id;
      readonly attribute long index;
      readonly attribute boolean connected;
      readonly attribute DOMHighResTimeStamp timestamp;
      readonly attribute GamepadMappingType mapping;
      readonly attribute FrozenArray<double> axes;
      readonly attribute FrozenArray<GamepadButton> buttons;
    };
    id attribute
    An identification string for the gamepad. This string identifies the brand or style of connected gamepad device. Typically, this will include the USB vendor and a product ID.
    index attribute
    The index of the gamepad in the Navigator. When multiple gamepads are connected to a user agent, indices MUST be assigned on a first-come, first-serve basis, starting at zero. If a gamepad is disconnected, previously assigned indices MUST NOT be reassigned to gamepads that continue to be connected. However, if a gamepad is disconnected, and subsequently the same or a different gamepad is then connected, the lowest previously used index MUST be reused.
    connected attribute
    Indicates whether the physical device represented by this object is still connected to the system. When a gamepad becomes unavailable, whether by being physically disconnected, powered off or otherwise unusable, the connected attribute MUST be set to false.
    timestamp attribute
    Last time the data for this gamepad was updated. Timestamp is a monotonically increasing value that allows the author to determine if the axes and button data have been updated from the hardware. The value must be relative to the navigationStart attribute of the PerformanceTiming interface. Since values are monotonically increasing they can be compared to determine the ordering of updates, as newer values will always be greater than or equal to older values. If no data has been received from the hardware, the value of the timestamp attribute should be the time relative to navigationStart when the Gamepad object was first made available to script.
    mapping attribute
    The mapping in use for this device. If the user agent has knowledge of the layout of the device, then it SHOULD indicate that a mapping is in use by setting this property to a known mapping name. Currently the only known mapping is "standard", which corresponds to the Standard Gamepad layout. If the user agent does not have knowledge of the device layout and is simply providing the controls as represented by the driver in use, then it MUST set the mapping property to the empty string.
    axes attribute
    Array of values for all axes of the gamepad. All axis values MUST be linearly normalized to the range [-1.0 .. 1.0]. If the controller is perpendicular to the ground with the directional stick pointing up, -1.0 SHOULD correspond to "forward" or "left", and 1.0 SHOULD correspond to "backward" or "right". Axes that are drawn from a 2D input device SHOULD appear next to each other in the axes array, X then Y. It is RECOMMENDED that axes appear in decreasing order of importance, such that element 0 and 1 typically represent the X and Y axis of a directional stick. The same object MUST be returned until the user agent needs to return different values (or values in a different order).
    buttons attribute
    Array of button states for all buttons of the gamepad. It is RECOMMENDED that buttons appear in decreasing importance such that the primary button, secondary button, tertiary button, and so on appear as elements 0, 1, 2, ... in the buttons array. The same object MUST be returned until the user agent needs to return different values (or values in a different order).

    5. GamepadButton Interface

    This interface defines the state of an individual button on a gamepad device.

    WebIDL[Exposed=Window]
    interface GamepadButton {
      readonly attribute boolean pressed;
      readonly attribute boolean touched;
      readonly attribute double value;
    };
    pressed attribute
    The pressed state of the button. This property MUST be true if the button is currently pressed, and false if it is not pressed. For buttons which do not have a digital switch to indicate a pure pressed or released state, the user agent MUST choose a threshold value to indicate the button as pressed when its value is above a certain amount. If the platform API gives a recommended value, the user agent SHOULD use that. In other cases, the user agent SHOULD choose some other reasonable value.
    touched attribute
    The touched state of the button. If the button is capable of detecting touch, this property MUST be true if the button is currently being touched, and false otherwise. If the button is not capable of detecting touch and is capable of reporting an analog value, this property MUST be true if the value property is greater than 0, and false if the value is 0. If the button is not capable of detecting touch and can only report a digital value, this property MUST mirror the pressed attribute.
    value attribute
    For buttons that have an analog sensor, this property MUST represent the amount which the button has been pressed. All button values MUST be linearly normalized to the range [0.0 .. 1.0]. 0.0 MUST mean fully unpressed, and 1.0 MUST mean fully pressed. For buttons without an analog sensor, only the values 0.0 and 1.0 for fully unpressed and fully pressed respectively, MUST be provided.

    6. GamepadMappingType enum

    This enum defines the set of known mappings for a Gamepad.

    WebIDLenum GamepadMappingType {
      "",
      "standard",
    };
    ""
    The empty string indicates that no mapping is in use for this gamepad.
    standard
    The Gamepad's controls have been mapped to the Standard Gamepad layout.

    8. GamepadEvent Interface

    WebIDL[Exposed=Window]
    
    interface GamepadEvent: Event {
      constructor(DOMString type, GamepadEventInit eventInitDict);
      [SameObject] readonly attribute Gamepad gamepad;
    };
    gamepad
    The single gamepad attribute provides access to the associated gamepad data for this event.

    8.1 GamepadEventInit dictionary

    WebIDLdictionary GamepadEventInit : EventInit {
      required Gamepad gamepad;
    };
    gamepad member
    The gamepad associated with this event.

    9. Remapping

    Each device manufacturer creates many different products and each has unique styles and layouts of buttons and axes. It is intended that the user agent support as many of these as possible.

    Additionally there are de facto standard layouts that have been made popular by game consoles. When the user agent recognizes the attached device, it is RECOMMENDED that it be remapped to a canonical ordering when possible. Devices that are not recognized should still be exposed in their raw form.

    There is currently one canonical device, the "Standard Gamepad". The standard gamepad has 4 axes, and up to 17 buttons. When remapping, the indices in axes[] and buttons[] should correspond as closely as possible to the physical locations in the diagram below. Additionally, the mapping property of the Gamepad SHOULD be set to the string "standard".

    The "Standard Gamepad" physical button locations are layed out in a left cluster of four buttons, a right cluster of four buttons, a center cluster of three buttons, and a pair of front facing buttons on the left and right side of the gamepad. The four axes of the "Standard Gamepad" are associated with a pair of analog sticks, one on the left and one on the right. The following table describes the buttons/axes and their physical locations.

    Button/Axis Location
    buttons[0] Bottom button in right cluster
    buttons[1] Right button in right cluster
    buttons[2] Left button in right cluster
    buttons[3] Top button in right cluster
    buttons[4] Top left front button
    buttons[5] Top right front button
    buttons[6] Bottom left front button
    buttons[7] Bottom right front button
    buttons[8] Left button in center cluster
    buttons[9] Right button in center cluster
    buttons[10] Left stick pressed button
    buttons[11] Right stick pressed button
    buttons[12] Top button in left cluster
    buttons[13] Bottom button in left cluster
    buttons[14] Left button in left cluster
    buttons[15] Right button in left cluster
    axes[0] Horizontal axis for left stick (negative left/positive right)
    axes[1] Vertical axis for left stick (negative up/positive down)
    axes[2] Horizontal axis for right stick (negative left/positive right)
    axes[3] Vertical axis for right stick (negative up/positive down)
    Figure 1 Visual representation of a standard gamepad layout.

    10. Usage Examples

    This section is non-normative.

    The example below demonstrates typical access to gamepads. Note the relationship with the requestAnimationFrame() method.

    function runAnimation() {
        window.requestAnimationFrame(runAnimation);
        for (const pad of navigator.getGamepads()) {
          // todo; simple demo of displaying pad.axes and pad.buttons
          console.log(pad);
        }
    }
    
    window.requestAnimationFrame(runAnimation);
    Best Practice 1: Coordination with requestAnimationFrame()

    Interactive applications will typically be using the requestAnimationFrame() method to drive animation, and will want coordinate animation with user gamepad input. As such, the gamepad data should be polled as closely as possible to immediately before the animation callbacks are executed, and with frequency matching that of the animation. That is, if the animation callbacks are running at 60Hz, the gamepad inputs should also be sampled at that rate.

    11. The gamepadconnected event

    User agents implementing this specification must provide a new DOM event, named gamepadconnected. The corresponding event MUST be of type GamepadEvent and MUST fire on the window object. Registration for and firing of the gamepadconnected event MUST follow the usual behavior of DOM Events. [DOM]

    A user agent MUST dispatch this event type to indicate the user has connected a gamepad. If a gamepad was already connected when the page was loaded, the gamepadconnected event SHOULD be dispatched when the user presses a button or moves an axis.

    12. The gamepaddisconnected event

    User agents implementing this specification must provide a new DOM event, named gamepaddisconnected. The corresponding event MUST be of type GamepadEvent and MUST fire on the window object. Registration for and firing of the gamepaddisconnected event MUST follow the usual behavior of DOM Events. [DOM]

    When a gamepad is disconnected from the user agent, if the user agent has previously dispatched a gamepadconnected event for that gamepad to a window, a gamepaddisconnected event MUST be dispatched to that same window.

    13. Other events

    More discussion needed, on whether to include or exclude axis and button changed events, and whether to roll them more together (gamepadchanged?), separate somewhat (gamepadaxischanged?), or separate by individual axis and button.

    14. Conformance

    As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

    The key words MUST, MUST NOT, RECOMMENDED, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

    This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.

    A. Acknowledgements

    This section is non-normative.

    Many have made contributions in code, comments, or documentation:

    Please let me know if I have inadvertently omitted your name.

    B. References

    B.1 Normative references

    [DOM]
    DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/
    [hr-time]
    High Resolution Time Level 2. Ilya Grigorik. W3C. 21 November 2019. W3C Recommendation. URL: http://www.vfdks.tw/TR/hr-time-2/
    [HTML]
    HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip J?genstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
    [NAVIGATION-TIMING]
    Navigation Timing. Zhiheng Wang. W3C. 17 December 2012. W3C Recommendation. URL: http://www.vfdks.tw/TR/navigation-timing/
    [RFC2119]
    Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
    [RFC8174]
    Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174
    [WebIDL]
    Web IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/
  • 山西拨付2.7亿元资金支持全省七大河流生态修复治理 2020-01-04
  • 国务院关税税则委员会发布公告决定对原产于美国的500亿美元进口商品加征关税 2019-12-22
  • 视频:世界杯路边“摄”之印象最深刻的瞬间 2019-12-21
  • 国务院关税税则委员会关于对原产于美国500亿美元进口商品加征关税的公告 2019-12-21
  • 【北京宝泽行车型报价】北京宝泽行4S店车型价格 2019-12-17
  • “改革开放40年山东教育成就展”启动 2019-12-17
  • 阶级理论已经过时了,现在所有的国家都是发展生产力。发展是硬道理,科学技术是第一生产力,都是解决社会需求不平衡,不充分的矛盾的, 2019-12-10
  • 回复@老老保老张工:那咋分配呢? 2019-11-17
  • 工信部:鼓励婴幼儿配方乳企质量安全追溯体系建设 2019-11-17
  • 第527期:过年该送健康礼,几点秘籍教给你 2019-11-11
  • 竹编:缝隙里的乡愁文章中国国家地理网 2019-11-11
  • 感触名家笔下的端午文化 吃香粽原来可以这样"文艺" 2019-11-06
  • 人民日报召开习近平新闻思想理论研讨会 2019-10-31
  • 鹏城展翅再高飞(壮阔东方潮 奋进新时代——庆祝改革开放40年) 2019-10-31
  • 财经 —频道 春城壹网 七彩云南 一网天下 2019-10-16