gamepad.html
changeset 108 d1f13495dcea
child 109 3d086bcaabe9
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/gamepad.html	Tue Sep 20 13:29:10 2011 -0700
@@ -0,0 +1,411 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Joystick</title>
+    <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
+    <meta name="viewport" content="width=device-width">
+    <!--
+      === NOTA BENE ===
+      For the three scripts below, if your spec resides on dev.w3 you can check them
+      out in the same tree and use relative links so that they'll work offline,
+     -->
+    <script src='http://dev.w3.org/2009/dap/ReSpec.js/js/respec.js' class='remove'></script>
+    <script class='remove'>
+      var respecConfig = {
+          // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
+          specStatus:           "ED",
+
+          // the specification's short name, as in http://www.w3.org/TR/short-name/
+          shortName:            "gamepad",
+
+          // if your specification has a subtitle that goes below the main
+          // formal title, define it here
+          // subtitle   :  "an excellent document",
+
+          // if you wish the publication date to be other than today, set this
+          //publishDate:  "2011-01-01",
+
+          // if the specification's copyright date is a range of years, specify
+          // the start date here:
+          // copyrightStart: "2005"
+
+          // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
+          // and its maturity status
+          // previousPublishDate:  "1977-03-15",
+          // previousMaturity:  "WD",
+
+          // if there a publicly available Editor's Draft, this is the link
+          edDraftURI:           "http://dvcs.w3.org/hg/webevents/raw-file/default/gamepad.html",
+
+          // if this is a LCWD, uncomment and set the end of its review period
+          // lcEnd: "2009-08-05",
+
+          // if you want to have extra CSS, append them to this list
+          // it is recommended that the respec.css stylesheet be kept
+          extraCSS:             ["http://www.w3.org/StyleSheets/TR/W3C-TR.css", "http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css"],
+
+          // editors, add as many as you like
+          // only "name" is required
+          editors:  [
+              { name: "Scott Graham", url: "http://h4ck3r.net/",
+                company: "Google", companyURL: "http://www.google.com/" },
+              { name: "Ted Mielczarek", url: "http://ted.mielczarek.org/",
+                company: "Mozilla", companyURL: "http://www.mozilla.org/" },
+          ],
+
+          // authors, add as many as you like.
+          // This is optional, uncomment if you have authors as well as editors.
+          // only "name" is required. Same format as editors.
+
+          //authors:  [
+          //    { name: "Your Name", url: "http://example.org/",
+          //      company: "Your Company", companyURL: "http://example.com/" },
+          //],
+
+          // name of the WG
+          wg:           "Web Events Working Group",
+
+          // URI of the public WG page
+          wgURI:        "http://www.w3.org/2010/webevents/",
+
+          // name (with the @w3c.org) of the public mailing to which comments are due
+          wgPublicList: "public-webevents",
+
+          // URI of the patent status for this WG, for Rec-track documents
+          // !!!! IMPORTANT !!!!
+          // This is important for Rec-track documents, do not copy a patent URI from a random
+          // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
+          // Team Contact.
+          wgPatentURI:  "http://www.w3.org/2004/01/pp-impl/45559/status",
+      };
+    </script>
+
+    <style type="text/css">
+      .event {
+        font-family: monospace;
+        color: #459900;
+      }
+
+      pre.idl {
+        white-space: pre-wrap;
+      }
+    </style>
+  </head>
+  <body>
+    <section id='abstract'>
+      The Joystick specification defines a low-level interface that represents
+      joystick devices (also known as game pads).
+    </section>
+
+    <section id='introduction' class='informative'>
+
+      <h2>Introduction</h2>
+
+      <p>Some <a>user agent</a>s have connected joystick devices (also known
+      as gamepads). These devices are desirable and suited to input for gaming
+      applications, and for &quot;10 foot&quot; user interfaces
+      (presentations, media viewers).</p>
+
+      <p>Currently, the only way for a joystick 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 <a>user agent</a> to
+      accomplish emulation.</p>
+
+      <p>Meanwhile, native applications are capable of accessing these devices
+      via system APIs.</p>
+
+      <p>The Joystick API provides a solution to this problem by specifying
+      interfaces that allow web applications to directly act on joystick
+      data.</p>
+
+      <p>This specification references interfaces from a number of other
+      specifications:</p>
+
+      <ul>
+      <li><a class="externalDFN">Document</a> [[!DOM-LEVEL-3-CORE]]</li>
+      <li><a class="externalDFN">DOMTimeStamp</a> [[!WEBIDL]]</li>
+      <li><a class="externalDFN">WindowAnimationTiming</a> [[ANIMATION-TIMING]]</li>
+      </ul>
+
+    </section>
+
+    <section id='conformance'>
+      <p>
+        This specification defines conformance criteria that apply to a single
+        product: the <dfn id="dfn-user-agent">user agent</dfn> that implements
+        the interfaces that it contains.
+      </p>
+
+      <p>
+        Implementations that use ECMAScript to implement the APIs defined in
+        this specification MUST implement them in a manner consistent with the
+        ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]] as
+        this specification uses that specification and terminology.
+      </p>
+
+      <p>
+        A conforming implementation is required to implement all fields
+        defined in this specification.
+      </p>
+    </section>
+
+    <section>
+      <h2><a>Joystick</a> Interface</h2>
+      <p>
+        This interface defines an individual joystick device.
+      </p>
+
+      <dl title='interface Joystick' class='idl'>
+
+        <dt>readonly attribute string id</dt>
+        <dd>
+          An identification string for the joystick.
+
+          This string identifies the brand or style of connected joystick
+          device. Typically, this will include the USB vendor and a product
+          ID.
+        </dd>
+
+        <dt>readonly attribute long index</dt>
+        <dd>
+          The index of the joystick in the <a>DocumentJoysticks</a>.
+
+          When multiple joysticks are connected to a <a>user agent</a>,
+          indices MUST be assigned on a first-come, first-serve basis,
+          starting at zero. If a joystick is disconnected, previously assigned
+          indices MUST NOT be reassigned to joysticks that continue to be
+          connected. However, if a joystick is disconnected, and subsequently
+          the same or a different joystick is then connected, index entries
+          MUST be reused.
+
+        </dd>
+
+        <dt>readonly attribute DOMTimeStamp timestamp</dt>
+
+        <dd>
+          Last time the data for this joystick was updated.
+
+          Timestamp is a monotonically increasing value that allows the author
+          to determine if the <code>axes</code> and <code>button</code> data
+          have been updated from the hardware, relative to a previously saved
+          timestamp.
+
+        </dd>
+
+        <dt>readonly attribute float[] axes</dt>
+        <dd>
+
+          Array of values for all axes of the joystick.
+
+          All axis values MUST be linearly normalized to the range [-1.0 ..
+          1.0]. As appropriate, -1.0 SHOULD correspond to "up" or "left", and
+          1.0 SHOULD correspond to "down" 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.
+
+        </dd>
+
+        <dt>readonly attribute float[] buttons</dt>
+        <dd>
+          Array of values for all buttons of the joystick.
+
+          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.
+
+          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.
+
+        </dd>
+
+        <dt>readonly attribute float[] suggestedAxesDeadZone</dt>
+        <dd>
+
+          Array of values that represent suggested amount of input to ignore
+          for corresponding values in the axes array. These values are
+          hardware dependent and reflect tolerances for sampling (sometimes
+          low-quality) analog inputs.
+
+        </dd>
+
+        <dt>readonly attribute float[] suggestedButtonsDeadZone</dt>
+        <dd>
+
+          Array of values that represent suggested amount of input to ignore
+          for corresponding values in the buttons array. These values are
+          hardware dependent and reflect tolerances for sampling (sometimes
+          low-quality) analog inputs.
+
+        </dd>
+
+      </dl>
+    </section>
+
+    <section>
+      <h2><a>DocumentJoysticks</a> Interface</h2>
+
+      <p>
+
+        This interface defines a collection of Joysticks. The
+        <a>DocumentJoysticks</a> interface MUST be implemented on the
+        <a>Document</a> object.
+
+      </p>
+
+
+      <dl title='interface DocumentJoysticks' class='idl'>
+        <dt>readonly attribute Joystick[] joysticks</dt>
+
+        <dd>
+
+          The currently connected and interacted-with joysticks.
+
+          Joysticks MUST only appear in the list if they are currently
+          connected to the <a>user agent</a>, and have been interacted with by
+          the user. Otherwise, they MUST not appear in the list to avoid a
+          malicious page from fingerprinting the user based on connected
+          devices.
+
+        </dd>
+
+      </dl>
+    </section>
+
+    <section>
+      <h2><a>JoystickEvent</a> Interface</h2>
+
+      <dl title='interface JoystickEvent' class='idl'>
+        <dt>readonly attribute Joystick joystick</dt>
+
+        <dd>
+
+            The single joystick attribute provides access to the associated
+            joystick data for this event.
+
+        </dd>
+
+      </dl>
+    </section>
+
+      
+    <section class="informative">
+        <h2>Usage Examples</h2>
+          
+          <p>
+
+            The example below demonstrates typical access to joysticks. Note
+            the relationship with the <a>WindowAnimationTiming</a>
+            [[!ANIMATION-TIMING]] interface.
+          </p>
+          
+          <section>
+              <pre class="example">
+
+function runAnimation()
+{
+    window.requestAnimationFrame(runAnimation);
+
+    for (var i = 0; i < document.joysticks.length; ++i)
+    {
+        var joy = document.joysticks[i];
+        // todo; simple demo of displaying joy.axes and joy.buttons
+    }
+}
+
+window.requestAnimationFrame(runAnimation);
+
+              </pre>
+          </section>
+
+          <div class="practice"> 
+              <p> 
+              <span id="practice-timing" class="practicelab">Coordination with
+              WindowAnimationTiming</span></p> 
+              <p class="practicedesc"> 
+
+              Interactive applications will typically be using the
+              <a>WindowAnimationTiming</a> interface to drive animation, and
+              will want coordinate animation with user joystick input. As
+              such, the joystick 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 joystick inputs
+              should also be sampled at that rate.
+
+              </p> 
+          </div> 
+
+
+    </section>
+
+    <section>
+
+      <h3 id="event-joystickconnected">The <dfn class="event">joystickconnected</dfn> event</h3>
+
+        <p>
+
+          A <a>user agent</a> MUST dispatch this event type to indicate the
+          user has connected a joystick. If a joystick was already connected
+          when the page was loaded, the <a>joystickconnected</a> event will be
+          dispatched when the user presses a button or moves an axis.
+
+        </p>
+
+    </section>
+
+    <section>
+
+        <h3 id="event-joystickdisconnected">The <dfn class="event">joystickdisconnected</dfn> event</h3>
+
+        <p>
+
+          When a joystick is disconnected from the <a>user agent</a>, if the
+          <a>user agent</a> has previously dispatched a
+          <a>joystickconnected</a> event, a <a>joystickdisconnected</a> event
+          MUST be dispatched.
+
+        </p>
+
+    </section>
+
+    <section>
+
+        <h3>Other events</h3>
+
+        <p>
+
+        <i>More discussion needed, on whether to include or exclude axis and button
+        changed events, and whether to roll them more together
+        (<code>joystickchanged</code>?), separate somewhat
+        (<code>joystickaxischanged</code>?), or separate by individual axis
+        and button.</i>
+
+        </p>
+
+    </section>
+
+    <section class='appendix informative'>
+      <h2>Acknowledgements</h2>
+      <p>
+        Many have made contributions in code, comments, or documentation: 
+      </p>
+        <ul>
+            <li>David Humphrey</li>
+            <li>Gregg Tavares</li>
+            <li>Jason Orendorff</li>
+            <li>Olli Pettay</li>
+            <li>Rick Waldron</li>
+            <li>Ted Mielczarek</li>
+        </ul>
+      <p>
+        Please let me know if I have inadvertently omitted your name.
+      </p>
+    </section>
+  </body>
+</html>