[gamelib-cvs] stick.html

[Ingvar Mattsson]

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>