1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<LINK rel="stylesheet" type="text/css" href="../CSS/revolution.css"> 6<base target="main"> 7<title>KPAD API Introduction</title> 8</head> 9 10<body> 11 12<h1>KPAD API</h1> 13 14<h2>Introduction</h2> 15<p> 16The KPAD library version from before Revolution SDK Version 2.3 has been renamed to KPADOld library. 17</p> 18 19<p> 20Current 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 <I>Main Changes from the KPADOld Library</I> shown below. 21</p> 22 23<p> 24<font color="#ff0000">KPAD library</font> 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. 25</p> 26 27<p> 28<B>Note:</B> Beginning with version 3.2 of the Revolution SDK, you can <font color="red">link to the WBC library</font> to obtain Wii Balance Board information. 29</p> 30 31<p> 32A sample program for testing KPAD library features is in <code>$(REVOLUTION_SDK_ROOT)/build/demos/kpaddemo/</code>. 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). 33</p> 34 35<p> 36The KPAD library is in the following path. 37</p> 38<ul> 39<li><CODE>$(REVOLUTION_SDK_ROOT)/RVL/lib/kpad[D].a </CODE> 40</ul> 41 42<p> 43Function declarations are in the <code>$(REVOLUTION_SDK_ROOT)/include/revolution/kpad.h</code> header file. 44</p> 45 46<h3>Concurrent Use with KPADOld Library</h3> 47<p> 48KPADOld 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 "<a href="../kpadOld/index.html" target="_top">Introduction</a>" in the KPADOld library reference manual. 49</p> 50 51<h2>Main Changes from the KPADOld Library</h2> 52 53<h3>Controller Data Sampling</h3> 54<p> 55KPADOld: Uses auto-sampling.(<a href="../wpad/WPADSetAutoSamplingBuf.html"><CODE>WPADSetAutoSamplingBuf</CODE></a> function).<br> KPAD: Uses the <font color="#ff0000">sampling callback</font>(<a href="../wpad/WPADSetSamplingCallback.html"><CODE>WPADSetSamplingCallback</CODE></a> function). 56</p> 57 58<p> 59The application can no longer call the <a href="../wpad/WPADSetSamplingCallback.html"><CODE>WPADSetSamplingCallback</CODE></a> function. <a href="KPADSetSamplingCallback.html">The <CODE>KPADSetSamplingCallback</CODE></a> 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 <CODE>NULL</CODE> as an argument to this function or call the <a href="./KPADShutdown.html"><code>KPADShutdown</code></a> function. Connecting or disconnecting a controller will not release the callback. 60</p> 61 62<h3>Connecting and Disconnecting a Controller</h3> 63<p> 64KPADOld: You can use either the <a href="../wpad/WPADProbe.html"><code>WPADProbe</code></a> function or the <a href="../wpad/WPADSetConnectCallback.html"><code>WPADSetConnectCallback</code></a> function.<br>KPAD: You can use the <a href="../wpad/WPADProbe.html"><code>WPADProbe</code></a> function, but not the <a href="../wpad/WPADSetConnectCallback.html"><code>WPADSetConnectCallback</code></a> function. You can also use the return value from the <a href="./KPADReadEx.html"><code>KPADReadEx</code></a> function instead of the WPAD library. 65</p> 66 67<p> 68Applications can no longer call the <a href="../wpad/WPADSetConnectCallback.html"><CODE>WPADSetConnectCallback</CODE></a> function while using the KPAD library. The <a href="../wpad/WPADSetConnectCallback.html"><CODE>WPADSetConnectCallback</CODE></a> function can be used as usual when the KPAD library is not in use. Also, the callback function registered before the call to <a href="./KPADInit.html"><CODE>KPADInit</CODE></a> is now maintained within the KPAD library and is called when connecting or disconnecting. When the KPAD library is being used, use the <a href="./KPADSetConnectCallback.html"><CODE>KPADSetConnectCallback</CODE></a> function to register callbacks. Although callbacks registered using this function are deleted by specifying <CODE>NULL</CODE> as an argument to this function or by calling <a href="./KPADShutdown.html"><code>KPADShutdown</code></a>, doing this will not clear any callbacks registered before beginning use of the KPAD library. 69</p> 70 71<h3>Changes in the <a href="./KPADStatus.html">KPADStatus</a> and <a href="./KPADEXStatus.html">KPADEXStatus</a> Structures</h3> 72<p> 73The size and order of some members of the <a href="./KPADStatus.html"><CODE>KPADStatus</CODE></a> and <a href="./KPADEXStatus.html"><CODE>KPADEXStatus</CODE></a> 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. 74</p> 75 76<h3><a href="./KPADReset.html">KPADReset</a> Function Operation</h3> 77<p> 78KPADOld: Resets the internal work immediately. Stops the rumble motor.(<a href="../wpad/WPADStopMotor.html"><CODE>WPADStopMotor</CODE></a> function).<br> 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 <a href="./KPADRead.html"><CODE>KPADRead</CODE></a> or <a href="./KPADReadEx.html"><code>KPADReadEx</code></a> function is called. 79</p> 80 81<h3>Addition of the <a href="./KPADInitEx.html">KPADInitEx</a> Function and Its Recommended Uses</h3> 82<p> 83The 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 <code>KPAD_RING_BUFS</code> is maintained for this purpose. The contents of this ring buffer are flushed every time the <a href="./KPADRead.html"><code>KPADRead</code></a> or <a href="./KPADReadEx.html"><code>KPADReadEx</code></a> function is called. 84</p> 85<p> 86When the <a href="./KPADInit.html">KPADInit</a> 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 <a href="./KPADInitEx.html"><CODE>KPADInitEx</CODE></a> function. Pass the additional buffer (an array of <code>KPADUnifiedWpadStatus</code> structures) and its size as arguments to the <a href="./KPADInitEx.html"><CODE>KPADInitEx</CODE></a> 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 <code>NULL</code> and zero. 87</p> 88<p> 89We recommend that you use the <a href="./KPADInitEx.html"><CODE>KPADInitEx</CODE></a> function for future development of applications. 90</p> 91 92<h3>Addition of the <a href="./KPADReadEx.html">KPADReadEx</a> Function and Its Recommended Uses</h3> 93<p> 94The <a href="./KPADRead.html">KPADRead</a> function returns the number of sets of sampling data, or zero if there are none. The <a href="./KPADReadEx.html"><CODE>KPADReadEx</CODE></a> 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: 95 96<table border="1" class="arguments"> 97 <tr> 98 <th>KPAD_READ_ERR_NONE</th> 99 <td>There is sampling data.</td> 100 </tr> 101 <tr> 102 <th>KPAD_READ_ERR_NO_DATA</th> 103 <td>No sampling data.</td> 104 </tr> 105 <tr> 106 <th>KPAD_READ_ERR_NO_CONTROLLER</th> 107 <td>The Wii Remote is not connected.</td> 108 </tr> 109 <tr> 110 <th>KPAD_READ_ERR_SETUP</th> 111 <td>WPAD library initialization is not complete.</td> 112 </tr> 113 <tr> 114 <th>KPAD_READ_ERR_LOCKED</th> 115 <td>Duplicate calls caused failure to obtain permission to process.</td> 116 </tr> 117 <tr> 118 <th>KPAD_READ_ERR_INIT</th> 119 <td>The <a href="./KPADInit.html"><CODE>KPADInit</CODE></a> function (or the <a href="./KPADInitEx.html"><CODE>KPADInitEx</CODE></a> function) has not been called.</td> 120 </tr> 121</table> 122<p> 123Even when the <a href="./KPADRead.html">KPADRead</a> 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 <a href="./KPADReadEx.html"><CODE>KPADReadEx</CODE></a> function will change the sampling buffer's contents, but if and only if <code>KPAD_READ_ERR_NO_DATA</code> is returned, then the contents at the start of the sampling buffer have not changed. 124</p> 125<p> 126We recommend that you use the <a href="./KPADReadEx.html"><CODE>KPADReadEx</CODE></a> function for future development of applications. 127</p> 128 129<h3>Error Codes for the <CODE>KPADStatus</CODE> Structure</h3> 130<p> 131The <SPAN class="argument">err</SPAN> member value of the <code>WPADStatus</code> structure that is obtained from the <a href="../wpad/WPADRead.html"><code>WPADRead</code></a> function will be copied into the <SPAN class="argument">wpad_err</SPAN> member of the <code>KPADStatus</code> structure. The error code passed into this member variable indicates the state of data received from the Wii Remote, as follows. 132</p> 133 134<TABLE class="arguments" border="1" > 135 <tbody> 136 <tr> 137 <th>WPAD_ERR_NONE</th> 138 <td>Data with the specified data format was received.</td> 139 </tr> 140 <tr> 141 <th>WPAD_ERR_NO_CONTROLLER</th> 142 <td>Data has never been received.</td> 143 </tr> 144 <tr> 145 <th>WPAD_ERR_INVALID</th> 146 <td>Data was received with a format that differs from the data format specified to the WPAD library.<br> 147 (In this case, the data for the Wii Remote and external extension controllers is invalid.)</td> 148 </tr> 149 <tr> 150 <th>WPAD_ERR_CORRUPTED</th> 151 <td>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.<br>(However, in this case Wii Remote data has not been corrupted.)</td> 152 </tr> 153 </tbody> 154</table> 155 156<p> 157To get the Wii Remote status, use the <a href="../wpad/WPADProbe.html"><code>WPADProbe</code></a> function in the WPAD library. The error codes returned from the <a href="../wpad/WPADProbe.html"><code>WPADProbe</code></a> function are shown below, along with their descriptions. <font color="red"><B>Note:</B> You can also use the <a href="./KPADReadEx.html"><code>KPADReadEx</code></a> function to check if a Wii Remote is connected.</font> 158</p> 159<TABLE class="arguments" border="1" > 160 <tbody> 161 <tr> 162 <th>WPAD_ERR_NONE</th> 163 <td>The Wii Remote is connected, and control commands are not being sent from the Wii console to the Wii Remote.</td> 164 </tr> 165 <tr> 166 <th>WPAD_ERR_NO_CONTROLLER</th> 167 <td>The Wii Remote is disconnected.</td> 168 </tr> 169 <tr> 170 <th>WPAD_ERR_BUSY</th> 171 <td>A control command has been sent to a connected Wii Remote, and the system is waiting for an ACK from the Wii Remote.</td> 172 </tr> 173 </tbody> 174</table> 175 176<p><font color="red">The error code that can be obtained by the <a href="../wpad/WPADProbe.html"><code>WPADProbe</code></a> function and the error code passed to the <code>WPADStatus</code> structure's <span class="argument">err</span> member each have different meanings. Be aware that they are not synchronized.</font> 177</p> 178 179<h3>When <a href="./KPADRead.html">KPADRead</a> or <a href="./KPADReadEx.html">KPADReadEx</a> Is Called Multiple Times from Different Threads or Interrupts</h3> 180<p> 181KPADOld: Call is prohibited because the operation is undefined.<br>KPAD: Returns zero if processing permissions failed to be obtained. The <a href="./KPADReadEx.html"><CODE>KPADReadEx</CODE></a> function will also return the error code <code>KPAD_READ_ERR_LOCKED</code>. 182</p> 183 184<h3>When <a href="./KPADReset.html">KPADReset</a> Is Called from a Different Thread or Interrupt While <a href="./KPADRead.html">KPADRead</a> or <a href="./KPADReadEx.html">KPADReadEx</a> Is Processing</h3> 185<p> 186KPADOld: Call is prohibited because the operation is undefined.<br>KPAD: Yes. 187</p> 188 189<h3>Time-Interval Restrictions on Calls to <a href="./KPADRead.html">KPADRead</a> or <a href="./KPADReadEx.html">KPADReadEx</a></h3> 190<p> 191KPADOld: Assumes that the function is called for each game frame.<br>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 <a href="./KPADInitEx.html"><CODE>KPADInitEx</CODE></a> function) beyond the number used in KPADOld. 192</p> 193 194<h3>When <a href="./KPADRead.html">KPADRead</a> or <a href="./KPADReadEx.html">KPADReadEx</a> Has Not Been Called for a Long Time</h3> 195<p> 196KPADOld: 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.<br>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. 197</p> 198 199<h3>Button Input on Wii Remote During Attaching or Detaching the Extended Controllers</h3> 200<p> 201KPADOld: Because internal work will be reset, swapping the extended controllers while pressing a button will result in the input being treated as a trigger.<br>KPAD: Internal work unrelated to the extended controllers will not be reset, so swapping while pressing a button will not be a problem. 202</p> 203 204<h3>Change in the Sampling Data During Extended Controller Attachment and Detachment</h3> 205<p> 206KPADOld: DPD and Motion Sensor values fluctuate more easily.<br>KPAD: Adding the data format check allows maximal possible control of the fluctuation caused by swapping. 207</p> 208 209<h3>Using the <a href="./KPADGetWPADRingBuffer.html">KPADGetWPADRingBuffer</a>, <a href="./KPADGetWPADFSRingBuffer.html">KPADGetWPADFSRingBuffer</a>, and <a href="./KPADGetWPADCLRingBuffer.html">KPADGetWPADCLRingBuffer</a> Functions with the <a href="../wpad/WPADGetLatestIndexInBuf.html">WPADGetLatestIndexInBuf</a> Function</h3> 210<p> 211KPADOld: 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 <a href="../wpad/WPADSetDataFormat.html"><CODE>WPADSetDataFormat</CODE></a> function. Thus, we cannot guarantee that the application can access the buffer in the appropriate data format.<br>KPAD: This method has been deprecated. Use the new <a href="./KPADGetUnifiedWpadStatus.html"><CODE>KPADGetUnifiedWpadStatus</CODE></a> function instead. 212</p> 213 214<h3>Clamp Processing for the Stick</h3> 215<p> 216KPADOld: Circular clamp is implemented.<br>KPAD: Added cross clamp. The default is circular clamp as with KPADOld. Select it through the <a href="./KPADEnableStickCrossClamp.html">KPADEnableStickCrossClamp</CODE></a> and <a href="./KPADDisableStickCrossClamp.html"><CODE>KPADDisableStickCrossClamp</CODE></a> functions. 217</p> 218 219<h3>Reading and Discarding Old Data</h3> 220<p> 221KPADOld: If a controller is disconnected when the <a href="./KPADRead.html"><CODE>KPADRead</CODE></a> function has not been called for a long time, the sampling buffer updates will stop. The <a href="./KPADRead.html"><CODE>KPADRead</CODE></a> function called next will use the old sampling data. If you want to use the newest sampling data, first call the <a href="./KPADRead.html"><CODE>KPADRead</CODE></a> function (specify <CODE>KPAD_MAX_READ_BUFS</CODE> for the storage count) and clear all internal sampling buffers.<br>KPAD: No processing is necessary because sampling buffer data is thrown away when a controller is disconnected. 222</p> 223 224<h3>Regarding Data Loss</h3> 225<p> 226The <a href="./KPADRead.html"><CODE>KPADRead</CODE></a> and <a href="./KPADReadEx.html"><CODE>KPADReadEx</CODE></a> 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.<br><br> 227 228KPADOld: These conditions can sometimes be improved by using the rebuilt KPAD library and changing the <code>KPAD_RING_BUFS</code> macro value in <code>$(REVOLUTION_SDK_ROOT)/include/revolution/kpad.h</code> to increase the ring buffer.<br>KPAD: Conditions can sometimes be improved by increasing the ring buffer that is passed to <a href="./KPADInitEx.html"><code>KPADInitEx</code></a>. 229</p> 230 231<h2>Process Flow</h2> 232<h3>KPAD Initialization</h3> 233<p> 234The KPAD library is initialized by calling either the <a href="./KPADInit.html"><CODE>KPADInit</CODE></a> function or the <a href="./KPADInitEx.html"><code>KPADInitEx</code></a> function. Call the <a href="../wpad/WPADRegisterAllocator.html"><CODE>WPADRegisterAllocator</CODE></a> function to register the memory allocator function for getting and deallocating memory with the WPAD library before calling these functions because they invoke the <a href="../wpad/WPADInit.html"><CODE>WPADInit</CODE></a> function internally. After the KPAD library is initialized, it uses the WPAD library <font color="#ff0000">sampling callback</font> (auto sampling for KPADOld) to get data and update its internal buffer. 235</p> 236 237<h3>Getting Controller Information</h3> 238<p> 239To load the specified channel's controller information into the <a href="./KPADStatus.html"><CODE>KPADStatus</CODE></a> structure, use the <a href="./KPADRead.html"><CODE>KPADRead</CODE></a> or <a href="./KPADReadEx.html"><CODE>KPADReadEx</CODE></a> function. The controller information to be read may be adjusted by calling the following functions beforehand. 240</p> 241 242<ul> 243<li>When adjusting the sharpness of the Wii Remote response and the hand tremor reduction level, use the <a href="./KPADSetPosParam.html"><CODE>KPADSetPosParam</CODE></a>, <a href="./KPADSetHoriParam.html"><CODE>KPADSetHoriParam</CODE></a>, <a href="./KPADSetDistParam.html"><CODE>KPADSetDistParam</CODE></a>, and <a href="./KPADSetAccParam.html"><CODE>KPADSetAccParam</CODE></a> functions. 244<li>The digital button repeat may be adjusted through the <a href="./KPADSetBtnRepeat.html"><CODE>KPADSetBtnRepeat</CODE></a> function. 245<li>Use the <a href="./KPADSetSensorHeight.html"><CODE>KPADSetSensorHeight</CODE></a>, <a href="./KPADEnableAimingMode.html"><CODE>KPADEnableAimingMode</CODE></a>, and <a href="./KPADDisableAimingMode.html"><CODE>KPADDisableAimingMode</CODE></a> 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. </font>The <a href="./KPADEnableAimingMode.html"><CODE>KPADEnableAimingMode</CODE></a> function is automatically called from the <a href="KPADInit.html"><CODE>KPADInit</CODE></a> function. 246<li>The clamp processing of the Nunchuk and Classic Controller sticks are adjusted through the<a href="./KPADEnableStickCrossClamp.html"><CODE>KPADEnableStickCrossClamp</CODE></a> and <a href="./KPADDisableStickCrossClamp.html"><CODE>KPADDisableStickCrossClamp</CODE></a> functions. 247</ul> 248 249<h3>Other</h3> 250<p> 251In some cases, it might be effective to call the <a href="./KPADReset.html"><CODE>KPADReset</CODE></a> function, such as during a change in scenes. However, because the <a href="./KPADReset.html"><CODE>KPADReset</CODE></a> function will have an ill effect on button trigger processing, <font color="#ff0000">avoid calling the function where possible</font>. It does not also need to be called when swapping external extension controllers. 252</p> 253 254<h2>Notes</h2> 255<h3>Differences in Coordinate Systems</h3> 256<p> 257The coordinate system of the coordinates obtained with the KPAD library is different from that used in the WPAD library. For details, see the <a href="./KPADStatus.html"><CODE>KPADStatus</CODE></a> and <a href="./KPADEXStatus.html"><CODE>KPADEXStatus</CODE></a> structure pages. 258</p> 259 260<H2>Revision History</H2> 261<P> 2622008/06/05 Deleted text about the <a href="./KPADSetObjInterval.html"><code>KPADSetObjInterval</code></a> function.<br>2008/06/03 Added an explanation for the <a href="./KPADReadEx.html"><code>KPADReadEx</code></a> function.<br>2008/05/29 Added explanations for the <a href="./KPADInitEx.html"><code>KPADInitEx</code></a> function.<br>2008/04/17 Mentioned that the Wii Balance Board is now supported. Revised differences with KPADOld.<br>2007/01/15 Revised such that the coordinate correction feature is enabled by default. As a result, revised the demo.<br> Fixed the following bug: the button repeat interval would increase if the maximum number of stored data items passed to the <a href="./KPADRead.html"><CODE>KPADRead</CODE></a> function was smaller than <code>KPAD_MAX_READ_BUFS</code>.<br> Corrected errors in the manuals of the <a href="./KPADEnableStickCrossClamp.html"><CODE>KPADEnableStickCrossClamp</CODE></a> and <a href="./KPADDisableStickCrossClamp.html"><CODE>KPADDisableStickCrossClamp</CODE></a> functions. <br>2006/10/25 Revised the description to match KPAD version 2.<br>2006/06/19 Support for UI Tool Version 4. Changed tentative product name to official name.<br>2006/05/15 Added to Notes methods to avoid loss of data when the intervals between calls of the <a href="./KPADRead.html"><CODE>KPADRead</CODE></a> function become too long.<br>2006/03/01 Initial version.<br> 263</P> 264 265<hr><p>CONFIDENTIAL</p></body> 266</html> 267