Controller Library (libpad): Difference between revisions
| Revision as of 02:47, 23 October 2026 RemmyLee (Formats: Sony paragraph voice; HMD, RSD extended files, full BS code book; sprite editor formats) | Revision as of 02:58, 23 October 2026 RemmyLee (Run-time library pages: 20 libraries from the Library Overview and Reference 4.4) | ||
| Line 1: | Line 1: | ||
| + | --- | ||
| + | title: Controller Library (libpad) | ||
| + | type: component | ||
| + | summary: Provides functions for reading the controllers and driving the DUAL SHOCK actuators. | ||
| + | category: Libraries | ||
| + | info: Library = libpad.lib | ||
| + | info: Header File = libpad.h | ||
| + | --- | ||
| + | |||
| + | ## 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.[^o13-9] | ||
| + | |||
| + | 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](/libraries/libetc/).[^o13-9] | ||
| + | |||
| + | A program that uses libpad links with libpad.lib and includes libpad.h.[^o13-9] | ||
| + | |||
| + | ## 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:[^o13-10] | ||
| + | |||
| + | Table: Terminal types | ||
| + | |||
| + | | Terminal type | Controller name | Model number | | ||
| + | | --- | --- | --- | | ||
| + | | 1 | Mouse | SCPH-1030 | | ||
| + | | 2 | 16-button analog | SLPH-00001 (Namco) | | ||
| + | | 3 | Gun controller | SLPH-00014 (Konami) | | ||
| + | | 4 | 16-button | SCPH-1080, 1150, 1200 | | ||
| + | | 5 | Analog joystick | SCPH-1110 | | ||
| + | | 6 | Gun controller | SLPH-00034 (Namco) | | ||
| + | | 7 | Analog Controller | SCPH-1150, 1200 | | ||
| + | | 8 | Multi Tap | SCPH-1070 | | ||
| + | |||
| + | 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:[^o13-13][^o2-20] | ||
| + | |||
| + | Table: Button state bits | ||
| + | |||
| + | | Bit | 16-button | Analog Controller | 16-button analog | Mouse | Gun (Konami) | Gun (Namco) | | ||
| + | | --- | --- | --- | --- | --- | --- | --- | | ||
| + | | D15 | Left | Left | Left | | | | | ||
| + | | D14 | Down | Down | Down | | | | | ||
| + | | D13 | Right | Right | Right | | | | | ||
| + | | D12 | Up | Up | Up | | | | | ||
| + | | D11 | Start | Start | Start | | Start | A | | ||
| + | | D10 | | R3 | | | | | | ||
| + | | D9 | | L3 | | | | | | ||
| + | | D8 | Select | Select | | | | | | ||
| + | | D7 to D4 | Symbol buttons | Symbol buttons | | | | | | ||
| + | | D7 | | | | | Trigger | | | ||
| + | | D6 | | | | | | B | | ||
| + | | D5 | | | A | | | Trigger | | ||
| + | | D4 | | | B | | | | | ||
| + | | D3 | R1 | R1 | R | Left | | | | ||
| + | | D2 | L1 | L1 | | Right | | | | ||
| + | | D1 | R2 | R2 | | | | | | ||
| + | | D0 | L2 | L2 | | | | | | ||
| + | |||
| + | ## 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.[^o13-17][^r12-25] | ||
| + | |||
| + | 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.[^o13-18] | ||
| + | |||
| + | ## 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:[^o13-17] | ||
| + | |||
| + | Table: DUAL SHOCK connection states | ||
| + | |||
| + | | Step | State | | ||
| + | | --- | --- | | ||
| + | | Controller not connected | PadStateDiscon | | ||
| + | | Connection detected | PadStateFindPad | | ||
| + | | Request for actuator information received | PadStateReqInfo | | ||
| + | | Actuator information retrieved | PadStateStable | | ||
| + | |||
| + | 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.[^o13-17][^o13-18] | ||
| + | |||
| + | ## 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.[^o13-18][^o13-19] | ||
| + | |||
| + | 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.[^o13-19] | ||
| + | |||
| + | ## 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.[^o13-18] | ||
| + | |||
| + | ## 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.[^o13-19] | ||
| + | |||
| + | ## 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.[^o13-19] | ||
| + | |||
| + | ## 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.[^o13-13] | ||
| + | |||
| + | 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:[^o13-13][^o13-14] | ||
| + | |||
| + | Table: System clock to pixel conversion | ||
| + | |||
| + | | Mode | Horizontal resolution | Coefficient | | ||
| + | | --- | --- | --- | | ||
| + | | NTSC | 256 | 0.158532 | | ||
| + | | PAL | 256 | 0.157086 | | ||
| + | |||
| + | ## 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.[^o13-14][^o13-15] | ||
| + | |||
| + | 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:[^o13-15] | ||
| + | |||
| + | Table: Multi Tap Memory Card channels | ||
| + | |||
| + | | Slot | Port 1 | Port 2 | | ||
| + | | --- | --- | --- | | ||
| + | | A | 0x00 | 0x10 | | ||
| + | | B | 0x01 | 0x11 | | ||
| + | | C | 0x02 | 0x12 | | ||
| + | | D | 0x03 | 0x13 | | ||
| + | |||
| + | ## 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.[^o13-15][^o13-16] | ||
| + | |||
| + | 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.[^o13-16] | ||
| + | |||
| + | ## Functions | ||
| + | |||
| + | In the tables below, Introduced is the run-time library version that added the item.[^reff124] | ||
| + | |||
| + | libpad has the following functions:[^reff124] | ||
| + | |||
| + | Table: libpad functions | ||
| + | |||
| + | | Function | Library | Introduced | Purpose | | ||
| + | | --- | --- | --- | --- | | ||
| + | | `DisableTAP` | libtap | 3.6 | Disable communication with the controller. | | ||
| + | | `EnableTAP` | libtap | 3.6 | Enables occurrence of an event. | | ||
| + | | `InitGUN` | libgun | 3.5 | Initialize gun. | | ||
| + | | `InitTAP` | libtap | 3.4 | Initialize controller. | | ||
| + | | `PadChkVsync` | libpad | 4.2 | Check communication with controller. | | ||
| + | | `PadEnableCom` | libpad | 4.2 | Enable/disable communication with the controller. | | ||
| + | | `PadEnableGun` | libpad | 4.2 | Enable/disable gun interrupts. | | ||
| + | | `PadGetState` | libpad | 4.2 | Get controller connection state. | | ||
| + | | `PadInfoAct` | libpad | 4.2 | Get actuator information. | | ||
| + | | `PadInfoComb` | libpad | 4.2 | Get information on actuator combinations that can be used simultaneously. | | ||
| + | | `PadInfoMode` | libpad | 4.2 | Get information about the controller mode. | | ||
| + | | `PadInitDirect` | libpad | 4.2 | Initialize controller environment (for direct connection to the main PlayStation unit). | | ||
| + | | `PadInitGun` | libpad | 4.2 | Initialize controller environment (for guns that use interrupts). | | ||
| + | | `PadInitMtap` | libpad | 4.2 | Initialize controller environment (for Multi Taps). | | ||
| + | | `PadRemoveGun` | libpad | 4.2 | Stop retrieval of horizontal/vertical gun position. | | ||
| + | | `PadSetAct` | libpad | 4.2 | Set transmit buffer. | | ||
| + | | `PadSetActAlign` | libpad | 4.2 | Set actuator parameter details to be sent to the controller. | | ||
| + | | `PadSetMainMode` | libpad | 4.2 | Switches / locks the controller mode selector. | | ||
| + | | `PadStartCom` | libpad | 4.2 | Start reading from controller. | | ||
| + | | `PadStopCom` | libpad | 4.2 | Stop controller read. | | ||
| + | | `RemoveGUN` | libgun | 3.6 | Remove gun driver. | | ||
| + | | `SelectGUN` | libgun | 3.5 | Select gun. | | ||
| + | | `SendTAP` | libtap | 3.7 | Send data to controller. | | ||
| + | | `StartGUN` | libgun | 3.6 | Start controller reading. | | ||
| + | | `StartTAP` | libtap | 3.4 | Start controller reading. | | ||
| + | | `StopGUN` | libgun | 3.6 | Halt controller reading. | | ||
| + | | `StopTAP` | libtap | 3.4 | Halt controller reading. | | ||
| + | |||
| + | ## References | ||
| + | |||
| + | [^o2-20]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 2-20. | ||
| + | [^o13-9]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 13-9. | ||
| + | [^o13-10]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 13-10. | ||
| + | [^o13-13]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 13-13. | ||
| + | [^o13-14]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 13-14. | ||
| + | [^o13-15]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 13-15. | ||
| + | [^o13-16]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 13-16. | ||
| + | [^o13-17]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 13-17. | ||
| + | [^o13-18]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 13-18. | ||
| + | [^o13-19]: Sony Computer Entertainment Inc. Run-Time Library Overview. Run-Time Library 4.4. January 1999. Page 13-19. | ||
| + | [^r12-25]: Sony Computer Entertainment Inc. Run-Time Library Reference. Run-Time Library 4.4. January 1999. Page 12-25. | ||
| + | [^reff124]: Sony Computer Entertainment Inc. Run-Time Library Reference. Run-Time Library 4.4. January 1999. Pages 12-4 to 12-43. | ||