gamepad.html
author Ted Mielczarek <ted@mielczarek.org>
Thu, 22 Jan 2015 09:16:39 -0500
changeset 35 105439653c33
parent 34 9eb32cbb247d
permissions -rw-r--r--
bug 26181 - make navigator.getGamepads return sequence<Gamepad?>
     1 <!DOCTYPE html>
     2 <html lang="en">
     3   <head>
     4     <title>Gamepad</title>
     5     <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
     6     <meta name="viewport" content="width=device-width">
     7     <!--
     8       === NOTA BENE ===
     9       For the three scripts below, if your spec resides on dev.w3 you can check them
    10       out in the same tree and use relative links so that they'll work offline,
    11      -->
    12     <script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove'></script>
    13     <script class='remove'>
    14       var respecConfig = {
    15           // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
    16           specStatus:           "ED",
    17 
    18           // the specification's short name, as in http://www.w3.org/TR/short-name/
    19           shortName:            "gamepad",
    20 
    21           // if your specification has a subtitle that goes below the main
    22           // formal title, define it here
    23           // subtitle   :  "an excellent document",
    24 
    25           // if you wish the publication date to be other than today, set this
    26           //publishDate:  "2011-01-01",
    27 
    28           // if the specification's copyright date is a range of years, specify
    29           // the start date here:
    30           // copyrightStart: "2005"
    31 
    32           // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
    33           // and its maturity status
    34           // previousPublishDate:  "1977-03-15",
    35           // previousMaturity:  "WD",
    36 
    37           // if there a publicly available Editor's Draft, this is the link
    38           edDraftURI:           "http://dvcs.w3.org/hg/gamepad/raw-file/default/gamepad.html",
    39 
    40           testSuiteURI: "http://w3c-test.org/gamepad/",
    41 
    42           // if this is a LCWD, uncomment and set the end of its review period
    43           // lcEnd: "2009-08-05",
    44 
    45           // editors, add as many as you like
    46           // only "name" is required
    47           editors:  [
    48               { name: "Scott Graham", url: "http://h4ck3r.net/",
    49                 company: "Google", companyURL: "http://www.google.com/" },
    50               { name: "Ted Mielczarek", url: "http://ted.mielczarek.org/",
    51                 company: "Mozilla", companyURL: "http://www.mozilla.org/" },
    52           ],
    53 
    54           // authors, add as many as you like.
    55           // This is optional, uncomment if you have authors as well as editors.
    56           // only "name" is required. Same format as editors.
    57 
    58           //authors:  [
    59           //    { name: "Your Name", url: "http://example.org/",
    60           //      company: "Your Company", companyURL: "http://example.com/" },
    61           //],
    62 
    63           // name of the WG
    64           wg:           "Web Applications Working Group",
    65 
    66           // URI of the public WG page
    67           wgURI:        "http://www.w3.org/2008/webapps/",
    68 
    69           // name (with the @w3c.org) of the public mailing to which comments are due
    70           wgPublicList: "public-webapps",
    71 
    72           // URI of the patent status for this WG, for Rec-track documents
    73           // !!!! IMPORTANT !!!!
    74           // This is important for Rec-track documents, do not copy a patent URI from a random
    75           // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
    76           // Team Contact.
    77           wgPatentURI:  "http://www.w3.org/2004/01/pp-impl/42538/status",
    78       };
    79     </script>
    80 
    81     <style type="text/css">
    82       .event {
    83         font-family: monospace;
    84         color: #459900;
    85       }
    86 
    87       pre.idl {
    88         white-space: pre-wrap;
    89       }
    90     </style>
    91     <link rel="stylesheet" type="text/css" href="https://www.w3.org/StyleSheets/TR/W3C-WD"/>
    92   </head>
    93   <body>
    94     <section id='abstract'>
    95       The Gamepad specification defines a low-level interface that represents
    96       gamepad devices.
    97     </section>
    98 
    99     <section id='sotd'>
   100       If you have comments for this spec, please send them to 
   101       <a href="mailto:public-webapps@w3.org">public-webapps@w3.org</a>
   102       with a Subject: prefix of <code>[gamepad]</code>. See
   103       <a href="https://www.w3.org/Bugs/Public/buglist.cgi?product=WebAppsWG&component=Gamepad&resolution=---">Bugzilla</a> 
   104       for this specification's open bugs.
   105     </section>
   106 
   107     <section id='introduction' class='informative'>
   108 
   109       <h2>Introduction</h2>
   110 
   111       <p>Some <a>user agent</a>s have connected gamepad devices. These devices
   112       are desirable and suited to input for gaming applications, and for
   113       &quot;10 foot&quot; user interfaces (presentations, media viewers).</p>
   114 
   115       <p>Currently, the only way for a gamepad to be used as input would be
   116       to emulate mouse or keyboard events, however this would lose information
   117       and require additional software outside of the <a>user agent</a> to
   118       accomplish emulation.</p>
   119 
   120       <p>Meanwhile, native applications are capable of accessing these devices
   121       via system APIs.</p>
   122 
   123       <p>The Gamepad API provides a solution to this problem by specifying
   124       interfaces that allow web applications to directly act on gamepad
   125       data.</p>
   126 
   127       <p>This specification references interfaces from a number of other
   128       specifications:</p>
   129 
   130       <ul>
   131       <li><a class="externalDFN">Navigator</a> [[!NAVIGATOR]]</li>
   132       <li><a class="externalDFN">DOMHighResTimeStamp</a> [[!HIGHRES-TIME]]</li>
   133       <li><a class="externalDFN">WindowAnimationTiming [[!ANIMATION-TIMING]]</a></li>
   134       <li><a class="externalDFN">PerformanceTiming [[!NAVIGATION-TIMING]]</a></li>
   135       </ul>
   136 
   137     </section>
   138 
   139     <section id='conformance'>
   140       <p>
   141         This specification defines conformance criteria that apply to a single
   142         product: the <dfn id="dfn-user-agent">user agent</dfn> that implements
   143         the interfaces that it contains.
   144       </p>
   145 
   146       <p>
   147         Implementations that use ECMAScript to implement the APIs defined in
   148         this specification MUST implement them in a manner consistent with the
   149         ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]] as
   150         this specification uses that specification and terminology.
   151       </p>
   152 
   153       <p>
   154         A conforming implementation is required to implement all fields
   155         defined in this specification.
   156       </p>
   157     </section>
   158 
   159     <section>
   160 
   161       <h2>Scope</h2>
   162 
   163       <p>Interfacing with external devices designed to control games has the
   164       potential to become large and intractable if approached in full
   165       generality. In this specification we explicitly choose to narrow scope
   166       to provide a useful subset of functionality that can be widely
   167       implemented and broadly useful.</p>
   168 
   169       <p>Specifically, we choose to only support the functionality required to
   170       support gamepads. Support for gamepads requires two input types: buttons
   171       and axes. Both buttons and axes are reported as analog values, buttons
   172       ranging from [0..1], and axes ranging from [-1..1].</p>
   173 
   174       <p>While the primary goal is support for gamepad devices, supporting
   175       these two types of analog inputs allows support for other similar devices
   176       common to current gaming systems including joysticks, driving wheels,
   177       pedals, and accelerometers. As such, the name "gamepad" is exemplary
   178       rather than trying to be a generic name for the entire set of devices
   179       addressed by this specification.</p>
   180 
   181       <p>We specifically exclude support for more complex devices that may also
   182       be used in some gaming contexts, including those that that do motion
   183       sensing, depth sensing, video analysis, gesture recognition, and so
   184       on.</p>
   185 
   186     </section>
   187 
   188     <section>
   189       <h2><dfn>Gamepad</dfn> Interface</h2>
   190       <p>
   191         This interface defines an individual gamepad device.
   192       </p>
   193 
   194       <dl title='interface Gamepad' class='idl'>
   195 
   196         <dt>readonly attribute DOMString id</dt>
   197         <dd>
   198           An identification string for the gamepad.
   199 
   200           This string identifies the brand or style of connected gamepad
   201           device. Typically, this will include the USB vendor and a product
   202           ID.
   203         </dd>
   204 
   205         <dt>readonly attribute long index</dt>
   206         <dd>
   207           The index of the gamepad in the Navigator.
   208 
   209           When multiple gamepads are connected to a <a>user agent</a>,
   210           indices MUST be assigned on a first-come, first-serve basis,
   211           starting at zero. If a gamepad is disconnected, previously assigned
   212           indices MUST NOT be reassigned to gamepads that continue to be
   213           connected. However, if a gamepad is disconnected, and subsequently
   214           the same or a different gamepad is then connected, index entries
   215           MUST be reused.
   216 
   217         </dd>
   218 
   219         <dt>readonly attribute boolean connected</dt>
   220         <dd>
   221           Indicates whether the physical device represented by this
   222           object is still connected to the system.
   223 
   224           When a gamepad becomes unavailable, whether by being physically
   225           disconnected, powered off or otherwise unusable, the
   226           <code>connected</code> attribute MUST be set to false.
   227         </dd>
   228 
   229         <dt>readonly attribute DOMHighResTimeStamp timestamp</dt>
   230 
   231         <dd>
   232           Last time the data for this gamepad was updated.
   233 
   234           Timestamp is a monotonically increasing value that allows the author
   235           to determine if the <code>axes</code> and <code>button</code> data
   236           have been updated from the hardware. The value must be relative to
   237           the <code>navigationStart</code> attribute of the PerformanceTiming
   238           interface. Since values are monotonically increasing they can be
   239           compared to determine the ordering of updates, as newer values will
   240           always be greater than or equal to older values.
   241 
   242           If no data has been received from the hardware, the value of
   243           the <code>timestamp</code> attribute should be the time relative
   244           to <code>navigationStart</code> when the Gamepad object was first
   245           made available to script.
   246         </dd>
   247 
   248         <dt>readonly attribute GamepadMappingType mapping</dt>
   249         <dd>
   250           The mapping in use for this device.
   251 
   252           If the user agent has knowledge of the layout of the device,
   253           then it SHOULD indicate that a mapping is in use by setting
   254           this property to a known mapping name. Currently the only
   255           known mapping is <code>"standard"</code>, which corresponds
   256           to the <a href="#remapping">Standard Gamepad layout</a>.
   257 
   258           If the user agent does not have knowledge of the device layout
   259           and is simply providing the controls as represented by the
   260           driver in use, then it MUST set the <code>mapping</code> property
   261           to an empty string.
   262         </dd>
   263 
   264         <dt>readonly attribute double[] axes</dt>
   265         <dd>
   266 
   267           Array of values for all axes of the gamepad.
   268 
   269           All axis values MUST be linearly normalized to the range [-1.0 ..
   270           1.0]. As appropriate, -1.0 SHOULD correspond to "up" or "left", and
   271           1.0 SHOULD correspond to "down" or "right".
   272 
   273           Axes that are drawn from a 2D input device SHOULD appear next to
   274           each other in the axes array, X then Y.
   275 
   276           It is RECOMMENDED that axes appear in decreasing order of
   277           importance, such that element 0 and 1 typically represent the X and
   278           Y axis of a directional stick.
   279 
   280         </dd>
   281 
   282         <dt>readonly attribute GamepadButton[] buttons</dt>
   283         <dd>
   284           Array of button states for all buttons of the gamepad.
   285 
   286           It is RECOMMENDED that buttons appear in decreasing importance such
   287           that the primary button, secondary button, tertiary button, and so
   288           on appear as elements 0, 1, 2, ... in the buttons array.
   289 
   290         </dd>
   291 
   292       </dl>
   293     </section>
   294 
   295     <section>
   296       <h2><dfn>GamepadButton</dfn> Interface</h2>
   297       <p>
   298         This interface defines the state of an individual button
   299         on a gamepad device.
   300       </p>
   301 
   302       <dl title='interface GamepadButton' class='idl'>
   303         <dt>readonly attribute boolean pressed</dt>
   304         <dd>
   305           The pressed state of the button. This property MUST be
   306           true if the button is currently pressed, and false if it is
   307           not pressed.
   308 
   309           For buttons which do not have a digital switch to indicate
   310           a pure pressed or released state, the user agent MUST
   311           choose a threshold value to indicate the button as pressed
   312           when its value is above a certain amount. If the platform
   313           API gives a recommended value, the user agent SHOULD use that.
   314           In other cases, the user agent SHOULD choose some other
   315           reasonable value.
   316         </dd>
   317 
   318         <dt>readonly attribute double value</dt>
   319         <dd>
   320           For buttons that have an analog sensor, this property
   321           MUST represent the amount which the button has been pressed.
   322 
   323           All button values MUST be linearly normalized to the range [0.0 ..
   324           1.0]. 0.0 MUST mean fully unpressed, and 1.0 MUST mean fully
   325           pressed.
   326 
   327           For buttons without an analog sensor, only the values 0.0 and 1.0
   328           for fully unpressed and fully pressed MUST be provided.
   329         </dd>
   330       </dl>
   331     </section>
   332 
   333     <section>
   334       <h2><dfn>GamepadMappingType</dfn> enum</h2>
   335       <p>
   336         This enum defines the set of known mappings for a Gamepad.
   337       </p>
   338 
   339       <dl title='enum GamepadMappingType' class='idl'>
   340         <!-- https://github.com/w3c/respec/issues/372 -->
   341         <dt>_</dt>
   342         <dd>
   343           The empty string indicates that no mapping is in use for this gamepad.
   344           <strong>Note:</strong> the WebIDL here is currently wrong due to a ReSpec bug. The actual enum value is the empty string ("").
   345         </dd>
   346 
   347         <dt>standard</dt>
   348         <dd>
   349           The Gamepad's controls have been mapped to the
   350           <a href="#remapping">Standard Gamepad layout</a>.
   351         </dd>
   352       </dl>
   353     </section>
   354 
   355     <section>
   356       <h2>Navigator Interface extension</h2>
   357 
   358       <p>
   359 
   360         This partial interface defines an extension to the Navigator
   361         interface.
   362 
   363       </p>
   364 
   365 
   366       <dl title='partial interface Navigator' class='idl'>
   367         <dt>sequence&lt;Gamepad?&gt; getGamepads()</dt>
   368 
   369         <dd>
   370 
   371           Retrieve a snapshot of the data for the the currently connected and
   372           interacted-with gamepads.
   373 
   374           Gamepads MUST only appear in the list if they are currently
   375           connected to the <a>user agent</a>, and at least one device has been
   376           interacted with by the user. If no devices have been interacted
   377           with, devices MUST NOT appear in the list to avoid a malicious page
   378           from fingerprinting the user.
   379 
   380           The length of the array returned MUST be at least one more than the
   381           maximum index value of the Gamepad objects returned in the array.
   382 
   383           The entries in the array MUST be the set of Gamepad objects that
   384           are visible to the current page, with each Gamepad present at the
   385           index in the array specified by its <a href="#widl-Gamepad-index">index</a>
   386           property. Array indices for which there is no connected Gamepad with
   387           the corresponding index should return null.
   388 
   389           <p>As an example, if there is one connected gamepad with an index of
   390             1, then the following code snippet describes the expected behavior:
   391 
   392           <pre class="example highlight">
   393             // gamepads should look like [null, [object Gamepad]]
   394             var gamepads = navigator.getGamepads();
   395             // The following statements should all evaluate to true.
   396             gamepads[0] == null;
   397             gamepads[1].index == 1;
   398           </pre>
   399         </dd>
   400       </dl>
   401     </section>
   402 
   403     <section>
   404       <h2><dfn>GamepadEvent</dfn> Interface</h2>
   405       <dl title='[Constructor(GamepadEventInit eventInitDict)] interface GamepadEvent : Event'
   406           class='idl'>
   407         <dt>readonly attribute Gamepad gamepad</dt>
   408 
   409         <dd>
   410 
   411             The single gamepad attribute provides access to the associated
   412             gamepad data for this event.
   413 
   414         </dd>
   415 
   416       </dl>
   417       <dl title='dictionary GamepadEventInit : EventInit' class='idl'>
   418         <dt>required Gamepad gamepad</dt>
   419         <dd>
   420           The gamepad associated with this event.
   421         </dd>
   422       </dl>
   423     </section>
   424 
   425     <section>
   426       <h2>Remapping</h2>
   427 
   428       <p>
   429 
   430         Each device manufacturer creates many different products and each has
   431         unique styles and layouts of buttons and axes. It is intended that the
   432         <a>user agent</a> support as many of these as possible.
   433 
   434       </p>
   435 
   436       <p>
   437 
   438         Additionally there are <em>de facto</em> standard layouts that have
   439         been made popular by game consoles. When the <a>user agent</a>
   440         recognizes the attached device, it is RECOMMENDED that it be remapped
   441         to a canonical ordering when possible. Devices that are not recognized
   442         should still be exposed in their raw form.
   443 
   444       </p>
   445 
   446       <p>
   447 
   448         There is currently one canonical device, the &quot;Standard
   449         Gamepad&quot;. The standard gamepad has 4 axes, and up to 17 buttons.
   450         When remapping, the indices in <a href="#widl-Gamepad-axes">axes</a>[] 
   451 	and <a href="widl-Gamepad-buttons">buttons</a>[]
   452         should correspond as closely as possible to the physical locations in
   453         the diagram below. Additionally, the <a href="#widl-Gamepad-mapping">
   454         <code>mapping</code></a> property of the Gamepad SHOULD be set to the
   455         string <code>"standard"</code>.
   456       </p>
   457 
   458       <embed src="standard_gamepad.svg" type="image/svg+xml" />
   459 
   460     </section>
   461 
   462     <section class="informative">
   463         <h2>Usage Examples</h2>
   464 
   465           <p>
   466 
   467             The example below demonstrates typical access to gamepads. Note
   468             the relationship with the <a href="#bib-ANIMATION-TIMING">WindowAnimationTiming</a>
   469             interface.
   470           </p>
   471 
   472           <section>
   473               <pre class="example">
   474 
   475 function runAnimation()
   476 {
   477     window.requestAnimationFrame(runAnimation);
   478 
   479     var gamepads = navigator.getGamepads();
   480 
   481     for (var i = 0; i < gamepads.length; ++i)
   482     {
   483         var pad = gamepads[i];
   484         // todo; simple demo of displaying pad.axes and pad.buttons
   485     }
   486 }
   487 
   488 window.requestAnimationFrame(runAnimation);
   489 
   490               </pre>
   491           </section>
   492 
   493           <div class="practice"> 
   494               <p> 
   495               <span id="practice-timing" class="practicelab">Coordination with
   496               WindowAnimationTiming</span></p> 
   497               <p class="practicedesc"> 
   498 
   499               Interactive applications will typically be using the
   500               <a href="#bib-ANIMATION-TIMING">WindowAnimationTiming</a> interface to drive animation, and
   501               will want coordinate animation with user gamepad input. As
   502               such, the gamepad data should be polled as closely as possible
   503               to immediately before the animation callbacks are executed, and
   504               with frequency matching that of the animation. That is, if the
   505               animation callbacks are running at 60Hz, the gamepad inputs
   506               should also be sampled at that rate.
   507 
   508               </p> 
   509           </div> 
   510 
   511 
   512     </section>
   513 
   514     <section>
   515 
   516       <h3 id="event-gamepadconnected">The <dfn class="event">gamepadconnected</dfn> event</h3>
   517 
   518         <p>
   519           User agents implementing this specification must provide a new DOM
   520           event, named <code>gamepadconnected</code>. The corresponding event
   521           MUST be of type <code>GamepadEvent</code> and MUST fire on the
   522           <code>window</code> object. Registration for and firing of the
   523           <code>gamepadconnected</code> event MUST follow the usual behavior
   524           of DOM4 Events. [[!DOM4]]
   525         </p>
   526 
   527         <p>
   528           A <a>user agent</a> MUST dispatch this event type to indicate the
   529           user has connected a gamepad. If a gamepad was already connected
   530           when the page was loaded, the <a>gamepadconnected</a> event SHOULD be
   531           dispatched when the user presses a button or moves an axis.
   532         </p>
   533 
   534     </section>
   535 
   536     <section>
   537 
   538         <h3 id="event-gamepaddisconnected">The <dfn class="event">gamepaddisconnected</dfn> event</h3>
   539 
   540         <p>
   541           User agents implementing this specification must provide a new DOM
   542           event, named <code>gamepaddisconnected</code>. The corresponding event
   543           MUST be of type <code>GamepadEvent</code> and MUST fire on the
   544           <code>window</code> object. Registration for and firing of the
   545           <code>gamepaddisconnected</code> event MUST follow the usual behavior
   546           of DOM4 Events. [[!DOM4]]
   547         </p>
   548 
   549         <p>
   550           When a gamepad is disconnected from the <a>user agent</a>, if the
   551           <a>user agent</a> has previously dispatched a
   552           <a>gamepadconnected</a> event for that gamepad to a window, a
   553           <a>gamepaddisconnected</a> event MUST be dispatched to that same
   554           window.
   555         </p>
   556 
   557     </section>
   558 
   559     <section>
   560 
   561         <h3>Other events</h3>
   562 
   563         <p>
   564 
   565         <i>More discussion needed, on whether to include or exclude axis and button
   566         changed events, and whether to roll them more together
   567         (<code>gamepadchanged</code>?), separate somewhat
   568         (<code>gamepadaxischanged</code>?), or separate by individual axis
   569         and button.</i>
   570 
   571         </p>
   572 
   573     </section>
   574 
   575     <section class='appendix informative'>
   576       <h2>Acknowledgements</h2>
   577       <p>
   578         Many have made contributions in code, comments, or documentation: 
   579       </p>
   580         <ul>
   581             <li>David Humphrey</li>
   582             <li>Gregg Tavares</li>
   583             <li>Marcin Wichary</li>
   584             <li>Jason Orendorff</li>
   585             <li>Olli Pettay</li>
   586             <li>Rick Waldron</li>
   587         </ul>
   588       <p>
   589         Please let me know if I have inadvertently omitted your name.
   590       </p>
   591     </section>
   592   </body>
   593 </html>