NAME
	ReadJoyPort -- return the state of the selected joy/mouse port. (V40)

   SYNOPSIS
	portState = ReadJoyPort(portNumber);
	D0                      D0

	ULONG ReadJoyPort(ULONG);

   FUNCTION
	This function is used to determine what device is attached to the
	joy port and the current position/button state. The user may attach
	a mouse, game controller, or joystick to the port and this function
	will dynamically detect which device is attached and return the
	appropriatly formatted portState.

	To determine the type of controller that is attached, this function
	clocks the game controller and/or interprets changes in the joy
	port data. Valid clocked data from the game controller is immediately
	detected. However, to accuratly determine if a mouse or joystick is
	attached, several calls to this function are required along with some
	movement at the joy port by the user.

	This function always executes immediatly.

	This is a low level single threaded function that does not fit the
	normal Amiga multitasking model. Only one task can be executing
	this routine at any time. All others will return immediately with
	JP_TYPE_NOTAVAIL.

	The nature of this routine is not meant to encourage non-multitasking
	friendly programming practices like polling loops. If your task
	is waiting for a transition to be returned use a WaitTOF() between
	calls to minimize the total system impact.

	When called the first time, for each port, this function attempts to
	acquire certain system resources. In order to aquire these resources
	this function MUST be called from a task, or a DOS process. If this
	function fails to aquire the necessary resources, it will
	return with JP_TYPE_NOTAVAIL. Once the resources are aquired (return
	value other than JP_TYPE_NOTAVAIL) this function may be used in
	interrupts.

   INPUTS
	portNumber - port to read, in the range 0 to 3.

   RESULT
	portState - bit map that identifies the device and the current
	            state of that device. The format of the bit map is
	            dependant on the type of device attached.

	            The following constants from <libraries/lowlevel.h>
	            are used to determine which device is attached and
	            the state of that device.

	            The type of device can be determined by applying
	            the mask JP_TYPE_MASK to the return value and comparing
	            the resultant value with the following:

	                JP_TYPE_NOTAVAIL        port data unavailable
	                JP_TYPE_GAMECTLR        game controller
	                JP_TYPE_MOUSE           mouse
	                JP_TYPE_JOYSTK          joystick
	                JP_TYPE_UNKNOWN         unknown device

	            If type = JP_TYPE_GAMECTLR the bit map of portState is:
	                JPF_BUTTON_BLUE         Blue - Stop
	                JPF_BUTTON_RED          Red - Select
	                JPF_BUTTON_YELLOW       Yellow - Repeat
	                JPF_BUTTON_GREEN        Green - Shuffle
	                JPF_BUTTON_FORWARD      Charcoal - Forward
	                JPF_BUTTON_REVERSE      Charcoal - Reverse
	                JPF_BUTTON_PLAY         Grey - Play/Pause
	                JPF_JOY_UP              Up
	                JPF_JOY_DOWN            Down
	                JPF_JOY_LEFT            Left
	                JPF_JOY_RIGHT           Right

	            If type = JP_TYPE_JOYSTK the bit map of portState is:
	                JPF_BUTTON_BLUE         Right
	                JPF_BUTTON_RED          Fire
	                JPF_JOY_UP              Up
	                JPF_JOY_DOWN            Down
	                JPF_JOY_LEFT            Left
	                JPF_JOY_RIGHT           Right

	            If type = JP_TYPE_MOUSE the bit map of portState is:
	                JPF_BUTTON_BLUE         Right mouse
	                JPF_BUTTON_RED          Left mouse
	                JPF_BUTTON_PLAY         Middle mouse
	                JP_MVERT_MASK           Mask for vertical counter
	                JP_MHORZ_MASK           Mask for horizontal counter

   SEE ALSO
	SetJoyPortAttrs()