home *** CD-ROM | disk | FTP | other *** search
/ Total Meltdown / dukenukemtotalmeltdown.img / util / dukectrl / readme.txt < prev    next >
Text File  |  1996-02-20  |  7KB  |  196 lines
  1. ======================================================
  2. =                                                    =
  3. = Controlling 3DRealms Games with an External Device =
  4. = Version 1.0                                        =
  5. = February 19, 1996                                  =
  6. = Written by Mark Dochtermann                        =
  7. =                                                    =
  8. ======================================================
  9.  
  10. INTRODUCTION
  11.  
  12. A number of 3DRealms games use the same external control interface.  The
  13. following specifications describe how the the control sysem works, and how
  14. you can interace to it.
  15.  
  16. GENERAL
  17.  
  18. All communication between an external driver and the game program is done
  19. through a shared data structure.  This data structure is passed into the
  20. game program by its flat linear address.  This structure is called the
  21. CONTROL structure and from here on will be referred to as such:
  22.  
  23. MAXEXTERNALAXES is defined as 6
  24. MAXEXTERNALBUTTONS is defined as 32
  25.  
  26. typedef struct
  27.    {
  28.  
  29.    // Each 3DRealms game has a unique CONTROL id.
  30.  
  31.    word  id;
  32.  
  33.    // Game executes an interrupt to communicate with driver
  34.  
  35.    word  intnum;
  36.  
  37.    // the current state of each axis
  38.    // Only the number of axes supported in your device should have
  39.    // values, otherwise these should be 0
  40.  
  41.    int32 axes[MAXEXTERNALAXES];
  42.  
  43.    // the current button state of your device
  44.  
  45.    int32 buttonstate;
  46.  
  47.    // the button mapping of your device
  48.    // 0 - single clicked button mappings
  49.    // 1 - double clicked button mappings
  50.  
  51.    byte  buttonmap[MAXEXTERNALBUTTONS][2];
  52.  
  53.    // the analog mapping of your axes
  54.    // any axes which are not supported should be left undefined
  55.  
  56.    byte  analogaxesmap[MAXEXTERNALAXES];
  57.  
  58.    // the command to send to the external driver
  59.  
  60.    word  command;
  61.  
  62.    // the digital mapping of your axes
  63.    // any axes which are not supported should be left undefined
  64.  
  65.    byte  digitalaxesmap[MAXEXTERNALAXES][2];
  66.    } ExternalControlInfo;
  67.  
  68. CONTROL contains all information necessary to communicate between the
  69. game and the driver.  When the CONTROL structure is initially passed
  70. into a game it must have certain critical information set in it.  This
  71. information includes: button mappings, analog axis mapping and digital
  72. axis mapping.
  73.  
  74. MAPPING BUTTONS
  75.  
  76. Buttons are mapped in a very simple manner.  Each button can have both a
  77. single-clicked effect as well as a double-clicked effect.  The
  78. determination of whether or not a button has been double-clicked or not is
  79. taken care of by the control system.  So the only thing the control system
  80. needs from an external device is the current state of the buttons.  The
  81. mapping of a button is as follows, for each button defined, place a
  82. gamefunction in the first array element for a single-clicked mapping and a
  83. gamefunction in the second array element for a double-clicked mapping.  A
  84. gamefunction is an enumerated type that changes from game to game.  A
  85. complete list of gamefunctions can be found in the file FUNCTION.H.  Now
  86. let's look at an example.  Suppose we have a three button mouse and we
  87. went to set up the buttons as follows:
  88.  
  89.   LMB single-clicked -> Fire
  90.   RMB single-clicked -> Strafe
  91.   MMB single-clicked -> Move_Forward
  92.   RMB double-clicked -> Open
  93.  
  94. All we would need to fill in to the button mapping array is :
  95.  
  96.   buttonmap[0][0] = gamefunc_Fire;
  97.   buttonmap[1][0] = gamefunc_Strafe;
  98.   buttonmap[2][0] = gamefunc_Move_Forward;
  99.   buttonmap[1][1] = gamefunc_Open;
  100.  
  101. Notice that the order of the mouse buttons went left,right,middle.  This
  102. is just a peculiarity of the mouse interface, not the control system.  It
  103. is important that all buttons that do not have mappings are setup to have
  104. an undefined mapping defined by EXTERNALBUTTONUNDEFINED.
  105.  
  106.  
  107. MAPPING ANALOG AXES
  108.  
  109. Axes can have any analog function assigned to them.  The analog functions
  110. are:
  111.  
  112. typedef enum
  113.    {
  114.    analog_turning=0,
  115.    analog_strafing=1,
  116.    analog_lookingupanddown=2,
  117.    analog_elevation=3,
  118.    analog_rolling=4,
  119.    analog_moving=5
  120.    } analogcontrol;
  121.  
  122. To assign a particular axis to an analog function simply place the analog
  123. function enumerated type in the analogaxismap for that axis.  For example,
  124. to setup the mappings for the mouse:
  125.  
  126. The mouse has two degrees of freedom or two axes X and Y.
  127. Let Axis 0 be X.
  128. Let Axis 1 be Y.
  129.  
  130.   analogaxesmap[0] = analog_turning;
  131.   analogaxesmap[1] = analog_moving;
  132.  
  133. Axes which are undefined should have the value EXTERNALAXISUNDEFINED.
  134.  
  135.  
  136. MAPPING DIGITAL AXES
  137.  
  138. Each axis is digitized internally in the control system.  It's digital
  139. value is then used to assert digital axis mappings.  These mappings are
  140. defined exactly the same way as the button mappings.  In order to specify
  141. which axis extreme you want to assign a gamefunction to use the following
  142. enumerated type:
  143.  
  144. typedef enum
  145.    {
  146.    axis_up,
  147.    axis_down,
  148.    axis_left,
  149.    axis_right
  150.    } axisdirection;
  151.  
  152. Here's an example.  Let's assume we are setting up mappings for a Gravis
  153. GamePad.  Since the GamePad is essentially a digital device, we want to
  154. ignore it's analog components and just use it's digital ones.  These
  155. mappings would look as follows:
  156.  
  157. The GamePad has two degrees of freedom or two axes X and Y.
  158. Let Axis 0 be X.
  159. Let Axis 1 be Y.
  160.  
  161.   digitalaxesmap[0][axis_left] = gamefunc_Turn_Left;
  162.   digitalaxesmap[0][axis_right] = gamefunc_Turn_Right;
  163.   digitalaxesmap[1][axis_up] = gamefunc_Move_Forward;
  164.   digitalaxesmap[1][axis_down] = gamefunc_Move_Backward;
  165.  
  166. Axes which are undefined should have the value EXTERNALAXISUNDEFINED.
  167.  
  168.  
  169. NOTE
  170.  
  171. Since analog and digital axis mappings are concurrent.  It is recommended
  172. that you get rid of an analog mapping for a specific axis if you also have
  173. digital mappings for that same axis.
  174.  
  175.  
  176. DURING THE GAME
  177.  
  178. The external driver will be queried once per frame for any new control
  179. information, at that time, the driver should place updated buttonstate
  180. information and axis information in CONTROL.  The control system limits
  181. all analog controls to +/- 32767.  Please refer to game specific
  182. documentation to find out how controls are limited inside the game.
  183.  
  184.  
  185. It is recommended that you manage your own stack when calling your
  186. driver code since the transfer stack provided by the dos extender may not
  187. be large enough for your driver.
  188.  
  189. Please Refer to game specific documentation for idiosyncracies of a
  190. certain game.
  191.  
  192. Happy Programming,
  193.  
  194. Mark D
  195. PARADIGM @ METRONET.COM
  196.