home *** CD-ROM | disk | FTP | other *** search
/ Virtual Reality Zone / VRZONE.ISO / mac / PC / PCGLOVE / GLOVE / OBJGLV.ZIP / DOC / PDRIVER.DOC < prev    next >
Text File  |  1992-09-25  |  9KB  |  226 lines
  1.  
  2.       REND386 POINTER, HEAD TRACKER, AND SWITCHING DEVICE DRIVERS
  3.                  Written by Dave Stampe, September 1992
  4.  
  5. Pointer device drivers are compiled in pseudo-tiny mode (code, data in one
  6. segment, stack not assumed in the same segment).  The interface is through
  7. an assembly routine at the start of the driver.
  8.  
  9. During development, the code may be linked with REND386 and appropriate
  10. changes made to POINTER.C to "fake" the load and initialization.  See
  11. MEMMODEL for more information.  At this stage, all assembly modules
  12. should use the .MODEL LARGE directive.
  13.  
  14. See the file MEMMODEL for a description of the memory modes, and how to
  15. compile your driver.
  16.  
  17. -------------------------------
  18.  
  19. STRUCTURE OF THE POINTER DRIVER
  20.  
  21. The driver consists of an assembly interface module (linked in first),
  22. a pconfig{} structure giving driver data, and an interperter module
  23. which is called from REND386.
  24.  
  25. The interperter accepts these commands and arguments:
  26.  
  27.  /* driver call equates: call *driver_pointer with this code */
  28.  /* all return *pconfig or integer */
  29.  #define DRIVER_INIT  0   /* rtns *pconfig, args = type    */
  30.  #define DRIVER_RESET 1   /* no rtn, no args               */
  31.  #define DRIVER_READ  2   /* rtns NULL if no data ready, else *pconfig */
  32.                                                     /* args = *pointer, mode */
  33.  #define DRIVER_CMD   3   /* args = mode, rtns *pconfig    */
  34.  #define DRIVER_CHECK 4   /* no args, rtns *pconfig        */
  35.  #define DRIVER_QUIT  5   /* no args, no rtn               */
  36.  
  37. Calls are usually made thru REND386's interface command, so
  38. avoid returning anything unexpected.
  39.  
  40.  
  41. INTERPERTER CALL DEFINITIONS (first argument)
  42.  
  43. DRIVER_INIT:
  44. First call after loading driver.  You may hook all interrupts, but
  45. be sure you know what you're doing!  And do not modify the timer interrupt
  46. rate, which will usually be between 140 and 200 ticks per second. Try
  47. to do your interrupt processing AFTER the original call.
  48. ARGS: type (may be used to set driver type, if marked as available
  49. in the pconfig.type field.
  50. RETURNS: Address of pconfig structure of driver.
  51.  
  52. DRIVER_RESET:
  53. Used to reset the driver, recenter it, etc.  No args or return, currently
  54. unused.
  55.  
  56. DRIVER_READ:
  57. Called to read driver position.  The read gives raw device coords if
  58. called in pointer mode, and the "mouse" screen location (scaled to match
  59. the .maxsx and .maxsy parameters in pconfig, which can be changed by
  60. the external software!).  The read data is recorded into the *pointer
  61. structure given as an argument.
  62. Note that all scaling, motion detection, etc. is performed by code
  63. in the REND386 pointer interface library.  You driver need not handle
  64. this, but it must handle gesture recognition or coding to buttons.
  65. ARGS: mode is P_POINTER or P_SCREEN, which may be or'd with P_CENTER to
  66. request recentering of the device as well.
  67. RETURNS: NULL if no new data, else address of pconfig.
  68.  
  69. DRIVER_CMD:
  70. Sends a direct command to driver.  No commands yet defined.
  71. ARGS: Command word
  72.  
  73. DRIVER_CHECK:
  74. RETURNS: address of pconfig if everything's OK, else NULL.
  75.  
  76. DRIVER_QUIT:
  77. Called on exit from the program, in reverse order that drivers were loaded.
  78. Should unhook all interrupts, etc.
  79.  
  80.  
  81. THE PCONFIG{} STRUCTURE:
  82.  
  83.  /* configuration structure: part of driver */
  84.  /* MUST corresp. to lefthand coord sys or negate scale! */
  85.  /* for non- ht devices, the scaling may be adjusted as desired */
  86.  
  87.  typedef struct _pconfig {
  88.              long xres, yres, zres;     /* position res: mm/tick in <16.16>  */
  89.              long maxx, maxy, maxz;     /* numeric range             */
  90.              long minx, miny, minz;
  91.  
  92.              long xrres, yrres, zrres;  /* rotation res: deg/tick in <16.16  */
  93.              long maxxr, maxyr, maxzr;  /* numeric range                */
  94.              long minxr, minyr, minzr;  /* min, max: left-hand dir.     */
  95.  
  96.              int maxsx, maxsy;    /* limits on mouse-mode motion (writable) */
  97.  
  98.              int databits;     /* what data is available from device */
  99.              int commands;     /* what sort of control is available  */
  100.              int nullkey;             /* button code for null keypress      */
  101.              int flexnum;      /* number of flex parameters          */
  102.              int delay;        /* millisec. read delay               */
  103.              int idelay;       /* internal delay in ms               */
  104.              int rrate;        /* max. reads per second possible     */
  105.              int type;         /* suggested useage                   */
  106.              char id[80];      /* id or more data                    */
  107.         } pconfig;
  108.  
  109. The resolution entries give the true space measurements of each "tick"
  110. (or unit) of the pointer devices's raw resolution.  These make it possible
  111. to use a device for head tracking directly.  If you wish, you may "fudge"
  112. this factor to expand the spatial range of a device.
  113. Rotational resolution is 1/65536 of the actual <16.16> format of the
  114. rotation resolution.  So, for example, the PowerGlove has 12 ticks for its
  115. entire rotation range.  The tick must be multiplied by 65536 in the
  116. driver, so that it will scale correctly.  These are used by the absscale()
  117. routine.
  118.  
  119. The max and min are used with the tscale() and rscale() functions to center
  120. and set the range of the pointer device.
  121.  
  122. The maxsx and maxsy values are used inside the driver to set mouse-emulation
  123. (screen coordinate) range, which goes from 0 to the maximum.  The x axis is
  124. positive rigt, the y axis is positive up.
  125.  
  126. Databits flags what response data is available:
  127.  
  128. For most mice, you may use button3->button1 | button2
  129. or pass it seperately.
  130.  
  131.  #define P_HASB1    0x0001   /* what buttons we can have  */
  132.  #define P_HASB2    0x0002   /* also mask for button bits */
  133.  #define P_HASB3    0x0004   /* should really return 0x07 for compatibility */
  134.  #define P_HASX     0x0008   /* which axes we can read */
  135.  #define P_HASY     0x0010
  136.  #define P_HASZ     0x0020
  137.  #define P_HASRX    0x0040   /* what rotations are available */
  138.  #define P_HASRY    0x0080
  139.  #define P_HASRZ    0x0100
  140.  #define P_HASGEST  0x0200   /* gestural interface   */
  141.  #define P_HASFLEX  0x0400   /* fingers?             */
  142.  #define P_HASKEYS  0x0800   /* do we have a keypad? */
  143.  #define P_HASSCR   0x1000   /* capable of emulating XY mouse */
  144.  
  145. The modes word contains bits to represent available modes for reading:
  146.  
  147.  #define P_CENTER    1   /* recenter without reinitializing */
  148.  #define P_SCREEN    2   /* screen mouse mode read     */
  149.  #define P_POINTER   4   /* any extended pointing mode */
  150.  
  151. The type word has bits to flag what type of uses the device driver may be
  152. useful for:
  153.  
  154.  #define P_NOPOS 0   /* just a keypad or something */
  155.  #define P_IS2D  1   /* 2D mouse, for example      */
  156.  #define P_IS2DP 2   /* 2D, but Z mapped by button */
  157.  #define P_IS3D  4   /* 3D mouse, for example      */
  158.  #define P_IS6D  8   /* 6D mouse, for example      */
  159.  #define P_IS3DG 16  /* 3D glove-- don't use rot   */
  160.  #define P_IS6DG 32  /* 6D glove-- use rotation    */
  161.  #define P_IS3RH 64  /* 3D (rotation) head tracker */
  162.  #define P_IS3TH 128 /* 3D (position) head tracker */
  163.  #define P_IS6H  256 /* full 6D head tracker       */
  164.  
  165.  
  166. All other functions are carried out by code in REND386 itself.
  167. If you need more data, look at the files mouseptr.c, drheader.asm,
  168. mkmpd.bat in the driver kit, and mouseptr.c, gloveptr.c, cursors.c, and
  169. pointer.c in the REND386 source.
  170.  
  171.  
  172. INTERRUPT HANDLERS
  173.  
  174. NEVER use the timer interrupt!  Hooking the timer interrupt is discouraged,
  175. as the order of initialization of devices is not well-defined.  REND386
  176. will hook the timer interrupt, and pass on calls every 55 mS, but if your
  177. code attempts to hook after REND386 has grabbed the timer, you'll get a
  178. call every 6 mS, and the Sega glasses will not synchronize properly.
  179.  
  180. You may set up serial and other interrupt handlers in your code, but
  181. it must be FARSTACK (see MEMMODEL for more information).  You should
  182. remove your handler at the DRIVER_QUIT call.  The processing time should
  183. extremely short, as otherwise the joystick driver will become noisy.
  184.  
  185. ---------------------------
  186. HEAD TRACKING DEVICES
  187.  
  188. These are identical to the pointer devices, except that they need
  189. not support screen-cursor modes, and only the tick-resolution
  190. is used when scaling their output.  Recentering is desirable, and
  191. the resolution should correspond to real-world values.
  192.  
  193. ---------------------------
  194. SWITCHING DRIVERS
  195.  
  196. These are always called from within an interrupt and so must use the
  197. reentrant header and be written entirely in assembler or use the
  198. TINY DS != SS model with no C library calls.
  199.  
  200. The calls have 2 integer parameters:
  201.  
  202. int switch_driver(int command, int eye);
  203.  
  204. where command is one of:
  205.  
  206. SW_INIT        0
  207. SW_QUIT        1
  208. SW_ADV_SWITCH  2
  209. SW_SYNC_SWITCH 3
  210.  
  211. SW_INIT and SW_QUIT are self-explanatory.  SW_SYNC_SWITCH is done
  212. during vertical retrace, and is the usual time to switch Sega
  213. glasses etc.
  214.  
  215. SW_ADV_SWITCH occurs 4-6 mS before the vertical
  216. retrace, so is useful for preloading various registers, loading
  217. addresses, etc.  It corresponds to the video address register load
  218. for page switching in REND386.  Your driver should return 1 if it
  219. wants REND386 to change the video page address, 0 if not.
  220.  
  221. The eye argument tells your driver which eye's view to display:
  222.  
  223. LEFT    1
  224. RIGHT     0
  225.  
  226.