osContStartReadData, osContGetReadData

Obtains data from Controller

Syntax

#include <ultra64.h>        /* os.h */
s32 osContStartReadData(OSMesgQueue *mq);
void osContGetReadData(OSContPad *pad);

Description

The osContStartReadData function issues a read data command to obtain the current positon of 3D stick and button settings from Controller. The osContGetReadData function returns these data to the location pointed to by the pad argument. You can obtain such information that A button of Controller is pressed down or that how much 3D stick is tilted. These two functions must be paired to use.

The message queue pointed to by the mq argument must be an initialized message queue associated with the OS_EVENT_SI event. Please see the osSetEventMesg() function in the N64 Online Function Reference Manual, for details on how to create this association.

The osContStartReadData function is called only to issue read command, and the message for completed data reading is returned to the message queue mq. Therefore, the osContGetReadData function should be called to obtain data after the osContStartReadData function is called, and osRecvMesg receives a message indicating data reading is completed. The osContStartReadData function takes around 2 milliseconds to complete its data reading and for osRecvMesg to receive a final message. Other processes such as re-drawing the screen can be performed while you are waiting.

You must supply a block of memory large enough for MAXCONTROLLERS structures of type OSContStatus. If the osContSetCh function (please see osContSetCh) sets the number of direct-type SI devices accessed at a value less than the MAXCONTROLLERS number, then the area secured can be smaller than the MAXCONTROLLERS number, provided more devices are not added later.

typedef struct {
    u16 button;     /* Controller button data */
    s8  stick_x;    /* Control stick's X coordinate position*/
    s8  stick_y;    /* Control stick's Y coordinate position*/
    u8  errno;      /* Error values returned from the Controller */
} OSContPad;

The Control Stick's coordinate positions stick_x and stick_y are signed characters with a range from -128 to 127. However, for the actual program we recommend using values within the ranges shown below:

• Left/right X axis +/- 61
• Up/down Y axis +/- 63
• X axis incline +/- 45
• Y axis incline +/- 47

button and the following static variables are ANDed to check which mouse button has been clicked. For instance, button is ANDed with START_BUTTON to check if the bit is ON in order to check if the start button has been clicked.

• START_BUTTON is the start button

• A_BUTTON is the A Button

• B_BUTTON is the B Button

• U_CBUTTONS is the C Button Up

• D_CBUTTONS is the C Button Down

• L_C_BUTTONS is the C Button Left

• R_CBUTTONS is the C Button Right

• U_JPAD is the Control Stick Up

• D_JPAD is the Control Stick Down

• L_JPAD is the Control Stick Left

• R_JPAD is the Control Stick Right

• Z_TRIG is the Z Button

• L_TRIG is the L Button

• R_TRIG is the R Button

If an error occurs when reading data from Controller, the following error numbers are returned to errno of OSContPad structure. If it is successful, 0 is returned.

CONT_NO_RESPONSE_ERROR

The controller does not respond. The controller is not inserted.

CONT_OVERRUN_ERROR

The controller sends data at a higher data transfer rate than the hardware can handle. In this case, you should ignore the data.

Example

void	mainproc(void)
{
  OSMesgQueue     intMesgQueue;
  OSMesg          intMesgBuf[1];
  OSContStatus    sdata[MAXCONTROLLERS];
  OSContPad       rdata[MAXCONTROLLERS];
  u8              pattern;
  int             i;
  int             cont_exist = 0;

  osCreateMesgQueue(&intMesgQueue, intMesgBuf, 1);
  osSetEventMesg(OS_EVENT_SI, &intMesgQueue, NULL);
  osContInit(&intMesgQueue, &pattern, &sdata[0]);

  /* Confirm if controller is inserted */
  for(i = 0; i < MAXCONTROLLERS; i++){
    if(((pattern >> i) & 1) && (sdata[i].errno == 0)){
     if((sdata[i].type & CONT_TYPE_MASK) == CONT_TYPE_NORMAL){
        osSyncPrintf("controller is inserted in port %d\n",i);
        cont_exist = 1;
      }
    }
  }

  /* if controller is inserted */
  if(cont_exist){
    /* start reading controller data */
     osContStartReadData(&intMesgQueue);
              %
              %
    /* Confirm the end of reading */
    osRecvMesg(&intMesgQueue, NULL, OS_MESG_BLOCK);
    /* get controller data */
    osContGetReadData(&rdata[0]);
  }
}

See also

osContInit, osContReset, osContStartQuery, osContSetCh, osSetEventMesg, and osRecvMesg

Revision History

1999/02/01 Completely revised.
1999/04/30 Changed format