home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / useful / dev / c / cmanual / devices / gameportdevice / gameportdevice.doc < prev    next >
Text File  |  1993-10-12  |  34KB  |  1,060 lines
  1. 3    GAMEPORT DEVICE
  2.  
  3. 3.1  INTRODUCTION
  4.  
  5. All Amiga models have two contacts to which you can connect extra
  6. input devices like a mouse, joystick, trackball, proportional
  7. joystick etc. If Intuition is used, the left gameport is
  8. reserved for a mouse that controls the pointer. However, the
  9. right port can be used freely.
  10.  
  11. To monitor these two gameports you can uses the Gameport
  12. Device. It is a clean and polite way of controlling the
  13. gameports. You can of course go directly on the hardware
  14. and check what is happening. This is both easier and faster,
  15. but should only be used in games since it is not so polite
  16. to the system.
  17.  
  18. If you go directly on the hardware your program will be
  19. machine dependent, and may not run on future models of the
  20. Amiga.
  21.  
  22. I doubt that Commodore ever will try to change the hardware
  23. position of the gameport, but you never know. Programs that
  24. use the Gameport device will on the other hand always work,
  25. even if an Amiga 4000 is released. So if you can use the
  26. Gameport Device instead of hitting the hardware directly,
  27. stick to the device. 
  28.  
  29.  
  30.  
  31. 3.2  COMMON INPUT DEVICES FOR THE GAMEPORT
  32.  
  33. To the gameports you can connect several types of input
  34. devices, like: - Mouse
  35.                - Joystick
  36.                - Proportional (analogue) joystick
  37.                - Light pen
  38.                - Drawing (Digitizing) tablet
  39.                - Trackball
  40.  
  41. The most commonly used input devices is undoubtedly the mouse and
  42. joystick. However, inputdevices like analogue joysticks, light
  43. pens and digitizing tablets are getting more and more popular.
  44.  
  45. It is very common that a joystick is already connected to the
  46. right port. Most games expect that, but it does not mean that
  47. you can not connect a second mouse or proportional joystick
  48. there. It is a good rule to always tell the user what type
  49. of input device he/she should use, before your program starts.
  50.  
  51.  
  52.  
  53. 3.2.1  MOUSE
  54.  
  55. The mouse is the most commonly used device since all Amigas are
  56. sold together with one. It is perfect for positioning cursors
  57. (like Intuition's pointer), or to move a gun-sight over some
  58. enemies.
  59.  
  60. A mouse usually consists of a rubber ball covered by a box
  61. with one or more buttons on top. When the user is sliding the
  62. mouse, the rubber ball is rotated and delta x and y movements
  63. are reported.
  64.  
  65. The normal Amiga mouse comes with two buttons, but there exist
  66. those with only one or three buttons.
  67.  
  68.  
  69.  
  70. 3.2.2  JOYSTICK
  71.  
  72. A normal joystick (also called absolute joystick) can only
  73. report 8 stick movements like: up, right, down, left and
  74. possible combinations like up and to the right. A joystick
  75. can have one or two buttons. Sadly most joystick comes with only
  76. one button.
  77.  
  78.  
  79.  
  80. 3.2.3  PROPORTIONAL JOYSTICK
  81.  
  82. A proportional (or analog) joystick is like a normal absolute
  83. joystick with one difference, it will report the exact delta
  84. position on the stick. The further in one direction, the higher
  85. number is broadcasted.
  86.  
  87. Proportional joysticks are perfect for flight simulators and
  88. similar programs. They are becoming more available nowadays,
  89. so it is a good idea to start supporting this type of device.
  90.  
  91. The Gameport Device can sadly not handle proportional joysticks
  92. for the moment which is a pity. However, I have included a
  93. small program in the "Input" drawer called "Analogue" which
  94. reads proportional (analogue) joystick movements directly from
  95. the hardware registers.
  96.  
  97.  
  98.  
  99. 3.2.4  LIGHT PEN
  100.  
  101. A light pen is a small device with which you can point anywhere
  102. on the screen in order to position a cursor or select an
  103. option. There have during the last years been a big discussion
  104. about which device, a mouse or a light pen, is easiest to use.
  105. I think it depends on what you are going to do. A pen is
  106. undoubtedly more natural for a beginner, but your arm gets very
  107. tired after some minutes, so it should not be used to much.
  108.  
  109. Luckily you do not need to bother about the light pen since it
  110. is also sadly not supported by the Gameport Device. However,
  111. newly made light pens usually comes with some software that
  112. replaces Intuition's mouse with the light pen. If you write
  113. your program as normal and is monitoring a mouse, the user can
  114. still connected and use a light pen. Your program whould not
  115. notice any difference.
  116.  
  117.  
  118.  
  119. 3.2.5  DRAWING (DIGITIZING) TABLET
  120.  
  121. Drawing (Digitizing) tablet is used in the same manner as a
  122. light pen, but with the advantage that your arm does not get
  123. so tired, and with the disadvantage that all your free space
  124. on your desk is suddenly occupied by a large sensitive tablet.
  125. (It is not recommended to spill hot coffee on it for example.)
  126.  
  127. Drawing tablets are not either supported by the Gameport
  128. Device. However, as same as with the light pen, most digitizing
  129. tablets comes with some software that replaces the normal
  130. mouse driver with its own driver. So if your program supports
  131. a mouse, it can also handle most digitizing tablets.
  132.  
  133.  
  134.  
  135. 3.2.5  TRACKBALL
  136.  
  137. A trackball is working exactly as a mouse, but with the
  138. advantage that you do not have to move it around. Since it
  139. acts exactly as a mouse you do not have to bother about any
  140. special routines for handling trackballs. Simply support
  141. mouse events and the user can connect a trackball instead.
  142.  
  143.  
  144.  
  145. 3.3  THE GAMEPORT DEVICE
  146.  
  147. The Gameport Device helps you to monitor the Amiga's two
  148. gameports. Port 1 (unit 0) is usually already occupied by
  149. Intuition, but port 2 (unit 1) can normally be used. The
  150. Gameport Device supports for the moment only two types
  151. of input devices, and they are: 1. Mouse (Trackball)
  152.                                 2. Joystick
  153.  
  154. To prepare the Gameport Device to handle input events you
  155. have to:
  156.  
  157.   1. Create a message port with which the Gameport Device
  158.      can communicate with you.
  159.      [ CreatePort() ]
  160.  
  161.   2. Allocate an input/output request block (structure).
  162.      [ CreateStdIO() ]     
  163.  
  164.   3. Open the Gameport Device
  165.      [ OpenDevice() ]
  166.  
  167.   4. Check if some other task is already using the gameport.
  168.      (A gameport can only be monitored by one task.)
  169.  
  170.   5. Tell the Gameport Device what type of input device you
  171.      want to monitor. (For the moment you can only monitor
  172.      mouse or joystick events.)
  173.  
  174.   6. Tell the Gameport Device what events should be reported,
  175.      and when.
  176.  
  177.   7. Tell the Gameport Device that we want to start collecting
  178.      gameport events.
  179.  
  180.  
  181.  
  182. 3.3.1  CREATE A MESSAGE PORT
  183.  
  184. As normal when you are using a device, you first have to create
  185. a message port with which the device can communicate with you.
  186. The simplest way is to create a message port by calling the
  187. CreatePort() function, which will return a pointer to a MsgPort
  188. structure (defined in the headerfile "exec/ports.h").
  189.  
  190. CreatePort() allocates and initializes a MsgPort structure. If
  191. you give it a string as first parameter it will also make the
  192. port public. If CreatePort() of some reason could not create a
  193. message port it returns NULL, otherwise if everything is OK it
  194. returns a pointer to the new MsgPort structure.
  195.  
  196.   Synopsis: msgp = CreatePort( name, pri );
  197.   
  198.   msgp:     (struct MsgPort *) Pointer to the new MsgPort
  199.             structure, or NULL if something went wrong.
  200.  
  201.   name:     (char *) Pointer to a string containing the name
  202.             of the message port, or NULL. If it is a string
  203.             the port will be made public (so other tasks can
  204.             find it) else only our task can use it.
  205.   
  206.   msgp:     (struct MsgPort *) Pointer to the MsgPort structure
  207.             that should be allocated.
  208.  
  209.   pri:      (BYTE) This message port's priority. Usually set
  210.             to 0 - normal priority.
  211.  
  212.  
  213. When your program terminates you must close the message port
  214. by calling the DeletePort() function!
  215.  
  216. DeletePort() deletes a message port. Every message port that
  217. has been allocated by CreatePort() must be deleted before the
  218. program terminates.
  219.  
  220.   Synopsis: DeletePort( msgp );
  221.  
  222.   msgp:     (struct MsgPort *) Pointer to the MsgPort structure,
  223.             that should be deallocated.
  224.  
  225.  
  226. Here is an example:
  227.  
  228.   /* Declare a pointer to our message port: */
  229.   struct MsgPort  *game_msg_port;
  230.  
  231.   /* Create the message port: */
  232.   /* (No name, priority 0.)   */
  233.   game_msg_port = CreatePort( 0, 0 );
  234.  
  235.   /* Check if we have received a message port or not: */
  236.   if( !game_msg_port )
  237.     /* ERROR! Could not create m