@DATABASE "JoyPorts"
@AUTHOR "Paul Manias"
@NODE "Main" "JoyPorts Documenation"

Name:         @{"JOYPORTS" LINK "Functions"} AUTODOC
Version:      0.7 Beta.
Date:         6 July 1997
Author:       Paul Manias
Copyright:    DreamWorld Productions, 1996-1997.  All rights reserved.
Notes:        This  document is still being written and will contain errors
              in  a  number  of  places.   The information within cannot be
	      treated as official until this autodoc reaches version 1.0.

@EndNode
---------------------------------------------------------------------------
@NODE "Functions" "JoyPort Functions"

 @{b}JOYPORT INTERFACE@{ub}
 @{"InitJoyPorts()" LINK "InitJoyPorts()"}
 @{"ReadJoyPort()"  LINK "ReadJoyPort()"}

@EndNode
---------------------------------------------------------------------------
@NODE "InitJoyPorts()" "JoyPorts/InitJoyPorts"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      InitJoyPorts()
Short:     Initialises the JoyPorts and resets the movement counters.
Assembler: InitJoyPorts()
C/C++:     void InitJoyPorts(void)

@{b}@{u}DESCRIPTION@{uu}@{ub}
If  you  are using any of the JoyPort related functions, then you will have
to  initialise  the  ports  before  trying to use them.  You must call this
function  in  the  initialisation  section  of your program, after you have
called AddInputHandler() (or AddScreen() which will do this for you).

You  will also need to call this function if you need the movement counters
reset  (note  that  even when you are not reading the joyports an interrupt
will  be  keeping track of any change in their movements).  If the user was
to  move  an  input  device  when  you are not calling any Read function, a
nonsense value may be returned if you start reading the ports again.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"ReadJoyPort" LINK "ReadJoyPort()"}

@EndNode
--------------------------------------------------------------------------
@NODE "ReadJoyPort()" "JoyPorts/ReadJoyPort"

@{b}@{u}FUNCTION@{uu}@{ub}
Name:      ReadJoyPort()
Short:     Reads any joystick device in a given joyport.
Assembler: JoyStatus = ReadJoyPort(PortName [d0], ReturnType [d1])
C/C++:     LONG ReadJoyPort(WORD PortName, WORD ReturnType)

@{b}@{u}DESCRIPTION@{uu}@{ub}
Reads the joyport and returns its status in the required format, regardless
of  what  playing  device  is  plugged in.  Currently supported devices are
standard  JoySticks, Analogue JoySticks, SegaPads, CD32 JoyPads, the mouse,
and the keyboard.

Unlike  the  lowlevel.library  equivalent of this function, this version is
much  faster and does not need to evaluate what device is currently plugged
in.   It simply reads the specified joy type from GMSPrefs and jumps to the
correct routine.

Future  devices may be added to this function - this will be transparent to
your program so that you can support devices that do not exist yet.

@{b}@{u}NOTE@{uu}@{ub}
The  first  time  you  call  this  function  it may return nonsense values.
Therefore you must call InitJoyPorts() before use.

@{b}@{u}INPUTS@{uu}@{ub}
PortName - JPORT1, JPORT2, JPORT3 or JPORT4.
ReturnType - JT_SWITCH: JoyStatus returns with switched bitflags. 
             JT_ZBXY:   JoyStatus returns with the ZBXY format.

@{b}@{u}RESULT@{uu}@{ub}
JoyStatus - Status of the JoyPort in one of the following two formats:

For  @{b}JT_SWITCH@{ub}  you  will  be  returned the joyport status in bits
which are set by:

  JS_LEFT,  JS_RIGHT, JS_UP,  JS_DOWN, JS_ZIN,   JS_ZOUT, JS_FIRE1,
  JS_FIRE2, JS_PLAY,  JS_RWD, JS_FFW,  JS_GREEN, JS_YELLOW

For  @{b}JT_ZBXY@{ub}  you  will be returned the joyport status in a packed
state, containing directional values and button status bits:

  BYTE | BIT RANGE | DATA
  -----+-----------+--------------------------------------
    1  |  0 -  7   | Y Direction
    2  |  8 - 15   | X Direction
    3  | 16 - 23   | Button status bits.
    4  | 23 - 31   | Z Direction (currently not supported)

  Button bits: JB_FIRE1/MB_LMB, JB_FIRE2/MB_RMB, JB_FIRE3/MB_MMB.

For @{b}JT_DATA@{ub} you will be returned a data structure which is derived
from the JT_ZBXY type.  It looks like this:

    STRUCTURE	JD,0
	WORD	JD_XChange
	WORD	JD_YChange
	WORD	JD_ZChange
	UWORD	JD_Buttons
	LABEL	JD_SIZEOF

The JD_Buttons field has the flags JD_FIRE1 ... JD_FIRE8.

@{b}@{u}SEE ALSO@{uu}@{ub}
@{"games/games.i" LINK "INCLUDES:games/games.i/Main"}

@EndNode