The KPAD library version from before Revolution SDK Version 2.3 has been renamed to KPADOld library.
Current implementation of the KPAD library is considerably different from the KPADOld library, so the application behavior will not match exactly. Also, the application source code may require some changes. To use the added functions effectively, refer to Main Changes from the KPADOld Library shown below.
KPAD library is a high-level library located in the upper part of the WPAD library. Compared to the use of the WPAD library directly, use of the KPAD library can get coordinates for where the Wii Remote is pointing more easily. It also provides features such as reducing the effects of hand tremor and adjusting the sensitivity of the Wii Remote. Besides the Wii Remote controller data, the Classic Controller and Nunchuk controller data can also be retrieved.
Note: Beginning with version 3.2 of the Revolution SDK, you can link to the WBC library to obtain Wii Balance Board information.
A sample program for testing KPAD library features is in $(REVOLUTION_SDK_ROOT)/build/demos/kpaddemo/. When using these samples, we recommend placing the Wii Remote and the Sensor Bar at least 1.5 meters apart (the samples may not function well at a distance of 1.0 meter).
The KPAD library is in the following path.
$(REVOLUTION_SDK_ROOT)/RVL/lib/kpad[D].a
Function declarations are in the $(REVOLUTION_SDK_ROOT)/include/revolution/kpad.h header file.
KPADOld and KPAD libraries cannot be used at the same time. KPADOld library is not linked to the application by default. To learn how to link the KPADOld library, see "Introduction" in the KPADOld library reference manual.
KPADOld: Uses auto-sampling.(WPADSetAutoSamplingBuf function).
KPAD: Uses the sampling callback(WPADSetSamplingCallback function).
The application can no longer call the WPADSetSamplingCallback function. The KPADSetSamplingCallback function can be used instead to call from sampling callback inside the KPAD library. Note that the callback registered through this function will not be released unless you either specify NULL as an argument to this function or call the KPADShutdown function. Connecting or disconnecting a controller will not release the callback.
KPADOld: You can use either the WPADProbe function or the WPADSetConnectCallback function.
KPAD: You can use the WPADProbe function, but not the WPADSetConnectCallback function. You can also use the return value from the KPADReadEx function instead of the WPAD library.
Applications can no longer call the WPADSetConnectCallback function while using the KPAD library. The WPADSetConnectCallback function can be used as usual when the KPAD library is not in use. Also, the callback function registered before the call to KPADInit is now maintained within the KPAD library and is called when connecting or disconnecting. When the KPAD library is being used, use the KPADSetConnectCallback function to register callbacks. Although callbacks registered using this function are deleted by specifying NULL as an argument to this function or by calling KPADShutdown, doing this will not clear any callbacks registered before beginning use of the KPAD library.
The size and order of some members of the KPADStatus and KPADEXStatus structures have changed. If the application writes to the members of these structures, revise the source code to match the new definition. While some members have been added, the source code should require minimal changes if only referencing the preexisting structure members.
KPADOld: Resets the internal work immediately. Stops the rumble motor.(WPADStopMotor function).
KPAD: Stops the rumble motor immediately. Internal works will not be reset with certain exceptions. The actual reset process is performed the next time the KPADRead or KPADReadEx function is called.
The KPAD library uses a ring buffer to store the Wii Remote input data used for the internal processing of each channel in turn. A buffer of length KPAD_RING_BUFS is maintained for this purpose. The contents of this ring buffer are flushed every time the KPADRead or KPADReadEx function is called.
When the KPADInit function is used, it uses this maintained ring buffer, but the old input data in the ring buffer can be lost if the interval between flushes is too long. In such cases, the length of the ring buffer can now be extended using the KPADInitEx function. Pass the additional buffer (an array of KPADUnifiedWpadStatus structures) and its size as arguments to the KPADInitEx function. This buffer is internally divided into four parts, and each is assigned for processing of a different channel, so make sure the size you specify is a multiple of 4. If additional buffer length is not necessary, pass NULL and zero.
We recommend that you use the KPADInitEx function for future development of applications.
The KPADRead function returns the number of sets of sampling data, or zero if there are none. The KPADReadEx function also returns the error code in the variable pointer passed as an argument, in addition to the same types of values. The error codes are as follows:
| KPAD_READ_ERR_NONE | There is sampling data. |
|---|---|
| KPAD_READ_ERR_NO_DATA | No sampling data. |
| KPAD_READ_ERR_NO_CONTROLLER | The Wii Remote is not connected. |
| KPAD_READ_ERR_SETUP | WPAD library initialization is not complete. |
| KPAD_READ_ERR_LOCKED | Duplicate calls caused failure to obtain permission to process. |
| KPAD_READ_ERR_INIT | The KPADInit function (or the KPADInitEx function) has not been called. |
Even when the KPADRead function returns zero, there is a possibility that the contents of the sampling buffer passed to it as an argument have changed. There is also a chance that the KPADReadEx function will change the sampling buffer's contents, but if and only if KPAD_READ_ERR_NO_DATA is returned, then the contents at the start of the sampling buffer have not changed.
We recommend that you use the KPADReadEx function for future development of applications.
KPADStatus Structure
The err member value of the WPADStatus structure that is obtained from the WPADRead function will be copied into the wpad_err member of the KPADStatus structure. The error code passed into this member variable indicates the state of data received from the Wii Remote, as follows.
| WPAD_ERR_NONE | Data with the specified data format was received. |
|---|---|
| WPAD_ERR_NO_CONTROLLER | Data has never been received. |
| WPAD_ERR_INVALID | Data was received with a format that differs from the data format specified to the WPAD library. (In this case, the data for the Wii Remote and external extension controllers is invalid.) |
| WPAD_ERR_CORRUPTED | An external extension controller such as the Nunchuk or Classic Controller is partially inserted into the Wii Remote, and the data for the external extension controller is corrupted. (However, in this case Wii Remote data has not been corrupted.) |
To get the Wii Remote status, use the WPADProbe function in the WPAD library. The error codes returned from the WPADProbe function are shown below, along with their descriptions. Note: You can also use the KPADReadEx function to check if a Wii Remote is connected.
| WPAD_ERR_NONE | The Wii Remote is connected, and control commands are not being sent from the Wii console to the Wii Remote. |
|---|---|
| WPAD_ERR_NO_CONTROLLER | The Wii Remote is disconnected. |
| WPAD_ERR_BUSY | A control command has been sent to a connected Wii Remote, and the system is waiting for an ACK from the Wii Remote. |
The error code that can be obtained by the WPADProbe function and the error code passed to the WPADStatus structure's err member each have different meanings. Be aware that they are not synchronized.
KPADOld: Call is prohibited because the operation is undefined.
KPAD: Returns zero if processing permissions failed to be obtained. The KPADReadEx function will also return the error code KPAD_READ_ERR_LOCKED.
KPADOld: Call is prohibited because the operation is undefined.
KPAD: Yes.
KPADOld: Assumes that the function is called for each game frame.
KPAD: Essentially the same as KPADOld. However, you can make it more difficult to drop data by increasing the number of sampling buffers (each of these is one-fourth of the buffer passed to the KPADInitEx function) beyond the number used in KPADOld.
KPADOld: If DPD is not being used, during the period of no calls a controller disconnect/reconnect will be treated as "no change in device," and the controller will not be initialized.
KPAD: The controller initialization procedure has been changed, so there will be no issues except for the loss of sampling data during the period of no calls.
KPADOld: Because internal work will be reset, swapping the extended controllers while pressing a button will result in the input being treated as a trigger.
KPAD: Internal work unrelated to the extended controllers will not be reset, so swapping while pressing a button will not be a problem.
KPADOld: DPD and Motion Sensor values fluctuate more easily.
KPAD: Adding the data format check allows maximal possible control of the fluctuation caused by swapping.
KPADOld: This was the recommended method. However, the WPAD auto-sampling buffer will be automatically cleared when the controller disconnects, and the buffer may not be completely full of the specified format immediately after specification of data format through the WPADSetDataFormat function. Thus, we cannot guarantee that the application can access the buffer in the appropriate data format.
KPAD: This method has been deprecated. Use the new KPADGetUnifiedWpadStatus function instead.
KPADOld: Circular clamp is implemented.
KPAD: Added cross clamp. The default is circular clamp as with KPADOld. Select it through the KPADEnableStickCrossClamp and KPADDisableStickCrossClamp functions.
KPADOld: If a controller is disconnected when the KPADRead function has not been called for a long time, the sampling buffer updates will stop. The KPADRead function called next will use the old sampling data. If you want to use the newest sampling data, first call the KPADRead function (specify KPAD_MAX_READ_BUFS for the storage count) and clear all internal sampling buffers.
KPAD: No processing is necessary because sampling buffer data is thrown away when a controller is disconnected.
The KPADRead and KPADReadEx functions are designed with the assumption that they will be called once every game frame. However, if the interval between calls to these functions grows too long due to a processing slowdown or some other reason, the KPAD library's internal ring buffer might go full circle, and data could be lost.
KPADOld: These conditions can sometimes be improved by using the rebuilt KPAD library and changing the KPAD_RING_BUFS macro value in $(REVOLUTION_SDK_ROOT)/include/revolution/kpad.h to increase the ring buffer.
KPAD: Conditions can sometimes be improved by increasing the ring buffer that is passed to KPADInitEx.
The KPAD library is initialized by calling either the KPADInit function or the KPADInitEx function. Call the WPADRegisterAllocator function to register the memory allocator function for getting and deallocating memory with the WPAD library before calling these functions because they invoke the WPADInit function internally. After the KPAD library is initialized, it uses the WPAD library sampling callback (auto sampling for KPADOld) to get data and update its internal buffer.
To load the specified channel's controller information into the KPADStatus structure, use the KPADRead or KPADReadEx function. The controller information to be read may be adjusted by calling the following functions beforehand.
KPADSetPosParam, KPADSetHoriParam, KPADSetDistParam, and KPADSetAccParam functions.
KPADSetBtnRepeat function.
KPADSetSensorHeight, KPADEnableAimingMode, and KPADDisableAimingMode functions to adjust the feature used to correct the screen coordinates to which the Wii Remote points. The coordinate correction feature is enabled by default. The KPADEnableAimingMode function is automatically called from the KPADInit function.
KPADEnableStickCrossClamp and KPADDisableStickCrossClamp functions.
In some cases, it might be effective to call the KPADReset function, such as during a change in scenes. However, because the KPADReset function will have an ill effect on button trigger processing, avoid calling the function where possible. It does not also need to be called when swapping external extension controllers.
The coordinate system of the coordinates obtained with the KPAD library is different from that used in the WPAD library. For details, see the KPADStatus and KPADEXStatus structure pages.
2008/06/05 Deleted text about the KPADSetObjInterval function.
2008/06/03 Added an explanation for the KPADReadEx function.
2008/05/29 Added explanations for the KPADInitEx function.
2008/04/17 Mentioned that the Wii Balance Board is now supported. Revised differences with KPADOld.
2007/01/15 Revised such that the coordinate correction feature is enabled by default. As a result, revised the demo.
Fixed the following bug: the button repeat interval would increase if the maximum number of stored data items passed to the KPADRead function was smaller than KPAD_MAX_READ_BUFS.
Corrected errors in the manuals of the KPADEnableStickCrossClamp and KPADDisableStickCrossClamp functions.
2006/10/25 Revised the description to match KPAD version 2.
2006/06/19 Support for UI Tool Version 4. Changed tentative product name to official name.
2006/05/15 Added to Notes methods to avoid loss of data when the intervals between calls of the KPADRead function become too long.
2006/03/01 Initial version.
CONFIDENTIAL