.TH osContInit 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
osContInit \- poll for and reset game controllers
.SH SYNOPSIS
.nf
\f3
.Op c
#include <ultra64.h>
.sp .8v
s32 osContInit(OSMesgQueue \(**mq, u8 \(**bitpattern, OSContStatus \(**status);
.Op
\f1
.fi
.SH DESCRIPTION
The 
.I osContInit
call resets all the game controllers and returns a bit pattern to 
indicate which game controllers are connected.
It also returns game controller's type 
and status back to 
.I status.
The user must supply a block of memory large enough for 
.I MAXCONTROLLERS
structures of type
.I OSContStatus.
The message queue
.I mq
must be an initialized message queue associated with the
.I OS_EVENT_SI
event.
See
.IR osSetEventMesg (3P)
for details on how to create this association.
Since the
.I osContInit
routine will wait on the message queue
.I mq,
this queue must not be shared.
A value of 0 is returned if the calls succeed, otherwise
-1 is returned.
.sp
The game controller's type can be one of the following defined constants:
.PP
.nf
.ta 5 20 
	CONT_ABSOLUTE	The controller contains counters inside and
			sends the joystick data as an absolute value.
	CONT_RELATIVE	The controller contains counters inside and
			sends the joystick data as a relative value.
	CONT_JOYPORT	The controller has a joyport which connects
			to a exchangeable CONTROLLER PAK.
.fi
.sp
The game controller's status is used for a CONTROLLER PAK and can be one of 
the following defined constants:
.PP
.nf
.ta 5 25
	CONT_CARD_ON	This bit is set if CONTROLLER PAK is
			connected to the controller.
	CONT_CARD_PULL	After controller is reset, if the CONTROLLER
			PAK is pulled out, this bit will be set.
	CONT_ADDR_CRC_ER 	This bit is set if the address is not 
			transfered to the joyport correctly.
.fi
.PP
The error returned from controllers can be:
.PP
.nf
.ta 5 30
	CONT_NO_RESPONSE_ERROR	The controller doesn't respond.
	CONT_OVERRUN_ERROR	The controller sends data at higher
				data transfer rate than the hardware 
				handling capability.
.fi
.PP
The user should ignore the data when detects 
.I CONT_OVERRUN_ERROR.
.SH EXAMPLE
.nf
.ta 5 20
main()
{
	OSMesgQueue      intMesgQueue;
	OSMesg           intMesgBuf[1];
	OSContStatus     sdata[MAXCONTROLLERS];
.sp
	osCreateMesgQueue(&intMesgQueue, intMesgBuf, 1);
	osSetEventMesg(OS_EVENT_SI, &intMesgQueue, dummyMessage);
	osContInit(&intMesgQueue, &pattern, &sdata[0]);
}
.fi
.SH "SEE ALSO"
.IR osContReset (3P),
.IR osContStartQuery (3P),
.IR osContGetQuery (3P),
.IR osContStartReadData (3P),
.IR osContGetReadData (3P),
.IR osContSetCh (3P)