home *** CD-ROM | disk | FTP | other *** search
/ The Best of Select: Games 3 / cd.iso / os2 / gi / gi.inf (.txt) next >
OS/2 Help File  |  1993-12-13  |  27KB  |  721 lines

  1.  
  2. ΓòÉΓòÉΓòÉ 1. Abstract ΓòÉΓòÉΓòÉ
  3.  
  4. Abstract 
  5.  
  6. GI is a generic Interface between Games  and Input Devices. 
  7.  
  8. GI was designed to detach the task of getting and normalizing data from input 
  9. devices from the task of programming a game. 
  10.  
  11. The following picture may clarify this: 
  12.  
  13.  
  14.       GAMES                                 INPUT DEVICES
  15.  
  16.   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ                          ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  17.   Γöé Wizard of Wor Γöé<ΓöÇΓöÉ                   ΓöîΓöÇ<ΓöÇΓöé Keyboard Γöé
  18.   ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ  Γöé                   Γöé   ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  19.   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  Γöé      ΓòöΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓòù     Γöé   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  20.   Γöé Boulder Dash  Γöé<ΓöÇΓö╝ΓöÇΓöÇ<ΓöÇΓöÇΓöÇΓòæ  GI  Γòæ<ΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇ<ΓöÇΓöé Joystick Γöé
  21.   ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ  Γöé      ΓòÜΓòÉΓòÉΓòÉΓòÉΓòÉΓòÉΓò¥     Γöé   ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  22.   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ  Γöé                   Γöé   ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  23.   Γöé Tron          Γöé<ΓöÇΓöñ                   Γö£ΓöÇ<ΓöÇΓöé Straight Γöé
  24.   ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ  Γöé                   Γöé   ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  25.                      Γöé                   Γöé
  26.         ...                                      ...
  27.  
  28. Therefore: 
  29.  
  30. o An Input Device knows how to handle data from a device (eg. a Joystick or a 
  31.   keyboard). 
  32.  
  33. o A Game does not care what kind of Input Device the user prefers. It just 
  34.   queries GI for user input. 
  35.  
  36. Or with other words: 
  37.  
  38. GI is a black box that hides all information about the user preferences of 
  39. input devices from the game. 
  40.  
  41.  
  42. ΓòÉΓòÉΓòÉ 2. Highlights ΓòÉΓòÉΓòÉ
  43.  
  44. Special Highlights of GI version 1.0 
  45.  
  46. o Interface for Games and Input Devices fully written in C 
  47. o Source code is available 
  48. o Sample code for both Games and Input Devices available 
  49. o GI is configured once for all Games! 
  50. o Possibility for per-Game configuration exists 
  51. o Analog Input Devices can be used with Games requireing digital user input and 
  52.   vice versa (although this has not been tested yet...) 
  53. o Up to 10 Players can play simultaneously! 
  54.  
  55.  
  56. ΓòÉΓòÉΓòÉ 3. Installation ΓòÉΓòÉΓòÉ
  57.  
  58. Installation 
  59.  
  60. GI consists of two ZIP-Files: 
  61.  
  62. o GIRUN.ZIP (all files needed to run GI) 
  63. o GISRC.ZIP (all source files for GI) 
  64.  
  65. These two ZIP-Files are bound together in GI.ZIP (as you noticed...). If you 
  66. just want to use GI, you just unzip GIRUN.ZIP. It contains all modules 
  67. required. 
  68.  
  69. The GISRC.ZIP file contains all the source code of GI! You don't need to unzip 
  70. the TOOLS.ZIP, PMTOOLS.ZIP and STD.ZIP files if you don't recompile GI. 
  71.  
  72. Installation step by step 
  73.  
  74.  1. Create a directory named "GI". GI is used in more than one game, so this 
  75.     step makes sense even if you don't like it... 
  76.  
  77.  2. Copy GIRUN.ZIP to this directory and change (cd) to it. 
  78.  
  79.  3. Unzip GIRUN.ZIP. 
  80.  
  81.  4. Make sure the following files have been unzipped correctly: 
  82.  
  83.    o GI.DLL 
  84.    o GICONFIG.EXE 
  85.  
  86.  5. Edit your CONFIG.SYS file: 
  87.  
  88.     a. Append the full drive and path name of the GI-directory to your 
  89.        LIBPATH-entry: 
  90.  
  91.               LIBPATH=...;C:\GI
  92.  
  93.        Otherwise you'll have to put all the dynamic link libraries (*.DLL) of 
  94.        GI to a location already mentioned in your LIBPATH-entry. 
  95.  
  96.     b. Add the following line to the end of your CONFIG.SYS: 
  97.  
  98.               SET GICONFIG=C:\GI\GICONFIG.DAT
  99.  
  100.        (Assuming you installed GI in a directory "GI" on the C: drive.) 
  101.  
  102.     c. If you have a PC-Joystick, add the following line to your CONFIG.SYS: 
  103.  
  104.               DEVICE=C:\GI\GAMEPORT.SYS
  105.  
  106.        (Again assuming you installed GI in C:\GI.) 
  107.  
  108.  6. Restart your system for the changes in CONFIG.SYS to take effect... 
  109.  
  110. That's it. After the restart of your system you can continue by configuring GI. 
  111.  
  112.  
  113. ΓòÉΓòÉΓòÉ 4. Configuration ΓòÉΓòÉΓòÉ
  114.  
  115. Configuration 
  116.  
  117. GI knows two diffrent kinds of configurations: 
  118.  
  119.  1. Global/Default configuration 
  120.  2. Local configuration 
  121.  
  122. Basics 
  123.  
  124. One of the base ideas behind GI was, that one configuration should be enough 
  125. for all kind of games. To statisfy this criterion GI has a global configuration 
  126. file (GICONFIG.DAT) that holds all information for the input devices. This file 
  127. is located as mentioned in the installation section. 
  128.  
  129. But since the restriction to only one configuration may be too hard (imagine a 
  130. game that uses really weird controls) the possibility for a local configuration 
  131. was introduced. This local or per-game configuration works just the same way as 
  132. the global configuration does. The only difference being that the configuration 
  133. file for the local configuration is located in the directory of the game 
  134. whereas the global configuration file resides in the GI directory. 
  135.  
  136. Configuration of GI 
  137.  
  138. Configuration of GI and its input devices is done with the GICONFIG program. 
  139. This program uses a standard OS/2 Presentation Manager interface. Configuration 
  140. is performed in two steps: 
  141.  
  142.  1. Select an input device from the list or define a new by pressing the New 
  143.     Player button and selecting one from the list presented. (You'll have to 
  144.     select the proper directory first, of course...) 
  145.  
  146.     Note:  Currently available devices are:STRAIGHT.DLL, KBD.DLL, JOY.DLL and 
  147.     TAPEDEV.DLL. See Devices for further information. 
  148.  2. Start the configure part of the selected device by pressing the Define 
  149.     button or double-clicking in the list of devices. 
  150.  
  151. Note:  Device 1 will be queryed for input to move player 1, device 2 for player 
  152. 2, etc.! 
  153.  
  154. Special Hint when inserting new devices 
  155.  
  156. When you hit the New Player button and no device in the list is highlighted, 
  157. the new device will be inserted at the end of the list. If there is already a 
  158. device highlighted, the new one will be inserted before the highlighted device! 
  159.  
  160.  
  161. ΓòÉΓòÉΓòÉ 5. Devices ΓòÉΓòÉΓòÉ
  162.  
  163. Devices 
  164.  
  165. GI cannot work without input devices (see Abstract). The most important devices 
  166. have already been realized and are part of this version of GI. 
  167.  
  168. Since GI is meant to be a generic interface, everybody is encouraged to 
  169. implement further devices. Detailed info in Writting a new Device. 
  170.  
  171. Prepared, but not implemented yet, is the possiblity to implement "intelligent" 
  172. computer players. Such a computer player device would of course need further 
  173. information about the rules and strucutres of a game. But for the game (and the 
  174. game programer) the computer player would be fully transparent. The game would 
  175. not be able to distinguish a human player from a computer player. This concept 
  176. hat already been used in realizing the Tape Recorder device. 
  177.  
  178.  
  179. ΓòÉΓòÉΓòÉ 5.1. Interface from GI to Devices ΓòÉΓòÉΓòÉ
  180.  
  181. Interface from GI to Devices 
  182.  
  183. Note:  This section is for programers only. 
  184.  
  185. Every device is placed in a dynamic link library that gets loaded and called by 
  186. GI. Therefore all devices have the same interface to GI and use excatly the 
  187. same mechanism for excanging data. 
  188.  
  189. A device must suffice to the following requirements: 
  190.  
  191. o Must contain the functions _GetDataSize, _InitializeDLL, _Name, _ConfigDLL, 
  192.   _Threshold and _Direction with the parameters as specified below 
  193.  
  194. o Must be callable with std. C-calling conventions 
  195.  
  196. The reason for these requirements being that GI comunicates with the device 
  197. only through these functions. Furtheron, the adresses of these functions are 
  198. calculated using a call-by-name mechanism (that's why the names are very 
  199. important). 
  200.  
  201. Required functions in a device 
  202.  
  203. o _GetDataSize (void): Returns the number of bytes required to hold all data, 
  204.   that the device needs to run (see instance data below). 
  205.  
  206. o _InitializeDLL (char __far16 *id): When GI is initialized, the devices are 
  207.   initialized with this function. They receive a pointer to a piece of memory 
  208.   (id) as parameter. The piece of memory has the size returned by the 
  209.   _GetDataSize() function of the device. I recommend to have a flag initialized 
  210.   in the instance data to detect, if the data area has already been initialized 
  211.   with default values or not. 
  212.  
  213. o _Name (char __far16 *mm): Copies the name of the device in ascii 
  214.   representation to the memory location (mm) specified by the parameter. This 
  215.   name is shown in the device-list in GICONFIG. 
  216.  
  217. o _ConfigDLL (char __far16 *id): Every device should have a configuration part. 
  218.   GI calls this part, when the user selects a device and presses the Define... 
  219.   button. The configuration should have a Presentation Manager interface (like 
  220.   the included devices have). In the configuration part, the user may do all 
  221.   that is needed to use the device for playing afterwards (definitions, 
  222.   calibrations of the device, ...). 
  223.  
  224.   Note:  The selections and definitions that should be saved, must be placed in 
  225.   the instance data. GI will save this area for you! 
  226.  
  227. o _Threshold (char __far16 *id): This function is called to convert analog to 
  228.   digital values. 
  229.  
  230.     Example 1:
  231.         analog Joystick:     device returns value=0..100
  232.  
  233.         GI:                  if game wants analog values then
  234.                                  return value
  235.                              else
  236.                                  if value < threshold then
  237.                                      return 0
  238.                                  else
  239.                                      return 1
  240.  
  241.     Example 2:
  242.         (digital) Keyboard:  device returns value=0 or threshold
  243.  
  244.         GI:                  return value to game
  245.  
  246.   As you notice, the threshold value has a different meaning for analog and 
  247.   digital devices. 
  248.  
  249.   Note:  All devices return values in the range 0..100. Digital devices must 
  250.   return the threshold value instead of 1. 
  251.  
  252. o _Direction (char __far16 *id, char __far16 *pi): This function is called 
  253.   whenever the game wants the actual values from the device. Parameters are: 
  254.  
  255.    - id: Pointer to the instance data. 
  256.  
  257.    - pi: Pointer to the PLAYERINFO-structure given to GI by the game. The 
  258.      device fills the direction[] field of this structure. GI calculates the 
  259.      direction, diagonal and buttons fields afterwards from the values found in 
  260.      the direction[] array. 
  261.  
  262. Note:  The leading underscore (_) is appended automatically, if you program in 
  263. C or declare the functions extern "C" in C++. 
  264.  
  265. Instance data 
  266.  
  267. The same device may be configured for more than one player (eg. two players 
  268. playing on the same keyboard). GI creates a new instance for every configured 
  269. use of the device (eg. different keys to move the figures). Therefore all 
  270. configured data should be placed in the instance data. GI will keep track of 
  271. saving and reloading the instance data for the devices. Don't create any 
  272. configuration files and don't use the Profile-functions of Presentation Manager 
  273. since you cannot be sure that your device will run with PM present! Furtheron 
  274. you should avoid using global variables even if you define your device to have 
  275. single nonshared data areas. The reason being that your device may be loaded 
  276. more than once within the same process and hence sees the same global data in 
  277. all instances. 
  278.  
  279. Writting a new Device 
  280.  
  281.  
  282. ΓòÉΓòÉΓòÉ 5.2. Writting a new Device ΓòÉΓòÉΓòÉ
  283.  
  284. Writting a new Device 
  285.  
  286. It's easy! 
  287.  
  288. Note:  This section is for programers only. 
  289.  
  290. I suggest you copy one of the existing devices (as close as possible to the one 
  291. you want to implement) and modify it. Some modifications are needed if you 
  292. don't use Borland C++. But in principle, it's very easy: 
  293.  
  294. o Make sure you #include <gi.h> 
  295. o Define all functions as desrcibed in  Interface from GI to device 
  296. o Implement a minimul functionality and compile your module to a DLL. 
  297. o Verify the correctness of the names with a library manager (if GI cannot find 
  298.   all functions, it will refuse to load the devie). 
  299. o Try loading your device in GICONFIG 
  300. o Implement the full functionality of your device 
  301. o Send your device to me for distribution in the next release! This step is 
  302.   optional but strongly recomended! 
  303.  
  304. Note:  If you need to debug your device, you'll need to recompile all parts of 
  305. GI. To do this you need the sources in TOOLS.ZIP also contained in this 
  306. distribution. You may use the GIMAKE.CMD command file if you work with Borland 
  307. C++. 
  308.  
  309.  
  310. ΓòÉΓòÉΓòÉ 5.3. Supported Devices ΓòÉΓòÉΓòÉ
  311.  
  312. Supported Devices 
  313.  
  314. Distributed with GI are some input devices. The source code for these is also 
  315. contained in the GISRC.ZIP file. 
  316.  
  317. Planned are devices for: 
  318.  
  319. o Game-Demos (Intros, etc.) 
  320. o Computer-Player 
  321. o Mouse (?) 
  322.  
  323. Refinement and enrichment of existing devices is also possible... 
  324.  
  325.  
  326. ΓòÉΓòÉΓòÉ 5.3.1. Straight Auto-Player ΓòÉΓòÉΓòÉ
  327.  
  328. Straight Auto-Player 
  329.  
  330. This device was designed to make debugging of games easier. It provides the 
  331. possibility of an player walking always in the same direction (or standing 
  332. still). 
  333.  
  334. This device is also very usefull to fill the list of installed players... 
  335.  
  336.  
  337. ΓòÉΓòÉΓòÉ 5.3.2. Joystick ΓòÉΓòÉΓòÉ
  338.  
  339. Joystick 
  340.  
  341. There are two kinds of joystick available on the market: 
  342.  
  343. o Digital Joysticks and 
  344. o Analog Joysticks 
  345.  
  346. The difference is very simple: Digital joysticks have (mostly) a mechanical 
  347. switch for every of the 4 directions (North, East, South and West) and the 
  348. fire-buttons. Analog joysticks have (mostly again) 2 variable resistors which 
  349. are connected to the stick in a manner, that their resitance changes as the 
  350. stick is moved in x- or y-direction. The actual value of these resistors gets 
  351. sampled (10 times per second) and digitized by the game-port. To access the 
  352. game-port under OS/2 the GAMEPORT.SYS driver must be installed. 
  353.  
  354. Note:  Support for digital joystick is not yet implemented. 
  355.  
  356. Configuring the analog Joystick 
  357.  
  358. The values of the resistors in a joystick vary from product to product. To 
  359. calculate the exact values and scale of the joystick, the resitor values at the 
  360. extremal points (upper left and lower right corner) must be taken. This is 
  361. called calibration. 
  362.  
  363. The calibration part of the joystick input device configuration can be 
  364. activated by pressing the Define Max.-button in the joystick configuration. 
  365.  
  366. The joystick configuration dialog shows on the left side the analog behaviour 
  367. of the joystick. If you move the stick, the tiny black point (should) change 
  368. its position... 
  369.  
  370. Note:  If the tiny point does not follow the movements of your joystick, 
  371. JOYSTICK.SYS may not be installed. Check Installation 
  372.  
  373. On the right side of the configuration dialog you see the digital 
  374. representation of the analog values on the left. Depending on the selected 
  375. threshold the checkboxes check with more or less movement of the stick. We 
  376. recomend to experiment with the setting for the threshold because this is 
  377. crucial for the behaviour in games requireing digital input! 
  378.  
  379.  
  380. ΓòÉΓòÉΓòÉ 5.3.3. Keyboard ΓòÉΓòÉΓòÉ
  381.  
  382. Keyboard 
  383.  
  384. The Keyboard Device works both in OS/2 Presentation Manager and OS/2 Full- 
  385. Screen mode (ever tried to do this?). It intercepts all keyboard activities and 
  386. checks wheter the actually pressed key (or combination of keys) matches any 
  387. defined pattern. 
  388.  
  389. Configuration 
  390.  
  391.  1. Select the direction or button you want to define the key(combination) for. 
  392.  2. Press the DEFINE button 
  393.  3. Press the START button in the new dialog window 
  394.  4. Hit the key(combination). The scan-values and state of the control-keys are 
  395.     displayed. 
  396.  5. If you hit the correct key(combination) press the STOP button 
  397.  6. Hit the TEST button and afterwards press your key(combination). If you hear 
  398.     a short beep, your key(combination) was accepted. 
  399.  7. Hit the OK button, your definition is completed. 
  400.  8. Go back to point 1 if you want to define more directions or buttons. 
  401.  
  402. Note:  An asterisk * on the left of a direction or key signals that it has been 
  403. defined. 
  404.  
  405. Warning: Define diferent keys for button 1 and button 2 since some games may 
  406. distinguish between the buttons! 
  407.  
  408. Threshold 
  409.  
  410. The Threshold slider comes to action, when the keyboard is used in a game 
  411. requesting analog input. Since it is impossible to tell how strong a key is 
  412. typed, the treshold value is used instead of 0 (key not pressed) and 1 (key 
  413. pressed)... 
  414.  
  415. Note:  The Keyboard device is also used XFEEL and BUILDER. 
  416.  
  417.  
  418. ΓòÉΓòÉΓòÉ 5.3.4. Tape Recorder ΓòÉΓòÉΓòÉ
  419.  
  420. Tape Recorder 
  421.  
  422. The Tape Recorder consists of two parts: 
  423.  
  424. o TAPEDEV.DLL: input device for GI 
  425. o TAPE.EXE: Program to control the tape 
  426.  
  427. The idea of the tape recorder is, that you can monitor and record input from 
  428. any other device and play it back later. The concept may be known from 
  429. keyboard-monitors that let you define and play back a series of keystrokes. The 
  430. Tape Recorder works just this way: You start recording and play the game. All 
  431. your movements get recorded. Later on you can play this session back. 
  432.  
  433. Stop on Overplay option 
  434.  
  435. This feature lets you interrupt (better stop) the playing back of a recorded 
  436. tape. Just let the tape run until you feel to take over. As soon as you move 
  437. your device you will override the tape and stop its running. 
  438.  
  439. Note:  This feature can be turned on and off in the Tape Recorder program. 
  440.  
  441. Configuring the Tape Recorder 
  442.  
  443.  1. Install a Tape Recorder Device (TAPEDEV.DLL) for the player you want to 
  444.     record 
  445.  2. Configure the Tape Recorder device: The port number must match the device 
  446.     you want to move your figure with. 
  447.  3. Finish configuring GI 
  448.  
  449. Say: You want to monitor player 1 in a game. Input comes from keyboard.
  450.  
  451. Then: You define the tape device a device number 1. The keyboard must also
  452. be defined (eg. number 3). Then you configure the tape devie to monitor
  453. port number 3.  OK?
  454.  
  455. Recording 
  456.  
  457.  1. Start the Tape Recorder program (TAPE.EXE) 
  458.  2. Select a file with the File...-button or enter a filename for the tape. 
  459.  3. Start your game and make selections and other stuff you don't want to be 
  460.     recorded. 
  461.  4. Switch back to the Tape Recorder and press the RECORD button. 
  462.  5. Switch to the game again and play. The Tape Recorder is now recording! 
  463.  6. As soon as you like, switch back to the Tape Recorder and press the STOP 
  464.     button. Your tape is ready! 
  465.  
  466. Playing back 
  467.  
  468.  1. Start the Tape Recorder program (TAPE.EXE), but only if it's not running... 
  469.  2. Select the file to play back. 
  470.  3. Start your game and move to the point your recording started. 
  471.  4. Switch back to the Tape Recorder and press the PLAY button. Your tape is 
  472.     running! 
  473.  5. If the "Stop on Overplay" option is checked, you can stop the show with a 
  474.     single movement from your original device! 
  475.  
  476. Note:  Play back will stop as soon as the end of the tape is reached. 
  477.  
  478. Concept of the Tape Recorder 
  479.  
  480. Let's look at it from the point of view of a game. 
  481.  
  482. The game wants user input. It calls GI with the number of the player. GI looks 
  483. at its internal table, which device corresponds to the requested player. Then, 
  484. GI requests the actual data from the device, normalizes it and returns it to 
  485. the game. 
  486.  
  487. Now the Tape Recorder consists of a Tape Device which can be called from GI as 
  488. any other device. But the Tape Device does not query any hardware. Instead it 
  489. calls GI and queries the actual data for the player configured. In Record-mode 
  490. the data is stored in a file and in Play-back-mode data is loaded from disk 
  491. instead of querying GI for the original device. 
  492.  
  493.  
  494. ΓòÉΓòÉΓòÉ 6. Games ΓòÉΓòÉΓòÉ
  495.  
  496. Games 
  497.  
  498. All started with Wizard of Wor. At a certain point in the process of developing 
  499. the game, we had to decide how to get the user input to move the figures. Since 
  500. we didn't have a joystick  or any other input device than mouse and keyboard 
  501. we "hard coded" the input-part of the game. 
  502.  
  503. But of course we were not content with this kind of restriction. And after we 
  504. released the game to public several people asked for joystick support. Now it 
  505. would have been easy to simply add this part, but as we were already planing 
  506. our next game (Boulder Dash), a generic solution to this problem seemed more 
  507. convenient... 
  508.  
  509. Since GI cannot exist without GAMES, we want to encourage everybody to adapt 
  510. existing games or write new games using GI for the user input! 
  511.  
  512.  
  513. ΓòÉΓòÉΓòÉ 6.1. Interface from Game to GI ΓòÉΓòÉΓòÉ
  514.  
  515. Interface from Game to GI 
  516.  
  517. Note:  This section is for programers only. 
  518.  
  519. Requirements 
  520.  
  521. The game must be programmed in a language that allows C-functions to be called. 
  522. Therefore the library GI.LIB must be linked to the game that uses GI. 
  523.  
  524. There are no problems if the game is written in C or C++, allmost any compiler 
  525. should be OK... 
  526.  
  527. Note:  GI.LIB contains just the definitions for the linker to know, that GI.DLL 
  528. must be loaded to actually execute the GI-functions. 
  529.  
  530. Interface functions and data structures 
  531.  
  532. There are only two functions and one data structure required for using GI in a 
  533. game: 
  534.  
  535. o PLAYERINFO-structure 
  536. o GIInitialize() 
  537. o GIGetDirection (PLAYERINFO *) 
  538. The prototypings and definitions are in GI.H which must be included to import 
  539. the functionality of GI. 
  540.  
  541. Meanings of data-members in PLAYERINFO-structure 
  542.  
  543. typedef struct _playerinfo
  544.   {
  545.   // Input Data
  546.   unsigned       player;     // Number of actual player
  547.   BOOL         analog;     // Game wants analog-values
  548.   int         x;        // Actual position x (optional)
  549.   int         y;        // Actual position y (optional)
  550.  
  551.   // Output Data
  552.   char         dir[6];     // Values of directions: Up, Right, Down, Left, B1, B2
  553.   char         direction;    // Strongest direction or DIRNONE
  554.   char         diagonal;    // 2nd strongest direction or DIRNONE
  555.   char         buttons;     // 2 bits for buttons
  556.  
  557.   // Strategy Data
  558.   unsigned       (*Move) (unsigned x, unsigned y);  // Callback to Game!
  559.   void         *stratdata;   // Data for Strategy-Instance
  560.   } PLAYERINFO, *PLAYERINFOP;
  561.  
  562. player: Zero-based number of player for which you want the actual direction and 
  563. button values. 
  564.  
  565. analog: TRUE if game wants analog values in the range of 0..100 for each of the 
  566. four directions (see below). FALSE if game wants digital input (eg. player 
  567. moves up, strenght not required). 
  568.  
  569. dir[6]: Actual values of the queried device of the 4 directions and the 2 
  570. buttons. 
  571.  
  572. direction: Strongest/main direction coded as mentioned below. 
  573.  
  574. diagonal: Second strongest/secondary direction. If you don't care about 
  575. diagonal moves, just ignore this field. Otherwise the actual direction is 
  576. between direction and diagonal (direction=up, diagonal=left --> diagonal left 
  577. up). 
  578.  
  579. buttons: Binary representation of the states of the two buttons. If a button is 
  580. pressed the corresponding bit is 1. 
  581.  
  582. Note:  All other fields in PLAYERINFO are not used yet! 
  583.  
  584. Coding of the directions 
  585.  
  586. #define DIRNONE   -1
  587. #define DIRUP    0
  588. #define DIRRIGHT   1
  589. #define DIRDOWN   2
  590. #define DIRLEFT   3
  591.  
  592. #define DIRBUT1   1
  593. #define DIRBUT2   2
  594.  
  595. The definitions of the four directions are as well the indices into the 
  596. direction[] array as the values of the direction and diagonal fields in 
  597. PLAYERINFO. 
  598.  
  599. Consider the following example: 
  600.  
  601.     /* pi.player and pi.analog must be initialized ! */
  602.  
  603.     if (GIGetDirection (&pi))
  604.         {
  605.         /* A error occured, see errdef.h for further coments...
  606.         }
  607.     if (pi.buttons)
  608.         {
  609.         /* process buttons now.... */
  610.         }
  611.     if (pi.direction != DIRNONE)  /* or use: pi.dir[] .... */
  612.         {
  613.         /* process direction .... */
  614.         }
  615.  
  616. Warning: Don't forget to call GIInitialize() somwhere in the startup of your 
  617. game! 
  618.  
  619. Comments 
  620.  
  621. o Typically, you allocate a PLAYERINFO-structure for every player your game 
  622.   will support. 
  623.  
  624. o The fields for strategy functionality are not yet used, since I don't have a 
  625.   good concept for an example of such a strategy player yet... 
  626.  
  627. o The interface was designed to be as narrow as possible to make it easier to 
  628.   use. 
  629.  
  630.  
  631. ΓòÉΓòÉΓòÉ 6.2. Games supporting GI ΓòÉΓòÉΓòÉ
  632.  
  633. Games supporting GI 
  634.  
  635. The three games that we wrote up to now have two things in common: 
  636.  
  637.  1. They use GI for getting user input 
  638.  2. Two players can play at the same time 
  639.  
  640. We don't want to make the impression of being "Game-Freaks", but we like 
  641. playing games and even more than that, we like to write programs. Not 
  642. necessarly games, well noted. Games are the ideal trade off between writting 
  643. good software and having some fun afterwards... 
  644.  
  645. And by the way: We also wanted to show that OS/2 is a good operating system! 
  646.  
  647.  
  648. ΓòÉΓòÉΓòÉ 6.2.1. Wizard of Wor ΓòÉΓòÉΓòÉ
  649.  
  650. Wizard of Wor 
  651.  
  652. Wizard of Wor is a port from an old C64 game. It was always one of my 
  653. favourite: simple but fascinating... 
  654.  
  655. The OS/2-port was done in C++, all code rewritten. The pictures and dungeons 
  656. are the same as in the original (took us quite some time to capture all the 
  657. figures...). Some differences occur in the speed-up during the game and the 
  658. speed of Worluk and the Wizard. 
  659.  
  660. Wizard of Wor is a real CPU-hog. One big problem was, that the maximal timer 
  661. resolution of OS/2 (32ms) was far too slow. So we decided to do a busy-waiting. 
  662. The mechanism of slowing the game down in a way that fast maschines are slowed 
  663. more than slow maschines was invented by Markus and is unique (well sort 
  664. of...). 
  665.  
  666. Note:  Our highscore on the original C64 Wizard of Wor is at 194'800 points in 
  667. two player mode! 
  668.  
  669.  
  670. ΓòÉΓòÉΓòÉ 6.2.2. Boulder Dash ΓòÉΓòÉΓòÉ
  671.  
  672. Boulder Dash 
  673.  
  674. An all time goodie. It exists on almost every game computer. This can be seen 
  675. as a port of the AMIGA version of Boulder Dash. Most of the ideas for the 
  676. special objects such as bombs, enemies, swamp, ..., were taken from there. 
  677.  
  678. For those how don't know Boulder Dash 
  679.  
  680. You (and perhaps your friend) are lost in a system of underground caves. Your 
  681. task is to collect the diamonds and enter in the house. You can not proceed to 
  682. the next level until you completed the level... 
  683.  
  684.  
  685. ΓòÉΓòÉΓòÉ 6.2.3. Tron ΓòÉΓòÉΓòÉ
  686.  
  687. Tron 
  688.  
  689. Famous motion picture. A real must for all computer freaks. First movie with 
  690. computer animated sequences (as far as I know). 
  691.  
  692. The game was introduced in the film. Two players, both try to lock each other 
  693. without crashing into the walls. This game is anything but perfect, many bugs 
  694. still wait to be fixed... 
  695.  
  696.  
  697. ΓòÉΓòÉΓòÉ 7. About 'n Credits ΓòÉΓòÉΓòÉ
  698.  
  699. About 'n Credits 
  700.  
  701. GI is free! Please use, extend, spread, ... GI as you like. 
  702.  
  703. For further enhancments, comments, questions or bugs please send an email or a 
  704. short note: 
  705.  
  706.       Roman Fischer
  707.       Leonhardstr. 12
  708.       CH-8001 Zuerich
  709.       Switzerland
  710.  
  711.       rofische@iiic.ethz.ch
  712.  
  713. Credits 
  714.  
  715. Special thanks go to Markus Hof, who always helps me out of conceptual troubles 
  716. and ported Wizard of Wor to GI! 
  717.  
  718. Credits to: Andre "Infid" Miodonski, ... 
  719.  
  720. Thanks to ICA Systems Inc. for their joystick driver, which is included in the 
  721. standard version of GI.