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