N64® Functions Menu

al - Audio Library Functions
gDP - DP GBI Macros
gdSP - General GBI Macros
gSP - SP GBI Macros
gt - Turbo Microcode RDP
gu - Graphics Utilities
Math - Math Functions
nuSys - NuSystem
os - N64 Operating System
sp - Sprite Library Functions
uh - Host to Target IO
64DD - N64 Disk Drive

Nintendo® Confidential

   

osContInit

Format
#include <ultra64.h>
s32 osContInit(OSMesgQueue *mq, u8 *bitpattern, OSContStatus *status);

What This Function Does
It initializes the game Controller. It initializes the internal variables to be used for the Controller and returns the bit pattern of the connected Controller to the location pointed to by the bitpattern argument. It also checks and returns the status of the connected Controller and the Controller Pak to the location pointed to by the status argument.

Before a Controller, Controller Pak, or EEPROM can be used, this function must be called. However, it is meaningless to call this function more than once.

This function does nothing if it is called again, after the first call. Therefore, you cannot check the Controller's status. If you want to check the status of the Controller or the Controller Pak after the first call, use the osContStartQuery and osContGetQuery functions.

The area specified by the status argument must be large enough to store the number of OSContstatus structures specified by MAXCONTROLLERS. The message queue (pointed to by the mg argument) must be the initialized message queue, linked to OS_EVENT_SI. To learn how to make the link, see osSetEventMesg. When the osContInit blocks on the message queue, do not share the queue. 0 is returned if the call is successful, otherwise -1 is returned. Here is the definition for the structure: 
typedef struct {
   u16type;  /*Controller type*/
   u8status; /*Controller Pak status*/
   u8errno;
}OSContStatus;
 According to the state of the Controller, the status->type becomes one of these:
  • CONT_ABSOLUTE - The Controller contains an internal counter and sends the control stick (A, B, X, Y, Z, L, R, Start buttons) data in its absolute value. This is the usual Controller response.
  • CONT_RELATIVE - The Controller contains an internal counter and sends the control stick (A, B, X, Y, Z, L, R, Start buttons) data in its relative value.
  • CONT_JOYPORT - The Controller is equipped with a Controller socket into which a Controller Pak can be connected.
According to the Controller Pak's status, status->status becomes one of these:
  • CONT_CARD_ON - This bit is set when a Controller Pak is connected to a Controller.
  • CONT_CARD_PULL - This bit is set when the Controller Pak is removed after the Controller has been reset.
  • CONT_ADDR_CRC_ER - This bit is set when the address was not transferred to the Controller socket properly.
When there is a problem reading the Controller, status->errno becomes one of these values:
  • CONT_NO_RESPONSE_ERROR - There is no response from the Controller. The Controller is not inserted.
  • CONT_OVERRUN_ERROR This bit is set when the Controller attempts to send the data faster than the hardware can handle. When this happens, disregard the data.
When it is recognized that the Controller socket was not connected (bitpattern's bit is zero, or status->errno is not zero), the Controller's status type and status value become invalid. You need to make sure the Controller is connected by looking at the bit pattern before examining the Controller type and status.

Before using an application that uses a standard Controller, make sure the CONT_ABSOLUTE and CONT_JOYPORT bits are high.

Nintendo 64 OS version 2.0F and later versions do not reset the Controller. Although it is not usually necessary, you can reset the Controller by using osContReset.

Example
main()
{
   OSMesgQueue intMesgQueue;
   OsMesg intMesgBuf[1];
   OSContStatus sdata[MAXCONTROLLERS];
   osCreateMesgQueue(
   osSetEventMesg(OS_EVENT_SI, 
   osContInit(
}
 See Also
osContReset
osContStartQuery
osContStartReadData
osContGetQuery
osContGetReadData
osContSetCh


Nintendo® Confidential

Warning: all information in this document is confidential and covered by a non-disclosure agreement. You are responsible for keeping this information confidential and protected. Nintendo will vigorously enforce this responsibility.
Copyright © 1998
Nintendo of America Inc. All rights reserved
Nintendo and N64 are registered trademarks of Nintendo
Last updated January 1998