gamepad.html
changeset 154 bbe9fa52b783
parent 138 9dc0265c3363
child 155 8fd2c534a9a3
equal deleted inserted replaced
153:8066aa392c1b 154:bbe9fa52b783
     1 <!DOCTYPE html>
     1 <!DOCTYPE html>
     2 <html lang="en">
     2 <html lang="en">
     3   <head>
     3   <head>
     4     <title>Gamepad</title>
     4     <title>Gamepad</title>
     5     <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
     5     <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
     6     <meta name="viewport" content="width=device-width">
     6     <meta name="Refresh" content="5; URL=../gamepad/gamepad.html">
     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='http://dev.w3.org/2009/dap/ReSpec.js/js/respec.js' 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/webevents/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           // if you want to have extra CSS, append them to this list
       
    44           // it is recommended that the respec.css stylesheet be kept
       
    45           extraCSS:             ["http://www.w3.org/StyleSheets/TR/W3C-TR.css", "http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css"],
       
    46 
       
    47           // editors, add as many as you like
       
    48           // only "name" is required
       
    49           editors:  [
       
    50               { name: "Scott Graham", url: "http://h4ck3r.net/",
       
    51                 company: "Google", companyURL: "http://www.google.com/" },
       
    52               { name: "Ted Mielczarek", url: "http://ted.mielczarek.org/",
       
    53                 company: "Mozilla", companyURL: "http://www.mozilla.org/" },
       
    54           ],
       
    55 
       
    56           // authors, add as many as you like.
       
    57           // This is optional, uncomment if you have authors as well as editors.
       
    58           // only "name" is required. Same format as editors.
       
    59 
       
    60           //authors:  [
       
    61           //    { name: "Your Name", url: "http://example.org/",
       
    62           //      company: "Your Company", companyURL: "http://example.com/" },
       
    63           //],
       
    64 
       
    65           // name of the WG
       
    66           wg:           "Web Events Working Group",
       
    67 
       
    68           // URI of the public WG page
       
    69           wgURI:        "http://www.w3.org/2010/webevents/",
       
    70 
       
    71           // name (with the @w3c.org) of the public mailing to which comments are due
       
    72           wgPublicList: "public-webevents",
       
    73 
       
    74           // URI of the patent status for this WG, for Rec-track documents
       
    75           // !!!! IMPORTANT !!!!
       
    76           // This is important for Rec-track documents, do not copy a patent URI from a random
       
    77           // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
       
    78           // Team Contact.
       
    79           wgPatentURI:  "http://www.w3.org/2004/01/pp-impl/45559/status",
       
    80       };
       
    81     </script>
       
    82 
       
    83     <style type="text/css">
       
    84       .event {
       
    85         font-family: monospace;
       
    86         color: #459900;
       
    87       }
       
    88 
       
    89       pre.idl {
       
    90         white-space: pre-wrap;
       
    91       }
       
    92     </style>
       
    93   </head>
     7   </head>
    94   <body>
     8   <body>
    95     <section id='abstract'>
     9     <p>
    96       The Gamepad specification defines a low-level interface that represents
    10       Moved to <a href="../gamepad/gamepad.html">https://dvcs.w3.org/gamepad/gamepad.html</a>.
    97       gamepad devices.
    11     </p>
    98     </section>
       
    99 
       
   100     <section id='introduction' class='informative'>
       
   101 
       
   102       <h2>Introduction</h2>
       
   103 
       
   104       <p>Some <a>user agent</a>s have connected gamepad devices. These devices
       
   105       are desirable and suited to input for gaming applications, and for
       
   106       &quot;10 foot&quot; user interfaces (presentations, media viewers).</p>
       
   107 
       
   108       <p>Currently, the only way for a gamepad to be used as input would be
       
   109       to emulate mouse or keyboard events, however this would lose information
       
   110       and require additional software outside of the <a>user agent</a> to
       
   111       accomplish emulation.</p>
       
   112 
       
   113       <p>Meanwhile, native applications are capable of accessing these devices
       
   114       via system APIs.</p>
       
   115 
       
   116       <p>The Gamepad API provides a solution to this problem by specifying
       
   117       interfaces that allow web applications to directly act on gamepad
       
   118       data.</p>
       
   119 
       
   120       <p>This specification references interfaces from a number of other
       
   121       specifications:</p>
       
   122 
       
   123       <ul>
       
   124       <li><a class="externalDFN">Navigator</a> [[!NAVIGATOR]]</li>
       
   125       <li><a class="externalDFN">DOMTimeStamp</a> [[!WEBIDL]]</li>
       
   126       <li><a class="externalDFN">WindowAnimationTiming</a> [[ANIMATION-TIMING]]</li>
       
   127       </ul>
       
   128 
       
   129     </section>
       
   130 
       
   131     <section id='conformance'>
       
   132       <p>
       
   133         This specification defines conformance criteria that apply to a single
       
   134         product: the <dfn id="dfn-user-agent">user agent</dfn> that implements
       
   135         the interfaces that it contains.
       
   136       </p>
       
   137 
       
   138       <p>
       
   139         Implementations that use ECMAScript to implement the APIs defined in
       
   140         this specification MUST implement them in a manner consistent with the
       
   141         ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]] as
       
   142         this specification uses that specification and terminology.
       
   143       </p>
       
   144 
       
   145       <p>
       
   146         A conforming implementation is required to implement all fields
       
   147         defined in this specification.
       
   148       </p>
       
   149     </section>
       
   150 
       
   151     <section>
       
   152 
       
   153       <h2>Scope</h2>
       
   154 
       
   155       <p>Interfacing with external devices designed to control games has the
       
   156       potential to become large and intractable if approached in full
       
   157       generality. In this specification we explicitly choose to narrow scope
       
   158       to provide a useful subset of functionality that can be widely
       
   159       implemented and broadly useful.</p>
       
   160 
       
   161       <p>Specifically, we choose to only support the functionality required to
       
   162       support gamepads. Support for gamepads requires two input types: buttons
       
   163       and axes. Both buttons and axes are reported as analog values, buttons
       
   164       ranging from [0..1], and axes ranging from [-1..1].</p>
       
   165       
       
   166       <p>While the primary goal is support for gamepad devices, supporting
       
   167       these two types of analog inputs allows support for other similar devices
       
   168       common to current gaming systems including joysticks, driving wheels,
       
   169       pedals, and accelerometers. As such, the name "gamepad" is exemplary
       
   170       rather than trying to be a generic name for the entire set of devices
       
   171       addressed by this specification.</p>
       
   172       
       
   173       <p>We specifically exclude support for more complex devices that may also
       
   174       be used in some gaming contexts, including those that that do motion
       
   175       sensing, depth sensing, video analysis, gesture recognition, and so
       
   176       on.</p>
       
   177 
       
   178     </section>
       
   179 
       
   180     <section>
       
   181       <h2><a>Gamepad</a> Interface</h2>
       
   182       <p>
       
   183         This interface defines an individual gamepad device.
       
   184       </p>
       
   185 
       
   186       <dl title='interface Gamepad' class='idl'>
       
   187 
       
   188         <dt>readonly attribute string id</dt>
       
   189         <dd>
       
   190           An identification string for the gamepad.
       
   191 
       
   192           This string identifies the brand or style of connected gamepad
       
   193           device. Typically, this will include the USB vendor and a product
       
   194           ID.
       
   195         </dd>
       
   196 
       
   197         <dt>readonly attribute long index</dt>
       
   198         <dd>
       
   199           The index of the gamepad in the <a>Navigator</a>.
       
   200 
       
   201           When multiple gamepads are connected to a <a>user agent</a>,
       
   202           indices MUST be assigned on a first-come, first-serve basis,
       
   203           starting at zero. If a gamepad is disconnected, previously assigned
       
   204           indices MUST NOT be reassigned to gamepads that continue to be
       
   205           connected. However, if a gamepad is disconnected, and subsequently
       
   206           the same or a different gamepad is then connected, index entries
       
   207           MUST be reused.
       
   208 
       
   209         </dd>
       
   210 
       
   211         <dt>readonly attribute DOMTimeStamp timestamp</dt>
       
   212 
       
   213         <dd>
       
   214           Last time the data for this gamepad was updated.
       
   215 
       
   216           Timestamp is a monotonically increasing value that allows the author
       
   217           to determine if the <code>axes</code> and <code>button</code> data
       
   218           have been updated from the hardware, relative to a previously saved
       
   219           timestamp.
       
   220 
       
   221         </dd>
       
   222 
       
   223         <dt>readonly attribute float[] axes</dt>
       
   224         <dd>
       
   225 
       
   226           Array of values for all axes of the gamepad.
       
   227 
       
   228           All axis values MUST be linearly normalized to the range [-1.0 ..
       
   229           1.0]. As appropriate, -1.0 SHOULD correspond to "up" or "left", and
       
   230           1.0 SHOULD correspond to "down" or "right".
       
   231 
       
   232           Axes that are drawn from a 2D input device SHOULD appear next to
       
   233           each other in the axes array, X then Y.
       
   234           
       
   235           It is RECOMMENDED that axes appear in decreasing order of
       
   236           importance, such that element 0 and 1 typically represent the X and
       
   237           Y axis of a directional stick.
       
   238 
       
   239         </dd>
       
   240 
       
   241         <dt>readonly attribute float[] buttons</dt>
       
   242         <dd>
       
   243           Array of values for all buttons of the gamepad.
       
   244 
       
   245           All button values MUST be linearly normalized to the range [0.0 ..
       
   246           1.0]. 0.0 MUST mean fully unpressed, and 1.0 MUST mean fully
       
   247           pressed.
       
   248 
       
   249           It is RECOMMENDED that buttons appear in decreasing importance such
       
   250           that the primary button, secondary button, tertiary button, and so
       
   251           on appear as elements 0, 1, 2, ... in the buttons array.
       
   252 
       
   253         </dd>
       
   254 
       
   255       </dl>
       
   256     </section>
       
   257 
       
   258     <section>
       
   259       <h2><a>Navigator</a> Interface extension</h2>
       
   260 
       
   261       <p>
       
   262 
       
   263         This partial interface defines an extension to the <a>Navigator</a>
       
   264         interface.
       
   265 
       
   266       </p>
       
   267 
       
   268 
       
   269       <dl title='partial interface Navigator' class='idl'>
       
   270         <dt>readonly attribute Gamepad[] gamepads</dt>
       
   271 
       
   272         <dd>
       
   273 
       
   274           The currently connected and interacted-with gamepads.
       
   275 
       
   276           Gamepads MUST only appear in the list if they are currently
       
   277           connected to the <a>user agent</a>, and have been interacted with by
       
   278           the user. Otherwise, they MUST not appear in the list to avoid a
       
   279           malicious page from fingerprinting the user based on connected
       
   280           devices.
       
   281 
       
   282         </dd>
       
   283 
       
   284       </dl>
       
   285     </section>
       
   286 
       
   287     <section>
       
   288       <h2><a>GamepadEvent</a> Interface</h2>
       
   289 
       
   290       <dl title='interface GamepadEvent' class='idl'>
       
   291         <dt>readonly attribute Gamepad gamepad</dt>
       
   292 
       
   293         <dd>
       
   294 
       
   295             The single gamepad attribute provides access to the associated
       
   296             gamepad data for this event.
       
   297 
       
   298         </dd>
       
   299 
       
   300       </dl>
       
   301     </section>
       
   302 
       
   303       
       
   304     <section class="informative">
       
   305         <h2>Usage Examples</h2>
       
   306           
       
   307           <p>
       
   308 
       
   309             The example below demonstrates typical access to gamepads. Note
       
   310             the relationship with the <a>WindowAnimationTiming</a>
       
   311             [[!ANIMATION-TIMING]] interface.
       
   312           </p>
       
   313           
       
   314           <section>
       
   315               <pre class="example">
       
   316 
       
   317 function runAnimation()
       
   318 {
       
   319     window.requestAnimationFrame(runAnimation);
       
   320 
       
   321     for (var i = 0; i < navigator.gamepads.length; ++i)
       
   322     {
       
   323         var pad = navigator.gamepads[i];
       
   324         // todo; simple demo of displaying pad.axes and pad.buttons
       
   325     }
       
   326 }
       
   327 
       
   328 window.requestAnimationFrame(runAnimation);
       
   329 
       
   330               </pre>
       
   331           </section>
       
   332 
       
   333           <div class="practice"> 
       
   334               <p> 
       
   335               <span id="practice-timing" class="practicelab">Coordination with
       
   336               WindowAnimationTiming</span></p> 
       
   337               <p class="practicedesc"> 
       
   338 
       
   339               Interactive applications will typically be using the
       
   340               <a>WindowAnimationTiming</a> interface to drive animation, and
       
   341               will want coordinate animation with user gamepad input. As
       
   342               such, the gamepad data should be polled as closely as possible
       
   343               to immediately before the animation callbacks are executed, and
       
   344               with frequency matching that of the animation. That is, if the
       
   345               animation callbacks are running at 60Hz, the gamepad inputs
       
   346               should also be sampled at that rate.
       
   347 
       
   348               </p> 
       
   349           </div> 
       
   350 
       
   351 
       
   352     </section>
       
   353 
       
   354     <section>
       
   355 
       
   356       <h3 id="event-gamepadconnected">The <dfn class="event">gamepadconnected</dfn> event</h3>
       
   357 
       
   358         <p>
       
   359 
       
   360           A <a>user agent</a> MUST dispatch this event type to indicate the
       
   361           user has connected a gamepad. If a gamepad was already connected
       
   362           when the page was loaded, the <a>gamepadconnected</a> event will be
       
   363           dispatched when the user presses a button or moves an axis.
       
   364 
       
   365         </p>
       
   366 
       
   367     </section>
       
   368 
       
   369     <section>
       
   370 
       
   371         <h3 id="event-gamepaddisconnected">The <dfn class="event">gamepaddisconnected</dfn> event</h3>
       
   372 
       
   373         <p>
       
   374 
       
   375           When a gamepad is disconnected from the <a>user agent</a>, if the
       
   376           <a>user agent</a> has previously dispatched a
       
   377           <a>gamepadconnected</a> event, a <a>gamepaddisconnected</a> event
       
   378           MUST be dispatched.
       
   379 
       
   380         </p>
       
   381 
       
   382     </section>
       
   383 
       
   384     <section>
       
   385 
       
   386         <h3>Other events</h3>
       
   387 
       
   388         <p>
       
   389 
       
   390         <i>More discussion needed, on whether to include or exclude axis and button
       
   391         changed events, and whether to roll them more together
       
   392         (<code>gamepadchanged</code>?), separate somewhat
       
   393         (<code>gamepadaxischanged</code>?), or separate by individual axis
       
   394         and button.</i>
       
   395 
       
   396         </p>
       
   397 
       
   398     </section>
       
   399 
       
   400     <section class='appendix informative'>
       
   401       <h2>Acknowledgements</h2>
       
   402       <p>
       
   403         Many have made contributions in code, comments, or documentation: 
       
   404       </p>
       
   405         <ul>
       
   406             <li>David Humphrey</li>
       
   407             <li>Gregg Tavares</li>
       
   408             <li>Jason Orendorff</li>
       
   409             <li>Olli Pettay</li>
       
   410             <li>Rick Waldron</li>
       
   411         </ul>
       
   412       <p>
       
   413         Please let me know if I have inadvertently omitted your name.
       
   414       </p>
       
   415     </section>
       
   416   </body>
    12   </body>
   417 </html>
    13 </html>