Update of /project/gamelib/cvsroot/source/doc In directory clnet:/tmp/cvs-serv30530

Modified Files: stick.html Log Message: IM Better documentation and some explanatory graphs.

Index: stick.html =================================================================== RCS file: /project/gamelib/cvsroot/source/doc/stick.html,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** stick.html 27 Dec 2006 16:29:57 -0000 1.1 --- stick.html 27 Dec 2006 19:27:24 -0000 1.2 *************** *** 37,41 **** terminate the polling thread, call TERMINATE-POLL with the object as argument). All relevant locking is done, keyed on if a joystick is ! polled or not</p>

<p>There are two arrays that are of interest in a joystick object --- 37,42 ---- terminate the polling thread, call TERMINATE-POLL with the object as argument). All relevant locking is done, keyed on if a joystick is ! polled or not. Still, the publicly available information will only be ! done after a call to UPDATE-STICK.</p>

<p>There are two arrays that are of interest in a joystick object *************** *** 44,45 **** --- 45,95 ---- supports up to 8 analog axes and up to 24 buttons (and will most likely crash in amusing ways, should these limits be too strict).</p> + + <p>As part of the update and transformation from signed 16-bit integers + to SINGLE-FLOAT, some transformations of the data can be done. The + (currently) available library functions are SIMPLE-TRANSFER (the + default), a simple division by 32768.0s0 and SQUARE-TRANSFER (the + result of a SIMPLE-TRANSFER, squared and multiplied by the + signum).</p> + + <p>A graph displaying these two transfer functions (X axis is raw + joystick data, Y axis is the displacement along the axis available + from GAMES-STICK):<br> + <img src="stick-transfers.png" alt="Transfer function graph"> + </p> + + <h3>Full STICK package exported symbol list</h3> + <dl> + <dt> (axes <i>joystick</i>) + <dd> Returns an array, with axis 0 at index 0, axis 1 at index 1 and + so on. + <dt> (buttons <i>joystick</i>) + <dd> Returns a bit-vector, with button 0 at index 0, button 1 at + index 1 and so forth. A value of 0 means "not pressed", a value of 1 + means "pressed". + <dt> (make-stick <i>device-file</i>) + <dd> Create a joystick object for the named device. + <dt> (set-transfer <i>joystick</i> <i>axis</i> <i>transfer-fn</i>) + <dd> Set the transfer function for axis to the desired transfer + function. A transfer function should map from [ -32768, 32767 ] to [ + -1.0s0, 1.0s0 ]. + <dt> (simple-transfer <i>value</i>) + <dd> A simple transfer function (linear mapping from the integer + range to the single-float range). + <dt> (square-transfer <i>value</i>) + <dd> A slightly more complex transfer function, causing less + sensitivity in the "close to centred" region and slightly higher + sensitivity in the more extreme regions. + <dt> (update-stick <i>joystick</i>) + <dd> Copy current (hidden) data to teh publicly available data. Also + applies the relevant transfer functions. + <dt> (continous-poll <i>joystick</i>) + <dd> Only available if build with :SB-THREAD available on + *FEATURES*.<br>Start a separate thread reading from the device. Still + requires UPDATE-STICK to copy from private to pubic data. + <dt> (terminate-poll <i>joystick</i>) + <dd> Only available if build with :SB-THREAD available on + *FEATURES*.<br>Terminate continous polling for a specific joystick. + </dl> + </body> + </html>