--- /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 "10 foot" 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>