Controller Library (libpad)

Provides functions for reading the controllers and driving the DUAL SHOCK actuators.

Overview

The controller library (libpad) lets applications communicate with the controllers, which are the input devices of the PlayStation. Applications process the data from the controllers directly and identify each controller while the program runs, and the library also supports the added features of DUAL SHOCK controllers.¹

libpad cannot be used together with the Multi Tap library (libtap) or the gun library (libgun). For the Multi Tap and guns, libpad provides PadInitMtap() and PadInitGun() itself. These libraries belong to the Controller/Peripherals libraries with libetc.¹

A program that uses libpad links with libpad.lib and includes libpad.h.¹

This library is part of the run-time library that Sony distributed with the Psy-Q development tools.²

Receive Buffer

Offset 0 of the receive buffer is 0x00 when the communication succeeded. The upper four bits of offset 1 hold the terminal type, and the lower four bits hold half the number of bytes received from the controller, which are stored from offset 2 on. The terminal types are the following:³

Offsets 2 and 3 hold the button state. Every button bit is 1 when the button is released and 0 when it is pressed, and the bits are assigned as follows:⁴⁵

Initialization

The controller is initialized in four steps. PadInitDirect(), or PadInitMtap() for a Multi Tap, initializes the controller environment. PadSetAct() sets the transmit buffer, and PadStartCom() begins communication. For a DUAL SHOCK, PadSetActAlign() then sets the order in which the actuator data is sent once the connection is established.⁶⁷

With a Memory Card, the Memory Card is initialized first with InitCARD(0), StartCARD() and _bu_init(). PadInitDirect() or PadInitMtap() then follows before PadStartCom(). With libmcrd, MemCardInit(0) and MemCardStart() are likewise called before the controller is initialized.⁸

Connection State

PadGetState() returns the connection state of the controller and also changes when the controller is swapped or its mode is switched, so it monitors both. Its value changes only during the vertical retrace interval, and it is therefore polled once per frame. A DUAL SHOCK passes through the following states:⁶

Other controllers go from PadStateDiscon to PadStateFindPad and then to PadStateFindCTP1 when the controller type is identified. A change of mode returns either kind to PadStateFindPad.⁶⁸

Actuators

The number of actuators that can vibrate at once is limited by the maximum current that the PlayStation can supply. The total current drain must therefore not exceed 60 units, where actuator 1 of the SCPH-1150 and SCPH-1200 draws 10 units and actuator 2 of the SCPH-1200 draws 20 units. For actuator 2, any value other than 0x00 means on. The limit applies only when a Multi Tap is used.⁸⁹

When a request would exceed 60 units, a limiter in the library refuses it. The actuators are counted in order of port number and then actuator number. For example, if actuator 1 is requested on four controllers of 20 units each, ports 00 to 02 vibrate and port 03 does not. A later request that still fits under the limit is granted, even after an earlier one has been refused.⁹

Analog Controller

When the stick of the Analog Controller is released it returns toward the center, but it may stop off center. An application that detects a released stick from its position allows for this error. For the SCPH-1200 the guaranteed range of the released stick is 80h plus or minus 25h.⁸

Transmission in Specific Frames

Communication with the controller normally takes place at every vertical sync, but it may be missed during frequent heavy interrupts such as streaming. PadChkVsync() returns 0 when the data of the previous frame was not sent. A program that sends data to the controller only in particular frames therefore checks this value.⁹

Parent and Child Processes

libpad keeps the connection state of the controllers and of the guns itself, and a controller is not recognized while that state is invalid. When parent and child processes both use a controller, each process therefore calls PadInitDirect() or PadInitMtap(), and PadInitGun() for guns.⁹

Guns

PadInitGun() only initializes the interrupt handler that obtains the horizontal and vertical position of a type 3 gun, so the communication is set up with PadInitDirect() or PadInitMtap() as usual. Other guns return their coordinates in the receive buffer in normal communication. Until PadEnableGun() is called, position interrupts are requested in every frame for each port with a type 3 controller, and PadEnableGun() masks the ones that are not needed.⁴

The horizontal position is a system clock count that is cleared at each horizontal blank, so it is converted to pixels for the screen mode and resolution. The pixel value is the coefficient times the clock count plus an offset:⁴¹⁰

Multi Tap Library

A Multi Tap connects up to 4 controllers and Memory Cards to one port. Communication needs at least one controller on the Multi Tap, and controllers and the Multi Tap itself may be inserted and removed during operation. Software that does not use libtap talks only to port A of the Multi Tap, which then passes the data through as if the controller were connected to the PlayStation directly. libtap returns the data of controllers A to D at bytes 4, 12, 20 and 28 of its receive packet.¹⁰¹¹

The Memory Card in each slot is accessed in the usual way with the channel set to the port number times 16 plus the card number from 0 to 3. InitCARD() takes 0 in this case, and a Multi Tap not inserted in port A is sometimes not recognized:¹¹

Gun Library

A program that uses libgun links with libgun.lib and includes libgun.h. The gun ID is 0x31, which is controller type 3 with 2 bytes of receive data. In the button data the S bit is the start button and the other two bits are the trigger and a button.¹¹¹²

InitGUN() sets up buffers that hold up to 20 pairs of vertical and horizontal counter values per frame. From library 4.0, DMA and interrupt processing are blocked during the gun interrupt to improve accuracy. The overhead therefore grows in horizontal sync units with the number of interrupts, and the manual recommends a small number.¹²

Functions

In the tables below, Introduced is the run-time library version that added the item.¹³

libpad has the following functions:¹³

References