Starting with version 3.3 of the Revolution SDK, KPADOld can no longer be used.
Starting with version 3.2 of the Revolution SDK, Wii Balance Board information can be obtained by linking the WBC library.
The KPAD library is a high-level library located above the WPAD library. Compared to using the WPAD library directly, the 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. It is also now possible to get 3D attitude information of the Wii remote from Wii MotionPlus information by passing a dedicated work area to the KPAD library.
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.
Use the WPADSetSamplingCallback function to configure the sampling callback inside the KPAD Library. When this is done, the application cannot call the WPADSetSamplingCallback function. In its place, use the KPADSetSamplingCallback function to set a user callback that is called from the 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.
Because the WPADSetConnectCallback function sets a callback inside the KPAD library, the application cannot call the WPADSetConnectCallback function. 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 by this function are released when NULL is given as the function argument or when the KPADShutdown function is called, these actions do not clear callbacks that were registered before the use of the KPAD library.
Check the connection status using the value returned by the WPADProbe function or the KPADReadEx function.
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.
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.
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 | The format of incoming data is different from the format specified for the WPAD library. Values other than err and dev are undefined. (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.
When the KPADRead or KPADReadEx functions are called, the ring buffer inside the KPAD library is flushed. For this reason, if data will be used by multiple threads, we recommend that you use a single thread and share the loaded data, rather than calling functions from multiple threads.
When the functions are called multiple times, they will return zero when they fail to gain processing rights. The KPADReadEx function will also return the error code KPAD_READ_ERR_LOCKED.
Implemented as circular clamping as well as cross-shape clamping. Circular clamping is used by default. Select it through the KPADEnableStickCrossClamp and KPADDisableStickCrossClamp functions.
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.
Conditions can sometimes be improved by increasing the ring buffer that is passed to the KPADInitEx function.
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 this, the KPAD library uses the WPAD library's sampling callback to get data and the KPAD library's internal buffer is updated.
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.
Because the Wii console and Wii Remote use wireless communication, poor signal conditions in the surrounding area can cause signal interference, and the Wii console may not be able to receive data from the Wii Remote. If these conditions persist, the KPADRead function may return zero. Even in these circumstances the Wii console and Wii Remote maintain their connection status, so do not judge their connection status from the return value of this function. To judge connection status, use the WPADProbe or WPADSetConnectCallback function. It is also possible to use the return value of the KPADReadEx function. KPAD_READ_ERR_NO_DATA is used as the return value when data cannot be received. KPAD_READ_ERR_NO_CONTROLLER is used as the return value when not connected.
The sensors used in the Wii MotionPlus are rate sensors (gyroscopes). These rate sensors can get the angular velocity around the axes for pitch, yaw, and roll. The values for each axis are stored in the KPADMPStatus structure and obtained with the KPADRead function. The KPADMPStatus structure has the members mpls, angle, and dir. The first two are defined as type Vec. The Vec type direction components are as follows: x is the pitch, y is the yaw, and z is the roll. The mpls member represents the angular velocity in each direction and stores a value where 1.0 corresponds to 360 dps (degrees per second). The angle member represents the angle in each direction and stores a value where 1.0 corresponds to 360 degrees. The dir member represents the 3D attitude expressed as a 3x3 matrix.
See the WPAD library Introduction for more detailed information on the Wii MotionPlus.
The Wii MotionPlus does not start immediately after it is plugged into the Wii Remote. Start the Wii MotionPlus by sending it the start command. Start and stop the Wii MotionPlus using the KPADEnableMpls and KPADDisableMpls functions, respectively. When these functions are called, the KPAD library checks the device's current state against the specified state and operates to bring about the specified state. If the state is not the specified state (for example, the Wii MotionPlus is not attached), then the function continues to send a startup command until the specified state comes into being. In addition, if you register a callback ahead of time using the KPADSetControlMplsCallback function, the following notfications are used: KPAD_STATE_CTRL_MPLS_START is sent when processing to start or stop the Wii MotionPlus is started, and KPAD_STATE_CTRL_MPLS_FINISHED is sent when processing is finished. If an error occurs during processing, a KPAD_STATE_CTRL_MPLS_FAILED_STD, KPAD_STATE_CTRL_MPLS_FAILED_FS, or KPAD_STATE_CTRL_FAILED_CL notification is sent, depending on the state passed to the KPADEnableMpls function. In addition to registering callbacks, you can also directly check the state of the Wii MotionPlus using the KPADGetMplsStatus function.
For example, suppose you pass WPAD_MPLS_FS to the KPADEnableMpls function and call it while the Wii MotionPlus is running in normal mode. A KPAD_STATE_CTRL_MPLS_START notification is issued, and a Wii MotionPlus mode change is initiated because the current state (WPAD_MPLS_STD) differs from the specified state (WPAD_MPLS_FS). Because the Wii MotionPlus must be temporarily stopped when switching between normal mode and extension mode, the KPAD library first stops the Wii MotionPlus. Note that the device type obtained by the WPADProbe function at this point is WPAD_DEV_CORE. Once the Wii MotionPlus has stopped, the Wii MotionPlus can be started in extension mode. Unless the state specified in the KPADEnableMpls or KPADDisableMpls function is changed, the KPAD library performs this entire series of operations.
To output audio from the Wii Remote speaker, audio output commands are sent to the Wii Remote. This process can be affected by processes sending other commands. This does not happen except when commands are being sent frequently. Note that because the KPADEnableMpls function sends the startup command to the Wii MotionPlus until a specified condition is met, the Wii Remote speaker cannot output audio if the Wii MotionPlus is detached while this function is called.
In some cases the Home Menu outputs audio from the Wii Remote speaker. If the Home Menu is started and the Wii MotionPlus is detached while the KPADEnableMpls function is called, the Wii Remote speaker cannot output audio.
You can avoid this problem by stopping the Wii MotionPlus when the Home Menu is started.
A dedicated work area is required for the KPAD library to process Wii MotionPlus data. Be sure to first set the work area using the KPADSetMplsWorkarea function if the KPAD library will be processing data. To get the amount of memory making up the work area, use the KPADGetMplsWorkSize function.
To deallocate the work area specified by the KPADSetMplsWorkarea function, pass NULL to the function. Memory is destroyed if the work area is deallocated while even one Wii MotionPlus is operating, so do not deallocate the work area at such times. Before deallocation, verify that Wii MotionPlus is not operating on any Wii Remote.
The Wii MotionPlus hardware maintains calibration values set during a constant-speed rotation and calibration values set at the zero point. However, it is necessary to reset the zero point as quickly as possible after startup because there is a possibility that the zero point after actual startup may differ from the calibrated value. The KPAD library therefore starts the calibration process after the Wii MotionPlus starts. The calibration process completes by momentarily stilling all motion of the Wii MotionPlus. Note that the calibration process does not complete if you keep moving the Wii MotionPlus.
We strongly recommend that you use Wii MotionPlus information after the calibration process completes.
The calibration process can be started at any time using the KPADStartMplsCalibration function.
Using the KPADRead function, the specified channel's Wii MotionPlus status is read into a KPADMPStatus structure, a member of the KPADStatus structure. The KPADRead function processes the WPADMPStatus structure in the order received and updates each member of the WPADMPStatus structure. Please note that attitude correction using acceleration and DPD is performed only on the latest status.
The KPAD library can perform the following corrections on Wii MotionPlus data.
Excluding zero-point drift correction, these correction processes can each be freely enabled or disabled. (Zero-point drift correction is always enabled.) Parameters can be used to adjust the degree of drift correction.
If this feature is enabled, the system does not respond to small movements. This feature is effective in situations, for example, where you want to capture only large movements in a particular direction. Specifically, there is no response to motion smaller than radius, specified by the KPADSetMplsZeroPlayParam function. The closer the current angular velocity is to the specified radius, the closer to zero the return value of the KPADIsEnableMplsZeroPlay function becomes.
The zero point may drift due to effects such as temperature while the Wii MotionPlus is in use. This correction process works by first determining whether the Wii MotionPlus is stationary. This is done by checking whether the Wii MotionPlus continues to return the same value for some interval of time. If the device is deemed to be stationary, the zero point is corrected to reflect the value. Also, three types of determination criteria have been prepared. Any one of these may be applied. The zero point is constantly corrected based on information such as how well current acceleration and past angular acceleration being buffered internally fit in the specified determination criteria. Get information regarding how well data fits from the return value of the KPADIsEnableMplsZeroDrift function. The closer the value is to 1, the better the fit. You can also assume that the closer to 1, the more stable the motion.
Note: Because this type of processing is performed, this correction may also be performed unintentionally during constant, uniform motion. Be sure to consider this issue in scenes that request precise movements from the player. In such scenes, this issue can be addressed either by making stricter determination criteria or by setting up a play tolerance around the zero point.
By configuring a certain attitude as the base attitude, even vigorous swinging that cannot be handled by other correction processing stops causing the attitude to shift very far from the base attitude. For example, this correction can be used when swinging a sword to set the ready stance as the base attitude.
When this compensation is enabled, correction is applied using an acceleration value in cases where the acceleration obtained from the accelerometer fits inside the range given by the force of gravity plus revise_range, specified by the KPADSetMplsAccReviseParam function.
If you enable this feature, correction processing is applied whenever the DPD detects and maintains sight of an object. Although this feature can apply precise corrections for the yaw and roll axes, corrections cannot be applied to the pitch axis because the position of the sensor bar differs by environment.
You can expect some degree of improvement in temperature drift when using the zero-point drift correction process. In addition, you should be able to mitigate drift to a certain degree by: correcting acceleration and DPD before the error becomes too large, and setting the base model beforehand for scenes in which motions are so small that these corrections are not triggered.
As stated in the specifications for Wii MotionPlus rate sensors, the scale value for the written calibration values can vary by as much as ±8 percent due to the effects of humidity, air temperature, and device age. This error cannot be mitigated by the KPAD library. When designing for the Wii MotionPlus, therefore, do not attempt to require an exact degree of accuracy.
When the KPADSetMplsMagnification function operates internally to calculate angular speed, you can set a different scaling factor for each direction of motion. Because you can use this function to evaluate the impact that these errors in attitude and angle will actually have on calculations, use it when verifying that your game can be played within the range of error.
The Classic Controller and the Classic Controller Pro have different shapes for the left and right analog buttons. The quantity of analog input also differs. However, the Classic Controller Pro is recognized as a regular Classic Controller when it is attached to the Wii remote, so applications cannot distinguish between the two.
For this reason, from SDK 3.3 on, LR analog button input is not allowed and always returns zero.Also, it is harder to send input from the LR buttons of the Classic Controller than from the Classic Controller Pro because the buttons must be pressed down. Now, even pressing the LR buttons a little is recognized as button input.
2009/12/02 Revised the explanation of the Home Menu.
2009/10/21 Deleted the text regarding KPADOld. Explained Wii MotionPlus startup with respect to the Wii Remote speaker and Home Menu.
2009/06/23 Added an explanation about the Classic Controller and the Classic Controller Pro.
2009/01/30 Added a description of the KPADReset function.
2009/01/22 Explained the margin of error for Wii MotionPlus calibration values.
2009/01/16 Explained the conditions for deallocating the work area used by Wii MotionPlus for data processing.
2009/01/07 Revised the description of signal interference.
2008/12/04 Added a comprehensive description for the Wii MotionPlus.
2008/10/01 Explained the Wii MotionPlus.
2008/06/05 Deleted a description of 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/08/27 Added a "Notes" item about the effects of signal interference.
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